= Foolscap =

"Foolscap" is the name for the next-generation RPC protocol, intended to
replace Perspective Broker. It has been under development (on and off) by
Brian Warner for several years.

The current release is [/releases/foolscap-0.3.2.tar.gz foolscap-0.3.2]
([/releases/foolscap-0.3.2.tar.gz.asc gpg sig]).

The recent Debian OpenSSL bug affects Foolscap: see DebianOpenSslBug for details.

It is released under the MIT license (see source:LICENSE for details), which
is the same license as Twisted uses.

The two primary responsibilities of an RPC protocol are to:

 1. serialize an object graph, and reconstruct a useful equivalent on the
    remote side
 1. allow the holder of a !RemoteReference in one process to invoke methods
    on a Referenceable in a different one

In addition, there are details like object naming, connection establishment,
controlling object serialization, reference lifetime, and error reporting.

== New features ==
(relative to oldpb, aka twisted.spread)

 * most inert Python types are serializable, including unicode and sets
 * clients and servers are implemented as
   [http://twistedmatrix.com/documents/current/api/twisted.application.service.html
   Services], which share connections when possible and are easy to shut down
 * links are encrypted/authenticated by default (using SSL)
 * all objects are accessed through secure/unguessable "FURLs"
  * explicitly published objects can be accessed through well-known FURLs
 * you can declare method signatures (with "constraints", either in Interface
   classes or as method attribute/decorators)
  * this enables defenses against resource-consumption DoS attacks, including
    stack-frame-exhaustion attacks
  * (TODO) you can ask the deserializer about your current maximum
    memory/stackframe exposure, based upon what objects are visible and what
    methods they declare
 * serializers for third-party classes can be registered using Adapters
 * serializers are more "streaming" than in oldpb
  * serializers can pause themselves, deferring serialization until later
  * serializers can be paused when the network pipe is full
 * newpb is architected to make it possible to rewrite
   serializers/deserializers in C, for speed
 * object graph depth is limited by available heap memory, not available
   stack depth

== Show Me The Doc ==

The documentation is in the [source:doc/ doc/ directory] and includes both
the protocol specification and a short user's manual. Rendered HTML from the
most recent release lives [/docs/ here], API docs are [/docs/api/index.html here],
and [/docs/using-foolscap.html using-foolscap.html] is probably the best
place to start.


== Show Me The Code ==

The current release is available [/releases/foolscap-0.3.2.tar.gz here]. This
is an alpha release, since the protocol has not been finalized, and
incompatible changes are being made every few months. Older releases are
available [/releases/ here].

The latest Foolscap code lives in a [http://www.selenic.com/mercurial/wiki/
mercurial] repository, at http://foolscap.lothar.com/repos/ . To retrieve a
copy of the trunk use the following command:

{{{
hg clone http://foolscap.lothar.com/repos/trunk foolscap-trunk
}}}

There are two online source-code browsers, the native hgwebdir.cgi at
http://foolscap.lothar.com/repos/trunk (which also has a
[http://foolscap.lothar.com/repos/trunk?style=gitweb gitweb-style view]), and
the Trac Mercurial plugin at the [/trac/browser Browse Source] link above.
Both are pretty handy.

Some day, Foolscap may be shipped as part of the "Twisted-Core" distribution,
but only after the protocol and code have stabilized a bit.

== Status ==

Foolscap is slowly getting closer to being ready for production use.
Applications which have full control over both ends of the wire and which can
thus tolerate wire-protocol changes are probably the best candidate.

The [source:doc/todo.txt 'todo.txt'] and [source:doc/jobs.txt 'jobs.txt']
files contain some of the things that need finishing before it will be ready.
Connection negotiation needs to be changed to use variable-length certificate
digests and certificate chains and variable-length object names, various
questions about making objects "giftable" by default or not need to be
answered and implemented, and we need to acquire operational experience with
Foolscap as a whole to think about usability.

Release 0.3.2 (as well as older releases) are available in the [/releases/
releases directory].

== Links ==

 * Foolscap takes many ideas from the [http://www.erights.org/ E Language].
   Foolscap is my attempt to make the concepts of E available to
   python+twisted programmers.
 * The Twisted wiki has [http://twistedmatrix.com/trac/wiki/FoolsCap a page]
   on Foolscap where this information used to live.


== Trac Hints ==

The old Trac starting page was moved to OldWikiStart


For a complete list of local wiki pages, see TitleIndex.