PsEPR Documentation: Protocol Guide

Loose coupling. Error recovery.

A channel name consists of a naming authority name followed by a hiearchy of channel subdivisions all separated by the character slash ("/"). The "naming authority" is the domain name of the entity managing the top level of the channel space and is used to provide a globally unique top to the hiearchy of channel names.

Some examples of channel names are:

/psepr.org/ns/planetlab/node/planetlab1.nbgisp.com/
/psepr.org/ns/planetlab/nodelist/
/cs.utexas.edu/channels/cities/Austin/

Note that channel names always begin and ends with a slash. There is currently no wildcard'ing but various constructs are reserved for future expansion -- the character "*" and an empty field ("//"), in particular.

The hiearchy of channel names can be used since PsEPR allows subscribing to all of the channels below a certain point in the hiearchy. For instance, getting a lease on the channel /psepr.org/ns/planetlab/node/ will return all of the events on all of the channels named as a subset of that channel (/psepr.org/ns/planetlab/node/planetlab1.nbgisp.com/, etc).

All channel names are "rooted". The leading MUST be present. All channel names also MUST have a slash at the end.

A detailed definition of channel is:

ChannelName ::= "/" ChannelNameAuthority "/" ChannelPart "/"

ChannelNameAuthority ::= ChannelElement

ChannelPart ::= ChannelElement [ "/" ChannelPart ]

ChannelElement ::= 1*(%x21-2e / %x30-3F / %x41-FE )
                  ; any octets that map to the printable
                  ; UTF-8 encoded Unicode 2.0 characters except
                  ; octet '0x2F' (which corresponds to the 
                  ; ASCII character '/').
                

The client must connect to a Jabber server and over time, services will be developed so a client connects to the optimal server. But, as a connection fallback, the initial installation of PsEPR client installs the file /usr/local/planetlab/etc/psepr-servers which contains a list of potential Jabber servers.

This file contains multiple lines with each line of the form:

INAME@ISERVER/IINSTANCE
              

The PsEPR installation guarantees that at least one of the servers listed in this file is operational. A client should walk through the entries in this file in random order until an operating server is discovered.

Once a connection is made to the PsEPR infrastruction, other services with information on connectivity can be consulted for a more optimal connection.

There is a non-XMPP connection that a client can make which is avaiable for the simple sending of events. The client creates a socket connection to the Router and sends a block of XML which contains both the authentication and the event. If the authentication is accepted, the event is routed through PsEPR. If authentication is not accepted, the event is lost and no indication is returned to the sender.

The format of this message is specified in a later section and client libraries will have helper functions like the one in the Java client library .

Events between the client and the router, have the following format:

<message to='REGISTRY@JABBER-SERVER/REGISTRY-INSTANCE'>
    <x seconds="EXPIRATION-SECONDS" xmlns="jabber:x:expire"/>
    <event xmlns="http://psepr.org/xs/event">
      <to>
          <channel>TO-CHANNEL-NAME</channel>
          <service>TO-SERVICE-NAME</service>
          <instance>TO-INSTANCE-NAME</instance>
      </to>
      <distribution>DISTRIBUTION</distribution>
      <from>
          <service>FROM-SERVICE-NAME></service>
          <instance>FROM-INSTANCE-NAME</instance>
      </from>
      <payload xmlns="PAYLOAD-NAMESPACE">
      </payload>
  </event>
</message>
            

The <event> element can include any XML content. The format of the content is specified by the namespace on the <event> element and the ones handled by the PsEPR system are explained below.

Several of the files have distinct values:

General payload.

