Class Tub

Parameters:

• certData - if provided, use it as a certificate rather than generating a new one. This is a PEM-encoded private/public keypair, as returned by Tub.getCertData()
• certFile - if provided, the Tub will store its certificate in this file. If the file does not exist when the Tub is created, the Tub will generate a new certificate and store it here. If the file does exist, the certificate will be loaded from this file.

  The simplest way to use the Tub is to choose a long-term location for the certificate, use certFile= to tell the Tub about it, and then let the Tub manage its own certificate.

  You may provide certData, or certFile, (or neither), but not both.

• options - a dictionary of options that can influence connection connection negotiation. Currently defined keys are:
  • debug_slow: if True, wait half a second between each negotiation response

Overrides: twisted.application.service.MultiService.__init__

Tell this service what its location is: a host:port description of how to reach it from the outside world. You need to use this because the Tub can't do it without help. If you do a s.listenOn('tcp:1234'), and the host is known as foo.example.com, then it would be appropriate to do:

   s.setLocation('foo.example.com:1234')

You must set the location before you can register any references.

Encrypted Tubs can have multiple location hints, just provide multiple arguments. Unauthenticated Tubs can only have one location.

Determine one of this host's publically-visible IP addresses and use it to set our location. This uses whatever source address would be used to get to a well-known public host (A.ROOT-SERVERS.NET), which is effectively the interface on which a default route lives. This is neither very pretty (IP address instead of hostname) nor guaranteed to work (it may very well be a 192.168 'private' address), but for publically-visible hosts this will probably produce a useable FURL.

This method returns a Deferred that will fire once the location is actually established. Calls to registerReference() must be put off until the location has been set. And of course, you must call listenOn() before calling autoSetLocation().

Start listening for connections.

Parameters:

• what (string or Listener instance) - a twisted.application.strports -style description, or a Listener instance returned by a previous call to listenOn.
• options - a dictionary of options that can influence connection negotiation before the target Tub has been determined

Returns:

The Listener object that was created. This can be used to stop listening later on, to have another Tub listen on the same port, and to figure out which port was allocated when you used a strports specification of 'tcp:0'.

Overrides: twisted.application.service.Service.startService

Overrides: twisted.application.service.Service.stopService

Make a Referenceable available to the outside world. A URL is returned which can be used to access this object. This registration will remain in effect (and the Tub will retain a reference to the object to keep it meaningful) until explicitly unregistered, or the Tub is shut down.

Parameters:

• name (string (optional)) - if provided, the object will be registered with this name. If not, a random (unguessable) string will be used.
• furlFile - if provided, get the name from this file (if it exists), and write the new FURL to this file. If 'name=' is also provided, it is used for the name, but the FURL is still written to this file.

Returns: string

the URL which points to this object. This URL can be passed to Tub.getReference() in any Tub on any host which can reach this one.

Add a function to help convert names to Referenceables.

When remote systems pass a FURL to their Tub.getReference(), our Tub will be asked to locate a Referenceable for the name inside that furl. The normal mechanism for this is to look at the table maintained by registerReference() and unregisterReference(). If the name does not exist in that table, other 'lookup handler' functions are given a chance. Each lookup handler is asked in turn, and the first which returns a non-None value wins.

This may be useful for cases where the furl represents an object that lives on disk, or is generated on demand: rather than creating all possible Referenceables at startup, the lookup handler can create or retrieve the objects only when someone asks for them.

Note that constructing the FURLs of these objects may be non-trivial. It is safe to create an object, use tub.registerReference in one invocation of a program to obtain (and publish) the furl, parse the furl to extract the name, save the contents of the object on disk, then in a later invocation of the program use a lookup handler to retrieve the object from disk. This approach means the objects that are created in a given invocation stick around (inside tub.strongReferences) for the rest of that invocation. An alternatve approach is to create the object but *not* use tub.registerReference, but in that case you have to construct the FURL yourself, and the Tub does not currently provide any support for doing this robustly.

Parameters:

• lookup - a callable which accepts a name (as a string) and returns either a Referenceable or None. Note that these strings should not contain a slash, a question mark, or an ampersand, as these are reserved in the FURL for later expansion (to add parameters beyond the object name)

Acquire a RemoteReference for the given SturdyRef/URL.

The Tub must be running (i.e. Tub.startService()) when this is invoked. Future releases may relax this requirement.

Returns:

a Deferred that fires with the RemoteReference

Establish (and maintain) a connection to a given PBURL.

I establish a connection to the PBURL and run a callback to inform the caller about the newly-available RemoteReference. If the connection is lost, I schedule a reconnection attempt for the near future. If that one fails, I keep trying at longer and longer intervals (exponential backoff).

I accept a callback which will be fired each time a connection attempt succeeds. This callback is run with the new RemoteReference and any additional args/kwargs provided to me. The callback should then use rref.notifyOnDisconnect() to get a message when the connection goes away. At some point after it goes away, the Reconnector will reconnect.

The Tub must be running (i.e. Tub.startService()) when this is invoked. Future releases may relax this requirement.

I return a Reconnector object. When you no longer want to maintain this connection, call the stopConnecting() method on the Reconnector. I promise to not invoke your callback after you've called stopConnecting(), even if there was already a connection attempt in progress. If you had an active connection before calling stopConnecting(), you will still have access to it, until it breaks on its own. (I will not attempt to break existing connections, I will merely stop trying to create new ones). All my Reconnector objects will be shut down when the Tub is stopped.

Usage:

def _got_ref(rref, arg1, arg2):
    rref.callRemote('hello again')
    # etc
rc = tub.connectTo(_got_ref, 'arg1', 'arg2')
...
rc.stopConnecting() # later

__provides__

Value:

<zope.interface.declarations.ClassProvides object at 0x873572c>