1.16 RC6 acknowledgements section

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@605 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0124.xml

@@ -40,9 +40,9 @@
     &stpeter;
     <revision>
       <version>1.6</version>
-      <date>2007-02-15</date>
+      <date>2007-02-21</date>
       <initials>ip</initials>
-      <remark>Multiple clarifications and restructuring without changes to protocol itself; changed title to BOSH; added section that fully explores the technique underlying the protocol; separated XMPP-specific features into new XEP-0206; added optional new Script Syntax and session pauses; added from and ver attributes; added hold attribute to session creation response; clarified polling too-frequently error; recommended clients use HTTP Pipelining.</remark>
+      <remark>Multiple clarifications and restructuring without changes to protocol itself; changed title to BOSH; added section that fully explores the technique underlying the protocol; separated XMPP-specific features into new XEP-0206; added optional new Script Syntax and session pauses; added Acknowledgements section; added from and ver attributes; added hold attribute to session creation response; clarified polling too-frequently error; recommended clients use HTTP Pipelining.</remark>
     </revision>
     <revision>
       <version>1.5</version>
@@ -234,6 +234,7 @@ Connection Manager
       <p>Note: Clients that only support <link url="#poll">Polling Sessions</link> MAY prevent the connection manager from waiting by setting 'wait' or 'hold' to "0". However, polling is NOT RECOMMENDED since the associated increase in bandwidth consumption and the decrease in responsiveness are typically one or two orders of magnitude!</p>
       <p>A connection manager MAY be configured to enable sessions with more than one &server; in different domains. When requesting a session with such a 'proxy' connection manager, a client SHOULD include a <strong>'route'</strong> attribute that specifies the protocol, hostname, and port of the &server; with which it wants to communicate, formatted as "proto:host:port" (e.g., "xmpp:jabber.org:9999"). <note>Although the syntax of the 'route' attribute bears a superficial resemblance to a URI or IRI, it is not a URI/IRI and MUST NOT be processed in accordance with the rules specified in <cite>RFC 3986</cite>, <cite>RFC 3987</cite>, or <cite>draft-saintandre-xmpp-iri</cite>.</note> A connection manager that is configured to work only with a single &server; (or only with a defined list of domains and the associated list of hostnames and ports that are serving those domains) MAY ignore the 'route' attribute. (Note that the 'to' attribute specifies the domain being served, not the hostame of the machine that is serving the domain.)</p>
       <p>A client MAY include a <strong>'from'</strong> attribute to enable the connection manager to forward its identity to the &server;.</p>
+      <p>A client MAY include an <strong>'ack'</strong> attribute (set to "1") to indicate that it will be using acknowledgements throughout the session and that the absence of an 'ack' attribute in any request is meaningful (see <link url="#ack">Acknowledgements</link>).</p>
       <p>A client MAY include a <strong>'secure'</strong> attribute to specify that communications between the connection manager and the &server; must be "secure". (Note: The 'secure' attribute is of type xs:boolean (see &w3xmlschema2;) and the default value is "false". &BOOLEANNOTE;) If a connection manager receives a session request with the 'secure' attribute set to "true" or "1", then it MUST respond to the client with a  <link url="#errorstatus-terminal">remote-connection-failed</link> error as soon as it determines that it cannot communicate in a secure way with the &server;. A connection manager SHOULD consider communications with the &server; to be "secure" if they are encrypted using SSL or TLS with verified certificates, or if it is running on the same physical machine as the &server;. A connection manager MAY consider communications over a "private" network to be secure, even without SSL or TLS; however, a network SHOULD be considered "private" only if the administrator of the connection manager is sure that unknown individuals or processes do not have access to the network (i.e., individuals or processes who do not have access to either the connection manager or the &server;). The connection manager SHOULD try to establish a secure connection with the &server; even if the client does not specifically require it.</p>
       <p>Some clients are constrained to only accept HTTP responses with specific Content-Types (e.g., "text/html"). The &lt;body/&gt; element of the first request MAY possess a <strong>'content'</strong> attribute. This specifies the value of the HTTP Content-Type header that MUST appear in all the connection manager's responses during the session. If the client request does not possess a 'content' attribute, then the HTTP Content-Type header of responses MUST be "text/xml; charset=utf-8".</p>
       <example caption="Requesting an HTTP session">
@@ -251,6 +252,7 @@ Content-Length: 104
       secure='true'
       ver='1.6'
       wait='60'
+      ack='1'
       xml:lang='en'
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
       <p>Note: All requests after the first one MUST include a valid 'sid' attribute (provided by the connection manager in the <link url="#session-create">Session Creation Response</link>). The initialization request is unique in that the &lt;body/&gt; element MUST NOT possess a 'sid' attribute.</p>
@@ -270,6 +272,7 @@ Content-Length: 104
         <li><strong>'hold'</strong> -- This attribute informs the client about the maximum number of requests the connection manager may keep waiting at any one time during the session. This value MUST NOT be greater than the value specified by the client in the session request.</li>
       </ul>
       <p>The connection manager MAY include an <strong>'accept'</strong> attribute in the session creation response element, to specify the content encodings it can decompress. After receiving a session creation response with an 'accept' attribute, clients MAY include an HTTP Content-Encoding header in subsequent requests (indicating one of the encodings specified in the 'accept' attribute) and compress the bodies of the requests accordingly.</p>
