0.11

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3111 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0237.xml

@@ -22,6 +22,13 @@
   <supersededby/>
   <shortname>N/A</shortname>
   &stpeter;
+  &dcridland;
+  <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>
@@ -111,8 +118,7 @@
 <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 MUST ensure that each roster modification will result in a different version and that the version associated with a given roster modification will be different from version associated with any previous roster modification for this session. (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>
-    <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 do not necessitate a change to the version. 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), the server MAY consider the item to have been modified and therefore MAY send the item to the client (typically via a roster push as described below).</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>
@@ -131,7 +137,8 @@ S: <iq from='romeo@montague.lit' id='r1h3vzp7' to='romeo@montague.lit/home' type
     ]]></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.</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. 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), the server SHOULD NOT consider the item to have been modified for purposes of roster versioning and therefore SHOULD NOT push the item to the client in an interim roster push.</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='qAxdnWNcA+lYf7CoN5wpBsvVVno='>
@@ -235,6 +242,29 @@ S: <iq from='romeo@montague.lit' id='dh361f35' to='romeo@montague.lit/home' type
   ]]></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='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>