JEP-0163: Personal Eventing Protocol

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Kevin Smith

Email: kevin@kismith.co.uk
JID: kevdadrum@jabber.ex.ac.uk

1. Introduction

2. Concepts and Approach

2.1. Every Account a Pubsub Service

2.2. One Node Per Namespace

2.3. One Publisher Per Node

2.4. Smart Defaults

2.5. Use Presence

3. Service Discovery

4. Publisher Use Cases

4.1. Creating a Node

4.2. Publishing an Item

4.3. Sending the Last Published Item

5. Subscriber Use Cases

5.1. Discovering Nodes

5.2. Subscribing to a Node

6. Recommended Defaults

7. Implementation Notes

7.1. Generating Notifications

7.2. Roster States

8. Security Considerations

9. IANA Considerations

10. Jabber Registrar Considerations

10.1. Protocol Namespaces

10.2. Service Discovery Category/Type

11. XML Schema

Notes

Revision History

2.1 Every Account a Pubsub Service

When a user creates an instant messaging and presence account (or has an account provisioned) at a Jabber server, that account should have associated with it a virtual pubsub service. This greatly simplifies the task of discovering the personal pubsub nodes associated with the account owner, since the root pubsub node simply is the account owner's bare JID (<node@domain.tld>). This assumption also simplifies publishing and subscribing.

2.2 One Node Per Namespace

To further simplify matters, we assume that there is only one publish-subscribe node associated with any given payload type (XML namespace) associated with the owner-publisher. For example, there is one pubsub node for User Geolocation [4], one node for User Tune [5], one node for User Mood [6], and so on. This simplifies discovery, publishing, and subscribing.

2.3 One Publisher Per Node

There is no need for multiple publishers to a personal eventing service, since by definition the service generates information associated with only one entity. The owner-publisher for every node is the bare JID of the account owner.

2.4 Smart Defaults

Most pubsub configuration options and metadata are not needed for personal eventing. Instead, servers should offer smart defaults to simplify node creation and management.

2.5 Use Presence

Although generic publish-subscribe service do not necessarily have access to presence information about subscribers, personal eventing services are closely integrated with presence, since each instant messaging and presence account simply is a virtual publish-subscribe service and the recommended access models are "presence" and "roster" (both of which involve presence subscriptions in XMPP instant messaging and presence systems). This presence information can be used to make notifications more intelligent, thus simplifying the task of developing compliant clients (see Protocol Design Guidelines [7]).

<iq from='juliet@capulet.com/balcony'
    to='capulet.com'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  

<iq from='capulet.com'
    to='juliet@capulet.com/balcony'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='pubsub' type='pep'/>
    <feature var='http://jabber.org/protocol/pubsub'/>
    <feature var='http://jabber.org/protocol/pubsub#pep'/>
    <feature var='http://jabber.org/protocol/pubsub#default_access_model_presence'/>
    ...
  </query>
</iq>
  

4.1 Creating a Node

First, the account owner creates the node.

Example 3. Account owner creates node

<iq type='set' id='create1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/mood'/>
    <configure/>
  </pubsub>
</iq>
    

There are several things to note about this node creation request:

1. Because the account owner's server supports PEP, no 'to' address is needed.
2. Following the principle of "one node per namespace", the node name is "http://jabber.org/protocol/mood".
3. Following the principle of "smart defaults", the PEP service has a default access model of "presence" so that the <create/> element does not need to include an 'access' attribute.
4. Following the principle of "smart defaults", the creation request contains an empty <configure/> child to denote that default node configuration is requested.

If no error occurs (see JEP-0060 for error scenarios), the server acknowledges success.

Example 4. Server returns result

<iq type='result' id='create1'/>
    

The value of the 'access' attribute SHOULD be "presence" or "roster" for PEP nodes but MAY be "open" (i.e., the value SHOULD NOT be "authorize" or "whitelist" since maintenance of such nodes requires interaction on the part of the node owner). The default access model for PEP nodes MUST be "presence" for IM servers but MAY be something other than "presence" for other PEP service types (e.g., non-IM servers).

