JEP-0163: Personal Eventing via Pubsub

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. Business Rules

7.1. Generating Notifications

7.1.1. Number of Notifications

7.1.2. When to Generate Notifications

7.2. Cancelling Subscriptions

8. Security Considerations

9. IANA Considerations

10. Jabber Registrar Considerations

10.1. Service Discovery Category/Type

11. XML Schema

Notes

Revision History

2.1 Every Account a Pubsub Service

When a user creates an account (or has an account provisioned) at a Jabber/XMPP server, that account should have associated with it a virtual pubsub service. This greatly simplifies the task of discovering the account owner's personal pubsub nodes, 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) for the owner-publisher. For example, there is one pubsub node for location events, one node for tune events, one node for mood events, 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 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 [8]).

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

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

4.1 Creating a Node

First, the account owner creates the node. (We use as our example a node to publish information about the user's current tune as specified in JEP-0118.) Here we assume that the default access model for the service is "presence" [11] and that the account owner desires a node with that access model.

Example 3. Account owner creates node

<iq from='juliet@capulet.com/balcony' type='set' id='create1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/tune'/>
    <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/tune".
3. 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 to='juliet@capulet.com/balcony' type='result' id='create1'/>
    

In order to request an access model other than the default, the account owner MUST include a data form (see Data Forms [12]) that contains a node configuration field of "pubsub#access_model" set to a value of "presence", "roster", or "open" (the value MAY be "authorize" or "whitelist" but these values are NOT RECOMMENDED for PEP nodes since maintenance of such nodes requires interaction on the part of the node owner).

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 from='juliet@capulet.com/balcony' type='set' id='create-roster-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/geoloc'/>
    <configure>
      <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#access_model'>
          <option><value>roster</value></option>
        </field>
        <field var='pubsub#roster_groups_allowed'>
          <option><value>friends</value></option>
        </field>
      </x>
    </configure>
  </pubsub>
</iq>
    

4.2 Publishing an Item

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

Example 6. Account owner publishes item

<iq from='juliet@capulet.com/balcony' type='set' id='pub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </publish>
  </pubsub>
</iq>
  

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

Example 7. Server returns result

<iq to='juliet@capulet.com/balcony' 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 8. Server generates notifications

<message from='juliet@capulet.com'
         to='romeo@montague.net/home'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </items>
  </event>
  <addresses xmlns='http://jabber.org/protocol/address'>
    <address type='replyto' jid='juliet@capulet.com/balcony'/>
  </addresses>
</message>

.
.
.
    

The server MUST set the 'from' address on the notification to the bare JID (<node@domain.tld>) of the publishing entity (in this example, "juliet@capulet.com"). The server SHOULD include an Extended Stanza Addressing [13] "replyto" extension specifying the publishing resource (in this 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). However, any errors related to the notification MUST be directed to the JID of the 'from' address on the notification (i.e., the bare JID) so that bounce processing can be handled by the PEP service rather than by the publishing client.

4.3 Sending the Last Published Item

As described in the Generating Notifications section of this document, a PEP service MUST send the last published item to all new subscribers and to all newly-available resources for each subscriber. [14]

Example 9. Subscriber sends presence from newly-available resource

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

Example 10. 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 11. PEP service sends last published item to newly-available resource

<message from='juliet@capulet.com'
         to='romeo@montague.net/orchard'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

5.1 Discovering Nodes

Node discovery is straightforward 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 12. 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 (as well as any other associated items as described in JEP-0030):

Example 13. 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/tune'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/activity'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/geolocation'/>
  </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 14. 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/tune' 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 15. Server allows subscription

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

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

Example 16. Server sends last published item

<message from='juliet@capulet.com' to='romeo@montague.net' type='headline' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

7.1 Generating Notifications

7.2 Cancelling Subscriptions

In order to ensure appropriate access to information published at nodes of type "presence" and "roster"", a PEP service MUST re-calculate access controls when:

1. A presence subscription state changes (e.g., when a subscription request is approved).
2. A roster item is modified (e.g., when the item is moved to a new roster group).

If the modification results in a loss of access, the service MUST cancel the entity's subscription and SHOULD send a message to the (former) subscriber informing it of the cancellation. For information about the format of messages sent to notify subscribers of subscription cancellation, see the "Notification of Subscription Denial or Cancellation" section of JEP-0060.

10.1 Service Discovery Category/Type

The Jabber Registrar includes a category of "pubsub" in its registry of Service Discovery identities (see <http://www.jabber.org/registrar/disco-features.html>); as a result of this JEP, the Registrar shall add a type of "pep" to that category.

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-0080: User Geolocation <http://www.jabber.org/jeps/jep-0080.html>.

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

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

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

6. Currently, many "extended presence" formats are sent using the <presence/> stanza type; however, this overloads presence, results in unnecessary presence traffic, and does not provide fine-grained control over access. The use of publish-subscribe rather than presence is therefore preferable.

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

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

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

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

11. Naturally, the default node configuration needs to be discovered via the method defined in JEP-0060.

12. JEP-0004: Data Forms <http://www.jabber.org/jeps/jep-0004.html>.

13. JEP-0033: Extended Stanza Addressing <http://www.jabber.org/jeps/jep-0033.html>.

14. That is, the default value of the "pubsub#send_last_published_item" node configuration field must be "on_sub_and_presence"; this behavior essentially mimics the functionality of presence as defined in XMPP IM.

15. If the only presence information received by the service is from resources that have specified negative priorities, the service MUST NOT send any notifications.

16. If the only presence information received by the service is from resources that have specified negative priorities, the service MUST NOT send any notifications.

17. 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/>.

Version 0.11 (2006-07-20)

Version 0.10 (2006-07-07)

Version 0.9 (2006-06-15)

Version 0.8 (2006-04-10)

Version 0.7 (2006-04-10)

Version 0.6 (2006-04-10)

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)