diff --git a/xep-0198.xml b/xep-0198.xml index 1e4e4272..72a6cbb4 100644 --- a/xep-0198.xml +++ b/xep-0198.xml @@ -7,10 +7,11 @@
Stream Management - This specification defines an XMPP protocol extension for active management of an XML stream between two XMPP entities, including features for stanza acknowledgements, stream resumption, and throttling notifications. + This specification defines an XMPP protocol extension for active management of an XML stream between two XMPP entities, including features for stanza acknowledgements and stream resumption. &LEGALNOTICE; 0198 Draft + Standards Track Standards @@ -23,9 +24,17 @@ http://xmpp.org/schemas/sm.xsd &infiniti; - &hildjj; &stpeter; + &hildjj; &fabio; + &dcridland; + &mwild; + + 1.2rc1 + 2011-02-11 + psa/dc/mw +

Simplification based on implementation experience: removed acking per number of stanzas exchanged because either entity can request an ack at any time; moved throttling feature to a separate specification; removed 'stanzas' attribute from <enable/> element; added 'location' attribute to <enabled/> element; clarified several implementation issues in the text; fixed several examples; versioned the XML namespace from urn:xmpp:sm:2 to urn:xmpp:sm:3.

 + 1.1 2010-03-05 @@ -146,21 +155,20 @@
-

&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.

+

&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.

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:

-

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.

-

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.

+

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 &xmppcore;) and are not counted or acked in stream management, since they exist for the purpose of managing stanzas themselves.

+

Stream management is used at the level of an XML stream. To check TCP connectivity underneath a given stream, it is RECOMMENDED to use whitespace keepalives (see Section 4.6.1 of &rfc3920bis;), &xep0199;, 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.

(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.)

 -

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;.

-

The stream management feature MUST NOT be offered unless the initiating entity has been authenticated (e.g., by means of SASL, &xep0078;, or &xep0220;).

+

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:3' namespace &VNOTE;.

+

Note: The initiating entity cannot negotiate stream management until it has authenticated with the receiving entity and (for clients) possibly until after it has bound a resource; see below for specific restrictions.

- + @@ -182,25 +190,26 @@ S:

To enable use of stream management, the initiating entity sends an <enable/> command to the receiving entity.

+C: ]]>

If the initiating entity wants to be allowed to resume the stream, it includes a boolean 'resume' attribute, which defaults to false &BOOLEANNOTE;. For information about resuming a previous session, see the Resumption section of this document.

The <enable/> element MAY include a 'max' attribute to specify the initiating entity's preferred maximum resumption time in seconds.

-

The <enable/> element MAY include a 'stanzas' attribute to specify the initiating entity's preferred number of stanzas between acks.

-

Upon receiving the enable request, the receiving entity MUST reply with an <enabled/> element or a <failed/> element qualified by the 'urn:xmpp:sm:2' namespace. The <failed/> element indicates that there was a problem establishing the stream management "session". The <enabled/> element indicates successful establishment of the stream management session.

+

Upon receiving the enable request, the receiving entity MUST reply with an <enabled/> element or a <failed/> element qualified by the 'urn:xmpp:sm:3' namespace. The <failed/> element indicates that there was a problem establishing the stream management "session". The <enabled/> element indicates successful establishment of the stream management session.

+S: ]]>

The parties can then the use stream management features defined below.

-

If the receiving entity allows session resumption, it MUST include a 'resume' attribute set to a value of "true" or "1".

+

If the receiving entity allows session resumption, it MUST include a 'resume' attribute set to a value of "true" or "1" &BOOLEANNOTE;.

+S: ]]>

The <enabled/> element MAY include a 'max' attribute to specify the receiving entity's preferred maximum resumption time.

-

The <enabled/> element MAY include a 'stanzas' attribute to specify the receiving entity's preferred number of stanzas between acks.

-

For client-to-server connections, the client SHOULD NOT attempt to enable stream management until after it has completed Resource Binding unless it is resuming a previous session (see Resumption). The server MAY enforce this order and return a <failed/> element in response (see Error Handling).

+

The <enabled/> element MAY include a 'location' attribute to specify the receiving entity's preferred IP address or hostname (optionally with a port) for reconnection; if reconnection to that location fails, the standard XMPP connection algorithm specified in &xmppcore; applies.

+

The initiating entity MUST NOT attempt to negotiate stream management until it is authenticated; i.e., it MUST NOT send an <enable/> element until after authentication (such as SASL, &xep0078; or &xep0220;) has been completed successfully.

+

For client-to-server connections, the client MUST NOT attempt to enable stream management until after it has completed Resource Binding unless it is resuming a previous session (see Resumption).

+

The server SHALL enforce this order and return a <failed/> element in response if the order is violated (see Error Handling).

+S: ]]> @@ -217,11 +226,17 @@ S:
  • The 'h' attribute identifies the last handled stanza (i.e., the last stanza that the receiver will acknowledge as having received).

    • An <a/> element MUST possess an 'h' attribute.

    -

    An <r/> element SHOULD NOT possess any attributes.

    +

    The <r/> element has no defined attributes.

    Definition: 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).

    -

    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., 232), the value of 'h' shall be reset from 232-1 back to zero (rather than being incremented to 232).

    -

    The following example shows a message sent by the client, a request for acknowledgement, and an ack of the stanza.

    - Receipt of an <r/> element does not imply that new stanzas have been transmitted by the peer; receipt of an <a/> element only indicates that new stanzas have been processed if the 'h' attribute has been incremented.

    +

    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., 232), the value of 'h' SHALL be reset from 232-1 back to zero (rather than being incremented to 232).

    +

    Note: In fact, 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/>, and the receiver's value needs to be initialized to 0 at the transmission or receipt of <enabled/>. It is expected that the receiver will response immediately to <enable/> and reset both counters.

    +

    The following annotated example shows a message sent by the client, a request for acknowledgement, and an ack of the stanza.

    + + + + C: @@ -231,13 +246,25 @@ C: -C: + -S: +S: + + + +C: + +S: ]]> -

    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 Throttling).

    -

    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).

    -

    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):

    +

    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 need to wait for an ack to continue sending stanzas.

    +

    Either party MAY send an <a/> element at any time (e.g., after it has received a certain number of stanzas, or after a certain period of time), even if it has not received an <r/> element from the other party.

    +

    When a party receives an <a/> element, 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).

    +

    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):