src/allmydata/introducer/interfaces.py

   1
   2 from zope.interface import Interface
   3 from foolscap.api import StringConstraint, TupleOf, SetOf, DictOf, Any, \
   4     RemoteInterface
   5 FURL = StringConstraint(1000)
   6
   7 # Announcements are (FURL, service_name, remoteinterface_name,
   8 #                    nickname, my_version, oldest_supported)
   9 #  the (FURL, service_name, remoteinterface_name) refer to the service being
  10 #  announced. The (nickname, my_version, oldest_supported) refer to the
  11 #  client as a whole. The my_version/oldest_supported strings can be parsed
  12 #  by an allmydata.util.version.Version instance, and then compared. The
  13 #  first goal is to make sure that nodes are not confused by speaking to an
  14 #  incompatible peer. The second goal is to enable the development of
  15 #  backwards-compatibility code.
  16
  17 Announcement = TupleOf(FURL, str, str,
  18                        str, str, str)
  19
  20 class RIIntroducerSubscriberClient(RemoteInterface):
  21     __remote_name__ = "RIIntroducerSubscriberClient.tahoe.allmydata.com"
  22
  23     def announce(announcements=SetOf(Announcement)):
  24         """I accept announcements from the publisher."""
  25         return None
  26
  27     def set_encoding_parameters(parameters=(int, int, int)):
  28         """Advise the client of the recommended k-of-n encoding parameters
  29         for this grid. 'parameters' is a tuple of (k, desired, n), where 'n'
  30         is the total number of shares that will be created for any given
  31         file, while 'k' is the number of shares that must be retrieved to
  32         recover that file, and 'desired' is the minimum number of shares that
  33         must be placed before the uploader will consider its job a success.
  34         n/k is the expansion ratio, while k determines the robustness.
  35
  36         Introducers should specify 'n' according to the expected size of the
  37         grid (there is no point to producing more shares than there are
  38         peers), and k according to the desired reliability-vs-overhead goals.
  39
  40         Note that setting k=1 is equivalent to simple replication.
  41         """
  42         return None
  43
  44 # When Foolscap can handle multiple interfaces (Foolscap#17), the
  45 # full-powered introducer will implement both RIIntroducerPublisher and
  46 # RIIntroducerSubscriberService. Until then, we define
  47 # RIIntroducerPublisherAndSubscriberService as a combination of the two, and
  48 # make everybody use that.
  49
  50 class RIIntroducerPublisher(RemoteInterface):
  51     """To publish a service to the world, connect to me and give me your
  52     announcement message. I will deliver a copy to all connected subscribers."""
  53     __remote_name__ = "RIIntroducerPublisher.tahoe.allmydata.com"
  54
  55     def publish(announcement=Announcement):
  56         # canary?
  57         return None
  58
  59 class RIIntroducerSubscriberService(RemoteInterface):
  60     __remote_name__ = "RIIntroducerSubscriberService.tahoe.allmydata.com"
  61
  62     def subscribe(subscriber=RIIntroducerSubscriberClient, service_name=str):
  63         """Give me a subscriber reference, and I will call its new_peers()
  64         method will any announcements that match the desired service name. I
  65         will ignore duplicate subscriptions.
  66         """
  67         return None
  68
  69 class RIIntroducerPublisherAndSubscriberService(RemoteInterface):
  70     __remote_name__ = "RIIntroducerPublisherAndSubscriberService.tahoe.allmydata.com"
  71     def get_version():
  72         return DictOf(str, Any())
  73     def publish(announcement=Announcement):
  74         return None
  75     def subscribe(subscriber=RIIntroducerSubscriberClient, service_name=str):
  76         return None
  77
  78 class IIntroducerClient(Interface):
  79     """I provide service introduction facilities for a node. I help nodes
  80     publish their services to the rest of the world, and I help them learn
  81     about services available on other nodes."""
  82
  83     def publish(furl, service_name, remoteinterface_name):
  84         """Once you call this, I will tell the world that the Referenceable
  85         available at FURL is available to provide a service named
  86         SERVICE_NAME. The precise definition of the service being provided is
  87         identified by the Foolscap 'remote interface name' in the last
  88         parameter: this is supposed to be a globally-unique string that
  89         identifies the RemoteInterface that is implemented."""
  90
  91     def subscribe_to(service_name, callback, *args, **kwargs):
  92         """Call this if you will eventually want to use services with the
  93         given SERVICE_NAME. This will prompt me to subscribe to announcements
  94         of those services. Your callback will be invoked with at least two
  95         arguments: a serverid (binary string), and an announcement
  96         dictionary, followed by any additional callback args/kwargs you give
  97         me. I will run your callback for both new announcements and for
  98         announcements that have changed, but you must be prepared to tolerate
  99         duplicates.
 100
 101         The announcement dictionary that I give you will have the following
 102         keys:
 103
 104          version: 0
 105          service-name: str('storage')
 106
 107          FURL: str(furl)
 108          remoteinterface-name: str(ri_name)
 109          nickname: unicode
 110          app-versions: {}
 111          my-version: str
 112          oldest-supported: str
 113
 114         Note that app-version will be an empty dictionary until #466 is done
 115         and both the introducer and the remote client have been upgraded. For
 116         current (native) server types, the serverid will always be equal to
 117         the binary form of the FURL's tubid.
 118         """
 119
 120     def connected_to_introducer():
 121         """Returns a boolean, True if we are currently connected to the
 122         introducer, False if not."""
 123