The Elko Presence Server Protocols

The Presence Server

The Presence Server is an Elko server that keeps track of the context presence (and, optionally, the physical position) of users connected to the various Context Servers. Context Servers may subscribe on their users' behalf to be notified about changes in other users' status, with these notifications being distributed according to interests derived from the subscribing users' social graphs. The Presence Server in turn gets social graph information via an external interface that allows applications to provide their own abstractions for social graph connectivity.

The Presence Server can also act as a relay point for propagating messages to users according to application-defined criteria, such as external identifiers, physical position, or social graph connectivity. These messages may originate from within the complex of Context Servers or from external event feeds.

A Presence Server understands two different JSON message protocols. These correspond to the two kinds of actors who may wish to communicate with a Presence Server: clients (usually Context Servers) providing and subscribing to presence information, and administrators. Each of the ports that a Presence Server listens for connections on can be configured to support either or both of these protocols.

Each of these protocols is associated with a particular object ref to which messages should be addressed:

client for clients providing and seeking presence information.
admin for administrator messages.

Common Protocols

While there are two different message protocols, they share a common set of messages pertaining to connection housekeeping. These messages may be targeted at either of the two protocol objects described above.

auth


 → { to:REF, op:"auth", auth:?AUTHDESC, label:?STR}

This message begins a new session with the Presence Server, providing whatever authorization credentials as may be appropriate (according to the Presence Server's server configuration) to gain access to services.

An auth message must be the first message sent to client, or admin on any new connection to the Presence Server. Any other message to these objects will result in immediate termination of the connection.

If the auth operation fails, the connection will be terminated by the Presence Server. Otherwise, the client is thereafter free to send messages according to the protocol of the REF that was authorized.

auth is a bundle of authorization information, as described below. The specific authorization information that is relevant depends on the configuration of the Presence Server server port being connected to. If the auth parameter is omitted, an uncontrolled access in open mode is assumed.
label is an optional label for the connection. This will be used in server log entries for debugging purposes and for identifying the connection in administrative requests.

Authorization information

The auth parameter of the auth message describes a bundle of authorization information to authorize access. Its general form is:


    { type:"auth", mode:STR, code:?STR, id:?STR }

where:

mode is the requested authorization mode. Currently recognized authorization modes are "open" and "password". Other modes may be relevant in the future or when talking to other kinds of servers.
code is an authorization code, whose meaning varies depending on the authorization mode. In the case of open mode, it is irrelevant and should not be provided. In the case of password mode, it is a password string.
id is an optional identity string, whose meaning varies depending on the authorization mode. In the case of open mode, it is irrelevant and should not be provided. In the case of password mode, it may or may not be relevant depending on the configuration.

disconnect


 → { to:REF, op:"disconnect" }

This message requests the server to terminate its connection to the sender. The connection to the server is broken.

ping


 → { to:REF, op:"ping", tag:?STR }

This message tests connectivity to the server.

tag is an optional string that may be anything of the client's choosing.

If the message is successfully received by the server, it will reply with:


 ← { to:REF, op:"pong", tag:?STR }

tag echoes the tag from the ping message, if there was one, or will be omitted if the original ping also omitted it.

debug


 → { to:REF, op:"debug", msg:STR }

This message delivers debugging information to the server. If the server is configured to permit this, the string given in the msg parameter will be written to the server's log. If the server is not configured to permit this, this message will simply be ignored.

Client Protocol

The Presence Server client protocol is used by a Context Server in order both to inform the Presence Server of changes in the status of users hosted by that Context Server and to request information about the status of users hosted by other Context Servers.

user


 → { to:"client", op:"user", context:CONTEXTREF_STR,
          user:USERREF_STR, on:BOOL }

This message informs the Presence Server of a user arriving in or departing from a context hosted by the sender.

where:

context is the ref of the context that the user entered or exited.
user is the ref of the user who entered or exited.
on is a flag that is true the user entered, false if the user exited.


 → { to:"client", op:"subscribe", context:STR,
          domains:?[STR], visible:?BOOL }

This message requests a subscription to notifications about changes in users' presence status. This subscription is requested on behalf of users in some context hosted by the requestor.

where:

context is the ref of a context (hosted by the sender) to which notifications should be sent when the presence status of "users of interest" changes. "Users of interest" are any users in the domain-specific social graphs of users currently in the named context.
domains is an optional array of the names of social graph domains of interest. The set of available social graph domains is application-specific, but might represent abstractions such as friends, enemies, allies, etc. If omitted, no notification subscriptions are actuall generated and this message serves only to update the visibility status of the named context.
visible is an optional boolean flag indicating whether users in the named context are to be considered visible to users outside the context. If true, users in the context are considered present. If false, it is as if user in the context are not online at all. If omitted, this flag defaults to true.

For example, the message:


   { to:"client", op:"subscribe", context:"ctx-foo", domain:["friends"] }

would be a request to be notified about changes in the presence status of the friends of users in the context ctx-foo.

When a subscription is first created, the Presence Server immediately sends notification messages to the subscribing Context Server updating it about any now relevant presence information. Thereafter, any time a user enters or leaves a context on one of the constellation of Context Servers connected to the Presence Server, one or more notifications may be generated announcing this information to interested parties. The form of these notifications is described in detail in the section Notifications below.

unsubscribe


 → { to:"client", op:"unsubscribe", context:STR }

This message requests the Presence Server to cancel a notification subscription established by an earlier subscribe request.

where:

context is the context ref of the context that is no longer interested in receiving presence status updates for its users. The indicated context is also then considered to no longer be visible.

Notifications

As the presence of users in different contexts on different users changes, the Presence Server sends notification messages to the various Context Servers informing them. There are two different notification messages:

utog


 ← { to:"client", op:"utog", user:USER_REF, ctx:CONTEXT_REF,
          on:BOOL, togroup:[DOMAIN_DESC] }

This message, "user to group", informs a group of users about the change in presence status of a single user.

user is the user ref of the user whose presence status has changed.
ctx is the contet ref of the context that the indicated user has entered or left
on is a boolean flag that, if true, indicates that the user entered the context (and is now online), and, if false, indicates that the user has exited the context (and is now offline).
togroup is an array of descriptors that indicates what users need to be informed of this event. There is one element in this array for each relevant social graph domain.

Each domain descriptor takes the form:


 { domain:STR, who:[CTX_DESC] }

where:

domain is the name of the social graph domain being described.
who is an array of descriptors listing the users, by context, who should be informed. There is one entry in this array of each context containing users to be notified.

Each context descriptor in turn takes the form:


 { ctx:CONTEXT_REF, users:[USER_REF] }

where:

ctx is the context ref of a context containing users to be informed.
users is an array of user refs of users in the given context who should be notified.

gtou


 ← { to:"client", op:"gtou", touser:USER_REF,
          ctx:CONTEXT_REF, group:[DOMAIN_DESC] }

This message, "group to user", informs a user about the presence of a group of other users.

touser is the user ref of the user who is being notified.
ctx is the context ref of the context in which the user is being notified (since different contexts may subscribe to different social graph domains).
group is an array of descriptors that indicate which users are present and where. There is one element of this array for each relevant social graph domain.

Each domain descriptor takes the form:


 { domain:STR, friends:[FRIEND_DESC] }

where:

domain is the name of the social graph domain being described.
friends is an array of descriptors listing the presences of other users. There is one entry in this array for each user whose presence is being described.

Each friend descriptor in turn takes the form:


 { user:USER_REF, ctx:CONTEXT_REF }

where:

user is the user ref of a user in the social graph of the user being notified (labelled here a "friend" for descriptive convenience, even though a given social graph domain can actually encode any sort of relationship, not just friendship).
ctx is the context ref of the context in which the friend is present. Note that unlike the utog notification, there is no online vs. offline presence indicator, as this notification is only ever used to describe users who are online.

Admin Protocol

The Presence Server admin protocol is used to administer the Presence Server itself.

dump


 → { to:"admin", op:"dump", depth:INT, user:?STR }

This message requests the Presence Server to provide a dump of its current set of known presence information to the requesting administrator.

where:

depth indicates the depth of detail to provide (see below).
user optionally limits the scope of the information dumped to presence information concerning the particular named user.

The Presence Server will reply with a message of the form:


 ← { to:"admin", op:"dump", numusers:INT,
          numpresences:INT,
          users:[USERDUMP] }

where:

numpresences is the total number of active user presenences currently being tracked by the Presence Server.
numusers is the number unique users whose presences are currently being tracked.
users is an array of user dump descriptors, each of which describes one user. This will only be provided if the value of the depth parameter was greater than 0.

The user dump descriptor takes the form:


 { user:STR, pres:[STR], conn:[FRIENDSDUMP] }

where:

user is the ref of the user whose presence information is being described.
pres is an array of the refs of the contexts in which the indicated user is currently present. This information is only provided if the depth parameter is greater than 1.
conn is is an array of social graph connection information for the indicated user, with one element for each social graph domain for which there is at least one user present who is connected to the indicated user by the graph. This information is only provided if the depth parameter is greater than 2.

The friends dump descriptor takes the form:


 { domain:STR, friends:[USERREF_STR] }

where:

domain is the name of the social graph domain.
friends is an array of the refs of other users connected to the user being dumped via the named social graph, who currently have some presence.

reinit


 → { to:"admin", op:"reinit" }

This message instructs the Presence Server to reinitialize itself.

shutdown


 → { to:"admin", op:"shutdown", kill:?BOOL }

This message instructs the Presence Server to shut down.

where:

kill is an optional flag that if true orders an abrupt termination. Normally, a server will empty its message queues, checkpoint any active state, and perform an orderly shutdown. However, if the kill flag is true, it will exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.

Elko: Presence Server Protocols

The Elko Presence Server Protocols

The Presence Server

Common Protocols

auth

Authorization information

disconnect

ping

debug

Client Protocol

user

subscribe

unsubscribe

Notifications

utog

gtou

Admin Protocol

dump

reinit

shutdown