This part of the specification is frozen and should not change any further in this version.
Contents |
Multicast Contexts
PSYC implements multicasting to deliver messages, events and information in general from one to multiple recipients. Contexts provide a semantic model to provide this functionality. Entities usually provide one or more contexts, which other entities can subscribe to.
Subscribing to an entity's context means that you want to receive messages and events related to that entity.
Subscribing a context (a multicast sender) whose data interests you is a fundamental operation. To protect yourself from SPIM it is necessary, that close to all communications have been created by mutual agreement. Before a sender can multicast information to you, you shall request entry, and it shall grant it to you.
Concepts
- A subscriber (an entity) would like to enter a context to receive its updates.
- Entities like persons and places can manage multiple contexts in order to multicast group communication, presence data or any other kind of updates or many-to-many exchanges.
- Contexts can be organized in a hierarchical manner (we speak of subcontexts or channels in that case). You can read about Channel Inheritance for more information on this.
- Multicast is the one-to-many routing operation of PSYC with optimized distribution, see also Spec:Routing.
An entity stays subscribed until one of the following happens:
- The entity unsubscribes
- A ping to it remains unresponded
- The circuit is lost or the remote server reports that the recipient could not be reached
- The context decides to remove (unsubscribe/kick) the entity for arbitrary reasons
Depending on the needs of the context, the context MAY choose to mark the recipient as currently unreachable (instead of instantly unsubscribing her) and remove her from the multicast tree, but also to be able to
- retry some time later
- simplify the repair process if the person wants to return – not have to go through subscription process again, very useful for friend management that might otherwise need user interaction
- redirect to a different UNI or UNL, if more than one was provided at subscription time.
Context interface
This section describes the interface of a context. Entities can offer this interface to let other entities subscribe to them.
Subscriber Requesting Entry
The following request methods are the basic set of methods that an entity can use to request becoming part of a context.
Subscribing to a context
This requests the membership of a context.
Required Variables in the packet:
- _target — the entity you want to subscribe to
- _tag — a tag identifying your request
- _source — optional, your UNL
Method name: _request_context_enter
NOTE: As PSYC nodes know which contexts their entities subscribed, they usually also know when they need to synchronize with the state of a newly entered context. To accomplish this, it is recommended that the PSYC node adds a "?" modifier to the outgoing _request_context_enter, which was initiated by the entity that wants to enter. This is only necessary when the node isn't already hosting other members of the same context, thus is already holding a copy of the current state.
Example
A client requesting subscription:
| :_target psyc://server.tld/@place :_tag 284232 _request_context_enter |
Informing other subscribers
If the place decides to inform people about new members, it multicasts a _notice_context_enter to all occupants (including the newly joined entity, as it also informs the joined entity, that others were informed about her arrival). The person who joined is kept in _source_relay in this configuration.
Required Variables:
- _context — The uniform of the sending context
- _source_relay — the uniform of the new entity
Method name: _notice_context_enter
This message can only be distinguished from other people joining the channel by looking at the _source_relay routing variable.
Example
A place informing all subscribers (including the new one) about the new member:
| :_context psyc://server.tld/@place :_source_relay psyc://someip:-3457/ _notice_context_enter |
Confirming a subscription request
When the request succeeds an _echo_context_enter is sent back to the subscription request as a reply. After the response is sent, the entered entity has (logically) become a member of the context. The person who joined is the _target, obviously.
Required Variables:
- _source — the sending entity
- _target — the sender of the request subscription
- _tag_relay — the tag from the original request
- _interface — optional, used to describe the interface the context provides
Method name: _echo_context_enter
The _source variable contains the address of the context you are a member of now.
When receiving a _echo_context_enter you MUST check whether it is in response to a former request or you trust the context you enter enough. This check is required to prevent others from forcing you into a SPIM context.
State synchronization MAY be included in the _echo_context_enter reply (for example when the requesting entity asked for a sync, or when the context believes the state needs to be resent). But note that the entering entity is NOT a member at the time of replying to the request. The additional state update MAY alternatively be as a separate packet (potentially without method) but it would not be sent in the _notice_context_enter message as that is going to all recipients and all multicast packets are identical.
Example
A place confirming a subscription request:
| :_source psyc://server.tld/@place :_target psyc://someip:-3457/ :_tag_relay 284232 _echo_context_enter |
Subscriber requesting leave
Leaving a context
This method asks the context to let you leave it, even though this is formally a polite request, it MUST NOT be denied by the context.
Required Variables:
- _target — the context from which the entity wants to unsubscribe
- _tag — a random tag
- _source — optionally, the uniform of the sender.
Method name: _request_context_leave
The subscriber implementation MUST NOT disturb his human user with further multicasts from the sender, but it MAY report abuse where appropriate.
Example
| :_target psyc://server.tld/@place :_tag 284232 _request_context_leave |
Confirming a request for unsubscription
Upon receiving a request for unsubscription, a context MUST confirm the request with an _echo_context_leave.
Required Variables:
- _target — the requesting uniform
- _source — the sending context
- _tag_relay — the original _tag from the request
Method name: _echo_context_leave
Example
| :_source psyc://server.tld/@place :_target psyc://someip:-3457/ :_tag_relay 284232 _echo_context_leave |
Telling others about leaving
- When unicast from a context, this method informs the member that she left the context.
- When multicast from a context, it informs all members that the member has left the context.
- When unicast to a context, this methods signals an unpolite end of the membership. No confirmation is needed then. (REMARK: Unfortunately some IRC gateways require this to properly emulate IRC behaviour)
Required Variables when context is sender:
- _context — the sending context
- _source_relay — the leaving member
Required Variables when context is receiver:
- _target — the receiving context
- _source — optional, the senders uniform
Method name: _notice_context_leave
Example
A multicast notice that a member left us:
| :_context psyc://server.tld/@place :_source_relay psyc://someip:-3457/ _notice_context_leave |
_warning, _error & _failure
You may also receive warnings, errors or failures stopping the transaction flow, both because there may be a problem or simply because the context doesn't like your face. See the respective chapters in the specification for appropriate candidates.
The _tag_relay included in these messages helps you take appropriate action.
Custom Commands
Custom commands provided by the context (see the psyced documentation Create Places for examples) may have collateral effects of entering or leaving channels. This is necessary to implement complex functions like a newscast with a preferences pop-up box. By the choice of preferences the appropriate channels are selected as to maintain optimized multicasting.