| 4 | | "Foolscap" is the name for the next-generation RPC protocol, intended to |
| 5 | | replace Perspective Broker. It has been under development (on and off) by |
| 6 | | Brian Warner for several years. |
| | 4 | "Foolscap" is an RPC protocol for Python+Twisted, providing a |
| | 5 | capability-based security model and flexible serialization. It is intended to |
| | 6 | replace Twisted's native "Perspective Broker" RPC system. Foolscap has been |
| | 7 | under development (on and off) by Brian Warner for several years. |
| 29 | | * most inert Python types are serializable, including unicode and sets |
| 30 | | * clients and servers are implemented as |
| 31 | | [http://twistedmatrix.com/documents/current/api/twisted.application.service.html Services], |
| 32 | | which share connections when possible and are easy to shut down |
| 33 | | * links are encrypted/authenticated by default (using SSL) |
| 34 | | * all objects are accessed through secure/unguessable "FURLs" |
| 35 | | * explicitly published objects can be accessed through well-known FURLs |
| 36 | | * you can declare method signatures (with "constraints", either in Interface |
| 37 | | classes or as method attribute/decorators) |
| 38 | | * this enables defenses against resource-consumption DoS attacks, including |
| 39 | | stack-frame-exhaustion attacks |
| 40 | | * (TODO) you can ask the deserializer about your current maximum |
| 41 | | memory/stackframe exposure, based upon what objects are visible and what |
| 42 | | methods they declare |
| 43 | | * serializers for third-party classes can be registered using Adapters |
| 44 | | * serializers are more "streaming" than in oldpb |
| 45 | | * serializers can pause themselves, deferring serialization until later |
| 46 | | * serializers can be paused when the network pipe is full |
| 47 | | * newpb is architected to make it possible to rewrite |
| 48 | | serializers/deserializers in C, for speed |
| 49 | | * object graph depth is limited by available heap memory, not available |
| 50 | | stack depth |
| | 45 | CompareToPB explains some of the differences between Foolscap and Perspective |
| | 46 | Broker |
| 54 | | The documentation is in the [source:doc/ doc/ directory] and includes both |
| 55 | | the protocol specification and a short user's manual. Rendered HTML from the |
| 56 | | most recent release lives [/docs/ here], API docs are [/docs/api/index.html here], |
| 57 | | and [/docs/using-foolscap.html using-foolscap.html] is probably the best |
| 58 | | place to start. |
| | 50 | Start with [/docs/using-foolscap.html using-foolscap.html] for a conceptual |
| | 51 | overview and basic tutorial. |
| | 52 | |
| | 53 | There are other manuals [/docs/ here], including portions of the protocol |
| | 54 | specification. Detailed (but somewhat hard-to-navigate) API docs are located |
| | 55 | [/docs/api/index.html here]. |
| | 56 | |
| | 57 | The links above refer to the most recent Foolscap release. All documentation |
| | 58 | lives in the source tree's [source:doc/ doc/ directory], so look there for |
| | 59 | the latest (not-yet-released) version. |
| 63 | | The current release is available [/releases/foolscap-0.4.2.tar.gz here]. This |
| 64 | | is an alpha release, since the protocol has not been finalized, and |
| 65 | | incompatible changes are being made every few months. Older releases are |
| 66 | | available [/releases/ here]. |
| 67 | | |
| 68 | | The latest Foolscap code lives in a [http://www.selenic.com/mercurial/wiki/ mercurial] |
| | 64 | Both current and older releases are available in the |
| | 65 | [/releases/ /releases directory]. The latest code lives in a |
| | 66 | [http://www.selenic.com/mercurial/wiki/ mercurial] |
| 87 | | Foolscap is slowly getting closer to being ready for production use. |
| 88 | | Applications which have full control over both ends of the wire and which can |
| 89 | | thus tolerate wire-protocol changes are probably the best candidate. |
| | 86 | The Foolscap wire protocol has been stable for about two years. There are |
| | 87 | changes and improvements I'd like to make to it, but they will probably be |
| | 88 | made in a compatible fashion. The protocol has several places for version |
| | 89 | negotiation, making this easier to achieve. |
