Haven't seen this one come back yet, but I'll comment now anyway.
Original patch included.
On Fri Sep 3 10:52:50 2010, [email protected] wrote:
Some suggestions for XEP-0198, to be explained in a mail I'll send
in a sec.
Obviously I've been working on XEP-0198 support - we're a way off
release on this, but I do have a deployed test now, and client (at
least) interop with Tobias Markmann's GSoC Psi implementation works.
extensions/xep-0198.xml | 35 ++++++++++++++++++++++++++---------
1 files changed, 26 insertions(+), 9 deletions(-)
This is a git patch of the (old, non-updated) mirror. I think it
should apply, though.
<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'
The problem here is that for XEP-0078 and XEP-0220, you can't
announce the feature after authentication. Not supporting XEP-0078
isn't a big loss, IMHO, but not supporting it for XEP-0220 would be
annoying.
Therefore, we need to announce support prior to authentication, even
though you can't use it yet.
]]></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'/>
I've tightened up the C2S requirement, because there's no signalling
to allow a client to know if it can enable 198 prior to resource
binding or not, and suck-it-and-see is not an extension mechanism.
I've also specifically stated here about the requirement to enable
only after auth - previously this was implicit in the feature
announcement restriction.
@@ -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>
Being picky.
<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>
This para basically states that you can say <r/> at any time without
harm, and you can acknowledge stanzas as many times as you like.
Tobias's code repeats <r/>'s at times, and I found it did no harm.
Nor did responding to them. Therefore I'm allowing the behaviour,
since I think it'll be quite common.
+ <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>
So there's two 'h' values, which the text hadn't really made clear,
even though it's obvious. Less obvious is that they get reset to zero
at different times.
Both Tobias and I reset our counts to zero on the <enable/>, and this
seemed sensible behaviour. Otherwise, you need to turn on 198 prior
to enabling it, which seems weird when you can't do anything useful
at that point.
+ <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>
I forgot to remove this - a note to myself about what needed
clarifying.
+ <p>The following annotated example shows a message sent by the
client, a request for acknowledgement, and an ack of the stanza.</p>
I annotated the example to make it clearer about what each actor
does, and when each counter is set.
<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. -->
+
Yes, pipelining <enable/> with subsequent stanzas does work, since if
the client enables at the right time, it'll almost certainly work.
+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'>
Noticed this was wrong. I've not checked every example.
- <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>
Decided to make this clearer about which direction acks need
recording. I'm still unhappy with the parenthesis at the end, I think
that's actually somewhat misleading, depending on how it's read.
<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>
I thought I'd add this in, since it's not made clear elsewhere.
XEP-0198 acking moves the error case from omission to duplication -
usually that's a preferably error - but resumption also removes the
duplication, as well as making everything a bit more predictable.
It *also* does fast-reconnect, but that's almost a by-product.
@@ -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>
Just a small comment there in the implementation notes.
Dave.
--
Dave Cridland - mailto:[email protected] - xmpp:[email protected]
- acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/
- http://dave.cridland.net/
Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade
>From a6aa0c71e476af838c8774de1c68c20057dfd863 Mon Sep 17 00:00:00 2001
From: Dave Cridland <[email protected]>
Date: Fri, 3 Sep 2010 10:49:52 +0100
Subject: [XEP-0198 PATCH] XEP-0198 suggestions
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
