mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-10 11:25:00 -05:00
0dba7e28cd
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3026 4b5297f7-1745-476d-ba37-a9c6900126ab
199 lines
12 KiB
XML
199 lines
12 KiB
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 changed, thus saving bandwidth during session establishment.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0237</number>
|
|
<status>Proposed</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>
|
|
&stpeter;
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2009-03-31</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified definition of sequence number.</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 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 changed. This document defines a small modification to the XMPP roster protocol specified in &xmppim; that enables "versioning" of roster information; when the client requests the roster it specifies its latest version, and the server will simply inform the client that it is up to date if the roster has not changed.</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 'ver' attribute is a strictly increasing sequence number that is increased (but not necessarily incremented-by-one) with any modification to the roster data. The value of the attribute MUST be a non-negative 64-bit integer, MUST be changed only by the server, and MUST be treated by the client as opaque. The server MUST ensure that each change to the roster data will result in a different sequence number and that the sequence number associated with a given roster modification will be greater than the sequence number associated with any previous roster modification. (Note: This rule effectively disallows the use of the system clock as a sequence number, since if the system time changes, e.g. because of an adjustment based on an NTP &rfc0958; update, the next generated value might be less than the previous one.)</p>
|
|
<p>For purposes of this specification, a "roster modification" is any change 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 do not result in a roster push do not necessitate a change to the sequence number.</p>
|
|
</section2>
|
|
<section2 topic='Client Request' anchor='request'>
|
|
<p>If a client supports roster versioning, it SHOULD include the 'ver' element in its request for the roster, where the 'ver' attribute is set to the sequence number associated with its last cache of the roster.</p>
|
|
<example caption="Roster get with sequence number"><![CDATA[
|
|
<iq from='romeo@montague.lit/home' id='r1' to='romeo@montague.lit' type='get'>
|
|
<query xmlns='jabber:iq:roster' ver='305'/>
|
|
</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 SHOULD set the 'ver' attribute to a value of zero (0).</p>
|
|
<p>Naturally, if the client does not support roster versioning or does not wish to bootstrap 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 With Unchanged Roster' anchor='response-unchanged'>
|
|
<p>If the roster has not changed since the version enumerated by the client, the server MUST return an empty IQ-result.</p>
|
|
<example caption="Roster result (unchanged)"><![CDATA[
|
|
<iq from='romeo@montague.lit' id='r1' to='romeo@montague.lit/home' type='result'/>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Server Response With Changed Roster' anchor='response-changed'>
|
|
<p>If the roster has changed since the version enumerated by the client, the server MUST return a &QUERY; element that includes the latest version number.</p>
|
|
<p>The &QUERY; element MUST either contain the complete roster (including the version number to indicate that the roster has changed) or be empty (indicating that roster changes will be sent as interim roster pushes).</p>
|
|
<p>In general, if returning the complete roster would use 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.</p>
|
|
<example caption="Roster result with complete roster"><![CDATA[
|
|
<iq from='romeo@montague.lit' id='r1' to='romeo@montague.lit/home' type='result'>
|
|
<query xmlns='jabber:iq:roster' ver='317'>
|
|
<item jid='bill@shakespeare.lit' subscription='both'/>
|
|
<item jid='nurse@capulet.lit' name='Nurse' subscription='both'>
|
|
<group>Servants</group>
|
|
</item>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>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.</p>
|
|
<example caption="Roster result with no items"><![CDATA[
|
|
<iq from='romeo@montague.lit' id='r1' to='romeo@montague.lit/home' type='result'>
|
|
<query xmlns='jabber:iq:roster' ver='317'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Interim roster pushes"><![CDATA[
|
|
<iq from='romeo@montague.lit' id='p1' to='romeo@montague.lit/home' type='set'>
|
|
<query xmlns='jabber:iq:roster' ver='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' ver='317'>
|
|
<item jid='bill@shakespeare.lit' subscription='both'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>The 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 (in this case, 305) and the new roster version (317).</li>
|
|
<li>During that time, the client might have received roster pushes related to roster version numbers 306, 307, 310, 311, 313, 314, 315, and 317 (the version numbers must be strictly increasing but there is no requirement that the sequence shall be continuous).</li>
|
|
<li>However, some of those roster pushes might have contained intermediate updates to the same roster item (e.g., changes in 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 changes applied while the client was in fact offline.</li>
|
|
</ol>
|
|
<p>The client can determine when the interim roster pushes have ended by comparing the version number it received on the empty &QUERY; element against the version number it receives in roster pushes.</p>
|
|
</section2>
|
|
<section2 topic='Subsequent Roster Pushes' anchor='roster-push'>
|
|
<p>When the server sends subsequent roster pushes to the client, it MUST include the updated roster version number. Roster pushes MUST occur in sequence order. The version 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 <cite>RFC 3921</cite> or <cite>rfc3921bis</cite>.</p>
|
|
<example caption="Roster push"><![CDATA[
|
|
<iq from='romeo@montague.lit' id='p3' to='romeo@montague.lit/home' type='set'>
|
|
<query xmlns='jabber:iq:roster' ver='319'>
|
|
<item jid='muse@shakespeare.lit' name='The Muse' subscription='to'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</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 <ver/> 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='Security Considerations' anchor='security'>
|
|
<p>It is possible that client-side caching of roster information (rather than holding them in memory only for the life of the 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='ns'>
|
|
<p>Until this specification advances to a status of Draft, the associated namespace for its stream feature shall be "urn:xmpp:features:rosterver". Upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;; the requested namespace is "urn:xmpp:seq", which is thought to be unique per the XMPP Registrar's requirements.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='XML Schemas' anchor='schemas'>
|
|
<p>This specification proposes addition of the 'ver' attribute to the schema for the 'jabber:iq:roster' namespace.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>Thanks to Dave Cridland, Richard Dobson, Fabio Forno, Alexander Gnauck, Juha Hartikainen, Joe Hildebrand, Justin Karneges, Curtis King, Pedro Melo, and Jiří Zárevúcký for their comments. The definition of a sequence number borrows concepts and text from &rfc4551;</p>
|
|
</section1>
|
|
|
|
</xep>
|