+      <p>A connection manager MAY include an <strong>'ack'</strong> attribute (set to the value of the 'rid' attribute of the session creation request) to indicate that it will be using acknowledgements throughout the session and that the absence of an 'ack' attribute in any response is meaningful (see <link url="#ack">Acknowledgements</link>).</p>
       <p>If the connection manager supports session pausing (see <link url="#inactive">Inactivity</link>) then it SHOULD advertise that to the client by including a <strong>'maxpause'</strong> attribute in the session creation response element. The value of the attribute indicates the maximum length of a temporary session pause (in seconds) that a client MAY request.</p>
       <p>For both requests and responses, the &lt;body/&gt; element and its content SHOULD be UTF-8 encoded. If the HTTP Content-Type header of a request/response specifies a character encoding other than UTF-8, then the connection manager MAY convert between UTF-8 and the other character encoding. However, even in this case, it is OPTIONAL for the connection manager to convert between encodings. The connection manager MAY inform the client which encodings it can convert by setting the optional <strong>'charsets'</strong> attribute in the session creation response element to a space-separated list of encodings. <note>Each character set name (or character encoding name -- we use the terms interchangeably) SHOULD be of type NMTOKEN, where the names are separated by the white space character #x20, resulting in a tokenized attribute type of NMTOKENS (see Section 3.3.1 of &w3xml;). Strictly speaking, the Character Sets registry maintained by the Internet Assigned Numbers Authority (see &lt;<link url='http://www.iana.org/assignments/character-sets'>http://www.iana.org/assignments/character-sets</link>&gt;) allows a character set name to contain any printable US-ASCII character, which might include characters not allowed by the NMTOKEN construction of XML 1.0; however, the only existing character set name which includes such a character is "NF_Z_62-010_(1973)".</note></p>
       <p>As soon as the connection manager has established a connection to the &server; and discovered its identity, it MAY forward the identity to the client by including a <strong>'from'</strong> attribute in a response, either in its session creation response, or (if it has not received the identity from the &server; by that time) in any subsequent response to the client. If it established a secure connection to the &server; (as defined in <link url='#session'>Initiating an HTTP Session</link>), then in the same response the connection manager SHOULD also include the <strong>'secure'</strong> attribute set to "true" or "1".</p>
@@ -283,6 +286,7 @@ Content-Length: 128
       polling='5'
       requests='2'
       hold='1'
+      ack='1573741820'
       accept='deflate,gzip'
       maxpause='120'
       sid='SomeSID'
@@ -390,6 +394,44 @@ Content-Length: 88
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
     <p>The connection manager MUST wait and respond in the same way as it does after receiving stanzas from the client.</p>
   </section1>
