Foolscap

This is a minor bugfix release to help Tahoe-LAFS.

It depends upon a newer version of I2P, which should handle Tahoe storage
servers that listen on I2P sockets (the Tahoe executable makes an outbound
connection to the local I2P daemon, however it then accepts inbound TLS
connections on that same socket, which confuses the TLS negotiation because
both sides appear to be "clients", and TLS requires exactly one "client" and
one "server").

It also fixes a minor Tub shutdown behavior to let unit tests work more
reliably. 274

This is a minor release to improve compatibility with Twisted and I2P.

In this release, the Foolscap test suite no longer uses several deprecated
and/or internal Twisted attributes, so it should pass cleanly on the next
release of Twisted (which will probably be named Twisted-17.0.0).

In addition, the I2P connection handler was enhanced to let applications pass
arbitrary kwargs through to the underlying "SAM" API.

Finally connection-status error messages should be slightly cleaner and
provide more useful information in the face of unrecogized exceptions.

Connection Status Reporting

This release adds an object named `ConnectionInfo`, which encapsulates
information about a connection (both progress while being established, and
the outcome once connected). This includes which connection hint was
successful, what happened with the other hints, which handlers were used for
each, and when the connection was made or lost. To get one of these, use
`tub.getConnectionInfoForFURL(furl)` any time after `getReference()` is
called, or `rref.getConnectionInfo()` after it resolves. 267

It also adds `ReconnectionInfo`, a similar object for Reconnectors. These
capture the state of reconnection process (trying, established, waiting), and
will provide a `ConnectionInfo` for the most recent (possibly successful)
connection attempt. The API is `reconnector.getReconnectionInfo()`. 268

For details, see "Connection Progress/Status" and "Reconnector Status" in
`doc/using-foolscap.rst`.

Connection Handler API Changes

To support `ConnectionInfo`, the Connection Handler API was changed.

The one backwards-incompatible change was that the `hint_to_endpoint()`
method now takes a third argument, to update the status as the handler makes
progress. External handler functions will need to be modified to accept this
new argument, and applications which use them should declare a dependency
upon the latest Foolscap version, to avoid runtime breakage.

Several backwards-compatible changes were made too: handlers can provide a
`describe()` method (which feeds `ConnectionInfo.connectionHandlers`), and
they can now set a special attribute on any exception they raise, to further
influence the status string.

In addition, the `tor.control_endpoint_maker()` handler now accepts an
optional second argument, which causes the maker function to be called with a
additional `update_status` argument. This backwards-compatible change allows
the maker function to influence the `ConnectionInfo` status too.

The Tor connection handler was enhanced to report distinct statuses for the
different phases of connection: launching a new copy of Tor, connecting to an
existing Tor daemon, etc.

Minor Fixes

Improvements

The TCP connection-hint handler can now accept square-bracket-wrapped IPv6
addresses in colon-hex format. You can produce FURLs with such hints by doing
this:

tub.setLocation("tcp:[2001:0DB8:f00e:eb00::1]:9900")

Foolscap Tubs have been using the IPv6-capable `HostnameEndpoint` since

Improvements

The `tor.socks_port()` handler was replaced by `tor.socks_endpoint()`, which
takes an Endpoint object (just like `tor.control_endpoint()` does). This
enables applications to speak SOCKS to the Tor daemon over e.g. a Unix-domain
socket. The `tor.socks_port()` API was removed, so applications using it must
upgrade. 265

The `allocate_tcp_port()` utility function would occasionally return ports
that were in use by other applications, when those applications bound their
own port to the loopback interface (127.0.0.1). allocate_tcp_port should no
longer do this.

Improved Tor Connection Handler

The `tor.control_endpoint` connection handler now properly handles the
config.SocksPort response provided by the debian Tor daemon (and possibly
others), which included a confusing unix-domain socket in its response.

The `tor.socks_port` handler was changed to accept both hostname and port
number. Using anything but "localhost" or "127.0.0.1" is highly discouraged,
as it would reveal your IP address to (possibly hostile) external hosts. This
change was made to support applications (e.g. Tahoe-LAFS) which accept
endpoint strings to configure socks_port, but then parse them and reject
anything but TCP endpoints (to match Foolscap's current limitations). Such
applications ought to warn their users to use only localhost.