<message to='REGISTRY@JABBER-SERVER/REGISTRY-INSTANCE'>
    <x seconds="EXPIRATION-SECONDS" xmlns="jabber:x:expire"/>
    <event xmlns="http://psepr.org/xs/event">
      <to>
          <channel>TO-CHANNEL-NAME</channel>
          <service>TO-SERVICE-NAME</service>
          <instance>TO-INSTANCE-NAME</instance>
      </to>
      <distribution>DISTRIBUTION</distribution>
      <from>
          <service>FROM-SERVICE-NAME></service>
          <instance>FROM-INSTANCE-NAME</instance>
      </from>
      <payload xmlns="http://psepr.org/xs/payload">
        XML-DATA
      </payload>
  </event>
</message>
            

A defined payload for a simple attribute/value pair. The bodies of both the field and value elements are text which follows the xml text inclusion rules.

<message to='REGISTRY@JABBER-SERVER/REGISTRY-INSTANCE'>
    <x seconds="EXPIRATION-SECONDS" xmlns="jabber:x:expire"/>
    <event xmlns="http://psepr.org/xs/event">
      <to>
          <channel>TO-CHANNEL-NAME</channel>
          <service>TO-SERVICE-NAME</service>
          <instance>TO-INSTANCE-NAME</instance>
      </to>
      <distribution>DISTRIBUTION</distribution>
      <from>
          <service>FROM-SERVICE-NAME></service>
          <instance>FROM-INSTANCE-NAME</instance>
      </from>
      <payload xmlns="http://psepr.org/xs/payload/attribute">
          <field>ATTRIBUTE-NAME</field>
          <value>ATTRIBUTE-VALUE</value>
          <expire>ATTRIBUTE-EXPIRE</expire>
          <serial>ATTRIBUTE-SERIAL</serial>
      </payload>
  </event>
</message>
            

A client requests to receive events on a channel by sending a lease event to that channel. The lease event specifies that this client wishes to receive events for some period in the future.

A client knows that PsEPR has noticed the lease by a lease message with a LEASE-OPERATION lease with the LEASE-IDENTIFIER if the origional register event appearing on the channel. PsEPR might not grant the whole requested duration. In that case, the lease message that is received will contain the granted duration.

Do note that a client can receive events on a channel before it sees the lease event. The lease event is best used to manage lease duration -- if a lease is not received, the client should renew the lease with another register event.

A client renews a lease by sending another register event. A client can undo a lease by sending a unregister event with the LEASE-IDENTIFIER of the origional lease.

<message to='REGISTRY@JABBER-SERVER/REGISTRY-INSTANCE'>
    <x seconds="EXPIRATION-SECONDS" xmlns="jabber:x:expire"/>
    <event xmlns="http://psepr.org/xs/event">
      <to>
          <channel>TO-CHANNEL-NAME</channel>
          <service>TO-SERVICE-NAME</service>
          <instance>TO-INSTANCE-NAME</instance>
      </to>
      <distribution>DISTRIBUTION</distribution>
      <from>
          <service>FROM-SERVICE-NAME></service>
          <instance>FROM-INSTANCE-NAME</instance>
      </from>
      <payload xmlns="http://psepr.org/xs/payload/lease">
          <identifier>LEASE-IDENTIFIER</identifier>
          <duration>LEASE-DURATION</duration>
          <op>LEASE-OPERATION</op>
          <type>LEASE-MESSAGE-TYPE</type>
      </payload>
  </event>
</message>
            

Clients can send an event by opening up a port on the PsEPR server and sending a block of XML which contains the authenication and the event.

<inputEvent>
  <authentication>
    <passwordAuth>
      <service>JABBER-ACCOUNT</service>
      <password>JABBER-PASSWORD</password>
    </passwordAuth>
  </authentication>
    <oneEvent>
      <event xmlns="http://psepr.org/xs/event">
        <to>
            <channel>TO-CHANNEL-NAME</channel>
            <service>TO-SERVICE-NAME</service>
            <instance>TO-INSTANCE-NAME</instance>
        </to>
        <distribution>DISTRIBUTION</distribution>
        <from>
            <service>FROM-SERVICE-NAME></service>
            <instance>FROM-INSTANCE-NAME</instance>
        </from>
        <payload xmlns="my:payload:namespace">
          XML-DATA
        </payload>
      </event>
    </oneEvent>
