Design/portal_notes

   1
   2                        Stem::Portal Design Notes
   3
   4 The Stem::Portal class supports the transmission of Stem Messages
   5 between Stem Hubs. Portals are based on sockets and are configured very
   6 similarly to a Socket with host and port attributes. Also a Portal can
   7 be designated a TCP/IP server or a client. Once two Hubs are connected
   8 via their Portals, they communicate peer to peer in full duplex mode.
   9
  10 Portals are sent a Message to transmit by the Stem::Msg delivery
  11 subsystem. The Message is converted to a byte stream format and written
  12 to the Portal socket. When a Portal reads a byte stream Message from its
  13 socket, it converts it back to an internal Message and sends it to the
  14 Stem::Msg class for delivery.
  15
  16 When a Stem Portal connects to another, they both exchange a special
  17 'register' type Stem Message. This message when received by a Portal is
  18 trapped and never sent for delivery to the Stem::Msg subsystem. The
  19 'register' message contains the Hub name of the remote Portal. This name
  20 is then stored in a registry private to the Portal class. It is used by
  21 the Stem::Msg delivery subsystem to look up which Portal to use to send
  22 out a remote message. You can see the current state of the Portal
  23 registry by sending a 'status' command message to the Portal class. This
  24 is easily done from the terminal (if the Hub has Stem::TtyMsg
  25 configured) with the command:
  26
  27         :port status
  28
  29 If you put a Hub name before the :, you will get the Portal registry
  30 status of that Hub.
  31
  32 A special alias is set up for a client Portal that is the first one
  33 configured in a Hub. It is given the alias DEFAULT and this Portal
  34 becomes the default destination for any Messages that aren't delivered
  35 locally. So if a Stem Message has no Hub in its 'to' address and the
  36 Cell name is not registered locally, it is sent to the DEFAULT Portal
  37 and hence to the Hub it is connected to. This is very similar to the
  38 default route in IP routers like the routed daemon. A new feature (to be
  39 implemented soon) will be to allow the setting of the DEFAULT Portal at
  40 configuration or run time.
  41
  42 Security of Hub to Hub communications are handled by the Portal
  43 Cells. There are two designs in progress, one which pipes over ssh to
  44 the other Hub, and an internal encryption module which will perform the
  45 same functions but be more efficient.