Routing

When an entity sends a packet to another entity the destination root entity has to decide where to put the packet next. Either it relays it to a remote entity or delivers it to a local one.

Where packets come from and where they should go to is mainly defined by the three routing variables _source, _target and _context.

Contents of _source, _target and _context

The routing variables can contain any uniform scheme. PSYC nodes SHOULD NOT assume that only psyc: scheme uniforms appear in these variables.

When the uniform scheme matches the psyc: scheme routing is performed as specified in this section.

When the scheme of the uniform in _target is not known the PSYC node MAY choose to forward the packet to a locally connected gateway. When receiving packets from a gateway _source and _context can also contain unknown uniform schemes.

NOTE: The psyc: scheme allows for more fine-grained routing decisions in the PSYC node and the PSYC network in general. This means that PSYC nodes know how to resolve PSYC uniforms to other hostnames and ports and can establish circuits to them to deliver the packet. Other schemes usually only travel between gateways and the PSYC server node they are connected to, no further resolution of the uniforms is done in this case.

Overview of basic routing operations

The basic operations of routing are defined by the presence or absence of the three _source, _context and _target variables. The various multicast strategies build on top of that. So let's first look at the important constellations, then open up a window to future PSYC developments.

Regular Unicast Messages

A regular unicast message uses _source and _target, no _context.

A message with a _source only, is a message to the root entity of the receiving node. (Typically a user requesting the amount of logged in users or similar.)

A message with a _target only, is a message coming from the root entity of the sending node. (Typically a short-lived script or automation like wikinotify, which sends some event notification to a given recipient.)

NOTE: Setting persistent entity variables is invalid for unicast messages in current PSYC. This means you MUST NOT try to apply modifiers (see also Spec:Packet) that modify end-to-end entity variables (eg. with the = operator) in messages without a _context set. Supporting this special case would cause plenty of extra implementation complexity with little advantage, and is therefore reserved for a potential future use. templates MAY still refer to persistent variables of the entity's context, however.

Multicast Messages

This is a message that comes from a context. (for example a chatroom, a user's own presence multicast or some other kind of context) whose recipients are defined by the context subscription mechanism only has the _context routing variable set. The original sender is delivered by _source_relay.

These messages have to be multicast to all members of a context. The general rule is: A multicast message SHOULD travel a physical Spec:Circuit only once.

For this to succeed a PSYC node needs to keep track of who is member of either a local or a remote context. There is a special case with person entities.

NOTE: The term for the manager of context multicasts in psyced is context slave.

Unicast Message for State Signaling

A message with _target and _context is a unicast from the place to a single member. The affected state however is the state of the self-sending _context. This is for example used to bring a new place member's state up to speed with the current conversation.

Future Multipeer Multicasting and Signaling

• A message with _source and _context is reserved for future use (It will probably be used for peer-to-multicast messages, as defined in a future PSYC version).

• A message with all three routing variables _source, _context and _target set is also reserved for future use (It will probably be a unicast from _source to _target, which configures the state between _source and _context. In a peer-to-multicast scenario this is a message that each sending participant unicasts to a new member of the group, given he finds his outgoing state important enough to do that. Other solutions to achieve the same result would be to reassign the state with the next posting, or not to use much state at all.)

Routing Variable Table

Same information again in a graphical style.

All invalid configurations are reserved for future use and only invalid in current PSYC version.

To support these routing rules we define some helper terms like logical source in Spec:Glossary.

Relaying

Some PSYC nodes (usually servers) or entities may provide the ability to relay packets.

Relaying MAY be done by servers which receive packets where the _target variable doesn't address a local entity, then the root entity will relay the packet.

When a packet is relayed it's original _source is moved to the _source_relay variable. The uniform of the relaying entity (either the root entity of a server or some other relaying entity) is then provided in the _source field.

NOTE: Usually PSYC roots limit relaying to trusted entities and sources, like for example Spec:Circuits from localhost.