git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3223 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-06-03 23:31:07 +00:00
parent 9ec4c153b9
commit 1d9315966e
1 changed files with 29 additions and 14 deletions

View File

@ -23,6 +23,20 @@
&hildjj;
&stpeter;
&fabio;
<revision>
<version>0.9</version>
<date>2009-06-03</date>
<initials>psa</initials>
<remark>
<ul>
<li>Specified that the value of the 'h' attribute starts at zero, not one.</li>
<li>Specified that the 'h' attribute is an unsignedInt and that it loops back to zero when reaching 2^32.</li>
<li>Added security consideration regarding session resumption and removed security consideration regarding proxies.</li>
<li>Clarified the meaning of handled as defining which entity has responsibility for a stanza.</li>
<li>Corrected schema and examples.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.8</version>
<date>2009-04-09</date>
@ -184,7 +198,8 @@ S: <failed xmlns='urn:xmpp:sm:2'>
</ul>
<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 stanzas have been accepted by the receiver, not necessarily that they have been fully processed by the receiver, delivered to a local entity such as another connected client on the same server, or routed to a remote entity at a different server. Therefore value of 'h' starts at one (the first stanza handled) and is incremented with each subsequent stanza handled.</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, it 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>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'
@ -198,7 +213,7 @@ C: <message from='laurence@example.net/churchyard'
C: <r xmlns='urn:xmpp:sm:2'>
S: <a xmlns='urn:xmpp:sm:2' h='1'>
S: <a xmlns='urn:xmpp:sm:2' h='0'>
]]></example>
<p>When an &lt;r/&gt; element ("request") is received, the recipient MUST acknowledge it by sending an &lt;a/&gt; element to the sender containing a value of 'h' that is equal to the number of stanzas handled by the recipient of the &lt;r/&gt; element. The response SHOULD be sent as soon as possible after receiving the &lt;r/&gt; element, and MUST NOT be withheld for any condition other than a timeout. For example, a client with a slow connection might want to collect many stanzas over a period of time before acking, and a server might want to throttle incoming stanzas. The sender does not have to wait for an ack to continue sending stanzas. Because acks indicate stanza acceptance, a server that is throttling stanzas MUST delay the response until the client is no longer being penalized (but SHOULD notify the client that it is throttling incoming stanzas, as described under <link url='#throttling'>Throttling</link>).</p>
<p>When a party returns an ack in response to an &lt;r/&gt; element or receives such an ack, it SHOULD keep a record of the 'h' value returned as the sequence number of the last handled stanza for the current stream (and discard the previous 'h' value).</p>
@ -264,7 +279,7 @@ S: <t xmlns='urn:xmpp:sm:2'/>
<p>Note: Sending a throttling notification to the stream peer does not necessarily indicate that the entity is throwing away all stanzas, only that the entity has voluntarily slowed its processing of incoming stanzas.</p>
<p>The throttling notification MAY include a 'stanzas' attribute so that the receiving entity can inform the initiating entity of changes to the maximum number of stanzas between acks. This enables the receiving entity to dynamically adjust stanza acking in response to network conditions or stream usage.</p>
<example caption='Throttling notification with acking adjustment'><![CDATA[
S: <n xmlns='urn:xmpp:sm:2' stanzas='5'/>
S: <t xmlns='urn:xmpp:sm:2' stanzas='5'/>
]]></example>
<p>If the number of unacknowledged stanzas is greater than or equal to the value of the 'stanzas' attribute, a peer MUST NOT send any further stanzas.</p>
<p>If an entity sets the value of 'stanzas' to zero, it has stopped reading from the stream entirely.</p>
@ -313,7 +328,7 @@ C: <r xmlns='urn:xmpp:sm:2'/>
]]></example>
<p>The server returns the roster and immediately sends an &lt;a/&gt; element to acknowledge handling of the stanza.</p>
<example caption='Server acknowledges handling of client stanza and sends a stanza'><![CDATA[
S: <a xmlns='urn:xmpp:sm:2' h='1'/>
S: <a xmlns='urn:xmpp:sm:2' h='0'/>
S: <iq id='ls72g593' type='result'>
<query xmlns='jabber:iq:roster'>
@ -325,7 +340,7 @@ S: <iq id='ls72g593' type='result'>
]]></example>
<p>The client then acknowledges receipt of the server's stanza, sends initial presence, and immediately sends an &lt;r/&gt; element to request acknowledgement, incrementing by one its internal representation of how many stanzas have been handled by the server.</p>
<example caption='Client sends a stanza and requests acknowledgement'><![CDATA[
C: <a xmlns='urn:xmpp:sm:2' h='1'/>
C: <a xmlns='urn:xmpp:sm:2' h='0'/>
C: <presence/>
@ -333,13 +348,13 @@ C: <r xmlns='urn:xmpp:sm:2'/>
]]></example>
<p>The server handles the stanza by broadcasting the user's presence and immediately sends an &lt;a/&gt; element to acknowledge handling of the stanza.</p>
<example caption='Server acknowledges handling of client stanza and sends a stanza'><![CDATA[
S: <a xmlns='urn:xmpp:sm:2' h='2'/>
S: <a xmlns='urn:xmpp:sm:2' h='1'/>
S: <presence from='romeo@montague.lit/orchard' to='romeo@montague.lit/orchard'/>
]]></example>
<p>The client then acks the server's second stanza and sends an outbound message followed by an &lt;r/&gt; element.</p>
<example caption='Client sends a stanza and requests acknowledgement'><![CDATA[
C: <a xmlns='urn:xmpp:sm:2' h='2'/>
C: <a xmlns='urn:xmpp:sm:2' h='1'/>
C: <message to='juliet@capulet.lit'>
<body>ciao!</body>
@ -349,7 +364,7 @@ C: <r xmlns='urn:xmpp:sm:2'/>
]]></example>
<p>The server handles the stanza by routing it to the remote contact and immediately sends an &lt;a/&gt; element to acknowledge handling of the stanza.</p>
<example caption='Server acknowledges handling of the stanza'><![CDATA[
S: <a xmlns='urn:xmpp:sm:2' h='3'/>
S: <a xmlns='urn:xmpp:sm:2' h='2'/>
]]></example>
<p>And so on.</p>
</section2>
@ -365,14 +380,14 @@ C: <message/>
C: <message/>
C: <message/>
C: <r/>
S: <a h='5'/>
S: <a h='4'/>
C: <message/>
C: <message/>
C: <message/>
C: <message/>
C: <message/>
C: <r/>
S: <a h='10'/>
S: <a h='9'/>
]]></example>
</section2>
@ -399,7 +414,7 @@ S: <t stanzas='5'/>
[client sends another message just because it can]
C: <message/>
[server has handled the first 3 messages so it finally replies to <r/>]
S: <a h='3'/>
S: <a h='2'/>
C: <message/>
C: <message/>
C: <message/>
@ -407,7 +422,7 @@ C: <message/>
[client has sent 5 messages so requests an ack]
C: <r/>
[throttling is over, server replies to 2nd <r/> and sets 'stanzas' back to 10]
S: <a h='8'/>
S: <a h='7'/>
S: <t stanzas='10'/>
]]></example>
</section2>
@ -415,7 +430,7 @@ S: <t stanzas='10'/>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Intermediate proxies MUST pass through all stanzas, else the parties will go out of sync.</p>
<p>A receiving entity MUST NOT allow an initiating entity to resume a stream management session until after the initiating entity has authenticated; this helps to prevent session hijacking.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
@ -543,7 +558,7 @@ S: <t stanzas='10'/>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='h'
type='xs:positiveInteger'
type='xs:unsignedInt'
use='optional'/>
<xs:attribute name='previd'
type='xs:string'