Foolscap

Plugins for Connection Handlers (236)

New types of connection hints can now be used, by installing a suitable
connection handler into the Tub. These hints could point to I2P servers or
Tor hidden-service (.onion) addresses. The built-in TCP handler can be
replaced entirely to protect a client's IP address by routing all connections
through Tor. Implementation of these plugins are left as exercise for the
reader: Foolscap only provides the built-in "DefaultTCP" handler. See
doc/connection-handlers.rst for details.

Shared Listeners are removed (239)

Until this version, it was possible to create a single Listener that serviced
multiple Tubs (by passing the Listener returned from `l=tubA.listenOn(where)`
into `tubB.listenOn(l)`). This seemed useful a long time ago, but in fact was
not, and the implementation caused irreparable problems that were exposed
while testing the new connection handlers. So support for shared Listeners
has been removed: Tubs can still use multiple Listeners, but each Listener
now services at most one Tub. In particular, `Tub.listenOn()` now only
accepts a string, not a Listener instance.

Note that relays and redirects are still on the roadmap, but neither feature
requires sharing a Listener between multiple local Tubs.

Extended-Form Connection Hints are removed

Support for extended-form connection hints has been removed. These were hints
with explicit key names like "tcp:host=example.org:port=12345", or
"tcp:example.org:timeout=30". They were added in the 0.7.0 release, but since
then we've realized that this is power that should not be granted to external
FURL providers.

The parser now only accepts "tcp:example.org:12345" and "example.org:12345".
Foolscap has never particularly encouraged applications to call
Tub.setLocation() with anything other than these two forms, so we do not
expect any compatibility problems.

Option to Disable Gifts (126)

"Gifts", more precisely known as "third-party reference introductions", occur
when one Tub sends you a message that includes a reference to some object on
a third Tub. This allows references to be passed around transparently,
without regard to which Tub they live on (yours, mine, or theirs), but allows
other Tubs to cause you to create network connections to hosts and ports of
their choosing. If this bothers you, the new `tub.setOption("accept-gifts",
False)` option instructs your Tub to reject these third-party references,
causing the calls that used them to signal a Violation error instead.

Unreachable Tubs now fully supported (208)

Unreachable "client-only" Tubs can be created by simply not calling either
`tub.listenOn()` nor `tub.setLocation()`. These Tubs can make outbound
connections, but will not accept inbound ones. `tub.registerReference()` will
throw an error, and Gifts delivered to third parties will not work.

Previous versions suggested using `tub.setLocation("")`: this is no longer
recommended.

new util.allocate_tcp_port() function

To support a future deprecation of `Tub.listenOn("tcp:0")`, the new
allocate_tcp_port() function was added to return (synchronously) a
currently-unused TCP port integer. This can be used during app configuration
to decide on a listening port, which can then be passed into
`Tub.listenOn("tcp:%d" % portnum)`. This may allow Tub.setLocation() to be
called *before* the reactor is started, simplifying application startup code
(this also requires a suitable hostname or IP address, which is a separate
issue).

Packaging/Dependency Changes

Foolscap now requires Twisted 10.1.0 or newer, to use Endpoints and
connection handler plugins.

Foolscap's logging system (specifically the twisted-to-foolscap bridge) is
now compatible with Twisted-15.2.0. The previous version had problems with
the new contents of twisted.logger's "eventDict" objects. (235)

UnauthenticatedTub is gone

As announced in the previous release, UnauthenticatedTub has been removed.
All Tubs are fully authenticated now.

Security Improvements

Foolscap now generates better TLS certificates, with 2048-bit RSA keys and
SHA256 digests. Previous versions used OpenSSL's defaults, which typically
meant 1024-bit MD5.

To benefit from the new certificates, you must regenerate your Tubs, which
means creating new FURLs (with new TubIDs). Previously-created Tubs will
continue to work normally: only new Tubs will be different.

Packaging/Dependency Changes

setup.py now requires setuptools

Foolscap now requires pyOpenSSL unconditionally, because all Tubs are
authenticated.

We now recommend "pip install ." to install Foolscap and all its
dependencies, instead of "python setup.py install". See 231 for details.

