1.10rc1

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

xep-0124.xml

@@ -11,6 +11,7 @@
     &LEGALNOTICE;
     <number>0124</number>
     <status>Draft</status>
+    <interim/>
     <type>Standards Track</type>
     <jig>Standards</jig>
     <dependencies>
@@ -28,6 +29,12 @@
     &dizzyd;
     &stpeter;
     &metajack;
+    <revision>
+      <version>1.10rc1</version>
+      <date>in progress, last updated 2010-06-10</date>
+      <initials>psa</initials>
+      <remark><p>Further clarified use of 'from' and 'to' attributes.</p></remark>
+    </revision>
     <revision>
       <version>1.9</version>
       <date>2009-11-06</date>
@@ -238,22 +245,23 @@
         <li><strong>'hold'</strong> -- This attribute specifies the maximum number of requests the connection manager is allowed to keep waiting at any one time during the session. If the client is not able to use HTTP Pipelining then this SHOULD be set to "1".</li>
       </ul>
       <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 both 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 (for XMPP) <cite>RFC 5122</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 hostname of the machine that is serving the domain.)</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:example.com: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 (for XMPP) <cite>RFC 5122</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 hostname 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>The &lt;body/&gt; element of the first request MAY also possess a <strong>'from'</strong> attribute, which specifies the originator of the first stream and which enables the connection manager to forward the originating entity's identity to the application server (e.g., the JabberID of an entity that is connecting to an XMPP server; see <cite>XEP-0206</cite>).</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>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 a BOSH session">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 104
 
 <body content='text/xml; charset=utf-8'
+      from='user@example.com'
       hold='1'
       rid='1573741820'
-      to='jabber.org'
+      to='example.com'
-      route='xmpp:jabber.org:9999'
+      route='xmpp:example.com:9999'
       ver='1.6'
       wait='60'
       ack='1'
@@ -274,6 +282,7 @@ Content-Length: 104
         <li><strong>'inactivity'</strong> -- This attribute specifies the longest allowable inactivity period (in seconds). This enables the client to ensure that the periods with no requests pending are never too long (see <link url="#poll">Polling Sessions</link> and <link url="#inactive">Inactivity</link>).</li>
         <li><strong>'requests'</strong> -- This attribute enables the connection manager to limit the number of simultaneous requests the client makes (see <link url="#overactive">Overactivity</link> and <link url="#poll">Polling Sessions</link>). The RECOMMENDED values are either "2" or one more than the value of the 'hold' attribute specified in the session request.</li>
         <li><strong>'hold'</strong> -- This attribute informs the client about the maximum number of requests the connection manager will 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>
+        <li><strong>'to'</strong> -- This attribute communicates the identity of the backend server to which the client is attempting to connect.</li>
       </ul>
       <p>The connection manager MAY include an <strong>'accept'</strong> attribute in the session creation response element, to specify a space-separated list of 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>
@@ -296,7 +305,7 @@ Content-Length: 128
       sid='SomeSID'
       charsets='ISO_8859-1 ISO-2022-JP'
       ver='1.6'
-      from='jabber.org'
+      from='example.com'
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
 
 
@@ -305,7 +314,7 @@ Content-Length: 128
 Content-Type: text/xml; charset=utf-8
 Content-Length: 128
 
-<body from='jabber.org'
+<body from='example.com'
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
     </section2>
   </section1>
@@ -313,7 +322,7 @@ Content-Length: 128
     <p>After the client has successfully completed all required preconditions, it can send and receive XML payloads via the HTTP binding.</p>
     <example caption="Transmitting payloads">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 188
@@ -386,7 +395,7 @@ Content-Length: 185
     <p>The client MAY poll the connection manager for incoming payloads by sending an empty &lt;body/&gt; element.</p>
     <example caption="Requesting XML Payloads">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 88
@@ -413,7 +422,7 @@ Content-Length: 64
       <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 in the case 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. The only exception is 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
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 88
@@ -442,7 +451,7 @@ Content-Length: 64
     <p>If a client encounters an exceptional temporary situation during which it will be unable to send requests to the connection manager for a period of time greater than the maximum inactivity period (e.g., while a runtime environment changes from one web page to another), and if the connection manager included a 'maxpause' attribute in its <link url="#session-create">Session Creation Response</link>, then the client MAY request a temporary increase to the maximum inactivity period by including a 'pause' attribute in a request. Note: If the connection manager did not specify a 'maxpause' attribute at the start of the session then the client MUST NOT send a 'pause' attribute during the session.</p>
     <example caption="Requesting a Session Pause">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 98
@@ -496,7 +505,7 @@ Content-Length: 68
     <p>At any time, the client MAY gracefully terminate the session by sending a &lt;body/&gt; element with a 'type' attribute set to "terminate". The termination request MAY include one or more payloads that the connection manager MUST forward to the server to ensure graceful logoff.</p>
     <example caption="Session termination by client">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 153
