This document specifies a simple subset of the publish-subscribe protocol for use in broadcasting state change events associated with instant messaging and presence user (e.g., extended presence).
WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Status: Experimental
Type: Standards Track
Number: 0163
Version: 0.4
Last Updated: 2006-02-02
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP IM, JEP-0060
Supersedes: None
Superseded By: None
Short Name: pep
Wiki Page: <http://wiki.jabber.org/index.php/Personal Eventing Protocol (JEP-0163)>
Email:
stpeter@jabber.org
JID:
stpeter@jabber.org
Email:
kevin@kismith.co.uk
JID:
kevdadrum@jabber.ex.ac.uk
This Jabber Enhancement Proposal is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this JEP has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The XMPP Publish-Subscribe [1] extension is commonly thought of as complicated. This is unfortunate, since it would be good to use it to broadcast personal state change events such as those described in Extended Presence Protocol Suite [2]. To make publish-subscribe functionality more accessible in the context of instant messaging and presence applications that conform to XMPP IM [3], this document defines best practices that can be followed by IM and presence client and server developers, hopefully resulting in the deployment of personal eventing protocol ("PEP") services across the Jabber IM network.
Note Well: This document describes all and only a subset of the full publish-subscribe protocol; any new features needed by PEP shall be defined in JEP-0060, not in this document. Until the provisional changes to JEP-0060 required for PEP are approved by the Jabber Council, readers of this document are referred to the version-in-progress located at <http://www.jabber.org/jeps/tmp/jep-0060-1.8.html>.
The personal eventing protocol (PEP) is based on five principles:
These principles are described more fully below.
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.
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.
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.
Most pubsub configuration options and metadata are not needed for personal eventing. Instead, servers should offer smart defaults to simplify node creation and management.
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]).
In order to discover whether a server or other entity supports the personal eventing protocol, an entity MUST use Service Discovery [8].
Example 1. Entity queries a server regarding protocol support
<iq from='juliet@capulet.com/balcony'
to='capulet.com'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
If a server supports PEP, it MUST return an identity of "pubsub/pep", MUST return a feature of "http://jabber.org/protocol/pubsub#pep", and MUST specify its default access model as described in JEP-0060.
Example 2. Server communicates protocol support
<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>
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:
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'>
<group>Friends</group>
</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>
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.
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>
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>
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:
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>
The default access model for a PEP service MUST be "presence" (a PEP service SHOULD support the "roster" access model and MAY support the "open" access model).
A PEP service SHOULD NOT support affiliations other than Owner and Subscriber.
A PEP service SHOULD use the following "smart defaults" for every node:
A PEP service MAY allow the owner-publisher's bare JID (<node@domain.tld>) to be a collection node, but MUST NOT support any other collection nodes.
A PEP service SHOULD NOT support instant nodes, since the "one node per namespace" rule makes instant nodes unnecessary.
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.
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.
A PEP service MAY enforce additional privacy and security policies when determining whether an entity is allowed to subscribe to a node or retrieve items from a node; however, any such policies shall be considered specific to an implementation or deployment and are out of scope for this document.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [9].
The Jabber Registrar [10] shall include 'http://jabber.org/protocol/pubsub#pep' in its registry of protocol namespaces.
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>
The schemas defined in JEP-0060 apply to the Personal Eventing Protocol.
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. 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/>.
10. 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/>.
END