Commit | Line | Data |
4536f655 |
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. |