If the account owner desires a roster access model for a node, it MUST specify that in the creation request:

Example 5. Account owner creates roster access node

<iq type='set' id='create-roster-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/geoloc'/>
    <configure access='roster'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        <field var='pubsub#roster_groups_allowed'>
          <option><value>friends</value></option>
        </field>
      </x>
    </configure>
  </pubsub>
</iq>
    

If the account owner desires an open access model for a node, it MUST specify that in the creation request:

Example 6. Account owner creates open access node

<iq type='set' id='create-open-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/mood'/>
    <configure access='open'/>
  </pubsub>
</iq>
    

4.2 Publishing an Item

Next, the account owner publishes an item to the node.

Example 7. Account owner publishes item

<iq type='set' id='pub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </publish>
  </pubsub>
</iq>
  

If no error occurs (see JEP-0060 for error scenarios), the server acknowledges success.

Example 8. Server returns result

<iq type='result' id='pub1'/>
    

The notification (with payload) is then delivered to all subscribers (see the Generating Notifications section of this document regarding proper generation of the 'to' address):

Example 9. Server generates notifications

<message from='juliet@capulet.com/balcony'
         to='romeo@montague.net/home'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </items>
  </event>
</message>

.
.
.
    

The server MUST set the 'from' address on the notification to the full JID (<node@domain.tld/resource>) of the publishing resource (in the previous example, "juliet@capulet.com/balcony"). This enables the subscriber's client to differentiate between information received from each of an account owner's resources (for example, different resources may be in different places and therefore may need to specify distinct geolocation data). Naturally, if there is only one active resource for the account owner, the subscriber's client can safely ignore the resource.

4.3 Sending the Last Published Item

As described below, a PEP service MUST send the last published item to all new subscribers. In addition, a PEP service MUST send the last published item to all newly-available resources for each subscriber. (Both of these behaviors essentially mimic the functionality of presence as defined in XMPP IM.)

Example 10. Subscriber sends presence from newly-available resource

<presence from='romeo@montague.net/orchard'/>
    

Example 11. Subscriber's server sends presence from newly-available resource to publisher's bare JID (i.e., PEP service)

<presence from='romeo@montague.net/orchard' to='juliet@capulet.com'/>
    

Example 12. PEP service sends last published item to newly-available resource

<message from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

5.1 Discovering Nodes

Node discovery is made easy since there is only one node per namespace. The potential subscriber may send a service discovery items request to the bare JID to discover all active pubsub nodes.

Example 13. Subscriber queries bare JID

<iq type='set' id='disco1' from='romeo@montague.net/home' to='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
    

Subject to access restrictions as described in JEP-0030, the account owner's server would then return a list of all pubsub nodes:

Example 14. Servers returns list of pubsub nodes

<iq type='result' id='disco1' to='romeo@montague.net/home' from='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/mood'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/activity'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/geolocation'/>
  </query>
</iq>
    

Alternatively, the potential subscriber may send a disco#info request to the specific node of interest:

Example 15. Subscriber queries specific node

<iq type='set' id='disco2' from='romeo@montague.net/home' to='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='http://jabber.org/protocol/mood'/>
</iq>
    

The account owner's server would then return information about the node (if it exists) or an <item-not-found/> error if the node does not exist:

Example 16. Servers returns node info

<iq type='result' id='disco2' to='romeo@montague.net/home' from='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#items'
         node='http://jabber.org/protocol/mood'>
    <identity category='pubsub' type='leaf'/>
    <feature var='http://jabber.org/protocol/pubsub'/>
  </query>
</iq>
    

5.2 Subscribing to a Node

In order to subscribe, a contact sends a subscription request to the account owner's bare JID (<node@domain.tld>) and specifies the desired node:

Example 17. Contact subscribes to a node