+  <section1 topic='Acknowledgements' anchor='ack'>
+    <section2 topic='Request Acknowledgements' anchor='ack-request'>
+      <p>When responding to a request that it has been holding, if the connection manager has already received a request with a higher 'rid' attribute then it MAY acknowledge that fact to the client. The connection manager MAY set the 'ack' attribute of any response to the value of the highest 'rid' attribute it has received where it has also received all requests with lower 'rid' values.</p>
+      <example caption="Response with request acknowledgement">
+<![CDATA[HTTP/1.1 200 OK
+Content-Type: text/xml; charset=utf-8
+Content-Length: 64
+
+<body ack='1249243564'
+      xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
+      <p>If the connection manager will be including 'ack' attributes on responses during a session then it MUST include an 'ack' attribute in its session creation response, and set the 'ack' attribute of responses throughout the session. Except that, after its session creation response, the connection manager SHOULD NOT include an 'ack' attribute in any response if the value would be the 'rid' of the request being responded to.</p>
+      <p>If the connection manager is permitted to hold more than one request at a time, then the reception of a lower-than-expected 'ack' value from the connection manager (or the unexpected abscence of an 'ack' attribute) can give the client an early warning that a network failure might have occured.</p>
+    </section2>
+    <section2 topic='Response Acknowledgements' anchor='ack-response'>
+      <p>The client MAY similarly inform the connection manager about the responses it has received by setting the 'ack' attribute of any request to the value of the highest 'rid' of a request for which it has already received a response where it has also received all responses associated with lower 'rid' values. If the client will be including 'ack' attributes on requests during a session then it MUST include an 'ack' attribute (set to '1') in its session creation request, and set the 'ack' attribute of requests throughout the session. Except that, after its session creation request, the client SHOULD NOT include an 'ack' attribute in any request if it has received responses to all its previous requests.</p>
+      <example caption="Request with response acknowledgement">
+<![CDATA[POST /webclient HTTP/1.1
+Host: httpcm.jabber.org
+Accept-Encoding: gzip, deflate
+Content-Type: text/xml; charset=utf-8
+Content-Length: 88
+
+<body rid='1249243566'
+      sid='SomeSID'
+      ack='1249243564'
+      xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
+      <p>After receiving a request with an 'ack' value less than the 'rid' of the last request that it has already responded to, the connection manager MAY inform the client of the situation by sending its next response immediately (instead of waiting until it has stanzas to send to the client), including a 'report' attribute set to one greater than the 'ack' attribute it received from the client, and a 'time' attribute set to the number of milliseconds since it sent the response associated with the 'report' attribute.</p>
+      <example caption="Response with report">
+<![CDATA[HTTP/1.1 200 OK
+Content-Type: text/xml; charset=utf-8
+Content-Length: 64
+
+<body report='1249243565'
+      time='852'
+      xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
+      <p>Upon reception of a response with 'report' and 'time' attributes, if the client has still not received the response associated with the request identifier (RID) specified by the 'report' attribute, then it MAY choose to resend the request associated with the missing response (see  <link url="#rids-broken">Broken Connections</link>).</p>
+    </section2>
+  </section1>
   <section1 topic='Inactivity' anchor='inactive'>
     <p>After receiving a response from the connection manager, if none of the client's requests are still being held by the connection manager (and if the session is not a <link url="#poll">Polling Session</link>), the client SHOULD make a new request as soon as possible. In any case, if no requests are being held, the client MUST make a new request before the maximum inactivity period has expired. The length of this period in seconds is specified by the 'inactivity' attribute in the session creation response.</p>
     <p>If the connection manager has responded to all the requests it has received within a session and the time since its last response is longer than the maximum inactivity period, then it SHOULD assume the client has been disconnected and terminate the session without informing the client. If the client subsequently makes another request, then the connection manager SHOULD respond as if the session does not exist.</p>
@@ -483,7 +525,7 @@ Content-Length: 68
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
     </section2>
     <section2 topic='Broken Connections' anchor='rids-broken'>
-      <p>Unreliable network communications or client constraints can result in broken connections. The connection manager SHOULD remember the 'rid' and the associated HTTP response body of the client's most recent requests which were not session pause requests (see <link url="#inactive">Inactivity</link>) and which did not result in an HTTP or binding error. The number of responses to non-pause requests kept in the buffer SHOULD be the same as the maximum number of simultaneous requests allowed by the connection manager.</p>
+      <p>Unreliable network communications or client constraints can result in broken connections. The connection manager SHOULD remember the 'rid' and the associated HTTP response body of the client's most recent requests which were not session pause requests (see <link url="#inactive">Inactivity</link>) and which did not result in an HTTP or binding error. The number of responses to non-pause requests kept in the buffer SHOULD be either the same as the maximum number of simultaneous requests allowed by the connection manager or, if <link url="#ack">Acknowledgements</link> are being used, the number of responses that have not yet been acknowledged.</p>
       <p>If the network connection is broken or closed before the client receives a response to a request from the connection manager, then the client MAY resend an exact copy of the original request. Whenever the connection manager receives a request with a 'rid' that it has already received, it SHOULD return an HTTP 200 (OK) response that includes the buffered copy of the original XML response to the client (i.e., a &lt;body/&gt; wrapper possessing appropriate attributes and optionally containing one or more XML stanzas or other allowable XML elements). If the original response is not available (e.g., it is no longer in the buffer), then the connection manager MUST return an 'item-not-found' terminal binding error:</p>
       <example caption="Response not in buffer error">
 <![CDATA[HTTP/1.1 200 OK
@@ -1046,6 +1088,7 @@ _BOSH_("<body rid='1249243562' sid='SomeSID'
                 processContents='lax'/>
       </xs:choice>
       <xs:attribute name='accept' type='xs:string' use='optional'/>
+      <xs:attribute name='ack' type='xs:positiveInteger' use='optional'/>
       <xs:attribute name='authid' type='xs:string' use='optional'/>
       <xs:attribute name='charsets' type='xs:NMTOKENS' use='optional'/>
       <xs:attribute name='condition' use='optional'>
@@ -1072,12 +1115,14 @@ _BOSH_("<body rid='1249243562' sid='SomeSID'
       <xs:attribute name='newkey' type='xs:string' use='optional'/>
       <xs:attribute name='pause' type='xs:short' use='optional'/>
       <xs:attribute name='polling' type='xs:short' use='optional'/>
+      <xs:attribute name='report' type='xs:positiveInteger' use='optional'/>
       <xs:attribute name='requests' type='xs:byte' use='optional'/>
       <xs:attribute name='rid' type='xs:positiveInteger' use='optional'/>
       <xs:attribute name='route' type='xs:string' use='optional'/>
       <xs:attribute name='secure' type='xs:boolean' use='optional' default='false'/>
       <xs:attribute name='sid' type='xs:string' use='optional'/>
       <xs:attribute name='stream' type='xs:string' use='optional'/>
+      <xs:attribute name='time' type='xs:short' use='optional'/>
       <xs:attribute name='to' type='xs:string' use='optional'/>
       <xs:attribute name='type' type='xs:string' use='optional'>
         <xs:simpleType>