[Standards-JIG] rfc3920bis: Stanza Acknowledgements

Justin Karneges justin-keyword-jabber.093179 at affinix.com
Sun Nov 5 02:12:41 UTC 2006


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'/>



More information about the Standards mailing list