xeps/xep-0237.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Roster Versioning</title>
  <abstract>This specification defines a proposed modification to the XMPP roster protocol that enables versioning of rosters such that the server will not send the roster to the client if the roster has not been modified, thus saving bandwidth during session establishment.</abstract>
  &LEGALNOTICE;
  <number>0237</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>N/A</shortname>
  <schemaloc>
    <ns>feature</ns>
    <url>http://www.xmpp.org/schemas/versioning-feature.xsd</url>
  </schemaloc>
  &stpeter;
  &dcridland;
  <revision>
    <version>1.0</version>
    <date>2009-05-27</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the XMPP Council, advanced specification to Draft.</p></remark>
  </revision>
  <revision>
    <version>0.12</version>
    <date>2009-05-14</date>
    <initials>psa</initials>
    <remark><p>Moved information about sending pushes to non-normative implementation guidelines; modified examples to reduce confusion.</p></remark>
  </revision>
  <revision>
    <version>0.11</version>
    <date>2009-04-30</date>
    <initials>dc/psa</initials>
    <remark><p>Added implementation guidelines.</p></remark>
  </revision>
  <revision>
    <version>0.10</version>
    <date>2009-04-27</date>
    <initials>psa</initials>
    <remark><p>Modified ver attribute to be an opaque identifier instead of (necessarily) a strictly-increasing sequence number; specified that an empty version ID indicates that the client wishes to bootstrap the use of roster versioning.</p></remark>
  </revision>
  <revision>
    <version>0.9</version>
    <date>2009-04-22</date>
    <initials>psa</initials>
    <remark><p>Further clarified several implementation notes.</p></remark>
  </revision>
  <revision>
    <version>0.8</version>
    <date>2009-04-20</date>
    <initials>psa</initials>
    <remark><p>Defined schema for stream feature; adjusted some wording for improved clarity.</p></remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2009-04-17</date>
    <initials>psa</initials>
    <remark><p>Modified the underlying model per list consensus; added more detailed scenarios to illustrate usage.</p></remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2009-03-31</date>
    <initials>psa</initials>
    <remark><p>Clarified definition of ver attribute.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2009-02-19</date>
    <initials>psa</initials>
    <remark><p>Reverted to a roster-specific method and modified presentation to enable incorporation into rfc3921bis.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2008-09-17</date>
    <initials>psa</initials>
    <remark><p>Defined new namespace and generalized to handle service discovery and other use cases in addition to rosters.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2008-04-21</date>
    <initials>psa</initials>
    <remark><p>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.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2008-03-06</date>
    <initials>psa</initials>
    <remark><p>Renamed to data sequencing; clarified server behavior.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2008-03-05</date>
    <initials>psa</initials>
    <remark><p>Initial published version; per Council consensus, removed optionality regarding semantics of the version attribute.</p></remark>
  </revision>
  <revision>
    <version>0.0.3</version>
    <date>2008-03-05</date>
    <initials>psa</initials>
    <remark><p>Corrected semantics of version attribute (should be a strictly increasing sequence number but may be any unique identifier).</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2008-03-04</date>
    <initials>psa</initials>
    <remark><p>Clarified description of roster diff; added diff attribute and specified its use in roster results; specified use of version attribute in roster pushes.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2008-03-04</date>
    <initials>psa</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>Although XMPP rosters can become quite large, they tend to change infrequently. Therefore it can be inefficient for the server to send the roster to the client during session establishment if the roster has not been modified. This document defines a small modification to the XMPP roster protocol specified in &xmppim; that enables "versioning" of roster information.</p>
  <p>The basic model is that if the client specifies a version ID when it requests the roster, the server returns an empty IQ-result. If the roster has been modified, the server sends versioned roster pushes for each roster item that has been touched in any way since the version specified by the client. The client processes each roster push as it normally would, modifying its local version ID with each roster push it receives. This enables the client to receive only the items that have been modified, not the entire roster.</p>
  &RFC3921BISNOTE;
</section1>