<iq type='set'
    from='romeo@montague.net/home'
    to='juliet@capulet.com'
    id='sub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='http://jabber.org/protocol/mood' jid='romeo@montague.net'/>
  </pubsub>
</iq>
    

The following scenarios are possible:

1. If the access model is "presence", the server MUST verify that the full JID of the 'from' address (or the bare JID portion of the full JID) has a presence subscription of type "both" or "from" in the account owner's roster. If so, the server SHOULD allow the entity to subscribe; if not, the server MUST disallow the subscription request.
2. If the access model is "roster", the server MUST verify that the full JID of the 'from' address (or the bare JID portion of the full JID) has a presence subscription of type "both" or "from" in the account owner's roster and is in the specified roster group. If so, the server SHOULD allow the entity to subscribe; if not, the server MUST disallow the subscription request.
3. If the access model is "open", the server SHOULD allow the entity to subscribe.

The only exception foreseen to the SHOULD requirements in the foregoing scenarios is the enforcement of local privacy and security policies as specified more fully in the Security Considerations section of this document. (In addition, a service MUST always allow the account owner to subscribe and to retrieve items.)

If no error occurs (see JEP-0060 for error conditions related to subscription requests), the server shall allow the subscription and return an IQ-result:

Example 18. Server allows subscription

<iq type='result'
    from='juliet@capulet.com'
    to='romeo@montague.net/home'
    id='sub1'/>
    

The service then MUST send the last published item to the new subscriber:

Example 19. Server sends last published item

<message from='juliet@capulet.com/balcony' to='romeo@montague.net' type='headline' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

7.1 Generating Notifications

If a PEP service has presence information about a subscriber, it MUST send one notification to the full JID (<node@domain.tld/resource>) of each of the subscriber's available resources, except for those that have specified a non-negative presence priority.

If a PEP service does not have presence information about a subscriber, it MUST send one notification only, addressed to the bare JID (<node@domain.tld>) of the subscriber.

7.2 Roster States

In order to ensure coherency for nodes of type "presence" and "roster", a PEP service SHOULD recalculate access controls whenever a roster item is modified (e.g., when a subscription request is approved or when the item is moved to a new roster group). If the modification results in a loss of access, a service MUST cancel the entity's subscription and MAY send a message to the (former) subscriber informing the entity of the cancellation.

10.1 Protocol Namespaces

The Jabber Registrar [11] shall include 'http://jabber.org/protocol/pubsub#pep' in its registry of protocol namespaces.

10.2 Service Discovery Category/Type

The Jabber Registrar includes a category of "pubsub" in its registry of Service Discovery identities; as a result of this JEP, the Registrar shall include an additional type of "pep".

The registry submission is as follows:

<category>
  <name>pubsub</name>
  <type>
    <name>pep</name>
    <desc>
      A personal eventing service that supports the 
      publish-subscribe subset defined in JEP-0163.
    </desc>
    <doc>JEP-0163</doc>
  </type>
</category>
    

1. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.

2. JEP-0119: Extended Presence Protocol Suite <http://www.jabber.org/jeps/jep-0119.html>.

3. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.

4. JEP-0080: User Geolocation <http://www.jabber.org/jeps/jep-0080.html>.

5. JEP-0118: User Tune <http://www.jabber.org/jeps/jep-0118.html>.

6. JEP-0107: User Mood <http://www.jabber.org/jeps/jep-0107.html>.

7. JEP-0134: Protocol Design Guidelines <http://www.jabber.org/jeps/jep-0134.html>.

8. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

9. JEP-0115: Entity Capabilities <http://www.jabber.org/jeps/jep-0115.html>.

10. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

11. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

Version 0.5 (2006-03-09)

Version 0.4 (2006-02-02)

Version 0.3 (2006-01-30)

Version 0.2 (2006-01-11)

Version 0.1 (2005-11-02)

Version 0.0.2 (2005-10-25)

Version 0.0.1 (2005-10-24)