moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

1.1rc1 

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3993 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2010-02-25 05:55:18 +00:00
parent 2b200b432c
commit 00c8ac8f85
1 changed files with 19 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
xep-0198.xml
View File

@ -11,6 +11,7 @@
&LEGALNOTICE;
<number>0198</number>
<status>Draft</status>
<interim/>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
@ -26,6 +27,12 @@
&hildjj;
&stpeter;
&fabio;
<revision>
<version>1.1rc1</version>
<date>in progress, last updated 2010-02-24</date>
<initials>psa/jk</initials>
<remark><p>Corrected value of 'h' so that zero means no stanzas have yet been handled; clarified distinction between a cleanly closed stream and an unfinished stream.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2009-06-17</date>
@ -141,16 +148,15 @@
<section1 topic='Introduction' anchor='intro'>
<p>&xmppcore; defines the fundamental streaming XML technology used by XMPP (i.e., stream establishment and termination including authentication and encryption). However, the core XMPP specification does not provide tools for actively managing a "live" XML stream.</p>
<p>The basic concept behind stream management is that the initiating entity (either a client or a server) and the receiving entity (a server) can exchange "commands" for active management of the stream. (Instead of using XMPP IQ, message, or presence stanzas, stream management uses a series of short XML elements at the root stream level.) In particular, it is expected that the following stream management features will improve network reliability and the end-user experience:</p>
<p>The basic concept behind stream management is that the initiating entity (either a client or a server) and the receiving entity (a server) can exchange "commands" for active management of the stream. The following stream management features are of particular interest because they are expected to improve network reliability and the end-user experience:</p>
<ul>
<li>Acks -- the ability to know if a stanza or series of stanzas has been received by one's peer.</li>
<li>Resumption -- the ability to quickly resume a stream that has been terminated.</li>
<li>Throttling -- the ability for the receiving entity to inform the initiating entity that rate limiting is in force.</li>
</ul>
<p>Detailed descriptions of these features are provided in the remainder of this specification.</p>
<p>Note: To check TCP connectivity for a given stream, it is RECOMMENDED to use &xep0199;, whitespace pings (see Section 5.7.3 of &rfc3920bis;), or TCP keepalives.</p>
<p>Note: This specification applies at the level of an XML stream between a client and a server or between two servers. By constrast, &xep0079; and &xep0184; define acks that are sent end-to-end over multiple streams; these facilities are useful in special scenarios but are unnecessary for checking of a direct stream between two XMPP entities. (It is also expected that this protocol will revive interest in Advanced Message Processing (AMP), because single-hop acks are necessary for AMP delivery receipts to function properly.)</p>
<p>Note: Examples prepended by "C:" are sent by a client and examples prepended by "S:" are sent by a server. Stream management can be used server-to-server but most of the examples in this specification show its use between a client and a server.</p>
<p>Stream management implements these features using short XML elements at the root stream level. These elements are not "stanzas" in the XMPP sense (i.e., not &IQ;, &MESSAGE;, or &PRESENCE; stanzas as defined in &rfc3920;) and are not counted or acked in stream management, since they exist for the purpose of managing stanzas themselves.</p>
<p>Stream management is used at the level of an XML stream. To check TCP connectivity underneath a given stream, it is RECOMMENDED to use &xep0199;, whitespace keepalives (see Section 5.7.3 of &rfc3920bis;), or TCP keepalives. By constrast with stream management, &xep0079; and &xep0184; define acks that are sent end-to-end over multiple streams; these facilities are useful in special scenarios but are unnecessary for checking of a direct stream between two XMPP entities.</p>
<p>(Examples prepended by "C:" are sent by a client and examples prepended by "S:" are sent by a server. Stream management can be used server-to-server but most of the examples in this specification show its use between a client and a server.)</p>
</section1>
<section1 topic='Stream Feature' anchor='feature'>
@ -214,7 +220,7 @@ S: <failed xmlns='urn:xmpp:sm:2'>
<p>An &lt;a/&gt; element MUST possess an 'h' attribute.</p>
<p>An &lt;r/&gt; element SHOULD NOT possess any attributes.</p>
<p class='def'><strong>Definition:</strong> Acknowledging a previously-received ack element indicates that the stanza(s) sent since then have been "handled" by the receiver. By "handled" we mean that the receiver has accepted responsibility for a stanza or stanzas (e.g., to process the stanza(s) directly, deliver the stanza(s) to a local entity such as another connected client on the same server, or route the stanza(s) to a remote entity at a different server); until a stanza has been affirmed as handled by the receiver, that stanza is the responsibility of the sender (e.g., to resend it or generate an error if it is never affirmed as handled by the receiver).</p>
<p>Note: The value of 'h' starts at zero for the first stanza handled and is incremented with each subsequent stanza handled. In the unlikely case that the number of stanzas handled during a stream management session exceeds the number of digits that can be represented by the unsignedInt datatype as specified in &w3xmlschema2; (i.e., 2<span class='super'>32</span>), the value of 'h' shall be reset from 2<span class='super'>32</span>-1 back to zero (rather than being incremented to 2<span class='super'>32</span>).</p>
<p>Note: The value of 'h' starts at zero before any stanzas are handled, is incremented to one for the first stanza handled, and is incremented again with each subsequent stanza handled. In the unlikely case that the number of stanzas handled during a stream management session exceeds the number of digits that can be represented by the unsignedInt datatype as specified in &w3xmlschema2; (i.e., 2<span class='super'>32</span>), the value of 'h' shall be reset from 2<span class='super'>32</span>-1 back to zero (rather than being incremented to 2<span class='super'>32</span>).</p>
<p>The following example shows a message sent by the client, a request for acknowledgement, and an ack of the stanza.</p>
<example caption='Simple stanza acking'><![CDATA[
C: <message from='laurence@example.net/churchyard'
@ -316,6 +322,11 @@ S: <failed xmlns='urn:xmpp:sm:2'>
<p>Stream management errors SHOULD be considered recoverable; however, misuse of stream management MAY result in termination of the stream.</p>
</section1>
<section1 topic='Stream Closure' anchor='closure'>
<p>A cleanly closed stream differs from an unfinished stream. If a client wishes to cleanly close its stream and end its session, it MUST send a &lt;/stream:stream&gt; so that the server can send unavailable presence on the client's behalf.</p>
<p>If the stream is not cleanly closed then the server SHOULD consider the stream to be unfinished (even if the client closes its TCP connection to the server) and SHOULD maintain the session on behalf of the client for a limited amount of time. The client can send whatever presence it wishes before leaving the stream in an unfinished state.</p>
</section1>
<section1 topic='Scenarios' anchor='scenarios'>
<p>The following scenarios illustrate several different uses of stream management. The examples are that of a client and a server, but stream management can also be used for server-to-server streams.</p>
@ -325,7 +336,7 @@ S: <failed xmlns='urn:xmpp:sm:2'>
<li>As an initiating entity, send &lt;enable/&gt; with no attributes, and ignore the attributes on the &lt;enabled/&gt; response.</li>
<li>As a receiving entity, ignore the attributes on the &lt;enable/&gt; element received, and respond via &lt;enabled/&gt; with no attributes.</li>
<li>When receiving an &lt;r/&gt; element, immediately respond via an &lt;a/&gt; element where the value of 'h' returned is the sequence number of the last handled stanza.</li>
<li>Keep an integer X for this stream session, initially set to zero. When about to send a stanza, first put the stanza (paired with the current value of X) in an "unacknowleged" queue. Then send the stanza over the wire with &lt;r/&gt; to request acknowledgement of that outbond stanza, and increment X by 1. When receiving an &lt;r/&gt; or &lt;a/&gt; element with an 'h' attribute, all stanzas whose paired value (X at the time of queueing) is less than or equal to the value of 'h' can be removed from the unacknowledged queue.</li>
<li>Keep an integer X for this stream session, initially set to zero. When about to send a stanza, first put the stanza (paired with the current value of X) in an "unacknowleged" queue. Then send the stanza over the wire with &lt;r/&gt; to request acknowledgement of that outbound stanza, and increment X by 1. When receiving an &lt;r/&gt; or &lt;a/&gt; element with an 'h' attribute, all stanzas whose paired value (X at the time of queueing) is less than or equal to the value of 'h' can be removed from the unacknowledged queue.</li>
</ul>
<p>This is enough of an implementation to minimally satisfy the peer, and allows basic tracking of each outbound stanza. If the stream connection is broken, the application has a queue of unacknowledged stanzas that it can choose to handle appropriately (e.g., warn a human user or silently send after reconnecting).</p>
<p>The following examples illustrate basic acking (here the client automatically acks each stanza it has received from the server, without first being prompted via an &lt;r/&gt; element).</p>
@ -633,7 +644,7 @@ S: <t stanzas='10'/>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Dave Cridland, Jack Erwin, Philipp Hancke, Curtis King, Tobias Markmann, Alexey Melnikov, Pedro Melo, Robin Redeker, and Mickaël Rémond for their feedback.</p>
<p>Thanks to Dave Cridland, Jack Erwin, Philipp Hancke, Curtis King, Tobias Markmann, Alexey Melnikov, Pedro Melo, Robin Redeker, Mickaël Rémond, and Matthew Wild for their feedback.</p>
</section1>
</xep>