(Available within Tor at: http://alzrgrdvxct6c63z.onion/trac)

= Foolscap =

"Foolscap" is an RPC protocol for Python+Twisted, providing a
capability-based security model and flexible serialization. It is intended to
replace Twisted's native "Perspective Broker" RPC system. Foolscap has been
under development (on and off) by Brian Warner for several years.

Download it here:
[http://foolscap.lothar.com/releases/foolscap-0.11.0.tar.gz foolscap-0.11.0]
([http://foolscap.lothar.com/releases/foolscap-0.11.0.tar.gz.asc gpg sig]
using key [http://foolscap.lothar.com/releases/foolscap-release-signing-key.asc 0xAF1B4A2A]) or
from its [http://pypi.python.org/pypi/foolscap/ PyPI page].

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

== NEWS ==

 * 23-Mar-2016: 0.11.0 released, use tox, require `twisted[tls]`, start on IPv6
 * 21-Jan-2016: 0.10.1 released, small str-vs-unicode version fix
 * 15-Jan-2016: 0.10.0 released, Twisted-15.3.0 compatible, drops Python-2.6
 * 21-Sep-2015: 0.9.1 released, adds connection plugins
 * 15-Apr-2015: 0.8.0 released, removes !UnauthenticatedTub, improves TLS certs
 * 23-Sep-2014: 0.7.0 released, fixes flappserver security vulnerability
 * 12-Aug-2014: 0.6.5 released, Twisted-14.0 compatible
 * 18-Jun-2012: 0.6.4 released, small fixes, git-over-flappserver updated
 * 05-Jan-2012: 0.6.3 released, really Twisted-11.1 compatible this time
 * 15-Oct-2011: 0.6.2 released, Twisted >11.1 compatible, git-over-foolscap tools
 * 16-Jan-2011: 0.6.1 released, small fixes
 * 28-Dec-2010: 0.6.0 released, Twisted-10.2 compatible
 * 25-Mar-2010: 0.5.1 released, O(n^2^) performance bug fixed
 * 18-Jan-2010: 0.5.0 released, "from foolscap.api import Tub", hush py2.6
   "sets" warning, added git-furl examples
 * 19-Jun-2009: git-over-flappserver tools added to tree: use a FURL to
   update/pull from a remote Git repository
 * 13-May-2008: The recent Debian OpenSSL bug affects Foolscap: see DebianOpenSslBug
   for details.

== Features ==

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.

Foolscap also provides a logging system which offers severity-triggered
"Incident Reports" of the events leading up to a problem, which can be
written to local disk or sent to a remote log gatherer. In addition, a
log-retrieving tool can be attached to an application's "flogport" to
retrieve recent events and subscribe to new ones.

FoolscapFeatures has a detailed list of features, including a description of
the main differences between Foolscap and Perspective Broker.

== Documentation ==

Start with [https://github.com/warner/foolscap/blob/latest-release/doc/using-foolscap.rst using-foolscap.html] for a conceptual
overview and basic tutorial.

There are other manuals [https://github.com/warner/foolscap/blob/latest-release/doc here], including portions of the protocol
specification.

The links above refer to the most recent Foolscap release. All documentation
lives in the source tree's [source:doc/ doc/ directory], so look there for
the latest (not-yet-released) version, or look on [https://github.com/warner/foolscap/blob/latest-release/doc github] for rendered versions.


== Show Me The Code ==

Both current and older releases are available in the
[http://foolscap.lothar.com/releases/ /releases directory]. The latest code lives in a !GitHub
project at https://github.com/warner/foolscap/ . To retrieve a
copy of the trunk use the following command:

{{{
git clone https://github.com/warner/foolscap.git
}}}

You can browse the source through github, or through this Trac instance's
[/browser Browse Source] feature.

== Status ==

The Foolscap wire protocol has been stable for about two years. There are
changes and improvements I'd like to make to it, but they will probably be
made in a compatible fashion. The protocol has several places for version
negotiation, making this easier to achieve.

== 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.

== Projects Using Foolscap ==

 * [http://tahoe-lafs.org/trac/tahoe Tahoe-LAFS], a secure robust distributed filesystem,
   uses Foolscap for all inter-node communication
 * [http://ipython.scipy.org/ IPython], an "enhanced interactive Python shell, uses
   Foolscap for its parallel computing features
 * your name here! please add your own Foolscap-using project link here