* Release 0.9.1 (21-Sep-2015)
Point release to deal with PyPI upload problems. No code changes.
* Release 0.9.0 (21-Sep-2015)
** 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)
* Release 0.8.0 (15-Apr-2015)
** 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.
* Release 0.7.0 (23-Sep-2014)
** 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)
* Release 0.6.5 (12-Aug-2014)
** 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)
* Release 0.6.4 (18-Jun-2012)
** 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
pkgsrc.
* Release 0.6.3 (05-Jan-2012)
** Compatibility Fixes
This release really is compatible with Twisted-11.1.0 . The previous Foolscap
release (0.6.2), despite the changes described below, suffered mild
incompatibilites with the new TLS code in the final Twisted-11.1.0 release.
The most common symptom is a DirtyReactorError in unit tests that use
Tub.stopService() in their tearDown() method (to coordinate shutdown and
cleanup). Another symptom is tests overlapping with one another, causing
port-already-in-use errors.
This incompatibility did not generally affect normal operation, but only
impacted unit tests.
** Other Changes
The Debian packaging tools in misc/ were removed, as they were pretty stale.
These days, both Debian and Ubuntu make their own Foolscap packages.
* Release 0.6.2 (15-Oct-2011)
** Compatibility Fixes
Foolscap-0.6.2 will be compatible with future versions of Twisted (>11.0.0).
The 0.6.1 release will not: a TLS change went into Twisted trunk recently
(after the 11.0.0 release) which broke Foolscap 0.6.1 and earlier.
This release also fixes a minor incompatibility with newer versions of
OpenSSL (0.9.8o was ok, 1.0.0d was not), which caused errors in the test
suite (but normal runtime operation) on e.g. Ubuntu 11.10 "Oneiric".
** Git-Over-Foolscap Tools
The doc/examples/ directory contains two executables (git-foolscap and
git-remote-pb) which, when placed in your $PATH, make it easy to use Foolscap
to access a Git repository. These use the flappserver/flappclient tools and
let you build a FURL that provides read-only or read-write access to a single
repository. This is somewhat like providing SSH access to a repo, but with a
much smaller scope: the client will only be able to manipulate the one
repository, and gets no other authority on the target system. See the tool's
inline comments for usage instructions.
** Minor Fixes
Using 'flappserver upload-file FILE1 FILE2 FILE3..' (with three or more
files) now correctly uploads all files: previously it only managed to upload
the first and last.
'flappserver' argument handling was improved slightly. A workaround was added
to handle a Twisted stdio-closing bug which affected flappserver's
run-command function and broke the git-foolscap tool. Several changes were
made for the benefit of Windows: log filenames all use hyphens (not colons),
log filtering tools tolerate the lack of atomic-rename filesystem operations,
and some unixisms in the test suite were removed.
The Tub.setLogGathererFURL() method can now accept a list (iterable) of log
gatherer FURLs, not just a single one.
require this.
* Release 0.6.1 (16-Jan-2011)
** Minor Fixes
The old "sets" module is no longer imported without wrapping the import in a
DeprecationWarning suppressor. We still import it from slicers.set for
compatibility with older code, but that import will not produce a warning.
This should make Foolscap quieter when used with Python 2.6 or later.
A new RemoteReference method named getDataLastReceivedAt() was added, which
will tell you when data was most recently received on the connection
supporting that reference. This can be compared against time.time() to see
how "live" the connection is. For performance reasons, this is only enabled
when keepalives are turned on, otherwise it returns None. (#169)
Some unreachable code was removed. (#165)
* Release 0.6.0 (28-Dec-2010)
** API Changes
*** "foolscap.api" now mandatory
The old import names from foolscap/__init__.py have been removed, finishing
the transition begun with 0.5.0 . Applications must now import Tub,
Referenceable, and so on from "foolscap.api". (#122)
** Compatibility Fixes
Foolscap-0.6.0 is compatible with Twisted-10.2 (released 29-Nov-2010). The
0.5.1 release was not: pb.Listener was depending upon the behavior of an
internal Twisted function that changed, causing an AttributeError in
"StreamServerEndpointService". This is fixed, but the code is still using an
undocumented internal attribute to handle port=0 which will need to be
replaced eventually. (#167)
The first unit test ("test__versions") spuriously failed against Twisted-10.1
and 10.2, mistakenly believing that 10.1 was older than 8.1.0 due to a
lexicographic comparison that should have been numeric.
** Other Changes
Incident filenames are now like "2008-08-22--16:20:28Z.flog" which are in UTC
and mostly ISO-8601 format (the real ISO-8601 would use "_" instead of "--").
This is also used for log-gatherer filenames. (#111)
The logging code now honors FLOGLEVEL= when using FLOGTOTWISTED=1; previously
FLOGLEVEL= was ignored when deciding which log events should be bridged to
the twisted logger. (#154)
Some minor packaging bugs were fixed.
This is a ground-up rewrite of Perspective Broker, which itself is Twisted's
native RPC/RMI protocol (Remote Procedure Call / Remote Method Invocation).
If you have control of both ends of the wire, and are thus not constrained to
use some other protocol like HTTP/XMLRPC/CORBA/etc, you might consider using
Foolscap.
Fundamentally, Foolscap allows you to make a python object in one process
available to code in other processes, which means you can invoke its methods
remotely. This includes a data serialization layer to convey the object
graphs for the arguments and the eventual response, and an object reference
system to keep track of which objects you are connecting to. It uses a
capability-based security model, such that once you create a non-public
object, it is only accessible to clients to whom you've given the
(unguessable) FURL. You can of course publish world-visible objects that
have well-known FURLs.