<section1 topic='Protocol' anchor='proto'>
  <section2 topic='Data Format' anchor='format'>
    <p>This document adds a new 'ver' attribute to the &QUERY; element qualified by the 'jabber:iq:roster' namespace, defined as follows.</p>
    <p class='def'><strong>Definition:</strong> The <strong>'ver' attribute</strong> is a string that identifies a particular version of the roster information. The value MUST be generated only by the server and MUST be treated by the client as opaque. The server can use any appropriate method for generating the version ID, such as a hash of the roster data or a strictly-increasing sequence number.</p>
  </section2>
  <section2 topic='Client Request' anchor='request'>
    <p>If a client supports roster versioning, it MUST include the 'ver' element in its request for the roster, where the 'ver' attribute is set to the version ID associated with its last cache of the roster.</p>
    <example caption="Roster get with version ID"><![CDATA[
C: <iq from='romeo@montague.lit/home' id='r1h3vzp7' to='romeo@montague.lit' type='get'>
     <query xmlns='jabber:iq:roster' ver='ver14'/>
   </iq>
    ]]></example>
    <p>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 versioning, it MUST set the 'ver' attribute to the empty string (i.e., <strong>ver=""</strong>).</p>
    <p>Naturally, if the client does not support roster versioning or does not wish to bootstrap the use of roster versioning, it will behave like an RFC-3921-compliant client by not including the 'ver' attribute.</p>
  </section2>
  <section2 topic='Server Response' anchor='response-result'>
    <p>Whether or not the roster has been modified since the version ID enumerated by the client, the server MUST either return the complete roster as described in RFC 3921 (including a 'ver' attribute that signals the latest version) or return an empty IQ-result (thus indicating that any roster modifications will be sent via roster pushes, as described below). In general, unless returning the complete roster would (1) use less bandwidth than sending individual roster pushes to the client (e.g., if the roster contains only a few items) or (2) the server cannot associate the version ID with any previous version it has on file, the server SHOULD send an empty IQ-result and then send the modifications (if any) via roster pushes.</p>
    <example caption="Empty roster result"><![CDATA[
S: <iq from='romeo@montague.lit' id='r1h3vzp7' to='romeo@montague.lit/home' type='result'/>
    ]]></example>
    <p>Note: This empty IQ-result is different from an empty &QUERY;, thus disambiguating this usage from an empty roster.</p>
    <p>If the roster has not been modified since the version ID enumerated by the client, the server will simply not send any roster pushes to the client (until and unless some relevant event triggers a roster push during the lifetime of the client's session).</p>
    <p>If the roster has been modified since the version ID enumerated by the client, the server MUST then send one roster push to the client for each roster item that has been modified since the version ID enumerated by the client. (We call a roster push that is sent for purposes of roster version synchronization an "interim roster push".)</p>
    <p class='def'><strong>Definition:</strong> A <strong>"roster modification"</strong> is any modification to the roster data that would result in a roster push to a connected client. Therefore internal states related to roster processing within the server that would not result in a roster push to a connected client do not necessitate a change to the version.</p>
    <example caption="Roster pushes"><![CDATA[
S: <iq from='romeo@montague.lit' id='ah382g67' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver34'>
       <item jid='tybalt@shakespeare.lit' subscription='remove'/>
     </query>
   </iq>

S: <iq from='romeo@montague.lit' id='b2gs90j5' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver42'>
       <item jid='bill@shakespeare.lit' subscription='both'/>
     </query>
   </iq>

S: <iq from='romeo@montague.lit' id='c73gs419' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver72'>
       <item jid='nurse@shakespeare.lit' name='Nurse' subscription='to'>
         <group>Servants</group>
       </item>
     </query>
   </iq>

S: <iq from='romeo@montague.lit' id='dh361f35' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver96'>
       <item jid='juliet@shakespeare.lit' name='Juliet' subscription='both'>
         <group>VIPs</group>
       </item>
     </query>
   </iq>
    ]]></example>
    <p>These "interim roster pushes" can be understood as follows:</p>
    <ol>
      <li>Imagine that the client had an active presence session for the entire time between its cached roster version (say, "ver14") and the new roster version (say, "ver96").</li>
      <li>During that time, the client might have received roster pushes related to various roster versions. However, some of those roster pushes might have contained intermediate updates to the same roster item (e.g., modifications to the subscription state for bill@shakespeare.lit from "none" to "to" and from "to" to "both").</li>
      <li>The interim roster pushes would not include all of the intermediate steps, only the final result of all modifications applied to each item while the client was in fact offline (say, "ver34", "ver42", "ver72", and "ver96").</li>
    </ol>
    <p>The client MUST handle an "interim roster push" in the same way it handles any roster push (indeed, from the client's perspective it cannot tell the difference between an "interim" roster push and a "live" roster push). If the client's session ends before it receives all of the interim roster pushes, when requesting the roster after reconnection it SHOULD request the version associated with the last roster <em>push</em> it received during the session that was disconnected, not the version associated with the roster <em>result</em> it received at the start of the session that was disconnected.</p>
    <p>When roster versioning is enabled, the server MUST include the updated roster version with each roster push. Roster pushes MUST occur in order of modification and the version contained in a roster push MUST be unique.</p>
  </section2>
</section1>

<section1 topic='Examples' anchor='examples'>
  <p>This section provides a detailed scenario that illustrates the use of roster versioning. In this example the client gets disconnected before the server has had a chance to send all of its roster pushes, but this is immaterial to the synchronization process.</p>
  <example caption="The roster synchronization process"><![CDATA[
C: <iq from='romeo@montague.lit/home' id='r1h3vzp7' to='romeo@montague.lit' type='get'>
     <query xmlns='jabber:iq:roster' ver='ver14'/>
   </iq>

S: <iq from='romeo@montague.lit' id='r1h3vzp7' to='romeo@montague.lit/home' type='result'/>

S: <iq from='romeo@montague.lit' id='ah382g67' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver34'>
       <item jid='tybalt@shakespeare.lit' subscription='remove'/>
     </query>
   </iq>

S: <iq from='romeo@montague.lit' id='b2gs90j5' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver42'>
       <item jid='bill@shakespeare.lit' subscription='both'/>
     </query>
   </iq>

S: </stream:stream>

[ reconnection ]

C: <iq from='romeo@montague.lit/home' id='r2xa7gf9' to='romeo@montague.lit' type='get'>
     <query xmlns='jabber:iq:roster' ver='ver42'/>
   </iq>

S: <iq from='romeo@montague.lit' id='r2xa7gf9' to='romeo@montague.lit/home' type='result'/>

S: <iq from='romeo@montague.lit' id='c73gs419' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver72'>
       <item jid='nurse@shakespeare.lit' name='Nurse' subscription='to'>
         <group>Servants</group>
       </item>
     </query>
   </iq>

S: <iq from='romeo@montague.lit' id='dh361f35' to='romeo@montague.lit/home' type='set'>
     <query xmlns='jabber:iq:roster' ver='ver96'>
       <item jid='juliet@shakespeare.lit' name='Juliet' subscription='both'>
         <group>VIPs</group>
       </item>
     </query>
   </iq>
    ]]></example>
</section1>

<section1 topic='Stream Feature' anchor='feature'>
  <p>If a server supports roster versioning, it MUST inform the connecting entity when returning stream features during the stream negotiation process; at the latest, when informing a client that resource binding is required. This is done by including a &lt;ver/&gt; element qualified by the 'urn:xmpp:features:rosterver' namespace.</p>
  <example caption="Stream features"><![CDATA[
<stream:features>
  <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
    <required/>
  </bind>
  <ver xmlns='urn:xmpp:features:rosterver'>
    <optional/>
  </ver>
</stream:features>
  ]]></example>
</section1>

<section1 topic='Implementation Guidelines' anchor='impl'>
  <p>This specification is specifically designed to allow for a wide range of implementation choices. These range from highly simplistic but inefficient, to very efficient but quite complex.</p>
  <p>This section provides suggestions, rather than instructions, on some lightweight approaches to conforming with the specification.</p>
  <section2 topic='Syntactic Conformance' anchor='impl-syntactic'>
    <p>A server can conform to this specification by accepting and ignoring the 'ver' attribute in requests, and providing an empty 'ver' attribute in each roster push.</p>
    <p>This provides no efficiency savings for clients.</p>
  </section2>
  <section2 topic='Exact-Match Conformance' anchor='impl-exactmatch'>
    <p>Using some digest (hash) of the roster, a server can identify unchanged rosters, and handle the case where the client sends a ver corresponding to the current roster state.</p>
    <p>This will account for the majority of cases, and represents a substantial saving. Server implementors are advised to canonicalize the form and ordering of roster items prior to applying the hash function. This hash function need not be cryptographically secure, merely resistent to collisions, and it is advisable to pick one that is fast to compute.</p>
    <p>No additional data need be stored, although storing the current hash will yield some performance advantage. This strategy is thought to be relatively safe in the face of data loss on the server.</p>
  </section2>
  <section2 topic='Add-Only Conformance' anchor='impl-addonly'>
    <p>Using a strictly increasing sequence for the 'ver' attribute, a server can "stamp" each roster item with its last change, and the roster as a whole with its last deletion. The server returns either the entire roster -- if a deletion has occured since the client's ver value -- or those changed items.</p>
    <p>Deletions are thought to be rare compared to additions and modifications, and as such this approach captures almost all changes. The additional storage cost is also low.</p>
    <p>Implementors could combine this strategy with the previous one, detecting a sequence of modifications yielding the same roster as the client has cached already, by constructing a ver attribute containing both a hash and sequence value. This might provide some resilience in the case of data loss.</p>
    <p>Implementors are advised that a pure timestamp is not suitable for this approach, since under some circumstances system clocks can go backwards (e.g., because of an adjustment based on an update triggered by use of the Network Time Protocol as described in &rfc0958;).</p>
  </section2>
  <section2 topic='Sending Pushes' anchor='impl-push'>
    <p>There are two primary approaches to server-side generation of the 'ver' attribute: complete roster hashes and strictly increasing sequence numbers. Whether the server will send roster pushes varies depending on the approach taken. For instance, if a series of roster modifications result in a roster item that does not differ from the version cached by the client (e.g., a modification to the item's 'name' attribute and then a modification back to the original value), then a server that implements the "complete roster hashes" approach would not consider the item to have been modified for purposes of roster versioning and therefore would not push the item to the client in an interim roster push; however, a server that implements the "strictly increasing sequence numbers" approach would send a roster push in this situtation.</p>
  </section2>
  <section2 topic='Client Implementation Guidelines' anchor='impl-client'>
    <p>Client implementors are reminded that the value of the 'ver' attribute is entirely opaque, and they should behave identically with each strategy described above by simply conforming to the specification. The only storage requirement for this specification is the last seen 'ver' attribute.</p>
  </section2>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>It is possible that client-side caching of roster information across sessions (rather than holding them in memory only for the life of a session) could introduce new vulnerabilities, such as misuse by malware. Implementations are advised to appropriately protect cached roster data.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p> 
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:features:rosterver</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &STREAMFEATURES;, as described in Section 4 of &xep0053;.</p>
  </section2>
</section1>

<section1 topic='XML Schemas' anchor='schemas'>

  <section2 topic='jabber:iq:roster' anchor='schemas-roster'>
    <p>This specification proposes addition of the 'ver' attribute to the schema for the 'jabber:iq:roster' namespace.</p>
  </section2>

  <section2 topic='Stream Feature' anchor='schemas-feature'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:features:rosterver'
    xmlns='urn:xmpp:features:rosterver'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0237: http://www.xmpp.org/extensions/xep-0237.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='ver'>
    <xs:complexType>
      <xs:choice>
        <xs:element name='optional' type='empty'/>
        <xs:element name='required' type='empty'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    ]]></code>
  </section2>

</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Dave Cridland, Richard Dobson, Leonid Evdokimov, Fabio Forno, Alexander Gnauck, Juha Hartikainen, Joe Hildebrand, Waqas Hussain, Justin Karneges, Sachin Khandelwal, Curtis King, Jonas Lindberg, Pedro Melo, Matthew Wild, Jiří Zárevúcký, and Florian Zeitz for their comments.</p>
</section1>

</xep>