Security Fixes

The "flappserver" feature was found to have a vulnerability in the
service-lookup code which, when combined with an attacker who has the ability
to write files to a location where the flappserver process could read them,
would allow that attacker to obtain control of the flappserver process.

Users who run flappservers should upgrade to 0.7.0, where this was fixed as
part of 226.

Each flappserver runs from a "base directory", and uses multiple files within
the basedir to track the services that have been configured. The format of
these files has changed. The flappserver tool in 0.7.0 remains capable of
reading the old format (safely), but will upgrade the basedir to the new
format when you use "flappserver add" to add a new service. Brand new
servers, created with "flappserver create", will use the new format.

The flappserver tool in 0.6.5 (or earlier) cannot handle this new format, and
will believe that no services have been configured. Therefore downgrading to
an older version of Foolscap will require manual reconstruction of the
configured services.

Major Changes

UnauthenticatedTub has been deprecated, and will be removed in the next
release (0.8.0). This seldom-used feature provides Foolscap's RPC semantics
without any of the security, and was included to enable the use of Foolscap
without depending upon the (challenging-to-install) PyOpenSSL library.
However, in practice, the lack of a solid dependency on PyOpenSSL has made
installation more difficult for applications that *do* want the security, and
UnauthenticatedTub is a footgun waiting to go off. Foolscap's code and
packaging will be simpler without it. (67)

Minor Changes

The "git-foolscap" tools, which make it possible to publish and clone Git
repositories over a Foolscap (flappserver) connection, have been moved from
their hiding place in doc/examples/ into their own project, hosted at
https://github.com/warner/git-foolscap . They will also be published on PyPI,
to enable "pip install git-foolscap".

The documentation was converted from Lore to ReStructuredText (.rst). Thanks
to Koblaid for the patient work. (148)

The connection-hint parser in 0.7.0 has been changed to handle all TCP forms
of Twisted's "Client Endpoint Descriptor" syntax, including the short
"tcp:127.0.0.1:9999" variant. A future version should handle arbitrary
endpoint descriptors (including Tor and i2p, see 203), but this small step
should improve forward compatibility. (216, 217)

Compatibility Fixes

This release is compatible with Twisted-14.0.0.

Foolscap no longer claims compatability with python-2.4.x or 2.5.x . These
old versions might still work, but there are no longer automated tests to
ensure this. Future versions will almost certainly *not* work with anything
older than python-2.6.x . Foolscap remains incompatible with py3, sorry.

Forward Compatibility

When parsing FURLs, the connection hints can now use TCP sockets described
with the Twisted Endpoints syntax (e.g. "tcp:host=127.0.0.1:port=9999"), in
addition to the earlier host:port "127.0.0.1:9999" form. Foolscap-0.6.5
ignores any hint that is not in one of these two forms. This should make it
easier to introduce new hint types in the future.

Minor Changes

The "ChangeLog" file is no longer updated.

Violation reports now include the method name. (201)

The "flappserver" tool explicitly rejects unicode input, rather than
producing hard-to-diagnose errors later. (209)

Minor Changes

The unreliable 'extras_require' property in setup.py, which allowed other
python programs to declare a dependency on foolscap's "secure_connections"
feature, was removed. See README.packagers for alternate instructions. (174)

'flogtool' log-dumping commands (dump, tail, web-viewer) now accept a
consistent --timestamps= argument to control how event times are displayed
(UTC, local, seconds-since-epoch, etc). (192, 193)

Certain invalid "location" strings (accepted by Tub.setLocation and put into
FURLs) are rejected earlier, and with better error messages. The error
message produced when 'flogtool dump' is given a FURL-file (instead of an
event log file) has been improved.

The Incident Gatherer will tolerate incident-file errors better, fetching
remaining incidents instead of halting. (190)

The git-over-foolscap tools were cleaned up, and the documentation was
brought into line with the implementation. (197)

Other minor bugs were fixed: 179, 191, 194, 195, 196

Compatibility Fixes

This release really is compatible with Twisted-11.1.0 . The previous Foolscap