wiki:WikiStart

Version 74 (modified by Brian Warner, 7 years ago) (diff)

release 0.13.1

(formerly available within Tor at: ​http://alzrgrdvxct6c63z.onion/trac , but disabled due to agressive spidering)

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: ​foolscap-0.13.1 (​gpg sig using key ​0xAF1B4A2A) or from its ​PyPI page.

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

NEWS

  • 20-Nov-2017: 0.13.1 released, improves test reliability, adds flappclient $TOR_* controls
  • 20-Nov-2017: 0.13.0 released, fixes compatibility with Twisted-17.9.0
  • 26-Jul-2017: 0.12.7 released, minor I2P improvement
  • 12-Jan-2017: 0.12.6 released, minor I2P and Twisted compatibility improvements
  • 07-Dec-2016: 0.12.5 released, adds ConnectionInfo and ReconnectionInfo
  • 27-Sep-2016: 0.12.4 released, adds tor.control_endpoint_maker, IPv6 hints
  • 01-Sep-2016: 0.12.3 released, improves tor.socks_endpoint, port-allocation
  • 28-Aug-2016: 0.12.2 released, fixed Tor connection plugins
  • 20-Aug-2016: 0.12.1 released, SOCKS/Tor/I2P connection plugins included
  • 20-Jul-2016: 0.12.0 released, auto-config removed, listenOn(endpoint)
  • 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

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
  2. 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 ​using-foolscap.html for a conceptual overview and basic tutorial.

There are other manuals ​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 doc/ directory, so look there for the latest (not-yet-released) version, or look on ​github for rendered versions.

Show Me The Code

Both current and older releases are available in the ​/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 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.

  • Foolscap takes many ideas from the ​E Language. Foolscap is my attempt to make the concepts of E available to python+twisted programmers.
  • The Twisted wiki has ​a page on Foolscap where this information used to live.

Projects Using Foolscap

  • ​Tahoe-LAFS, a secure robust distributed filesystem, uses Foolscap for all inter-node communication
  • ​IPython once used Foolscap for the parallel/remote-kernel communication protocol, but switched to ZeroMQ in 2011
  • ​git-foolscap lets you share access to Git repositories (read+write or read-only) by sharing a FURL, rather than by adding a shell account
  • your name here! please add your own Foolscap-using project link here