This specification proposes a modification to the XMPP roster management protocol to support sequencing of roster changes for more efficient downloading of the roster information.
WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards 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.
Series: XEP
Number: 0237
Publisher: XMPP Standards Foundation
Status:
Experimental
Type:
Standards Track
Version: 0.3
Last Updated: 2008-04-21
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM
Supersedes: None
Superseded By: None
Short Name: NOT-YET-ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Roster Sequencing (XEP-0237)>
JabberID:
stpeter@jabber.org
URI:
https://stpeter.im/
The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.
Errata may be sent to <editor@xmpp.org>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards 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 document 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 following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. Introduction
2. Protocol
2.1. Advertising Support
2.2. Roster Get
2.3. Roster Is Unchanged
2.4. Roster Has Changed
2.5. Subsequent Roster Pushes
3. Security Considerations
4. IANA Considerations
5. XMPP Registrar Considerations
5.1. Protocol Namespaces
6. XML Schemas
6.1. Roster Management
6.2. Stream Feature
7. Acknowledgements
Notes
Revision History
Note: This document describes a protocol or best practice that is intended for incorporation into the specification that will supersede RFC 3921 [1] within the Internet Standards Process, i.e., rfc3921bis [2]. This document is provided only for the purpose of open community discussion of the potential modification and will be obsoleted as soon as the relevant RFC is published.
RFC 3921 specifies that an XMPP client must retrieve the entire roster on login. However, XMPP rosters can be quite large and often the roster has not changed since it was last retrieved. If the client could cache the roster and retrieve only changes to the roster, the login process could be significantly streamlined, which could be especially valuable over low-bandwidth connections such as those common in mobile environments. This document defines a method for such streamlining, via the concept of roster sequencing.
Note: This document is provided for discussion purposes in order to improve roster management in XMPP systems. It is not meant to supersede the text in RFC 3921. However, the recommendations in this document may be folded into rfc3921bis.
This document specifies the addition of a 'sequence' attribute to the <query/> element qualified by the 'jabber:iq:roster' namespace.
The value of the 'sequence' attribute MUST be a non-negative integer representing a strictly increasing sequence number that is increased (but not necessarily incremented-by-one) with any change to the roster. The server shall increase the sequence number even if a particular connected resource does not support this extension. The sequence number contained in a roster push MUST be unique. A "change to the roster" is any addition of, update to, or removal of a roster item that would result in a roster push, including changes in subscription states, as described in RFC 3921 or rfc3921bis.
The 'sequence' attribute is used as described in the following sections.
If a server supports roster sequencing, it MUST inform the client when returning stream features during the stream setup process, at the latest when informing the client that resource binding is required. This is done by including a <roster-sequencing/> element qualified by the 'urn:xmpp:tmp:roster-sequencing' namespace (see Protocol Namespaces regarding issuance of one or more permanent namespaces).
<stream:features> <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'> <required/> </bind> <roster-sequencing xmlns='urn:xmpp:tmp:roster-sequencing'/> </stream:features>
If a client supports roster sequencing and knows that the server does so, it SHOULD include the 'sequence' attribute in its request for the roster, set to the sequence number associated with its last cache of the roster.
<iq from='romeo@montague.lit/home' id='r1' to='romeo@montague.lit' type='get'> <query xmlns='jabber:iq:roster' sequence='305'/> </iq>
If the client has not yet cached the roster or the cache is lost or corrupted, but the client wishes to bootstrap the use of roster sequencing, it SHOULD include the 'sequence' attribute set to a value of zero (0).
Naturally, if the client does not support roster sequencing or does not wish to bootstrap use of roster sequencing, it will behave like an RFC-3921-compliant client by not including the 'sequence' attribute.
If the roster has not changed since the version enumerated by the client, the server MUST return an empty IQ-result.
<iq from='romeo@montague.lit' id='r1' type='result'/>
If the roster version has increased since the version enumerated by the client, the server MUST return a <query/> element that includes the latest sequence number.
The <query/> element MUST either contain the complete roster (including the sequence number to indicate that the roster has changed) or be empty (indicating that roster changes will be sent as interim roster pushes).
In general, if returning the complete roster would use less less bandwidth than sending individual roster pushes to the client (e.g., if the roster contains only a few items), the server should return the complete roster.
<iq from='romeo@montague.lit' id='r1' to='romeo@montague.lit/home' type='result'> <query xmlns='jabber:iq:roster' sequence='317'> <item jid='bill@shakespeare.lit' subscription='both'/> <item jid='nurse@capulet.lit' name='Nurse' subscription='both'> <group>Servants</group> </item </query> </iq>
However, if returning the complete roster would use more bandwidth than sending individual roster pushes to the client (e.g., if the roster contains many items, only a few of which have changed), the server should return an empty <query/> element, then send individual roster pushes.
<iq from='romeo@montague.lit' id='r1' to='romeo@montague.lit/home' type='result'> <query xmlns='jabber:iq:roster' sequence='317'/> </iq>
<iq from='romeo@montague.lit' id='p1' to='romeo@montague.lit/home' type='set'> <query xmlns='jabber:iq:roster' sequence='313'> <item jid='shylock@shakespeare.lit' subscription='remove'/> </query> </iq> <iq from='romeo@montague.lit' id='p2' to='romeo@montague.lit/home' type='set'> <query xmlns='jabber:iq:roster' sequence='317'> <item jid='bill@shakespeare.lit' subscription='both'/> </query> </iq>
The interim roster pushes can be understood as follows:
The client can determine when the interim roster pushes have ended by comparing the sequence number it received on the empty <query/> element against the sequence number it receives in roster pushes.
When the server sends subsequent roster pushes to the client, it MUST include the updated roster sequence number. Roster pushes MUST occur in sequence order.
<iq from='romeo@montague.lit' id='p3' to='romeo@montague.lit/home' type='set'> <query xmlns='jabber:iq:roster' sequence='318'> <item jid='muse@shakespeare.lit' name='The Muse' subscription='to'/> </query> </iq>
It is possible that caching of the roster (rather than holding it in memory only for the life of the session) could introduce new vulnerabilities. Client implementations should take care to appropriately protect the cached roster information.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [3].
Until this specification advances to a status of Draft, the associated namespace for its stream feature shall be "urn:xmpp:tmp:roster-sequencing"; upon advancement of this specification, the XMPP Registrar [4] shall issue a permanent namespace in accordance with the process defined in Section 4 of XMPP Registrar Function [5].
If this modification to the roster management protocol is added to rfc3921bis and approved by the IESG in the specification that supersedes RFC 3921, the schema for the roster management namespace would be changed as follows.
<?xml version='1.0' encoding='UTF-8'?> <xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema' targetNamespace='jabber:iq:roster' xmlns='jabber:iq:roster' elementFormDefault='qualified'> <xs:element name='query'> <xs:complexType> <xs:sequence> <xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/> </xs:sequence> <xs:attribute name='sequence' use='optional' type='xs:nonNegativeInteger'/> </xs:complexType> </xs:element> <xs:element name='item'> <xs:complexType> <xs:sequence> <xs:element ref='group' minOccurs='0' maxOccurs='unbounded'/> </xs:sequence> <xs:attribute name='ask' use='optional'> <xs:simpleType> <xs:restriction base='xs:NCName'> <xs:enumeration value='subscribe'/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name='jid' type='xs:string' use='required'/> <xs:attribute name='name' type='xs:string' use='optional'/> <xs:attribute name='subscription' use='optional'> <xs:simpleType> <xs:restriction base='xs:NCName'> <xs:enumeration value='both'/> <xs:enumeration value='from'/> <xs:enumeration value='none'/> <xs:enumeration value='remove'/> <xs:enumeration value='to'/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name='group' type='xs:string'/> </xs:schema>
<?xml version='1.0' encoding='UTF-8'?> <xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema' targetNamespace='urn:xmpp:tmp:roster-sequencing' xmlns='urn:xmpp:tmp:roster-sequencing' elementFormDefault='qualified'> <xs:element name='roster-sequencing' type='empty'> </xs:schema>
Thanks to Dave Cridland, Richard Dobson, Fabio Forno, Alexander Gnauck, Juha Hartikainen, Joe Hildebrand, Justin Karneges, and Pedro Melo for their comments.
1. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.
2. rfc3921bis: proposed revisions to Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/draft-saintandre-rfc3921bis>. (work in progress)
3. 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/>.
4. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.
5. XEP-0053: XMPP Registrar Function <http://www.xmpp.org/extensions/xep-0053.html>.
Defined protocol solely in terms of full rosters and roster pushes (no more roster diffs); added implementation notes; clarified server behavior if cached version is unavailable.
(psa)Renamed to roster sequencing; clarified server behavior.
(psa)Initial published version; per Council consensus, removed optionality regarding semantics of the version attribute.
(psa)Corrected semantics of version attribute (should be a strictly increasing sequence number but may be any unique identifier).
(psa)Clarified description of roster diff; added diff attribute and specified its use in roster results; specified use of version attribute in roster pushes.
(psa)First draft.
(psa)END