Ignore:
Timestamp:
02/09/12 06:17:24 (8 years ago)
Author:
fielding@…
Message:

(editorial) reorder method sections by common and related use

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p2-semantics.xml

    r1849 r1850  
    653653<section title="Method Definitions" anchor="method.definitions">
    654654
    655 <section title="OPTIONS" anchor="OPTIONS">
    656   <rdf:Description>
    657     <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
    658     <idempotent xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</idempotent>
    659   </rdf:Description>
    660   <iref primary="true" item="OPTIONS method" x:for-anchor=""/>
    661   <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/>
    662 <t>
    663    The OPTIONS method requests information about the
    664    communication options available on the request/response chain
    665    identified by the effective request URI. This method allows a client to
    666    determine the options and/or requirements associated with a resource,
    667    or the capabilities of a server, without implying a resource action
    668    or initiating a resource retrieval.
    669 </t>
    670 <t>
    671    Responses to the OPTIONS method are not cacheable.
    672 </t>
    673 <t>
    674    If the OPTIONS request includes a message body (as indicated by the
    675    presence of <x:ref>Content-Length</x:ref> or <x:ref>Transfer-Encoding</x:ref>),
    676    then the media type &MUST; be indicated by a <x:ref>Content-Type</x:ref>
    677    field. Although this specification does not define any use for such a body,
    678    future extensions to HTTP might use the OPTIONS body to make more detailed
    679    queries on the server.
    680 </t>
    681 <t>
    682    If the request-target (&request-target;) is an asterisk ("*"),
    683    the OPTIONS request is
    684    intended to apply to the server in general rather than to a specific
    685    resource. Since a server's communication options typically depend on
    686    the resource, the "*" request is only useful as a "ping" or "no-op"
    687    type of method; it does nothing beyond allowing the client to test
    688    the capabilities of the server. For example, this can be used to test
    689    a proxy for HTTP/1.1 conformance (or lack thereof).
    690 </t>
    691 <t>
    692    If the request-target is not an asterisk, the OPTIONS request applies
    693    only to the options that are available when communicating with that
    694    resource.
    695 </t>
    696 <t>
    697    A <x:ref>200 (OK)</x:ref> response &SHOULD; include any header fields that
    698    indicate optional features implemented by the server and applicable to that
    699    resource (e.g., <x:ref>Allow</x:ref>), possibly including extensions not
    700    defined by this specification. The response body, if any, &SHOULD; also
    701    include information about the communication options. The format for such a
    702    body is not defined by this specification, but might be defined by
    703    future extensions to HTTP. Content negotiation &MAY; be used to select
    704    the appropriate response format. If no response body is included, the
    705    response &MUST; include a <x:ref>Content-Length</x:ref> field with a
    706    field-value of "0".
    707 </t>
    708 <t>
    709    The <x:ref>Max-Forwards</x:ref> header field &MAY; be used to target a
    710    specific proxy in the request chain (see <xref target="header.max-forwards"/>).
    711    If no Max-Forwards field is present in the request, then the forwarded
    712    request &MUST-NOT; include a Max-Forwards field.
    713 </t>
    714 </section>
    715 
    716655<section title="GET" anchor="GET">
    717656  <rdf:Description>
     
    1014953</section>
    1015954
     955<section title="CONNECT" anchor="CONNECT">
     956  <iref primary="true" item="CONNECT method" x:for-anchor=""/>
     957  <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/>
     958<t>
     959   The CONNECT method requests that the proxy establish a tunnel
     960   to the request-target and, if successful, thereafter restrict its behavior
     961   to blind forwarding of packets until the connection is closed.
     962</t>
     963<t>
     964   When using CONNECT, the request-target &MUST; use the authority form
     965   (&request-target;); i.e., the request-target consists of only the
     966   host name and port number of the tunnel destination, separated by a colon.
     967   For example,
     968</t>
     969<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
     970CONNECT server.example.com:80 HTTP/1.1
     971Host: server.example.com:80
     972
     973</artwork></figure>
     974<t>
     975   Any <x:ref>2xx (Successful)</x:ref> response to a CONNECT request indicates that the
     976   proxy has established a connection to the requested host and port,
     977   and has switched to tunneling the current connection to that server
     978   connection.
     979   The tunneled data from the server begins immediately after the blank line
     980   that concludes the successful response's header block.
     981</t>
     982<t>
     983   A server &SHOULD-NOT; send any <x:ref>Transfer-Encoding</x:ref> or
     984   <x:ref>Content-Length</x:ref> header fields in a successful response.
     985   A client &MUST; ignore any Content-Length or Transfer-Encoding header
     986   fields received in a successful response.
     987</t>
     988<t>
     989   Any response other than a successful response indicates that the tunnel
     990   has not yet been formed and that the connection remains governed by HTTP.
     991</t>
     992<t>
     993   Proxy authentication might be used to establish the
     994   authority to create a tunnel:
     995</t>
     996<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
     997CONNECT server.example.com:80 HTTP/1.1
     998Host: server.example.com:80
     999Proxy-Authorization: basic aGVsbG86d29ybGQ=
     1000
     1001</artwork></figure>
     1002<t>
     1003   A message body on a CONNECT request has no defined semantics. Sending a
     1004   body on a CONNECT request might cause existing implementations to reject
     1005   the request.
     1006</t>
     1007<t>
     1008   Similar to a pipelined HTTP/1.1 request, data to be tunneled from client
     1009   to server &MAY; be sent immediately after the request (before a response
     1010   is received). The usual caveats also apply:
     1011   data can be discarded if the eventual response is negative, and the
     1012   connection can be reset with no response if more than one TCP segment
     1013   is outstanding.
     1014</t>
     1015<t>
     1016   It might be the case that the proxy itself can only reach the requested
     1017   origin server through another proxy.  In this case, the first proxy
     1018   &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel
     1019   to the authority.  A proxy &MUST-NOT; respond with any <x:ref>2xx</x:ref> status code
     1020   unless it has either a direct or tunnel connection established to the
     1021   authority.
     1022</t>
     1023<t>
     1024   If at any point either one of the peers gets disconnected, any
     1025   outstanding data that came from that peer will be passed to the other
     1026   one, and after that also the other connection will be terminated by
     1027   the proxy. If there is outstanding data to that peer undelivered,
     1028   that data will be discarded.
     1029</t>
     1030<t>
     1031   An origin server which receives a CONNECT request for itself &MAY;
     1032   respond with a <x:ref>2xx</x:ref> status code to indicate that a connection is
     1033   established.  However, most origin servers do not implement CONNECT.
     1034</t>
     1035</section>
     1036
     1037<section title="OPTIONS" anchor="OPTIONS">
     1038  <rdf:Description>
     1039    <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
     1040    <idempotent xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</idempotent>
     1041  </rdf:Description>
     1042  <iref primary="true" item="OPTIONS method" x:for-anchor=""/>
     1043  <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/>
     1044<t>
     1045   The OPTIONS method requests information about the
     1046   communication options available on the request/response chain
     1047   identified by the effective request URI. This method allows a client to
     1048   determine the options and/or requirements associated with a resource,
     1049   or the capabilities of a server, without implying a resource action
     1050   or initiating a resource retrieval.
     1051</t>
     1052<t>
     1053   Responses to the OPTIONS method are not cacheable.
     1054</t>
     1055<t>
     1056   If the OPTIONS request includes a message body (as indicated by the
     1057   presence of <x:ref>Content-Length</x:ref> or <x:ref>Transfer-Encoding</x:ref>),
     1058   then the media type &MUST; be indicated by a <x:ref>Content-Type</x:ref>
     1059   field. Although this specification does not define any use for such a body,
     1060   future extensions to HTTP might use the OPTIONS body to make more detailed
     1061   queries on the server.
     1062</t>
     1063<t>
     1064   If the request-target (&request-target;) is an asterisk ("*"),
     1065   the OPTIONS request is
     1066   intended to apply to the server in general rather than to a specific
     1067   resource. Since a server's communication options typically depend on
     1068   the resource, the "*" request is only useful as a "ping" or "no-op"
     1069   type of method; it does nothing beyond allowing the client to test
     1070   the capabilities of the server. For example, this can be used to test
     1071   a proxy for HTTP/1.1 conformance (or lack thereof).
     1072</t>
     1073<t>
     1074   If the request-target is not an asterisk, the OPTIONS request applies
     1075   only to the options that are available when communicating with that
     1076   resource.
     1077</t>
     1078<t>
     1079   A <x:ref>200 (OK)</x:ref> response &SHOULD; include any header fields that
     1080   indicate optional features implemented by the server and applicable to that
     1081   resource (e.g., <x:ref>Allow</x:ref>), possibly including extensions not
     1082   defined by this specification. The response body, if any, &SHOULD; also
     1083   include information about the communication options. The format for such a
     1084   body is not defined by this specification, but might be defined by
     1085   future extensions to HTTP. Content negotiation &MAY; be used to select
     1086   the appropriate response format. If no response body is included, the
     1087   response &MUST; include a <x:ref>Content-Length</x:ref> field with a
     1088   field-value of "0".
     1089</t>
     1090<t>
     1091   The <x:ref>Max-Forwards</x:ref> header field &MAY; be used to target a
     1092   specific proxy in the request chain (see <xref target="header.max-forwards"/>).
     1093   If no Max-Forwards field is present in the request, then the forwarded
     1094   request &MUST-NOT; include a Max-Forwards field.
     1095</t>
     1096</section>
     1097
    10161098<section title="TRACE" anchor="TRACE">
    10171099  <rdf:Description>
     
    10461128</t>
    10471129</section>
    1048 
    1049 <section title="CONNECT" anchor="CONNECT">
    1050   <iref primary="true" item="CONNECT method" x:for-anchor=""/>
    1051   <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/>
    1052 <t>
    1053    The CONNECT method requests that the proxy establish a tunnel
    1054    to the request-target and, if successful, thereafter restrict its behavior
    1055    to blind forwarding of packets until the connection is closed.
    1056 </t>
    1057 <t>
    1058    When using CONNECT, the request-target &MUST; use the authority form
    1059    (&request-target;); i.e., the request-target consists of only the
    1060    host name and port number of the tunnel destination, separated by a colon.
    1061    For example,
    1062 </t>
    1063 <figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
    1064 CONNECT server.example.com:80 HTTP/1.1
    1065 Host: server.example.com:80
    1066 
    1067 </artwork></figure>
    1068 <t>
    1069    Any <x:ref>2xx (Successful)</x:ref> response to a CONNECT request indicates that the
    1070    proxy has established a connection to the requested host and port,
    1071    and has switched to tunneling the current connection to that server
    1072    connection.
    1073    The tunneled data from the server begins immediately after the blank line
    1074    that concludes the successful response's header block.
    1075 </t>
    1076 <t>
    1077    A server &SHOULD-NOT; send any <x:ref>Transfer-Encoding</x:ref> or
    1078    <x:ref>Content-Length</x:ref> header fields in a successful response.
    1079    A client &MUST; ignore any Content-Length or Transfer-Encoding header
    1080    fields received in a successful response.
    1081 </t>
    1082 <t>
    1083    Any response other than a successful response indicates that the tunnel
    1084    has not yet been formed and that the connection remains governed by HTTP.
    1085 </t>
    1086 <t>
    1087    Proxy authentication might be used to establish the
    1088    authority to create a tunnel:
    1089 </t>
    1090 <figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
    1091 CONNECT server.example.com:80 HTTP/1.1
    1092 Host: server.example.com:80
    1093 Proxy-Authorization: basic aGVsbG86d29ybGQ=
    1094 
    1095 </artwork></figure>
    1096 <t>
    1097    A message body on a CONNECT request has no defined semantics. Sending a
    1098    body on a CONNECT request might cause existing implementations to reject
    1099    the request.
    1100 </t>
    1101 <t>
    1102    Similar to a pipelined HTTP/1.1 request, data to be tunneled from client
    1103    to server &MAY; be sent immediately after the request (before a response
    1104    is received). The usual caveats also apply:
    1105    data can be discarded if the eventual response is negative, and the
    1106    connection can be reset with no response if more than one TCP segment
    1107    is outstanding.
    1108 </t>
    1109 <t>
    1110    It might be the case that the proxy itself can only reach the requested
    1111    origin server through another proxy.  In this case, the first proxy
    1112    &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel
    1113    to the authority.  A proxy &MUST-NOT; respond with any <x:ref>2xx</x:ref> status code
    1114    unless it has either a direct or tunnel connection established to the
    1115    authority.
    1116 </t>
    1117 <t>
    1118    If at any point either one of the peers gets disconnected, any
    1119    outstanding data that came from that peer will be passed to the other
    1120    one, and after that also the other connection will be terminated by
    1121    the proxy. If there is outstanding data to that peer undelivered,
    1122    that data will be discarded.
    1123 </t>
    1124 <t>
    1125    An origin server which receives a CONNECT request for itself &MAY;
    1126    respond with a <x:ref>2xx</x:ref> status code to indicate that a connection is
    1127    established.  However, most origin servers do not implement CONNECT.
    1128 </t>
    1129 </section>
    1130 </section>
    1131 
     1130</section>
    11321131</section>
    11331132
Note: See TracChangeset for help on using the changeset viewer.