From: Dave Cridland <[email protected]>
Some suggestions for XEP-0198, to be explained in a mail I'll send in a sec.
---
extensions/xep-0198.xml | 35 ++++++++++++++++++++++++++---------
1 files changed, 26 insertions(+), 9 deletions(-)
diff --git a/extensions/xep-0198.xml b/extensions/xep-0198.xml
index 11369f2..b96e2d8 100644
--- a/extensions/xep-0198.xml
+++ b/extensions/xep-0198.xml
@@ -159,8 +159,8 @@
</section1>
<section1 topic='Stream Feature' anchor='feature'>
- <p>After negotiating use of TLS and authenticating via SASL, the receiving
entity returns a new stream header to the intiating entity along with stream
features, where the features include an <sm/> element qualified by the
'urn:xmpp:sm:2' namespace &VNOTE;.</p>
- <p>The stream management feature MUST NOT be offered unless the initiating
entity has been authenticated (e.g., by means of SASL, &xep0078;, or
&xep0220;).</p>
+ <p>The receiving entity returns a stream header to the intiating entity
along with stream features, where the features include an <sm/> element
qualified by the 'urn:xmpp:sm:2' namespace &VNOTE;.</p>
+ <p>Note: The initiating entity cannot negotiate stream management until
authenticated and possibly bound; see below for specific restrictions.</p>
<example caption='Server sends new stream header along with stream
features'><![CDATA[
S: <stream:stream
from='example.com'
@@ -198,7 +198,9 @@ S: <enabled xmlns='urn:xmpp:sm:2' id='some-long-sm-id'
resume='true'/>
]]></example>
<p>The <enabled/> element MAY include a 'max' attribute to specify the
receiving entity's preferred maximum resumption time.</p>
<p>The <enabled/> element MAY include a 'stanzas' attribute to specify
the receiving entity's preferred number of stanzas between acks.</p>
- <p>For client-to-server connections, the client SHOULD NOT attempt to enable
stream management until after it has completed Resource Binding <em>unless it
is resuming a previous session</em> (see <link
url='#resumption'>Resumption</link>). The server MAY enforce this order and
return a <failed/> element in response (see <link url='#errors'>Error
Handling</link>).</p>
+ <p>In no case may an initiating entity negotiate stream management until it
is authenticated, thus the client MUST NOT send an <enable/> element until
after authentication (such as SASL, &xep78; or &xep220;) has been completed
successfully.</p>
+ <p>For client-to-server connections, the client MUST NOT attempt to enable
stream management until after it has completed Resource Binding <em>unless it
is resuming a previous session</em> (see <link
url='#resumption'>Resumption</link>).</p>
+ <p>The server SHALL enforce this order and return a <failed/> element
in response (see <link url='#errors'>Error Handling</link>).</p>
<example caption='Server returns error if client attempts to enable stream
management before resource binding'><![CDATA[
S: <failed xmlns='urn:xmpp:sm:2'>
<unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@@ -217,11 +219,16 @@ S: <failed xmlns='urn:xmpp:sm:2'>
<li>The 'h' attribute identifies the last <strong>handled</strong> stanza
(i.e., the last stanza that the receiver will acknowledge as having
received).</li>
</ul>
<p>An <a/> element MUST possess an 'h' attribute.</p>
- <p>An <r/> element SHOULD NOT possess any attributes.</p>
+ <p>An <r/> element has no defined 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 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>
+ <p>Receipt of an <r/> element does not imply that new stanzas have been
transmitted by the peer; receipt of an <a/> elementonly indicates new
stanzas have been processed if the 'h' attribute has incremented.</p>
+ <p>Note: The value of 'h' starts at zero at the point stream management is
enabled or requested to be enabled, is incremented to one for the first stanza
handled, and is incremented by one 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>(( Not quite... There are two values of h, one for the initiator, and one
for the receiver. The Initiator's value needs to be intialized to 0 at the
transmission or receipt of <enable/>, the receiver's at the transmission or
receipt of <enabled/>. It is to be expected that the receiver will response
immediately to <enable/> and reset both counters. ))</p>
+ <p>The following annotated 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: <enable xmlns='urn:xmpp:sm:2'/>
+ <!-- Client sets outbound count
+ to zero. -->
C: <message from='[email protected]/churchyard'
to='[email protected]'
xml:lang='en'>
@@ -230,14 +237,22 @@ C: <message from='[email protected]/churchyard'
with my letters to thy lord.
</body>
</message>
+ <!-- Note that client need not wait for
+ response. -->
+
+S: <enabled xmlns='urn:xmpp:sm:2'/>
+ <!-- Server receives enable, and responds,
+ setting both inbound and outbound counts
+ to zero.
+ Client sets inbound count to zero. -->
C: <r xmlns='urn:xmpp:sm:2'>
-S: <a xmlns='urn:xmpp:sm:2' h='0'>
+S: <a xmlns='urn:xmpp:sm:2' h='1'>
]]></example>
<p>When an <r/> element ("request") is received, the recipient MUST
acknowledge it by sending an <a/> element to the sender containing a
value of 'h' that is equal to the number of stanzas handled by the recipient of
the <r/> element. The response SHOULD be sent as soon as possible after
receiving the <r/> 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 <r/> 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>
- <p>If a stream ends and it is not resumed within the time specified in the
original <enabled/> element, the sequence number and any associated state
MAY be discarded by both parties. Before the session state is discarded,
implementations SHOULD take alternative action regarding any unhandled stanzas
(i.e., stanzas sent after the most recent 'h' value):</p>
+ <p>When a party receives an ack it SHOULD keep a record of the 'h' value
returned as the sequence number of the last handled outbound stanza for the
current stream (and discard the previous value).</p>
+ <p>If a stream ends and it is not resumed within the time specified in the
original <enabled/> element, the sequence number and any associated state
MAY be discarded by both parties. Before the session state is discarded,
implementations SHOULD take alternative action regarding any unhandled stanzas
(i.e., stanzas sent after the most recent 'h' value received):</p>
<ul>
<li>A server SHOULD treat unacknowledged stanzas in the same way that it
would treat a stanza sent to an unavailable resource, by either returning an
error to the sender or committing the stanza to offline storage.</li>
<li>A user-oriented client SHOULD try to silently resend the stanzas upon
reconnection or inform the user of the failure via appropriate user-interface
elements.</li>
@@ -246,6 +261,7 @@ S: <a xmlns='urn:xmpp:sm:2' h='0'>
<section1 topic='Resumption' anchor='resumption'>
<p>It can happen that an XML stream is terminated unexpectedly (e.g.,
because of network outages). In this case, it is desirable to quickly resume
the former stream rather than complete the tedious process of stream
establishment, roster retrieval, and presence broadcast.</p>
+ <p>In addition, this allows entities to establish definitively which stanzas
require resending and which do not, eliminating replay issues.</p>
<p>To request that the stream will be resumable, when enabling stream
management the initiating entity MUST add a 'resume' attribute to the
<enable/> element with a value of "true" or "1" &BOOLEANNOTE;.</p>
<example caption='Client enables stream management'><![CDATA[
C: <enable xmlns='urn:xmpp:sm:2' resume='true'/>
@@ -419,6 +435,7 @@ C: <message/>
C: <r/>
S: <a h='9'/>
]]></example>
+ <p>In particular, on mobile networks, it is advisable to only request
and/or send acknowledgements when there is other data to be sent, or in lieu of
a &xep199 ping or whitespace probe.</p>
</section2>
<section2 topic='Throttling Scenario' anchor='scenarios-throttle'>
--
1.7.0.4