</inputEvent>
            

Here are several examples of messages and exchanges.

A service ('pldb) asks for a lease for 900 seconds on the channel /psepr.org/ns/planetlab/list/nodes/:

<message to='psepr_router@jabber.services.planet-lab.org'>
  <x seconds='60' xmlns='jabber:x:expire'/>
  <event xmlns='http://psepr.org/xs/event'>
    <to>
      <channel>psepr.org/ns/planetlab/list/nodes/</channel>
      <service>psepr_router</service>
      <instance></instance>
    </to>
    <from>
      <service>pldb</service>
      <instance>planetlab6.nbgisp.com/list/nodes/</instance>
    </from>
    <payload xmlns='http://psepr.org/xs/payload/lease'>
      <duration>900</duration>
      <intifier>psepr-1104515112</identifier>
      <op>register</op>
      <type>http://psepr.org/xs/payload/pldbdeadbeat</type>
    </payload>
  </event>
</message>
          

The PsEPR registry responds to the lease message with a lease confirmation:

<message 
    from='psepr_registry@jabber.services.planet-lab.org/loudmouth-test-registry'
    to='pldb@jabber.services.planet-lab.org/planetlab6.nbgisp.com/list/nodes/'
    xmlns='jabber:client'>
  <x seconds='60' xmlns='jabber:x:expire'/>
  <event xmlns='http://psepr.org/xs/event'>
    <to>
      <channel>psepr.org/ns/planetlab/list/nodes/</channel>
      <service>psepr_router</service>
      <instance/>
    <to>
    <from>
      <service>pldb</service>
      <instance>planetlab6.nbgisp.com/list/nodes/</instance>
    <from>
    <payload xmlns='http://psepr.org/xs/payload/lease'>
      <duration>900</duration>
      <identifier>psepr-1104515112</identifier>
      <op>lease</op>
      <type>http://psepr.org/xs/payload/pldbdeadbeat</type>
    </payload>
  </event>
</message>
            

As a default, the PsEPR server uses the following port assignments. Check the configuration files, though, since port assignments can always be over-ridden.

The origional design of PsEPR thought that using an existing messaging interface for events would allow leveraging existing tools and applications. XMPP seemed like a good starting point. It didn't work out as well as expected: the existing open source XMPP server implementations either died under heavy load or had features that were too tied to it's instant messaging roots.

The outcome of this initial decision, thought, is that the protocol to access the PsEPR server is XMPP-like. I use the term "XMPP-like" because no attempt was made to make it XMPP compliant. The servers only accept enough XMPP messages to allow some of the existing XMPP client libraries to talk to PsEPR servers. No attempt has been made to do compatability testing so client library implementors should just follow the messages described herein.

It is possible that advances in XMPP standards and implementations may have rendered the basic pub/sub functionality of PsEPR obsolete, PsEPR was designed as a research vehicle for eventing infrastructures. Different semantics for subscription, filtering and routing are all potential extenstions to the basic functions currently implimented in PsEPR.

The XMPP protocol has two classes of messages: 'messages' which are used by PsEPR for event, and 'queries' which are used for authentication.

There are several attributes and elements that XMPP can include in the messages. These are ignored by the PsEPR server and do not create errors.

<iq id="IDENT">
  <query xmlns="jabber:iq:auth">
  </query>
</iq>
              

<iq id="IDENT">
  <query xmlns="jabber:iq:auth">
    <password/>
  </query>
</iq>
              

<iq id="IDENT">
  <query xmlns="jabber:iq:auth">
    <username>USERNAME</username>
    <password>PASSWORD</password>
    <resource>RESOURCE</resource>
  </query>
</iq>
              

<iq id="IDENT">
  <query xmlns="jabber:iq:auth">
    <username>USERNAME</username>
    <resource>RESOURCE</resource>
  </query>
</iq>