@@ -571,7 +580,7 @@ Content-Length: 68
       <p>The client MUST set the 'newkey' attribute of the first request in the session to the value K(n).</p>
       <example caption="Session Request with Initial Key">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 104
@@ -579,7 +588,7 @@ Content-Length: 104
 <body content='text/xml; charset=utf-8'
       hold='1'
       rid='1573741820'
-      to='jabber.org'
+      to='example.com'
       wait='60'
       xml:lang='en'
       newkey='ca393b51b682f61f98e7877d61146407f3d0a770'
@@ -587,7 +596,7 @@ Content-Length: 104
     <p>The client MUST set the 'key' attribute of all subsequent requests to the value of the next key in the generated sequence (decrementing from K(n-1) towards K(1) with each request sent).</p>
     <example caption="Request with Key">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 88
@@ -617,7 +626,7 @@ Content-Length: 68
       </ol>
       <example caption="New Key Sequence">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 188
@@ -658,22 +667,22 @@ Content-Length: 128
       sid='SomeSID'
       charsets='ISO_8859-1 ISO-2022-JP'
       ver='1.6'
-      from='jabber.org'
+      from='example.com'
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
     </section2>
     <section2 topic="Adding Streams To A Session" anchor='multi-add'>
       <p>If the connection manager included a 'stream' attribute in its session creation response then the client MAY ask it to open another stream at any time by sending it an empty &lt;body/&gt; element with a 'to' attribute. The request MUST include valid 'sid' and 'rid' <note>The 'rid' attribute is always incremented normally without reference to any 'stream' attribute.</note> attributes, and SHOULD also include an 'xml:lang' attribute. The request MAY include 'route', 'from' and 'secure' attributes (see <link url="#session-request">Session Creation Request</link>), but it SHOULD NOT include 'ver', 'content', 'hold' or 'wait' attributes (since a new session is not being created).</p>
       <example caption="Requesting another stream">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 104
 
 <body sid='SomeSID'
       rid='1573741820'
-      to='jabber.org'
+      to='example.com'
-      route='xmpp:jabber.org:9999'
+      route='xmpp:example.com:9999'
       xml:lang='en'
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
       <p>If the connection manager did not indicate its support for multiple streams at the start of the session, then it MUST ignore the extra attributes and treat the request as a normal empty request for payloads (see <link url="#payloads">Sending and Receiving XML Payloads</link>). <note>This helps to ensure backwards-compatibility with older implementations.</note> Otherwise it MUST open a new stream with the specified server (see <link url="#session-create">Session Creation Response</link>), generate a new stream name, and respond to the client with the name. The response MAY also include 'from' and 'secure' attributes, but it SHOULD NOT include 'sid', 'requests', 'polling', 'hold', 'inactivity', 'maxpause', 'accept', 'charsets', 'ver' or 'wait' attributes.</p>
@@ -683,7 +692,7 @@ Content-Type: text/xml; charset=utf-8
 Content-Length: 128
 
 <body stream='secondStreamName'
-      from='jabber.org'
+      from='example.com'
       xmlns='http://jabber.org/protocol/httpbind'/>]]></example>
       <p>Note: If the response did not include either 'from' or 'secure' attributes then they MAY be sent in a subsequent response instead (see <link url="#session-create">Session Creation Response</link>). In that case the 'stream' attribute MUST also be specified.</p>
     </section2>
@@ -693,7 +702,7 @@ Content-Length: 128
       <p>Note: Empty &lt;body/&gt; elements that do not include a 'from' or 'secure' attribute SHOULD NOT include a 'stream' attribute (since nothing is being transmitted for any stream). If such a &lt;body/&gt; element does include a 'stream' attribute then the receiving entity SHOULD ignore the attribute.</p>
     <example caption="Client sends payload with a stream name">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 188
@@ -725,7 +734,7 @@ Content-Length: 185
       <p>If no stream name is specified by the client then the connection manager MUST broadcast the payloads over all open streams. <note>The broadcast payloads can be of any type.</note></p>
     <example caption="Client asks for a payload to be broadcast">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 188
@@ -742,7 +751,7 @@ Content-Length: 188
       <p>If more than one stream is open within a session, the client MAY close one open stream at any time using the procedure described in the section <link url="#terminate">Terminating the HTTP Session</link> above, taking care to specify the stream name with a 'stream' attribute. If the client closes the last stream the connection manager MUST terminate the session. If the client does not specify a stream name then the connection manager MUST close all open streams (sending any payloads the terminate request contains to all streams), and terminate the session.</p>
       <example caption="Client closes one stream">
 <![CDATA[POST /webclient HTTP/1.1
-Host: httpcm.jabber.org
+Host: httpcm.example.com
 Accept-Encoding: gzip, deflate
 Content-Type: text/xml; charset=utf-8
 Content-Length: 153