Changes between Version 35 and Version 36 of WikiStart


Ignore:
Timestamp:
06/20/2009 02:04:06 AM (15 years ago)
Author:
Brian Warner
Comment:

rewrite, simplify a bit

Legend:

Unmodified
Added
Removed
Modified
  • WikiStart

    v35 v36  
    22= Foolscap =
    33
    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
     5capability-based security model and flexible serialization. It is intended to
     6replace Twisted's native "Perspective Broker" RPC system. Foolscap has been
     7under development (on and off) by Brian Warner for several years.
    78
    8 The current release is 0.4.2: download it here: [/releases/foolscap-0.4.2.tar.gz foolscap-0.4.2]
    9 ([/releases/foolscap-0.4.2.tar.gz.asc gpg sig]) or from its [http://pypi.python.org/pypi/foolscap/0.4.2 PyPI page].
    10 
    11 The recent Debian OpenSSL bug affects Foolscap: see DebianOpenSslBug for details.
     9Download it here:
     10[/releases/foolscap-0.4.2.tar.gz foolscap-0.4.2]
     11([/releases/foolscap-0.4.2.tar.gz.asc gpg sig]) or
     12from its [http://pypi.python.org/pypi/foolscap/0.4.2 PyPI page].
    1213
    1314It is released under the MIT license (see source:LICENSE for details), which
    1415is the same license as Twisted uses.
     16
     17== NEWS ==
     18
     19 * 19-Jun-2009: git-over-flappserver tools added to tree: use a FURL to
     20   update/pull from a remote Git repository
     21 * 16-Jun-2009: 0.4.2 released, with a new "application server", making it
     22   safe and easy to remotely run specific commands or move files into a
     23   specific directory
     24 * 13-May-2008: The recent Debian OpenSSL bug affects Foolscap: see DebianOpenSslBug
     25   for details.
     26
     27== Features ==
    1528
    1629The two primary responsibilities of an RPC protocol are to:
     
    2437controlling object serialization, reference lifetime, and error reporting.
    2538
    26 == New features ==
    27 (relative to oldpb, aka twisted.spread)
     39Foolscap also provides a logging system which offers severity-triggered
     40"Incident Reports" of the events leading up to a problem, which can be
     41written to local disk or sent to a remote log gatherer. In addition, a
     42log-retrieving tool can be attached to an application's "flogport" to
     43retrieve recent events and subscribe to new ones.
    2844
    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
     45CompareToPB explains some of the differences between Foolscap and Perspective
     46Broker
    5147
    52 == Show Me The Doc ==
     48== Documentation ==
    5349
    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.
     50Start with [/docs/using-foolscap.html using-foolscap.html] for a conceptual
     51overview and basic tutorial.
     52
     53There are other manuals [/docs/ here], including portions of the protocol
     54specification. Detailed (but somewhat hard-to-navigate) API docs are located
     55[/docs/api/index.html here].
     56
     57The links above refer to the most recent Foolscap release. All documentation
     58lives in the source tree's [source:doc/ doc/ directory], so look there for
     59the latest (not-yet-released) version.
    5960
    6061
    6162== Show Me The Code ==
    6263
    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]
     64Both 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]
    6967repository, at http://foolscap.lothar.com/repos/ . To retrieve a
    7068copy of the trunk use the following command:
     
    7371hg clone http://foolscap.lothar.com/repos/trunk foolscap-trunk
    7472}}}
     73
    7574
    7675There are two online source-code browsers, the native hgwebdir.cgi at
     
    8584== Status ==
    8685
    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.
     86The Foolscap wire protocol has been stable for about two years. There are
     87changes and improvements I'd like to make to it, but they will probably be
     88made in a compatible fashion. The protocol has several places for version
     89negotiation, making this easier to achieve.
    9090
    9191The [source:doc/todo.txt 'todo.txt'] and [source:doc/jobs.txt 'jobs.txt']
     
    9797Foolscap as a whole to think about usability.
    9898
    99 Release 0.4.2 (as well as older releases) are available in the [/releases/
    100 releases directory].
    101 
    10299== Links ==
    103100
     
    108105   on Foolscap where this information used to live.
    109106
     107== Projects Using Foolscap ==
     108
     109 * [http://allmydata.org/trac/tahoe Tahoe], a secure robust distributed filesystem,
     110   uses Foolscap for all inter-node communication
     111 * [http://ipython.scipy.org/ IPython], an "enhanced interactive Python shell, uses
     112   Foolscap for its parallel computing features
     113 * your name here! please add your own Foolscap-using project link here
    110114
    111115== Trac Hints ==