[Standards-JIG] rfc3920bis: Stanza Acknowledgements

[Peter Saint-Andre]

If you write this up in an updated version of jep-ack, we'll publish it.

See the following URL and forward from there in the Council discussion:

http://www.jabber.org/muc-logs/council@conference.jabber.org/2006-11-06.html#12:36:40

/psa

Justin Karneges wrote:
> Hello,
> 
> Here is some proposed text for RFC 3920, covering stanza acknowledgements.  
> The proposal combines what is covered here:
>   http://www.xmpp.org/extensions/inbox/ack.html
> and here:
>   http://mail.jabber.org/pipermail/standards-jig/2006-April/010797.html
> 
> (Note: pings are not covered, but we can still discuss them.)
> 
> This protocol allows for requesting stream-level acks or tagging stream-level 
> sequence numbers on a per-stanza basis.
> 
> I tried to keep the text in the same spirit as the rest of the RFC, and some 
> sentences are copied/modified from other sections.  The "Section X" would 
> probably become Section 7 (pushing Resource Binding to Section 8, and on).
> 
> Enjoy,
> -Justin
> 
> -----
> 
> X. Stanza Acknowledgements
> 
> X.1. Overview
> 
> XMPP includes a method for acknowledging stanza reception, to allow for
> transmission error detection and recovery.
> 
> The following rules apply:
>   1. An initiating entity that complies with this specification MUST include
>      the 'version' attribute set to a value of "1.0" in the initial stream
>      header.
>   2. When a receiving entity that complies with this specification receives
>      an initial stream header that includes the 'version' attribute set to a
>      value of at least "1.0", after sending a stream header in reply
>      (including the version flag), it MUST include an <ack/> element
>      (qualified by the 'urn:ietf:params:xml:ns:xmpp-ack' namespace) along
>      with the list of other stream features it supports.
> 
> X.2. Narrative
> 
> When an initiating entity activates the acknowledgement feature with a
> receiving entity, the steps involved are as follows:
> 
>   1. The initiating entity opens a TCP connection and initiates the stream
>      by sending the opening XML stream header to the receiving entity,
>      including the 'version' attribute set to a value of at least "1.0".
>   2. The receiving entity responds by opening a TCP connection and sending
>      an XML stream header to the initiating entity, including the 'version'
>      attribute set to a value of at least "1.0".
>   3. The receiving entity offers the acknowledgement feature to the
>      initiating entity by including it with the list of other supported
>      stream features.
>   4. The initiating entity issues the enable command (i.e., a <enable/>
>      element qualified by the 'urn:ietf:params:xml:ns:xmpp-ack' namespace)
>      to instruct the receiving entity that it wishes to enable the
>      acknowledgement feature.  The element MAY contain a 'previd' attribute
>      and a 'prevc' attribute, if the initiating entity wishes to recover a
>      previously known acknowledgement session.  The value of the 'previd'
>      attribute is set to the same value as the 'id' attribute of the
>      <stream> in the previous session.  The value of the 'prevc' attribute,
>      if applicable, is set to the last received sequence number (discussed
>      below) by the initiating entity.  If the initiating entity is not
>      recovering a past session, the 'previd' and 'prevc' attributes MUST NOT
>      be included.
>   5. The receiving entity MUST reply with an <enabled/> element qualified by
>      the 'urn:ietf:params:xml:ns:xmpp-ack' namespace.  If the initiating
>      entity provided a 'previd' attribute in the <enable/> element, and the
>      receiving entity supports session recovery, then the receiving entity
>      MAY provide a 'prevc' attribute in the <enabled/> element.  The value
>      of this attribute is set to the last received sequence number
>      (discussed below) for the previous session.  If the receiving entity
>      does not support session recovery, or does not recognize the 'previd'
>      as an earlier session, or there is no known last received sequence
>      number for the session, then the attribute MUST NOT be included.
>   6. When a stanza is sent by either the initiating or receiving entity, an
>      'r' attribute ("request ack") or a 'c' attribute ("sequence number")
>      qualified by the 'urn:ietf:params:xml:ns:xmpp-ack' namespace MAY be
>      provided in the top-level element of the stanza to indicate how
>      acknowledgements are to be handled with respect to the stanza.  If no
>      acknowledgement processing is desired for a stanza, then the attribute
>      MUST NOT be included.  Note that only stanzas ('message', 'presence',
>      and 'iq', in the jabber:client or jabber:server namespaces) can have
>      this kind of processing applied.  Non-stanza elements, such as those
>      related to authentication or other stream-level purposes are not to be
>      acknowledged using this protocol.
>   7. When a stanza is received, containing an 'r' attribute ("request ack")
>      with a value of "true", the recipient MUST acknowledge the stanza by
>      sending an <a/> element qualified by the
>      'urn:ietf:params:xml:ns:xmpp-ack' namespace back to the sender.
>      Stanzas not containing an 'r' attribute MUST NOT be acknowledged.
>      Several stanzas MAY be acknowledged at one time by including an 'n'
>      attribute in the <a/> element, set to the integer value of the number
>      of stanzas.  An ack indicates stanza acceptance, in that the stanza is
>      now safe in the receiver's hands and that the receiver will take care
>      of it from that point.  Acks do not indicate successful delivery to a
>      remote entity beyond the receiver.  The sender does not have to wait
>      for an ack to continue sending stanzas.  Acks SHOULD be sent as soon as
>      possible, 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. As acks indicate stanza
>      acceptance, a server that is throttling stanzas MUST defer the acks
>      until the client is no longer being penalized.
>   8. When a stanza is received, containing a 'c' attribute ("sequence
>      number"), the recipient SHOULD keep a record of this value as the last
>      received sequence number for the current stream.  Everytime a new
>      sequence number is received, the previous number can be forgotten.
>   9. If the stanza is to be routed over another stream (for example, if the
>      receiving entity is a server), then the receiver of the stanza MUST
>      remove any 'r' and 'c' attributes (qualified by the
>      'urn:ietf:params:xml:ns:xmpp-ack' namespace) from the stanza before
>      passing it along.
> 
> Examples of stanza acknowledgements are provided under Section 9.
> 
> 
> 9.1. Client-to-Server
> 
> ...
> Step 2: Server responds by sending a stream header to client:
> 
> <stream:features>
>   <starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'>
>     <required/>
>   </starttls>
>   <mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
>     <mechanism>DIGEST-MD5</mechanism>
>   </mechanisms>
>   <ack xmlns='urn:ietf:params:xml:ns:xmpp-ack'/>
> </stream:features>
> ...
> 
> Step 17: Client enables stanza acknowledgements:
> 
> <enable xmlns='urn:ietf:params:xml:ns:xmpp-ack'/>
> 
> Step 18: Server informs client that the feature is enabled:
> 
> <enabled xmlns='urn:ietf:params:xml:ns:xmpp-ack'/>
> 
> ...
> [Somewhere else]
> 
> Client sends a message, requesting an ack from the server:
> 
> <message from='laurence at example.net/churchyard'
>          to='juliet at example.com'
>          xml:lang='en'
>          xmlns:ack='urn:ietf:params:xml:ns:xmpp-ack'
>          ack:r='true'>
>     <body>I'll send a friar with speed, to Mantua,
>           with my letters to thy lord.</body>
> </message>
> 
> Server responds with ack:
> 
> <a xmlns='urn:ietf:params:xml:ns:xmpp-ack'/>
> ...
> 
> Client sends a message, with attached sequence number:
> 
> <message from='laurence at example.net/churchyard'
>          to='juliet at example.com'
>          xml:lang='en'
>          xmlns:ack='urn:ietf:params:xml:ns:xmpp-ack'
>          ack:c='7'>
>     <body>I'll send a friar with speed, to Mantua,
>           with my letters to thy lord.</body>
> </message>
> ...
> 
> [session recovery]
> 
> Client enables stanza acknowledgements, attempting to recover a previous
> session:
> 
> <enable xmlns='urn:ietf:params:xml:ns:xmpp-ack' previd='c2s_345'/>
> 
> Server informs client that the feature is enabled:
> 
> <enabled xmlns='urn:ietf:params:xml:ns:xmpp-ack' prevc='7'/>
> 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 7358 bytes
Desc: S/MIME Cryptographic Signature
Url : http://mail.jabber.org/pipermail/standards/attachments/20061106/b3133a95/smime.bin