| 707 | | <h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a> <a id="introduction" href="#introduction">Introduction</a></h1> |
| 708 | | <p id="rfc.section.1.p.1">The Hypertext Transfer Protocol (HTTP) is an application-level request/response protocol that uses extensible semantics and |
| 709 | | self-descriptive message payloads for flexible interaction with network-based hypertext information systems. This document |
| 710 | | is the first in a series of documents that collectively form the HTTP/1.1 specification: |
| 711 | | </p> |
| 712 | | <ul class="empty"> |
| 713 | | <li>RFC xxx1: Message Syntax and Routing</li> |
| 714 | | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content" id="rfc.xref.Part2.1">RFC xxx2</cite>: Semantics and Content |
| 715 | | </li> |
| 716 | | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests" id="rfc.xref.Part4.1">RFC xxx3</cite>: Conditional Requests |
| 717 | | </li> |
| 718 | | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests" id="rfc.xref.Part5.1">RFC xxx4</cite>: Range Requests |
| 719 | | </li> |
| 720 | | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching" id="rfc.xref.Part6.1">RFC xxx5</cite>: Caching |
| 721 | | </li> |
| 722 | | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication" id="rfc.xref.Part7.1">RFC xxx6</cite>: Authentication |
| 723 | | </li> |
| 724 | | </ul> |
| 725 | | <p id="rfc.section.1.p.2">This HTTP/1.1 specification obsoletes and moves to historic status <cite title="Hypertext Transfer Protocol -- HTTP/1.1" id="rfc.xref.RFC2616.1">RFC 2616</cite>, its predecessor <cite title="Hypertext Transfer Protocol -- HTTP/1.1" id="rfc.xref.RFC2068.1">RFC 2068</cite>, and <cite title="Use and Interpretation of HTTP Version Numbers" id="rfc.xref.RFC2145.1">RFC 2145</cite> (on HTTP versioning). This specification also updates the use of CONNECT to establish a tunnel, previously defined in <cite title="Upgrading to TLS Within HTTP/1.1" id="rfc.xref.RFC2817.1">RFC 2817</cite>, and defines the "https" URI scheme that was described informally in <cite title="HTTP Over TLS" id="rfc.xref.RFC2818.1">RFC 2818</cite>. |
| 726 | | </p> |
| 727 | | <p id="rfc.section.1.p.3">HTTP is a generic interface protocol for information systems. It is designed to hide the details of how a service is implemented |
| 728 | | by presenting a uniform interface to clients that is independent of the types of resources provided. Likewise, servers do |
| 729 | | not need to be aware of each client's purpose: an HTTP request can be considered in isolation rather than being associated |
| 730 | | with a specific type of client or a predetermined sequence of application steps. The result is a protocol that can be used |
| 731 | | effectively in many different contexts and for which implementations can evolve independently over time. |
| 732 | | </p> |
| 733 | | <p id="rfc.section.1.p.4">HTTP is also designed for use as an intermediation protocol for translating communication to and from non-HTTP information |
| 734 | | systems. HTTP proxies and gateways can provide access to alternative information services by translating their diverse protocols |
| 735 | | into a hypertext format that can be viewed and manipulated by clients in the same way as HTTP services. |
| 736 | | </p> |
| 737 | | <p id="rfc.section.1.p.5">One consequence of this flexibility is that the protocol cannot be defined in terms of what occurs behind the interface. Instead, |
| 738 | | we are limited to defining the syntax of communication, the intent of received communication, and the expected behavior of |
| 739 | | recipients. If the communication is considered in isolation, then successful actions ought to be reflected in corresponding |
| 740 | | changes to the observable interface provided by servers. However, since multiple clients might act in parallel and perhaps |
| 741 | | at cross-purposes, we cannot require that such changes be observable beyond the scope of a single response. |
| 742 | | </p> |
| 743 | | <p id="rfc.section.1.p.6">This document describes the architectural elements that are used or referred to in HTTP, defines the "http" and "https" URI |
| 744 | | schemes, describes overall network operation and connection management, and defines HTTP message framing and forwarding requirements. |
| 745 | | Our goal is to define all of the mechanisms necessary for HTTP message handling that are independent of message semantics, |
| 746 | | thereby defining the complete set of requirements for message parsers and message-forwarding intermediaries. |
| 747 | | </p> |
| 748 | | <h2 id="rfc.section.1.1"><a href="#rfc.section.1.1">1.1</a> <a id="intro.requirements" href="#intro.requirements">Requirement Notation</a></h2> |
| 749 | | <p id="rfc.section.1.1.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" |
| 750 | | in this document are to be interpreted as described in <a href="#RFC2119" id="rfc.xref.RFC2119.1"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>. |
| 751 | | </p> |
| 752 | | <p id="rfc.section.1.1.p.2">Conformance criteria and considerations regarding error handling are defined in <a href="#conformance" title="Conformance and Error Handling">Section 2.5</a>. |
| 753 | | </p> |
| 754 | | <div id="rfc.iref.g.1"></div> |
| 755 | | <div id="rfc.iref.g.2"></div> |
| 756 | | <div id="rfc.iref.g.3"></div> |
| 757 | | <div id="rfc.iref.g.4"></div> |
| 758 | | <div id="rfc.iref.g.5"></div> |
| 759 | | <div id="rfc.iref.g.6"></div> |
| 760 | | <div id="rfc.iref.g.7"></div> |
| 761 | | <div id="rfc.iref.g.8"></div> |
| 762 | | <div id="rfc.iref.g.9"></div> |
| 763 | | <div id="rfc.iref.g.10"></div> |
| 764 | | <div id="rfc.iref.g.11"></div> |
| 765 | | <div id="rfc.iref.g.12"></div> |
| 766 | | <h2 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2</a> <a id="notation" href="#notation">Syntax Notation</a></h2> |
| 767 | | <p id="rfc.section.1.2.p.1">This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a href="#RFC5234" id="rfc.xref.RFC5234.1"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC5234]</cite></a> with the list rule extension defined in <a href="#abnf.extension" title="ABNF list extension: #rule">Appendix B</a>. <a href="#collected.abnf" title="Collected ABNF">Appendix C</a> shows the collected ABNF with the list rule expanded. |
| 768 | | </p> |
| 769 | | <div id="core.rules"> |
| 770 | | <p id="rfc.section.1.2.p.2"> The following core rules are included by reference, as defined in <a href="#RFC5234" id="rfc.xref.RFC5234.2"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC5234]</cite></a>, <a href="http://tools.ietf.org/html/rfc5234#appendix-B.1">Appendix B.1</a>: ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG |
| 771 | | (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR |
| 772 | | (any visible <a href="#USASCII" id="rfc.xref.USASCII.1"><cite title="Coded Character Set -- 7-bit American Standard Code for Information Interchange">[USASCII]</cite></a> character). |
| | 725 | <div id="introduction"> |
| | 726 | <h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a> <a href="#introduction">Introduction</a></h1> |
| | 727 | <p id="rfc.section.1.p.1">The Hypertext Transfer Protocol (HTTP) is an application-level request/response protocol that uses extensible semantics and |
| | 728 | self-descriptive message payloads for flexible interaction with network-based hypertext information systems. This document |
| | 729 | is the first in a series of documents that collectively form the HTTP/1.1 specification: |
| | 731 | <ul class="empty"> |
| | 732 | <li>RFC xxx1: Message Syntax and Routing</li> |
| | 733 | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content" id="rfc.xref.Part2.1">RFC xxx2</cite>: Semantics and Content |
| | 734 | </li> |
| | 735 | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests" id="rfc.xref.Part4.1">RFC xxx3</cite>: Conditional Requests |
| | 736 | </li> |
| | 737 | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests" id="rfc.xref.Part5.1">RFC xxx4</cite>: Range Requests |
| | 738 | </li> |
| | 739 | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching" id="rfc.xref.Part6.1">RFC xxx5</cite>: Caching |
| | 740 | </li> |
| | 741 | <li><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication" id="rfc.xref.Part7.1">RFC xxx6</cite>: Authentication |
| | 742 | </li> |
| | 743 | </ul> |
| | 744 | <p id="rfc.section.1.p.2">This HTTP/1.1 specification obsoletes and moves to historic status <cite title="Hypertext Transfer Protocol -- HTTP/1.1" id="rfc.xref.RFC2616.1">RFC 2616</cite>, its predecessor <cite title="Hypertext Transfer Protocol -- HTTP/1.1" id="rfc.xref.RFC2068.1">RFC 2068</cite>, and <cite title="Use and Interpretation of HTTP Version Numbers" id="rfc.xref.RFC2145.1">RFC 2145</cite> (on HTTP versioning). This specification also updates the use of CONNECT to establish a tunnel, previously defined in <cite title="Upgrading to TLS Within HTTP/1.1" id="rfc.xref.RFC2817.1">RFC 2817</cite>, and defines the "https" URI scheme that was described informally in <cite title="HTTP Over TLS" id="rfc.xref.RFC2818.1">RFC 2818</cite>. |
| | 745 | </p> |
| | 746 | <p id="rfc.section.1.p.3">HTTP is a generic interface protocol for information systems. It is designed to hide the details of how a service is implemented |
| | 747 | by presenting a uniform interface to clients that is independent of the types of resources provided. Likewise, servers do |
| | 748 | not need to be aware of each client's purpose: an HTTP request can be considered in isolation rather than being associated |
| | 749 | with a specific type of client or a predetermined sequence of application steps. The result is a protocol that can be used |
| | 750 | effectively in many different contexts and for which implementations can evolve independently over time. |
| | 751 | </p> |
| | 752 | <p id="rfc.section.1.p.4">HTTP is also designed for use as an intermediation protocol for translating communication to and from non-HTTP information |
| | 753 | systems. HTTP proxies and gateways can provide access to alternative information services by translating their diverse protocols |
| | 754 | into a hypertext format that can be viewed and manipulated by clients in the same way as HTTP services. |
| | 755 | </p> |
| | 756 | <p id="rfc.section.1.p.5">One consequence of this flexibility is that the protocol cannot be defined in terms of what occurs behind the interface. Instead, |
| | 757 | we are limited to defining the syntax of communication, the intent of received communication, and the expected behavior of |
| | 758 | recipients. If the communication is considered in isolation, then successful actions ought to be reflected in corresponding |
| | 759 | changes to the observable interface provided by servers. However, since multiple clients might act in parallel and perhaps |
| | 760 | at cross-purposes, we cannot require that such changes be observable beyond the scope of a single response. |
| | 761 | </p> |
| | 762 | <p id="rfc.section.1.p.6">This document describes the architectural elements that are used or referred to in HTTP, defines the "http" and "https" URI |
| | 763 | schemes, describes overall network operation and connection management, and defines HTTP message framing and forwarding requirements. |
| | 764 | Our goal is to define all of the mechanisms necessary for HTTP message handling that are independent of message semantics, |
| | 765 | thereby defining the complete set of requirements for message parsers and message-forwarding intermediaries. |
| | 766 | </p> |
| | 767 | <div id="intro.requirements"> |
| | 768 | <h2 id="rfc.section.1.1"><a href="#rfc.section.1.1">1.1</a> <a href="#intro.requirements">Requirement Notation</a></h2> |
| | 769 | <p id="rfc.section.1.1.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" |
| | 770 | in this document are to be interpreted as described in <a href="#RFC2119" id="rfc.xref.RFC2119.1"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>. |
| | 771 | </p> |
| | 772 | <p id="rfc.section.1.1.p.2">Conformance criteria and considerations regarding error handling are defined in <a href="#conformance" title="Conformance and Error Handling">Section 2.5</a>. |
| | 773 | </p> |
| | 774 | </div> |
| | 775 | <div id="notation"> |
| | 776 | <div id="rfc.iref.g.1"></div> |
| | 777 | <div id="rfc.iref.g.2"></div> |
| | 778 | <div id="rfc.iref.g.3"></div> |
| | 779 | <div id="rfc.iref.g.4"></div> |
| | 780 | <div id="rfc.iref.g.5"></div> |
| | 781 | <div id="rfc.iref.g.6"></div> |
| | 782 | <div id="rfc.iref.g.7"></div> |
| | 783 | <div id="rfc.iref.g.8"></div> |
| | 784 | <div id="rfc.iref.g.9"></div> |
| | 785 | <div id="rfc.iref.g.10"></div> |
| | 786 | <div id="rfc.iref.g.11"></div> |
| | 787 | <div id="rfc.iref.g.12"></div> |
| | 788 | <h2 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2</a> <a href="#notation">Syntax Notation</a></h2> |
| | 789 | <p id="rfc.section.1.2.p.1">This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a href="#RFC5234" id="rfc.xref.RFC5234.1"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC5234]</cite></a> with the list rule extension defined in <a href="#abnf.extension" title="ABNF list extension: #rule">Appendix B</a>. <a href="#collected.abnf" title="Collected ABNF">Appendix C</a> shows the collected ABNF with the list rule expanded. |
| | 790 | </p> |
| | 791 | <div id="core.rules"> |
| | 792 | <p id="rfc.section.1.2.p.2"> The following core rules are included by reference, as defined in <a href="#RFC5234" id="rfc.xref.RFC5234.2"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC5234]</cite></a>, <a href="https://tools.ietf.org/html/rfc5234#appendix-B.1">Appendix B.1</a>: ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG |
| | 793 | (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR |
| | 794 | (any visible <a href="#USASCII" id="rfc.xref.USASCII.1"><cite title="Coded Character Set -- 7-bit American Standard Code for Information Interchange">[USASCII]</cite></a> character). |
| | 795 | </p> |
| | 796 | </div> |
| | 797 | <p id="rfc.section.1.2.p.3">As a convention, ABNF rule names prefixed with "obs-" denote "obsolete" grammar rules that appear for historical reasons.</p> |
| | 798 | </div> |
| 775 | | <p id="rfc.section.1.2.p.3">As a convention, ABNF rule names prefixed with "obs-" denote "obsolete" grammar rules that appear for historical reasons.</p> |
| 776 | | <h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> <a id="architecture" href="#architecture">Architecture</a></h1> |
| 777 | | <p id="rfc.section.2.p.1">HTTP was created for the World Wide Web architecture and has evolved over time to support the scalability needs of a worldwide |
| 778 | | hypertext system. Much of that architecture is reflected in the terminology and syntax productions used to define HTTP. |
| 779 | | </p> |
| 780 | | <div id="rfc.iref.c.1"></div> |
| 781 | | <div id="rfc.iref.s.1"></div> |
| 782 | | <div id="rfc.iref.c.2"></div> |
| 783 | | <h2 id="rfc.section.2.1"><a href="#rfc.section.2.1">2.1</a> <a id="operation" href="#operation">Client/Server Messaging</a></h2> |
| 784 | | <p id="rfc.section.2.1.p.1">HTTP is a stateless request/response protocol that operates by exchanging <dfn>messages</dfn> (<a href="#http.message" title="Message Format">Section 3</a>) across a reliable transport or session-layer "<dfn>connection</dfn>" (<a href="#connection.management" title="Connection Management">Section 6</a>). An HTTP "<dfn>client</dfn>" is a program that establishes a connection to a server for the purpose of sending one or more HTTP requests. An HTTP "<dfn>server</dfn>" is a program that accepts connections in order to service HTTP requests by sending HTTP responses. |
| 785 | | </p> |
| 786 | | <div id="rfc.iref.u.1"></div> |
| 787 | | <div id="rfc.iref.o.1"></div> |
| 788 | | <div id="rfc.iref.b.1"></div> |
| 789 | | <div id="rfc.iref.s.2"></div> |
| 790 | | <div id="rfc.iref.s.3"></div> |
| 791 | | <div id="rfc.iref.r.1"></div> |
| 792 | | <p id="rfc.section.2.1.p.2">The terms client and server refer only to the roles that these programs perform for a particular connection. The same program |
| 793 | | might act as a client on some connections and a server on others. We use the term "<dfn>user agent</dfn>" to refer to any of the various client programs that initiate a request, including (but not limited to) browsers, spiders |
| 794 | | (web-based robots), command-line tools, native applications, and mobile apps. The term "<dfn>origin server</dfn>" is used to refer to the program that can originate authoritative responses to a request. For general requirements, we use |
| 795 | | the terms "<dfn>sender</dfn>" and "<dfn>recipient</dfn>" to refer to any component that sends or receives, respectively, a given message. |
| 796 | | </p> |
| 797 | | <p id="rfc.section.2.1.p.3">HTTP relies upon the Uniform Resource Identifier (URI) standard <a href="#RFC3986" id="rfc.xref.RFC3986.1"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> to indicate the target resource (<a href="#target-resource" title="Identifying a Target Resource">Section 5.1</a>) and relationships between resources. Messages are passed in a format similar to that used by Internet mail <a href="#RFC5322" id="rfc.xref.RFC5322.1"><cite title="Internet Message Format">[RFC5322]</cite></a> and the Multipurpose Internet Mail Extensions (MIME) <a href="#RFC2045" id="rfc.xref.RFC2045.1"><cite title="Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies">[RFC2045]</cite></a> (see <a href="p2-semantics.html#differences.between.http.and.mime" title="Differences between HTTP and MIME">Appendix A</a> of <a href="#Part2" id="rfc.xref.Part2.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> for the differences between HTTP and MIME messages). |
| 798 | | </p> |
| 799 | | <p id="rfc.section.2.1.p.4">Most HTTP communication consists of a retrieval request (GET) for a representation of some resource identified by a URI. In |
| 800 | | the simplest case, this might be accomplished via a single bidirectional connection (===) between the user agent (UA) and |
| 801 | | the origin server (O). |
| 802 | | </p> |
| 803 | | <div id="rfc.figure.u.1"></div><pre class="drawing"> request > |
| | 800 | <div id="architecture"> |
| | 801 | <h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> <a href="#architecture">Architecture</a></h1> |
| | 802 | <p id="rfc.section.2.p.1">HTTP was created for the World Wide Web architecture and has evolved over time to support the scalability needs of a worldwide |
| | 803 | hypertext system. Much of that architecture is reflected in the terminology and syntax productions used to define HTTP. |
| | 804 | </p> |
| | 805 | <div id="operation"> |
| | 806 | <div id="rfc.iref.c.1"></div> |
| | 807 | <div id="rfc.iref.s.1"></div> |
| | 808 | <div id="rfc.iref.c.2"></div> |
| | 809 | <h2 id="rfc.section.2.1"><a href="#rfc.section.2.1">2.1</a> <a href="#operation">Client/Server Messaging</a></h2> |
| | 810 | <p id="rfc.section.2.1.p.1">HTTP is a stateless request/response protocol that operates by exchanging <dfn>messages</dfn> (<a href="#http.message" title="Message Format">Section 3</a>) across a reliable transport or session-layer "<dfn>connection</dfn>" (<a href="#connection.management" title="Connection Management">Section 6</a>). An HTTP "<dfn>client</dfn>" is a program that establishes a connection to a server for the purpose of sending one or more HTTP requests. An HTTP "<dfn>server</dfn>" is a program that accepts connections in order to service HTTP requests by sending HTTP responses. |
| | 811 | </p> |
| | 812 | <div id="rfc.iref.u.1"></div> |
| | 813 | <div id="rfc.iref.o.1"></div> |
| | 814 | <div id="rfc.iref.b.1"></div> |
| | 815 | <div id="rfc.iref.s.2"></div> |
| | 816 | <div id="rfc.iref.s.3"></div> |
| | 817 | <div id="rfc.iref.r.1"></div> |
| | 818 | <p id="rfc.section.2.1.p.2">The terms client and server refer only to the roles that these programs perform for a particular connection. The same program |
| | 819 | might act as a client on some connections and a server on others. We use the term "<dfn>user agent</dfn>" to refer to any of the various client programs that initiate a request, including (but not limited to) browsers, spiders |
| | 820 | (web-based robots), command-line tools, native applications, and mobile apps. The term "<dfn>origin server</dfn>" is used to refer to the program that can originate authoritative responses to a request. For general requirements, we use |
| | 821 | the terms "<dfn>sender</dfn>" and "<dfn>recipient</dfn>" to refer to any component that sends or receives, respectively, a given message. |
| | 822 | </p> |
| | 823 | <p id="rfc.section.2.1.p.3">HTTP relies upon the Uniform Resource Identifier (URI) standard <a href="#RFC3986" id="rfc.xref.RFC3986.1"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> to indicate the target resource (<a href="#target-resource" title="Identifying a Target Resource">Section 5.1</a>) and relationships between resources. Messages are passed in a format similar to that used by Internet mail <a href="#RFC5322" id="rfc.xref.RFC5322.1"><cite title="Internet Message Format">[RFC5322]</cite></a> and the Multipurpose Internet Mail Extensions (MIME) <a href="#RFC2045" id="rfc.xref.RFC2045.1"><cite title="Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies">[RFC2045]</cite></a> (see <a href="p2-semantics.html#differences.between.http.and.mime" title="Differences between HTTP and MIME">Appendix A</a> of <a href="#Part2" id="rfc.xref.Part2.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> for the differences between HTTP and MIME messages). |
| | 824 | </p> |
| | 825 | <p id="rfc.section.2.1.p.4">Most HTTP communication consists of a retrieval request (GET) for a representation of some resource identified by a URI. In |
| | 826 | the simplest case, this might be accomplished via a single bidirectional connection (===) between the user agent (UA) and |
| | 827 | the origin server (O). |
| | 828 | </p> |
| | 829 | <div id="rfc.figure.u.1"></div><pre class="drawing"> request > |
| 835 | | </span></pre> <p>(Note that the content length includes the trailing CR/LF sequence of the body text)</p> |
| 836 | | <h2 id="rfc.section.2.2"><a href="#rfc.section.2.2">2.2</a> <a id="implementation-diversity" href="#implementation-diversity">Implementation Diversity</a></h2> |
| 837 | | <p id="rfc.section.2.2.p.1">When considering the design of HTTP, it is easy to fall into a trap of thinking that all user agents are general-purpose browsers |
| 838 | | and all origin servers are large public websites. That is not the case in practice. Common HTTP user agents include household |
| 839 | | appliances, stereos, scales, firmware update scripts, command-line programs, mobile apps, and communication devices in a multitude |
| 840 | | of shapes and sizes. Likewise, common HTTP origin servers include home automation units, configurable networking components, |
| 841 | | office machines, autonomous robots, news feeds, traffic cameras, ad selectors, and video delivery platforms. |
| 842 | | </p> |
| 843 | | <p id="rfc.section.2.2.p.2">The term "user agent" does not imply that there is a human user directly interacting with the software agent at the time of |
| 844 | | a request. In many cases, a user agent is installed or configured to run in the background and save its results for later |
| 845 | | inspection (or save only a subset of those results that might be interesting or erroneous). Spiders, for example, are typically |
| 846 | | given a start URI and configured to follow certain behavior while crawling the Web as a hypertext graph. |
| 847 | | </p> |
| 848 | | <p id="rfc.section.2.2.p.3">The implementation diversity of HTTP means that we cannot assume the user agent can make interactive suggestions to a user |
| 849 | | or provide adequate warning for security or privacy options. In the few cases where this specification requires reporting |
| 850 | | of errors to the user, it is acceptable for such reporting to only be observable in an error console or log file. Likewise, |
| 851 | | requirements that an automated action be confirmed by the user before proceeding can be met via advance configuration choices, |
| 852 | | run-time options, or simply not proceeding with the unsafe action. |
| 853 | | </p> |
| 854 | | <div id="rfc.iref.i.1"></div> |
| 855 | | <h2 id="rfc.section.2.3"><a href="#rfc.section.2.3">2.3</a> <a id="intermediaries" href="#intermediaries">Intermediaries</a></h2> |
| 856 | | <p id="rfc.section.2.3.p.1">HTTP enables the use of intermediaries to satisfy requests through a chain of connections. There are three common forms of |
| 857 | | HTTP <dfn>intermediary</dfn>: proxy, gateway, and tunnel. In some cases, a single intermediary might act as an origin server, proxy, gateway, or tunnel, |
| 858 | | switching behavior based on the nature of each request. |
| 859 | | </p> |
| 860 | | <div id="rfc.figure.u.4"></div><pre class="drawing"> > > > > |
| | 861 | </span></pre><p>(Note that the content length includes the trailing CR/LF sequence of the body text)</p> |
| | 862 | </div> |
| | 863 | <div id="implementation-diversity"> |
| | 864 | <h2 id="rfc.section.2.2"><a href="#rfc.section.2.2">2.2</a> <a href="#implementation-diversity">Implementation Diversity</a></h2> |
| | 865 | <p id="rfc.section.2.2.p.1">When considering the design of HTTP, it is easy to fall into a trap of thinking that all user agents are general-purpose browsers |
| | 866 | and all origin servers are large public websites. That is not the case in practice. Common HTTP user agents include household |
| | 867 | appliances, stereos, scales, firmware update scripts, command-line programs, mobile apps, and communication devices in a multitude |
| | 868 | of shapes and sizes. Likewise, common HTTP origin servers include home automation units, configurable networking components, |
| | 869 | office machines, autonomous robots, news feeds, traffic cameras, ad selectors, and video delivery platforms. |
| | 870 | </p> |
| | 871 | <p id="rfc.section.2.2.p.2">The term "user agent" does not imply that there is a human user directly interacting with the software agent at the time of |
| | 872 | a request. In many cases, a user agent is installed or configured to run in the background and save its results for later |
| | 873 | inspection (or save only a subset of those results that might be interesting or erroneous). Spiders, for example, are typically |
| | 874 | given a start URI and configured to follow certain behavior while crawling the Web as a hypertext graph. |
| | 875 | </p> |
| | 876 | <p id="rfc.section.2.2.p.3">The implementation diversity of HTTP means that we cannot assume the user agent can make interactive suggestions to a user |
| | 877 | or provide adequate warning for security or privacy options. In the few cases where this specification requires reporting |
| | 878 | of errors to the user, it is acceptable for such reporting to only be observable in an error console or log file. Likewise, |
| | 879 | requirements that an automated action be confirmed by the user before proceeding can be met via advance configuration choices, |
| | 880 | run-time options, or simply not proceeding with the unsafe action. |
| | 881 | </p> |
| | 882 | </div> |
| | 883 | <div id="intermediaries"> |
| | 884 | <div id="rfc.iref.i.1"></div> |
| | 885 | <h2 id="rfc.section.2.3"><a href="#rfc.section.2.3">2.3</a> <a href="#intermediaries">Intermediaries</a></h2> |
| | 886 | <p id="rfc.section.2.3.p.1">HTTP enables the use of intermediaries to satisfy requests through a chain of connections. There are three common forms of |
| | 887 | HTTP <dfn>intermediary</dfn>: proxy, gateway, and tunnel. In some cases, a single intermediary might act as an origin server, proxy, gateway, or tunnel, |
| | 888 | switching behavior based on the nature of each request. |
| | 889 | </p> |
| | 890 | <div id="rfc.figure.u.4"></div><pre class="drawing"> > > > > |
| 864 | | message that travels the whole chain will pass through four separate connections. Some HTTP communication options might apply |
| 865 | | only to the connection with the nearest, non-tunnel neighbor, only to the end-points of the chain, or to all connections along |
| 866 | | the chain. Although the diagram is linear, each participant might be engaged in multiple, simultaneous communications. For |
| 867 | | example, B might be receiving requests from many clients other than A, and/or forwarding requests to servers other than C, |
| 868 | | at the same time that it is handling A's request. |
| 869 | | </p> |
| 870 | | <p id="rfc.section.2.3.p.4"> <span id="rfc.iref.u.2"></span><span id="rfc.iref.d.1"></span> <span id="rfc.iref.i.2"></span><span id="rfc.iref.o.2"></span> We use the terms "<dfn>upstream</dfn>" and "<dfn>downstream</dfn>" to describe various requirements in relation to the directional flow of a message: all messages flow from upstream to downstream. |
| 871 | | Likewise, we use the terms inbound and outbound to refer to directions in relation to the request path: "<dfn>inbound</dfn>" means toward the origin server and "<dfn>outbound</dfn>" means toward the user agent. |
| 872 | | </p> |
| 873 | | <p id="rfc.section.2.3.p.5"><span id="rfc.iref.p.1"></span> A "<dfn>proxy</dfn>" is a message forwarding agent that is selected by the client, usually via local configuration rules, to receive requests |
| 874 | | for some type(s) of absolute URI and attempt to satisfy those requests via translation through the HTTP interface. Some translations |
| 875 | | are minimal, such as for proxy requests for "http" URIs, whereas other requests might require translation to and from entirely |
| 876 | | different application-level protocols. Proxies are often used to group an organization's HTTP requests through a common intermediary |
| 877 | | for the sake of security, annotation services, or shared caching. |
| 878 | | </p> |
| 879 | | <p id="rfc.section.2.3.p.6"> <span id="rfc.iref.t.1"></span> <span id="rfc.iref.n.1"></span> An HTTP-to-HTTP proxy is called a "<dfn>transforming proxy</dfn>" if it is designed or configured to modify request or response messages in a semantically meaningful way (i.e., modifications, |
| 880 | | beyond those required by normal HTTP processing, that change the message in a way that would be significant to the original |
| 881 | | sender or potentially significant to downstream recipients). For example, a transforming proxy might be acting as a shared |
| 882 | | annotation server (modifying responses to include references to a local annotation database), a malware filter, a format transcoder, |
| 883 | | or an intranet-to-Internet privacy filter. Such transformations are presumed to be desired by the client (or client organization) |
| 884 | | that selected the proxy and are beyond the scope of this specification. However, when a proxy is not intended to transform |
| 885 | | a given message, we use the term "<dfn>non-transforming proxy</dfn>" to target requirements that preserve HTTP message semantics. See <a href="p2-semantics.html#status.203" title="203 Non-Authoritative Information">Section 6.3.4</a> of <a href="#Part2" id="rfc.xref.Part2.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> and <a href="p6-cache.html#header.warning" title="Warning">Section 7.5</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> for status and warning codes related to transformations. |
| 886 | | </p> |
| 887 | | <p id="rfc.section.2.3.p.7"><span id="rfc.iref.g.13"></span><span id="rfc.iref.r.4"></span> <span id="rfc.iref.a.1"></span> A "<dfn>gateway</dfn>" (a.k.a., "<dfn>reverse proxy</dfn>") is a receiving agent that acts as a layer above some other server(s) and translates the received requests to the underlying |
| 888 | | server's protocol. Gateways are often used to encapsulate legacy or untrusted information services, to improve server performance |
| 889 | | through "<dfn>accelerator</dfn>" caching, and to enable partitioning or load-balancing of HTTP services across multiple machines. |
| 890 | | </p> |
| 891 | | <p id="rfc.section.2.3.p.8">A gateway behaves as an origin server on its outbound connection and as a user agent on its inbound connection. All HTTP requirements |
| 892 | | applicable to an origin server also apply to the outbound communication of a gateway. A gateway communicates with inbound |
| 893 | | servers using any protocol that it desires, including private extensions to HTTP that are outside the scope of this specification. |
| 894 | | However, an HTTP-to-HTTP gateway that wishes to interoperate with third-party HTTP servers <em class="bcp14">MUST</em> conform to HTTP user agent requirements on the gateway's inbound connection and <em class="bcp14">MUST</em> implement the <a href="#header.connection" class="smpl">Connection</a> (<a href="#header.connection" id="rfc.xref.header.connection.1" title="Connection">Section 6.1</a>) and <a href="#header.via" class="smpl">Via</a> (<a href="#header.via" id="rfc.xref.header.via.1" title="Via">Section 5.7.1</a>) header fields for both connections. |
| 895 | | </p> |
| 896 | | <p id="rfc.section.2.3.p.9"><span id="rfc.iref.t.2"></span> A "<dfn>tunnel</dfn>" acts as a blind relay between two connections without changing the messages. Once active, a tunnel is not considered a party |
| 897 | | to the HTTP communication, though the tunnel might have been initiated by an HTTP request. A tunnel ceases to exist when both |
| 898 | | ends of the relayed connection are closed. Tunnels are used to extend a virtual connection through an intermediary, such as |
| 899 | | when Transport Layer Security (TLS, <a href="#RFC5246" id="rfc.xref.RFC5246.1"><cite title="The Transport Layer Security (TLS) Protocol Version 1.2">[RFC5246]</cite></a>) is used to establish confidential communication through a shared firewall proxy. |
| 900 | | </p> |
| 901 | | <p id="rfc.section.2.3.p.10"><span id="rfc.iref.i.3"></span> <span id="rfc.iref.t.3"></span> <span id="rfc.iref.c.3"></span> The above categories for intermediary only consider those acting as participants in the HTTP communication. There are also |
| 902 | | intermediaries that can act on lower layers of the network protocol stack, filtering or redirecting HTTP traffic without the |
| 903 | | knowledge or permission of message senders. Network intermediaries often introduce security flaws or interoperability problems |
| 904 | | by violating HTTP semantics. For example, an "<dfn>interception proxy</dfn>" <a href="#RFC3040" id="rfc.xref.RFC3040.1"><cite title="Internet Web Replication and Caching Taxonomy">[RFC3040]</cite></a> (also commonly known as a "<dfn>transparent proxy</dfn>" <a href="#RFC1919" id="rfc.xref.RFC1919.1"><cite title="Classical versus Transparent IP Proxies">[RFC1919]</cite></a> or "<dfn>captive portal</dfn>") differs from an HTTP proxy because it is not selected by the client. Instead, an interception proxy filters or redirects |
| 905 | | outgoing TCP port 80 packets (and occasionally other common port traffic). Interception proxies are commonly found on public |
| 906 | | network access points, as a means of enforcing account subscription prior to allowing use of non-local Internet services, |
| 907 | | and within corporate firewalls to enforce network usage policies. They are indistinguishable from a man-in-the-middle attack. |
| 908 | | </p> |
| 909 | | <p id="rfc.section.2.3.p.11">HTTP is defined as a stateless protocol, meaning that each request message can be understood in isolation. Many implementations |
| 910 | | depend on HTTP's stateless design in order to reuse proxied connections or dynamically load-balance requests across multiple |
| 911 | | servers. Hence, servers <em class="bcp14">MUST NOT</em> assume that two requests on the same connection are from the same user agent unless the connection is secured and specific |
| 912 | | to that agent. Some non-standard HTTP extensions (e.g., <a href="#RFC4559" id="rfc.xref.RFC4559.1"><cite title="SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows">[RFC4559]</cite></a>) have been known to violate this requirement, resulting in security and interoperability problems. |
| 913 | | </p> |
| 914 | | <div id="rfc.iref.c.4"></div> |
| 915 | | <h2 id="rfc.section.2.4"><a href="#rfc.section.2.4">2.4</a> <a id="caches" href="#caches">Caches</a></h2> |
| 916 | | <p id="rfc.section.2.4.p.1">A "<dfn>cache</dfn>" is a local store of previous response messages and the subsystem that controls its message storage, retrieval, and deletion. |
| 917 | | A cache stores cacheable responses in order to reduce the response time and network bandwidth consumption on future, equivalent |
| 918 | | requests. Any client or server <em class="bcp14">MAY</em> employ a cache, though a cache cannot be used by a server while it is acting as a tunnel. |
| 919 | | </p> |
| 920 | | <p id="rfc.section.2.4.p.2">The effect of a cache is that the request/response chain is shortened if one of the participants along the chain has a cached |
| 921 | | response applicable to that request. The following illustrates the resulting chain if B has a cached copy of an earlier response |
| 922 | | from O (via C) for a request that has not been cached by UA or A. |
| 923 | | </p> |
| 924 | | <div id="rfc.figure.u.5"></div><pre class="drawing"> > > |
| | 894 | message that travels the whole chain will pass through four separate connections. Some HTTP communication options might apply |
| | 895 | only to the connection with the nearest, non-tunnel neighbor, only to the end-points of the chain, or to all connections along |
| | 896 | the chain. Although the diagram is linear, each participant might be engaged in multiple, simultaneous communications. For |
| | 897 | example, B might be receiving requests from many clients other than A, and/or forwarding requests to servers other than C, |
| | 898 | at the same time that it is handling A's request. |
| | 899 | </p> |
| | 900 | <p id="rfc.section.2.3.p.4"><span id="rfc.iref.u.2"></span><span id="rfc.iref.d.1"></span> <span id="rfc.iref.i.2"></span><span id="rfc.iref.o.2"></span> We use the terms "<dfn>upstream</dfn>" and "<dfn>downstream</dfn>" to describe various requirements in relation to the directional flow of a message: all messages flow from upstream to downstream. |
| | 901 | Likewise, we use the terms inbound and outbound to refer to directions in relation to the request path: "<dfn>inbound</dfn>" means toward the origin server and "<dfn>outbound</dfn>" means toward the user agent. |
| | 902 | </p> |
| | 903 | <p id="rfc.section.2.3.p.5"><span id="rfc.iref.p.1"></span> A "<dfn>proxy</dfn>" is a message forwarding agent that is selected by the client, usually via local configuration rules, to receive requests |
| | 904 | for some type(s) of absolute URI and attempt to satisfy those requests via translation through the HTTP interface. Some translations |
| | 905 | are minimal, such as for proxy requests for "http" URIs, whereas other requests might require translation to and from entirely |
| | 906 | different application-level protocols. Proxies are often used to group an organization's HTTP requests through a common intermediary |
| | 907 | for the sake of security, annotation services, or shared caching. |
| | 908 | </p> |
| | 909 | <p id="rfc.section.2.3.p.6"><span id="rfc.iref.t.1"></span> <span id="rfc.iref.n.1"></span> An HTTP-to-HTTP proxy is called a "<dfn>transforming proxy</dfn>" if it is designed or configured to modify request or response messages in a semantically meaningful way (i.e., modifications, |
| | 910 | beyond those required by normal HTTP processing, that change the message in a way that would be significant to the original |
| | 911 | sender or potentially significant to downstream recipients). For example, a transforming proxy might be acting as a shared |
| | 912 | annotation server (modifying responses to include references to a local annotation database), a malware filter, a format transcoder, |
| | 913 | or an intranet-to-Internet privacy filter. Such transformations are presumed to be desired by the client (or client organization) |
| | 914 | that selected the proxy and are beyond the scope of this specification. However, when a proxy is not intended to transform |
| | 915 | a given message, we use the term "<dfn>non-transforming proxy</dfn>" to target requirements that preserve HTTP message semantics. See <a href="p2-semantics.html#status.203" title="203 Non-Authoritative Information">Section 6.3.4</a> of <a href="#Part2" id="rfc.xref.Part2.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> and <a href="p6-cache.html#header.warning" title="Warning">Section 7.5</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> for status and warning codes related to transformations. |
| | 916 | </p> |
| | 917 | <p id="rfc.section.2.3.p.7"><span id="rfc.iref.g.13"></span><span id="rfc.iref.r.4"></span> <span id="rfc.iref.a.1"></span> A "<dfn>gateway</dfn>" (a.k.a., "<dfn>reverse proxy</dfn>") is a receiving agent that acts as a layer above some other server(s) and translates the received requests to the underlying |
| | 918 | server's protocol. Gateways are often used to encapsulate legacy or untrusted information services, to improve server performance |
| | 919 | through "<dfn>accelerator</dfn>" caching, and to enable partitioning or load-balancing of HTTP services across multiple machines. |
| | 920 | </p> |
| | 921 | <p id="rfc.section.2.3.p.8">A gateway behaves as an origin server on its outbound connection and as a user agent on its inbound connection. All HTTP requirements |
| | 922 | applicable to an origin server also apply to the outbound communication of a gateway. A gateway communicates with inbound |
| | 923 | servers using any protocol that it desires, including private extensions to HTTP that are outside the scope of this specification. |
| | 924 | However, an HTTP-to-HTTP gateway that wishes to interoperate with third-party HTTP servers <em class="bcp14">MUST</em> conform to HTTP user agent requirements on the gateway's inbound connection and <em class="bcp14">MUST</em> implement the <a href="#header.connection" class="smpl">Connection</a> (<a href="#header.connection" id="rfc.xref.header.connection.1" title="Connection">Section 6.1</a>) and <a href="#header.via" class="smpl">Via</a> (<a href="#header.via" id="rfc.xref.header.via.1" title="Via">Section 5.7.1</a>) header fields for both connections. |
| | 925 | </p> |
| | 926 | <p id="rfc.section.2.3.p.9"><span id="rfc.iref.t.2"></span> A "<dfn>tunnel</dfn>" acts as a blind relay between two connections without changing the messages. Once active, a tunnel is not considered a party |
| | 927 | to the HTTP communication, though the tunnel might have been initiated by an HTTP request. A tunnel ceases to exist when both |
| | 928 | ends of the relayed connection are closed. Tunnels are used to extend a virtual connection through an intermediary, such as |
| | 929 | when Transport Layer Security (TLS, <a href="#RFC5246" id="rfc.xref.RFC5246.1"><cite title="The Transport Layer Security (TLS) Protocol Version 1.2">[RFC5246]</cite></a>) is used to establish confidential communication through a shared firewall proxy. |
| | 930 | </p> |
| | 931 | <p id="rfc.section.2.3.p.10"><span id="rfc.iref.i.3"></span> <span id="rfc.iref.t.3"></span> <span id="rfc.iref.c.3"></span> The above categories for intermediary only consider those acting as participants in the HTTP communication. There are also |
| | 932 | intermediaries that can act on lower layers of the network protocol stack, filtering or redirecting HTTP traffic without the |
| | 933 | knowledge or permission of message senders. Network intermediaries often introduce security flaws or interoperability problems |
| | 934 | by violating HTTP semantics. For example, an "<dfn>interception proxy</dfn>" <a href="#RFC3040" id="rfc.xref.RFC3040.1"><cite title="Internet Web Replication and Caching Taxonomy">[RFC3040]</cite></a> (also commonly known as a "<dfn>transparent proxy</dfn>" <a href="#RFC1919" id="rfc.xref.RFC1919.1"><cite title="Classical versus Transparent IP Proxies">[RFC1919]</cite></a> or "<dfn>captive portal</dfn>") differs from an HTTP proxy because it is not selected by the client. Instead, an interception proxy filters or redirects |
| | 935 | outgoing TCP port 80 packets (and occasionally other common port traffic). Interception proxies are commonly found on public |
| | 936 | network access points, as a means of enforcing account subscription prior to allowing use of non-local Internet services, |
| | 937 | and within corporate firewalls to enforce network usage policies. They are indistinguishable from a man-in-the-middle attack. |
| | 938 | </p> |
| | 939 | <p id="rfc.section.2.3.p.11">HTTP is defined as a stateless protocol, meaning that each request message can be understood in isolation. Many implementations |
| | 940 | depend on HTTP's stateless design in order to reuse proxied connections or dynamically load-balance requests across multiple |
| | 941 | servers. Hence, servers <em class="bcp14">MUST NOT</em> assume that two requests on the same connection are from the same user agent unless the connection is secured and specific |
| | 942 | to that agent. Some non-standard HTTP extensions (e.g., <a href="#RFC4559" id="rfc.xref.RFC4559.1"><cite title="SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows">[RFC4559]</cite></a>) have been known to violate this requirement, resulting in security and interoperability problems. |
| | 943 | </p> |
| | 944 | </div> |
| | 945 | <div id="caches"> |
| | 946 | <div id="rfc.iref.c.4"></div> |
| | 947 | <h2 id="rfc.section.2.4"><a href="#rfc.section.2.4">2.4</a> <a href="#caches">Caches</a></h2> |
| | 948 | <p id="rfc.section.2.4.p.1">A "<dfn>cache</dfn>" is a local store of previous response messages and the subsystem that controls its message storage, retrieval, and deletion. |
| | 949 | A cache stores cacheable responses in order to reduce the response time and network bandwidth consumption on future, equivalent |
| | 950 | requests. Any client or server <em class="bcp14">MAY</em> employ a cache, though a cache cannot be used by a server while it is acting as a tunnel. |
| | 951 | </p> |
| | 952 | <p id="rfc.section.2.4.p.2">The effect of a cache is that the request/response chain is shortened if one of the participants along the chain has a cached |
| | 953 | response applicable to that request. The following illustrates the resulting chain if B has a cached copy of an earlier response |
| | 954 | from O (via C) for a request that has not been cached by UA or A. |
| | 955 | </p> |
| | 956 | <div id="rfc.figure.u.5"></div><pre class="drawing"> > > |
| 928 | | is cacheable, there might be additional constraints placed by the client or by the origin server on when that cached response |
| 929 | | can be used for a particular request. HTTP requirements for cache behavior and cacheable responses are defined in <a href="p6-cache.html#caching.overview" title="Overview of Cache Operation">Section 2</a> of <a href="#Part6" id="rfc.xref.Part6.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. |
| 930 | | </p> |
| 931 | | <p id="rfc.section.2.4.p.5">There are a wide variety of architectures and configurations of caches deployed across the World Wide Web and inside large |
| 932 | | organizations. These include national hierarchies of proxy caches to save transoceanic bandwidth, collaborative systems that |
| 933 | | broadcast or multicast cache entries, archives of pre-fetched cache entries for use in off-line or high-latency environments, |
| 934 | | and so on. |
| 935 | | </p> |
| 936 | | <h2 id="rfc.section.2.5"><a href="#rfc.section.2.5">2.5</a> <a id="conformance" href="#conformance">Conformance and Error Handling</a></h2> |
| 937 | | <p id="rfc.section.2.5.p.1">This specification targets conformance criteria according to the role of a participant in HTTP communication. Hence, HTTP |
| 938 | | requirements are placed on senders, recipients, clients, servers, user agents, intermediaries, origin servers, proxies, gateways, |
| 939 | | or caches, depending on what behavior is being constrained by the requirement. Additional (social) requirements are placed |
| 940 | | on implementations, resource owners, and protocol element registrations when they apply beyond the scope of a single communication. |
| 941 | | </p> |
| 942 | | <p id="rfc.section.2.5.p.2">The verb "generate" is used instead of "send" where a requirement differentiates between creating a protocol element and merely |
| 943 | | forwarding a received element downstream. |
| 944 | | </p> |
| 945 | | <p id="rfc.section.2.5.p.3">An implementation is considered conformant if it complies with all of the requirements associated with the roles it partakes |
| 946 | | in HTTP. Note that SHOULD-level requirements are relevant here, unless one of the documented exceptions is applicable. |
| 947 | | </p> |
| 948 | | <p id="rfc.section.2.5.p.4">Conformance applies to both the syntax and semantics of HTTP protocol elements. A sender <em class="bcp14">MUST NOT</em> generate protocol elements that convey a meaning that is known by that sender to be false. A sender <em class="bcp14">MUST NOT</em> generate protocol elements that do not match the grammar defined by the ABNF rules for those protocol elements that are applicable |
| 949 | | to the sender's role. If a received protocol element is processed, the recipient <em class="bcp14">MUST</em> be able to parse any value that would match the ABNF rules for that protocol element, excluding only those rules not applicable |
| 950 | | to the recipient's role. |
| 951 | | </p> |
| 952 | | <p id="rfc.section.2.5.p.5">Unless noted otherwise, a recipient <em class="bcp14">MAY</em> attempt to recover a usable protocol element from an invalid construct. HTTP does not define specific error handling mechanisms |
| 953 | | except when they have a direct impact on security, since different applications of the protocol require different error handling |
| 954 | | strategies. For example, a Web browser might wish to transparently recover from a response where the <a href="p2-semantics.html#header.location" class="smpl">Location</a> header field doesn't parse according to the ABNF, whereas a systems control client might consider any form of error recovery |
| 955 | | to be dangerous. |
| 956 | | </p> |
| 957 | | <h2 id="rfc.section.2.6"><a href="#rfc.section.2.6">2.6</a> <a id="http.version" href="#http.version">Protocol Versioning</a></h2> |
| 958 | | <p id="rfc.section.2.6.p.1">HTTP uses a "<major>.<minor>" numbering scheme to indicate versions of the protocol. This specification defines version "1.1". |
| 959 | | The protocol version as a whole indicates the sender's conformance with the set of requirements laid out in that version's |
| 960 | | corresponding specification of HTTP. |
| 961 | | </p> |
| 962 | | <p id="rfc.section.2.6.p.2">The version of an HTTP message is indicated by an HTTP-version field in the first line of the message. HTTP-version is case-sensitive.</p> |
| 963 | | <div id="rfc.figure.u.6"></div><pre class="inline"><span id="rfc.iref.g.14"></span><span id="rfc.iref.g.15"></span> <a href="#http.version" class="smpl">HTTP-version</a> = <a href="#http.version" class="smpl">HTTP-name</a> "/" <a href="#core.rules" class="smpl">DIGIT</a> "." <a href="#core.rules" class="smpl">DIGIT</a> |
| | 960 | is cacheable, there might be additional constraints placed by the client or by the origin server on when that cached response |
| | 961 | can be used for a particular request. HTTP requirements for cache behavior and cacheable responses are defined in <a href="p6-cache.html#caching.overview" title="Overview of Cache Operation">Section 2</a> of <a href="#Part6" id="rfc.xref.Part6.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. |
| | 962 | </p> |
| | 963 | <p id="rfc.section.2.4.p.5">There are a wide variety of architectures and configurations of caches deployed across the World Wide Web and inside large |
| | 964 | organizations. These include national hierarchies of proxy caches to save transoceanic bandwidth, collaborative systems that |
| | 965 | broadcast or multicast cache entries, archives of pre-fetched cache entries for use in off-line or high-latency environments, |
| | 966 | and so on. |
| | 967 | </p> |
| | 968 | </div> |
| | 969 | <div id="conformance"> |
| | 970 | <h2 id="rfc.section.2.5"><a href="#rfc.section.2.5">2.5</a> <a href="#conformance">Conformance and Error Handling</a></h2> |
| | 971 | <p id="rfc.section.2.5.p.1">This specification targets conformance criteria according to the role of a participant in HTTP communication. Hence, HTTP |
| | 972 | requirements are placed on senders, recipients, clients, servers, user agents, intermediaries, origin servers, proxies, gateways, |
| | 973 | or caches, depending on what behavior is being constrained by the requirement. Additional (social) requirements are placed |
| | 974 | on implementations, resource owners, and protocol element registrations when they apply beyond the scope of a single communication. |
| | 975 | </p> |
| | 976 | <p id="rfc.section.2.5.p.2">The verb "generate" is used instead of "send" where a requirement differentiates between creating a protocol element and merely |
| | 977 | forwarding a received element downstream. |
| | 978 | </p> |
| | 979 | <p id="rfc.section.2.5.p.3">An implementation is considered conformant if it complies with all of the requirements associated with the roles it partakes |
| | 980 | in HTTP. Note that SHOULD-level requirements are relevant here, unless one of the documented exceptions is applicable. |
| | 981 | </p> |
| | 982 | <p id="rfc.section.2.5.p.4">Conformance applies to both the syntax and semantics of HTTP protocol elements. A sender <em class="bcp14">MUST NOT</em> generate protocol elements that convey a meaning that is known by that sender to be false. A sender <em class="bcp14">MUST NOT</em> generate protocol elements that do not match the grammar defined by the ABNF rules for those protocol elements that are applicable |
| | 983 | to the sender's role. If a received protocol element is processed, the recipient <em class="bcp14">MUST</em> be able to parse any value that would match the ABNF rules for that protocol element, excluding only those rules not applicable |
| | 984 | to the recipient's role. |
| | 985 | </p> |
| | 986 | <p id="rfc.section.2.5.p.5">Unless noted otherwise, a recipient <em class="bcp14">MAY</em> attempt to recover a usable protocol element from an invalid construct. HTTP does not define specific error handling mechanisms |
| | 987 | except when they have a direct impact on security, since different applications of the protocol require different error handling |
| | 988 | strategies. For example, a Web browser might wish to transparently recover from a response where the <a href="p2-semantics.html#header.location" class="smpl">Location</a> header field doesn't parse according to the ABNF, whereas a systems control client might consider any form of error recovery |
| | 989 | to be dangerous. |
| | 990 | </p> |
| | 991 | </div> |
| | 992 | <div id="http.version"> |
| | 993 | <h2 id="rfc.section.2.6"><a href="#rfc.section.2.6">2.6</a> <a href="#http.version">Protocol Versioning</a></h2> |
| | 994 | <p id="rfc.section.2.6.p.1">HTTP uses a "<major>.<minor>" numbering scheme to indicate versions of the protocol. This specification defines version "1.1". |
| | 995 | The protocol version as a whole indicates the sender's conformance with the set of requirements laid out in that version's |
| | 996 | corresponding specification of HTTP. |
| | 997 | </p> |
| | 998 | <p id="rfc.section.2.6.p.2">The version of an HTTP message is indicated by an HTTP-version field in the first line of the message. HTTP-version is case-sensitive.</p> |
| | 999 | <div id="rfc.figure.u.6"></div><pre class="inline"><span id="rfc.iref.g.14"></span><span id="rfc.iref.g.15"></span> <a href="#http.version" class="smpl">HTTP-version</a> = <a href="#http.version" class="smpl">HTTP-name</a> "/" <a href="#core.rules" class="smpl">DIGIT</a> "." <a href="#core.rules" class="smpl">DIGIT</a> |
| 966 | | version") indicates the HTTP messaging syntax, whereas the second digit ("minor version") indicates the highest minor version |
| 967 | | to which the sender is conformant and able to understand for future communication. The minor version advertises the sender's |
| 968 | | communication capabilities even when the sender is only using a backwards-compatible subset of the protocol, thereby letting |
| 969 | | the recipient know that more advanced features can be used in response (by servers) or in future requests (by clients). |
| 970 | | </p> |
| 971 | | <p id="rfc.section.2.6.p.5">When an HTTP/1.1 message is sent to an HTTP/1.0 recipient <a href="#RFC1945" id="rfc.xref.RFC1945.1"><cite title="Hypertext Transfer Protocol -- HTTP/1.0">[RFC1945]</cite></a> or a recipient whose version is unknown, the HTTP/1.1 message is constructed such that it can be interpreted as a valid HTTP/1.0 |
| 972 | | message if all of the newer features are ignored. This specification places recipient-version requirements on some new features |
| 973 | | so that a conformant sender will only use compatible features until it has determined, through configuration or the receipt |
| 974 | | of a message, that the recipient supports HTTP/1.1. |
| 975 | | </p> |
| 976 | | <p id="rfc.section.2.6.p.6">The interpretation of a header field does not change between minor versions of the same major HTTP version, though the default |
| 977 | | behavior of a recipient in the absence of such a field can change. Unless specified otherwise, header fields defined in HTTP/1.1 |
| 978 | | are defined for all versions of HTTP/1.x. In particular, the <a href="#header.host" class="smpl">Host</a> and <a href="#header.connection" class="smpl">Connection</a> header fields ought to be implemented by all HTTP/1.x implementations whether or not they advertise conformance with HTTP/1.1. |
| 979 | | </p> |
| 980 | | <p id="rfc.section.2.6.p.7">New header fields can be defined such that, when they are understood by a recipient, they might override or enhance the interpretation |
| 981 | | of previously defined header fields. When an implementation receives an unrecognized header field, the recipient <em class="bcp14">MUST</em> ignore that header field for local processing regardless of the message's HTTP version. An unrecognized header field received |
| 982 | | by a proxy <em class="bcp14">MUST</em> be forwarded downstream unless the header field's field-name is listed in the message's <a href="#header.connection" class="smpl">Connection</a> header field (see <a href="#header.connection" id="rfc.xref.header.connection.2" title="Connection">Section 6.1</a>). These requirements allow HTTP's functionality to be enhanced without requiring prior update of deployed intermediaries. |
| 983 | | </p> |
| 984 | | <p id="rfc.section.2.6.p.8">Intermediaries that process HTTP messages (i.e., all intermediaries other than those acting as tunnels) <em class="bcp14">MUST</em> send their own HTTP-version in forwarded messages. In other words, they <em class="bcp14">MUST NOT</em> blindly forward the first line of an HTTP message without ensuring that the protocol version in that message matches a version |
| 985 | | to which that intermediary is conformant for both the receiving and sending of messages. Forwarding an HTTP message without |
| 986 | | rewriting the HTTP-version might result in communication errors when downstream recipients use the message sender's version |
| 987 | | to determine what features are safe to use for later communication with that sender. |
| 988 | | </p> |
| 989 | | <p id="rfc.section.2.6.p.9">An HTTP client <em class="bcp14">SHOULD</em> send a request version equal to the highest version to which the client is conformant and whose major version is no higher |
| 990 | | than the highest version supported by the server, if this is known. An HTTP client <em class="bcp14">MUST NOT</em> send a version to which it is not conformant. |
| 991 | | </p> |
| 992 | | <p id="rfc.section.2.6.p.10">An HTTP client <em class="bcp14">MAY</em> send a lower request version if it is known that the server incorrectly implements the HTTP specification, but only after |
| 993 | | the client has attempted at least one normal request and determined from the response status or header fields (e.g., <a href="p2-semantics.html#header.server" class="smpl">Server</a>) that the server improperly handles higher request versions. |
| 994 | | </p> |
| 995 | | <p id="rfc.section.2.6.p.11">An HTTP server <em class="bcp14">SHOULD</em> send a response version equal to the highest version to which the server is conformant and whose major version is less than |
| 996 | | or equal to the one received in the request. An HTTP server <em class="bcp14">MUST NOT</em> send a version to which it is not conformant. A server <em class="bcp14">MAY</em> send a <a href="p2-semantics.html#status.505" class="smpl">505 (HTTP Version Not |
| 997 | | Supported)</a> response if it cannot send a response using the major version used in the client's request. |
| 998 | | </p> |
| 999 | | <p id="rfc.section.2.6.p.12">An HTTP server <em class="bcp14">MAY</em> send an HTTP/1.0 response to an HTTP/1.0 request if it is known or suspected that the client incorrectly implements the HTTP |
| 1000 | | specification and is incapable of correctly processing later version responses, such as when a client fails to parse the version |
| 1001 | | number correctly or when an intermediary is known to blindly forward the HTTP-version even when it doesn't conform to the |
| 1002 | | given minor version of the protocol. Such protocol downgrades <em class="bcp14">SHOULD NOT</em> be performed unless triggered by specific client attributes, such as when one or more of the request header fields (e.g., <a href="p2-semantics.html#header.user-agent" class="smpl">User-Agent</a>) uniquely match the values sent by a client known to be in error. |
| 1003 | | </p> |
| 1004 | | <p id="rfc.section.2.6.p.13">The intention of HTTP's versioning design is that the major number will only be incremented if an incompatible message syntax |
| 1005 | | is introduced, and that the minor number will only be incremented when changes made to the protocol have the effect of adding |
| 1006 | | to the message semantics or implying additional capabilities of the sender. However, the minor version was not incremented |
| 1007 | | for the changes introduced between <a href="#RFC2068" id="rfc.xref.RFC2068.2"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2068]</cite></a> and <a href="#RFC2616" id="rfc.xref.RFC2616.2"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2616]</cite></a>, and this revision has specifically avoiding any such changes to the protocol. |
| 1008 | | </p> |
| 1009 | | <div id="rfc.iref.r.5"></div> |
| 1010 | | <h2 id="rfc.section.2.7"><a href="#rfc.section.2.7">2.7</a> <a id="uri" href="#uri">Uniform Resource Identifiers</a></h2> |
| 1011 | | <p id="rfc.section.2.7.p.1">Uniform Resource Identifiers (URIs) <a href="#RFC3986" id="rfc.xref.RFC3986.2"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> are used throughout HTTP as the means for identifying resources (<a href="p2-semantics.html#resources" title="Resources">Section 2</a> of <a href="#Part2" id="rfc.xref.Part2.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). URI references are used to target requests, indicate redirects, and define relationships. |
| 1012 | | </p> |
| 1013 | | <p id="rfc.section.2.7.p.2">This specification adopts the definitions of "URI-reference", "absolute-URI", "relative-part", "port", "host", "path-abempty", |
| 1014 | | "query", "segment", and "authority" from the URI generic syntax. In addition, we define an "absolute-path" rule (that differs |
| 1015 | | from RFC 3986's "path-absolute" in that it allows a leading "//") and a "partial-URI" rule for protocol elements that allow |
| 1016 | | a relative URI but not a fragment. |
| 1017 | | </p> |
| 1018 | | <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.16"></span><span id="rfc.iref.g.17"></span><span id="rfc.iref.g.18"></span><span id="rfc.iref.g.19"></span><span id="rfc.iref.g.20"></span><span id="rfc.iref.g.21"></span><span id="rfc.iref.g.22"></span><span id="rfc.iref.g.23"></span><span id="rfc.iref.g.24"></span> <a href="#uri" class="smpl">URI-reference</a> = <URI-reference, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.3"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-4.1">Section 4.1</a>> |
| 1019 | | <a href="#uri" class="smpl">absolute-URI</a> = <absolute-URI, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.4"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-4.3">Section 4.3</a>> |
| 1020 | | <a href="#uri" class="smpl">relative-part</a> = <relative-part, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.5"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-4.2">Section 4.2</a>> |
| 1021 | | <a href="#uri" class="smpl">authority</a> = <authority, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.6"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.2">Section 3.2</a>> |
| 1022 | | <a href="#uri" class="smpl">path-abempty</a> = <path-abempty, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.7"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.3">Section 3.3</a>> |
| 1023 | | <a href="#uri" class="smpl">port</a> = <port, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.8"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.2.3">Section 3.2.3</a>> |
| 1024 | | <a href="#uri" class="smpl">query</a> = <query, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.9"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.4">Section 3.4</a>> |
| 1025 | | <a href="#uri" class="smpl">segment</a> = <segment, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.10"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.3">Section 3.3</a>> |
| 1026 | | <a href="#uri" class="smpl">uri-host</a> = <host, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.11"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.2.2">Section 3.2.2</a>> |
| | 1002 | version") indicates the HTTP messaging syntax, whereas the second digit ("minor version") indicates the highest minor version |
| | 1003 | to which the sender is conformant and able to understand for future communication. The minor version advertises the sender's |
| | 1004 | communication capabilities even when the sender is only using a backwards-compatible subset of the protocol, thereby letting |
| | 1005 | the recipient know that more advanced features can be used in response (by servers) or in future requests (by clients). |
| | 1006 | </p> |
| | 1007 | <p id="rfc.section.2.6.p.5">When an HTTP/1.1 message is sent to an HTTP/1.0 recipient <a href="#RFC1945" id="rfc.xref.RFC1945.1"><cite title="Hypertext Transfer Protocol -- HTTP/1.0">[RFC1945]</cite></a> or a recipient whose version is unknown, the HTTP/1.1 message is constructed such that it can be interpreted as a valid HTTP/1.0 |
| | 1008 | message if all of the newer features are ignored. This specification places recipient-version requirements on some new features |
| | 1009 | so that a conformant sender will only use compatible features until it has determined, through configuration or the receipt |
| | 1010 | of a message, that the recipient supports HTTP/1.1. |
| | 1011 | </p> |
| | 1012 | <p id="rfc.section.2.6.p.6">The interpretation of a header field does not change between minor versions of the same major HTTP version, though the default |
| | 1013 | behavior of a recipient in the absence of such a field can change. Unless specified otherwise, header fields defined in HTTP/1.1 |
| | 1014 | are defined for all versions of HTTP/1.x. In particular, the <a href="#header.host" class="smpl">Host</a> and <a href="#header.connection" class="smpl">Connection</a> header fields ought to be implemented by all HTTP/1.x implementations whether or not they advertise conformance with HTTP/1.1. |
| | 1015 | </p> |
| | 1016 | <p id="rfc.section.2.6.p.7">New header fields can be defined such that, when they are understood by a recipient, they might override or enhance the interpretation |
| | 1017 | of previously defined header fields. When an implementation receives an unrecognized header field, the recipient <em class="bcp14">MUST</em> ignore that header field for local processing regardless of the message's HTTP version. An unrecognized header field received |
| | 1018 | by a proxy <em class="bcp14">MUST</em> be forwarded downstream unless the header field's field-name is listed in the message's <a href="#header.connection" class="smpl">Connection</a> header field (see <a href="#header.connection" id="rfc.xref.header.connection.2" title="Connection">Section 6.1</a>). These requirements allow HTTP's functionality to be enhanced without requiring prior update of deployed intermediaries. |
| | 1019 | </p> |
| | 1020 | <p id="rfc.section.2.6.p.8">Intermediaries that process HTTP messages (i.e., all intermediaries other than those acting as tunnels) <em class="bcp14">MUST</em> send their own HTTP-version in forwarded messages. In other words, they <em class="bcp14">MUST NOT</em> blindly forward the first line of an HTTP message without ensuring that the protocol version in that message matches a version |
| | 1021 | to which that intermediary is conformant for both the receiving and sending of messages. Forwarding an HTTP message without |
| | 1022 | rewriting the HTTP-version might result in communication errors when downstream recipients use the message sender's version |
| | 1023 | to determine what features are safe to use for later communication with that sender. |
| | 1024 | </p> |
| | 1025 | <p id="rfc.section.2.6.p.9">An HTTP client <em class="bcp14">SHOULD</em> send a request version equal to the highest version to which the client is conformant and whose major version is no higher |
| | 1026 | than the highest version supported by the server, if this is known. An HTTP client <em class="bcp14">MUST NOT</em> send a version to which it is not conformant. |
| | 1027 | </p> |
| | 1028 | <p id="rfc.section.2.6.p.10">An HTTP client <em class="bcp14">MAY</em> send a lower request version if it is known that the server incorrectly implements the HTTP specification, but only after |
| | 1029 | the client has attempted at least one normal request and determined from the response status or header fields (e.g., <a href="p2-semantics.html#header.server" class="smpl">Server</a>) that the server improperly handles higher request versions. |
| | 1030 | </p> |
| | 1031 | <p id="rfc.section.2.6.p.11">An HTTP server <em class="bcp14">SHOULD</em> send a response version equal to the highest version to which the server is conformant and whose major version is less than |
| | 1032 | or equal to the one received in the request. An HTTP server <em class="bcp14">MUST NOT</em> send a version to which it is not conformant. A server <em class="bcp14">MAY</em> send a <a href="p2-semantics.html#status.505" class="smpl">505 (HTTP Version Not |
| | 1033 | Supported)</a> response if it cannot send a response using the major version used in the client's request. |
| | 1034 | </p> |
| | 1035 | <p id="rfc.section.2.6.p.12">An HTTP server <em class="bcp14">MAY</em> send an HTTP/1.0 response to an HTTP/1.0 request if it is known or suspected that the client incorrectly implements the HTTP |
| | 1036 | specification and is incapable of correctly processing later version responses, such as when a client fails to parse the version |
| | 1037 | number correctly or when an intermediary is known to blindly forward the HTTP-version even when it doesn't conform to the |
| | 1038 | given minor version of the protocol. Such protocol downgrades <em class="bcp14">SHOULD NOT</em> be performed unless triggered by specific client attributes, such as when one or more of the request header fields (e.g., <a href="p2-semantics.html#header.user-agent" class="smpl">User-Agent</a>) uniquely match the values sent by a client known to be in error. |
| | 1039 | </p> |
| | 1040 | <p id="rfc.section.2.6.p.13">The intention of HTTP's versioning design is that the major number will only be incremented if an incompatible message syntax |
| | 1041 | is introduced, and that the minor number will only be incremented when changes made to the protocol have the effect of adding |
| | 1042 | to the message semantics or implying additional capabilities of the sender. However, the minor version was not incremented |
| | 1043 | for the changes introduced between <a href="#RFC2068" id="rfc.xref.RFC2068.2"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2068]</cite></a> and <a href="#RFC2616" id="rfc.xref.RFC2616.2"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2616]</cite></a>, and this revision has specifically avoiding any such changes to the protocol. |
| | 1044 | </p> |
| | 1045 | </div> |
| | 1046 | <div id="uri"> |
| | 1047 | <div id="rfc.iref.r.5"></div> |
| | 1048 | <h2 id="rfc.section.2.7"><a href="#rfc.section.2.7">2.7</a> <a href="#uri">Uniform Resource Identifiers</a></h2> |
| | 1049 | <p id="rfc.section.2.7.p.1">Uniform Resource Identifiers (URIs) <a href="#RFC3986" id="rfc.xref.RFC3986.2"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> are used throughout HTTP as the means for identifying resources (<a href="p2-semantics.html#resources" title="Resources">Section 2</a> of <a href="#Part2" id="rfc.xref.Part2.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). URI references are used to target requests, indicate redirects, and define relationships. |
| | 1050 | </p> |
| | 1051 | <p id="rfc.section.2.7.p.2">This specification adopts the definitions of "URI-reference", "absolute-URI", "relative-part", "port", "host", "path-abempty", |
| | 1052 | "query", "segment", and "authority" from the URI generic syntax. In addition, we define an "absolute-path" rule (that differs |
| | 1053 | from RFC 3986's "path-absolute" in that it allows a leading "//") and a "partial-URI" rule for protocol elements that allow |
| | 1054 | a relative URI but not a fragment. |
| | 1055 | </p> |
| | 1056 | <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.16"></span><span id="rfc.iref.g.17"></span><span id="rfc.iref.g.18"></span><span id="rfc.iref.g.19"></span><span id="rfc.iref.g.20"></span><span id="rfc.iref.g.21"></span><span id="rfc.iref.g.22"></span><span id="rfc.iref.g.23"></span><span id="rfc.iref.g.24"></span> <a href="#uri" class="smpl">URI-reference</a> = <URI-reference, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.3"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-4.1">Section 4.1</a>> |
| | 1057 | <a href="#uri" class="smpl">absolute-URI</a> = <absolute-URI, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.4"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-4.3">Section 4.3</a>> |
| | 1058 | <a href="#uri" class="smpl">relative-part</a> = <relative-part, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.5"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-4.2">Section 4.2</a>> |
| | 1059 | <a href="#uri" class="smpl">authority</a> = <authority, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.6"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.2">Section 3.2</a>> |
| | 1060 | <a href="#uri" class="smpl">path-abempty</a> = <path-abempty, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.7"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.3">Section 3.3</a>> |
| | 1061 | <a href="#uri" class="smpl">port</a> = <port, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.8"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.2.3">Section 3.2.3</a>> |
| | 1062 | <a href="#uri" class="smpl">query</a> = <query, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.9"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.4">Section 3.4</a>> |
| | 1063 | <a href="#uri" class="smpl">segment</a> = <segment, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.10"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.3">Section 3.3</a>> |
| | 1064 | <a href="#uri" class="smpl">uri-host</a> = <host, defined in <a href="#RFC3986" id="rfc.xref.RFC3986.11"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.2.2">Section 3.2.2</a>> |
| 1031 | | any form of reference (URI-reference), only a URI in absolute form (absolute-URI), only the path and optional query components, |
| 1032 | | or some combination of the above. Unless otherwise indicated, URI references are parsed relative to the effective request |
| 1033 | | URI (<a href="#effective.request.uri" title="Effective Request URI">Section 5.5</a>). |
| 1034 | | </p> |
| 1035 | | <h3 id="rfc.section.2.7.1"><a href="#rfc.section.2.7.1">2.7.1</a> <a id="http.uri" href="#http.uri">http URI scheme</a></h3> |
| 1036 | | <div id="rfc.iref.h.1"></div> |
| 1037 | | <div id="rfc.iref.u.3"></div> |
| 1038 | | <p id="rfc.section.2.7.1.p.1">The "http" URI scheme is hereby defined for the purpose of minting identifiers according to their association with the hierarchical |
| 1039 | | namespace governed by a potential HTTP origin server listening for TCP connections on a given port. |
| 1040 | | </p> |
| 1041 | | <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.25"></span> <a href="#http.uri" class="smpl">http-URI</a> = "http:" "//" <a href="#uri" class="smpl">authority</a> <a href="#uri" class="smpl">path-abempty</a> [ "?" <a href="#uri" class="smpl">query</a> ] |
| 1042 | | </pre><p id="rfc.section.2.7.1.p.3">The HTTP origin server is identified by the generic syntax's <a href="#uri" class="smpl">authority</a> component, which includes a host identifier and optional TCP port (<a href="#RFC3986" id="rfc.xref.RFC3986.12"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.2.2">Section 3.2.2</a>). The remainder of the URI, consisting of both the hierarchical path component and optional query component, serves as an |
| 1043 | | identifier for a potential resource within that origin server's name space. |
| 1044 | | </p> |
| 1045 | | <p id="rfc.section.2.7.1.p.4">If the host identifier is provided as an IP address, then the origin server is any listener on the indicated TCP port at that |
| 1046 | | IP address. If host is a registered name, then that name is considered an indirect identifier and the recipient might use |
| 1047 | | a name resolution service, such as DNS, to find the address of a listener for that host. The host <em class="bcp14">MUST NOT</em> be empty; if an "http" URI is received with an empty host, then it <em class="bcp14">MUST</em> be rejected as invalid. If the port subcomponent is empty or not given, then TCP port 80 is assumed (the default reserved |
| 1048 | | port for WWW services). |
| 1049 | | </p> |
| 1050 | | <p id="rfc.section.2.7.1.p.5">Regardless of the form of host identifier, access to that host is not implied by the mere presence of its name or address. |
| 1051 | | The host might or might not exist and, even when it does exist, might or might not be running an HTTP server or listening |
| 1052 | | to the indicated port. The "http" URI scheme makes use of the delegated nature of Internet names and addresses to establish |
| 1053 | | a naming authority (whatever entity has the ability to place an HTTP server at that Internet name or address) and allows that |
| 1054 | | authority to determine which names are valid and how they might be used. |
| 1055 | | </p> |
| 1056 | | <p id="rfc.section.2.7.1.p.6">When an "http" URI is used within a context that calls for access to the indicated resource, a client <em class="bcp14">MAY</em> attempt access by resolving the host to an IP address, establishing a TCP connection to that address on the indicated port, |
| 1057 | | and sending an HTTP request message (<a href="#http.message" title="Message Format">Section 3</a>) containing the URI's identifying data (<a href="#message.routing" title="Message Routing">Section 5</a>) to the server. If the server responds to that request with a non-interim HTTP response message, as described in <a href="p2-semantics.html#status.codes" title="Response Status Codes">Section 6</a> of <a href="#Part2" id="rfc.xref.Part2.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>, then that response is considered an authoritative answer to the client's request. |
| 1058 | | </p> |
| 1059 | | <p id="rfc.section.2.7.1.p.7">Although HTTP is independent of the transport protocol, the "http" scheme is specific to TCP-based services because the name |
| 1060 | | delegation process depends on TCP for establishing authority. An HTTP service based on some other underlying connection protocol |
| 1061 | | would presumably be identified using a different URI scheme, just as the "https" scheme (below) is used for resources that |
| 1062 | | require an end-to-end secured connection. Other protocols might also be used to provide access to "http" identified resources |
| 1063 | | — it is only the authoritative interface used for mapping the namespace that is specific to TCP. |
| 1064 | | </p> |
| 1065 | | <p id="rfc.section.2.7.1.p.8">The URI generic syntax for authority also includes a deprecated userinfo subcomponent (<a href="#RFC3986" id="rfc.xref.RFC3986.13"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.2.1">Section 3.2.1</a>) for including user authentication information in the URI. Some implementations make use of the userinfo component for internal |
| 1066 | | configuration of authentication information, such as within command invocation options, configuration files, or bookmark lists, |
| 1067 | | even though such usage might expose a user identifier or password. Senders <em class="bcp14">MUST</em> exclude the userinfo subcomponent (and its "@" delimiter) when an "http" URI is transmitted within a message as a request |
| 1068 | | target or header field value. Recipients of an "http" URI reference <em class="bcp14">SHOULD</em> parse for userinfo and treat its presence as an error, since it is likely being used to obscure the authority for the sake |
| 1069 | | of phishing attacks. |
| 1070 | | </p> |
| 1071 | | <h3 id="rfc.section.2.7.2"><a href="#rfc.section.2.7.2">2.7.2</a> <a id="https.uri" href="#https.uri">https URI scheme</a></h3> |
| 1072 | | <div id="rfc.iref.h.2"></div> |
| 1073 | | <div id="rfc.iref.u.4"></div> |
| 1074 | | <p id="rfc.section.2.7.2.p.1">The "https" URI scheme is hereby defined for the purpose of minting identifiers according to their association with the hierarchical |
| 1075 | | namespace governed by a potential HTTP origin server listening to a given TCP port for TLS-secured connections <a href="#RFC5246" id="rfc.xref.RFC5246.2"><cite title="The Transport Layer Security (TLS) Protocol Version 1.2">[RFC5246]</cite></a>. |
| 1076 | | </p> |
| 1077 | | <p id="rfc.section.2.7.2.p.2">All of the requirements listed above for the "http" scheme are also requirements for the "https" scheme, except that a default |
| 1078 | | TCP port of 443 is assumed if the port subcomponent is empty or not given, and the TCP connection <em class="bcp14">MUST</em> be secured, end-to-end, through the use of strong encryption prior to sending the first HTTP request. |
| 1079 | | </p> |
| 1080 | | <div id="rfc.figure.u.9"></div><pre class="inline"><span id="rfc.iref.g.26"></span> <a href="#https.uri" class="smpl">https-URI</a> = "https:" "//" <a href="#uri" class="smpl">authority</a> <a href="#uri" class="smpl">path-abempty</a> [ "?" <a href="#uri" class="smpl">query</a> ] |
| | 1069 | any form of reference (URI-reference), only a URI in absolute form (absolute-URI), only the path and optional query components, |
| | 1070 | or some combination of the above. Unless otherwise indicated, URI references are parsed relative to the effective request |
| | 1071 | URI (<a href="#effective.request.uri" title="Effective Request URI">Section 5.5</a>). |
| | 1072 | </p> |
| | 1073 | <div id="http.uri"> |
| | 1074 | <h3 id="rfc.section.2.7.1"><a href="#rfc.section.2.7.1">2.7.1</a> <a href="#http.uri">http URI scheme</a></h3> |
| | 1075 | <div id="rfc.iref.h.1"></div> |
| | 1076 | <div id="rfc.iref.u.3"></div> |
| | 1077 | <p id="rfc.section.2.7.1.p.1">The "http" URI scheme is hereby defined for the purpose of minting identifiers according to their association with the hierarchical |
| | 1078 | namespace governed by a potential HTTP origin server listening for TCP connections on a given port. |
| | 1079 | </p> |
| | 1080 | <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.25"></span> <a href="#http.uri" class="smpl">http-URI</a> = "http:" "//" <a href="#uri" class="smpl">authority</a> <a href="#uri" class="smpl">path-abempty</a> [ "?" <a href="#uri" class="smpl">query</a> ] |
| | 1081 | </pre><p id="rfc.section.2.7.1.p.3">The HTTP origin server is identified by the generic syntax's <a href="#uri" class="smpl">authority</a> component, which includes a host identifier and optional TCP port (<a href="#RFC3986" id="rfc.xref.RFC3986.12"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.2.2">Section 3.2.2</a>). The remainder of the URI, consisting of both the hierarchical path component and optional query component, serves as an |
| | 1082 | identifier for a potential resource within that origin server's name space. |
| | 1083 | </p> |
| | 1084 | <p id="rfc.section.2.7.1.p.4">If the host identifier is provided as an IP address, then the origin server is any listener on the indicated TCP port at that |
| | 1085 | IP address. If host is a registered name, then that name is considered an indirect identifier and the recipient might use |
| | 1086 | a name resolution service, such as DNS, to find the address of a listener for that host. The host <em class="bcp14">MUST NOT</em> be empty; if an "http" URI is received with an empty host, then it <em class="bcp14">MUST</em> be rejected as invalid. If the port subcomponent is empty or not given, then TCP port 80 is assumed (the default reserved |
| | 1087 | port for WWW services). |
| | 1088 | </p> |
| | 1089 | <p id="rfc.section.2.7.1.p.5">Regardless of the form of host identifier, access to that host is not implied by the mere presence of its name or address. |
| | 1090 | The host might or might not exist and, even when it does exist, might or might not be running an HTTP server or listening |
| | 1091 | to the indicated port. The "http" URI scheme makes use of the delegated nature of Internet names and addresses to establish |
| | 1092 | a naming authority (whatever entity has the ability to place an HTTP server at that Internet name or address) and allows that |
| | 1093 | authority to determine which names are valid and how they might be used. |
| | 1094 | </p> |
| | 1095 | <p id="rfc.section.2.7.1.p.6">When an "http" URI is used within a context that calls for access to the indicated resource, a client <em class="bcp14">MAY</em> attempt access by resolving the host to an IP address, establishing a TCP connection to that address on the indicated port, |
| | 1096 | and sending an HTTP request message (<a href="#http.message" title="Message Format">Section 3</a>) containing the URI's identifying data (<a href="#message.routing" title="Message Routing">Section 5</a>) to the server. If the server responds to that request with a non-interim HTTP response message, as described in <a href="p2-semantics.html#status.codes" title="Response Status Codes">Section 6</a> of <a href="#Part2" id="rfc.xref.Part2.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>, then that response is considered an authoritative answer to the client's request. |
| | 1097 | </p> |
| | 1098 | <p id="rfc.section.2.7.1.p.7">Although HTTP is independent of the transport protocol, the "http" scheme is specific to TCP-based services because the name |
| | 1099 | delegation process depends on TCP for establishing authority. An HTTP service based on some other underlying connection protocol |
| | 1100 | would presumably be identified using a different URI scheme, just as the "https" scheme (below) is used for resources that |
| | 1101 | require an end-to-end secured connection. Other protocols might also be used to provide access to "http" identified resources |
| | 1102 | — it is only the authoritative interface used for mapping the namespace that is specific to TCP. |
| | 1103 | </p> |
| | 1104 | <p id="rfc.section.2.7.1.p.8">The URI generic syntax for authority also includes a deprecated userinfo subcomponent (<a href="#RFC3986" id="rfc.xref.RFC3986.13"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.2.1">Section 3.2.1</a>) for including user authentication information in the URI. Some implementations make use of the userinfo component for internal |
| | 1105 | configuration of authentication information, such as within command invocation options, configuration files, or bookmark lists, |
| | 1106 | even though such usage might expose a user identifier or password. Senders <em class="bcp14">MUST</em> exclude the userinfo subcomponent (and its "@" delimiter) when an "http" URI is transmitted within a message as a request |
| | 1107 | target or header field value. Recipients of an "http" URI reference <em class="bcp14">SHOULD</em> parse for userinfo and treat its presence as an error, since it is likely being used to obscure the authority for the sake |
| | 1108 | of phishing attacks. |
| | 1109 | </p> |
| | 1110 | </div> |
| | 1111 | <div id="https.uri"> |
| | 1112 | <h3 id="rfc.section.2.7.2"><a href="#rfc.section.2.7.2">2.7.2</a> <a href="#https.uri">https URI scheme</a></h3> |
| | 1113 | <div id="rfc.iref.h.2"></div> |
| | 1114 | <div id="rfc.iref.u.4"></div> |
| | 1115 | <p id="rfc.section.2.7.2.p.1">The "https" URI scheme is hereby defined for the purpose of minting identifiers according to their association with the hierarchical |
| | 1116 | namespace governed by a potential HTTP origin server listening to a given TCP port for TLS-secured connections <a href="#RFC5246" id="rfc.xref.RFC5246.2"><cite title="The Transport Layer Security (TLS) Protocol Version 1.2">[RFC5246]</cite></a>. |
| | 1117 | </p> |
| | 1118 | <p id="rfc.section.2.7.2.p.2">All of the requirements listed above for the "http" scheme are also requirements for the "https" scheme, except that a default |
| | 1119 | TCP port of 443 is assumed if the port subcomponent is empty or not given, and the TCP connection <em class="bcp14">MUST</em> be secured, end-to-end, through the use of strong encryption prior to sending the first HTTP request. |
| | 1120 | </p> |
| | 1121 | <div id="rfc.figure.u.9"></div><pre class="inline"><span id="rfc.iref.g.26"></span> <a href="#https.uri" class="smpl">https-URI</a> = "https:" "//" <a href="#uri" class="smpl">authority</a> <a href="#uri" class="smpl">path-abempty</a> [ "?" <a href="#uri" class="smpl">query</a> ] |
| 1202 | | the <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field is defined in <a href="p2-semantics.html#header.date" title="Date">Section 7.1.1.2</a> of <a href="#Part2" id="rfc.xref.Part2.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> as containing the origination timestamp for the message in which it appears. |
| 1203 | | </p> |
| 1204 | | <h3 id="rfc.section.3.2.1"><a href="#rfc.section.3.2.1">3.2.1</a> <a id="field.extensibility" href="#field.extensibility">Field Extensibility</a></h3> |
| 1205 | | <p id="rfc.section.3.2.1.p.1">HTTP header fields are fully extensible: there is no limit on the introduction of new field names, each presumably defining |
| 1206 | | new semantics, nor on the number of header fields used in a given message. Existing fields are defined in each part of this |
| 1207 | | specification and in many other specifications outside the core standard. New header fields can be introduced without changing |
| 1208 | | the protocol version if their defined semantics allow them to be safely ignored by recipients that do not recognize them. |
| 1209 | | </p> |
| 1210 | | <p id="rfc.section.3.2.1.p.2">New HTTP header fields ought to be be registered with IANA in the Message Header Field Registry, as described in <a href="p2-semantics.html#header.field.registry" title="Header Field Registry">Section 8.3</a> of <a href="#Part2" id="rfc.xref.Part2.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>. A proxy <em class="bcp14">MUST</em> forward unrecognized header fields unless the field-name is listed in the <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.3" title="Connection">Section 6.1</a>) or the proxy is specifically configured to block, or otherwise transform, such fields. Other recipients <em class="bcp14">SHOULD</em> ignore unrecognized header fields. |
| 1211 | | </p> |
| 1212 | | <h3 id="rfc.section.3.2.2"><a href="#rfc.section.3.2.2">3.2.2</a> <a id="field.order" href="#field.order">Field Order</a></h3> |
| 1213 | | <p id="rfc.section.3.2.2.p.1">The order in which header fields with differing field names are received is not significant. However, it is "good practice" |
| 1214 | | to send header fields that contain control data first, such as <a href="#header.host" class="smpl">Host</a> on requests and <a href="p2-semantics.html#header.date" class="smpl">Date</a> on responses, so that implementations can decide when not to handle a message as early as possible. A server <em class="bcp14">MUST</em> wait until the entire header section is received before interpreting a request message, since later header fields might include |
| 1215 | | conditionals, authentication credentials, or deliberately misleading duplicate header fields that would impact request processing. |
| 1216 | | </p> |
| 1217 | | <p id="rfc.section.3.2.2.p.2">A sender <em class="bcp14">MUST NOT</em> generate multiple header fields with the same field name in a message unless either the entire field value for that header |
| 1218 | | field is defined as a comma-separated list [i.e., #(values)] or the header field is a well-known exception (as noted below). |
| 1219 | | </p> |
| 1220 | | <p id="rfc.section.3.2.2.p.3">Multiple header fields with the same field name can be combined into one "field-name: field-value" pair, without changing |
| 1221 | | the semantics of the message, by appending each subsequent field value to the combined field value in order, separated by |
| 1222 | | a comma. The order in which header fields with the same field name are received is therefore significant to the interpretation |
| 1223 | | of the combined field value; a proxy <em class="bcp14">MUST NOT</em> change the order of these field values when forwarding a message. |
| 1224 | | </p> |
| 1225 | | <div class="note" id="rfc.section.3.2.2.p.4"> |
| 1226 | | <p> <b>Note:</b> In practice, the "Set-Cookie" header field (<a href="#RFC6265" id="rfc.xref.RFC6265.2"><cite title="HTTP State Management Mechanism">[RFC6265]</cite></a>) often appears multiple times in a response message and does not use the list syntax, violating the above requirements on |
| 1227 | | multiple header fields with the same name. Since it cannot be combined into a single field-value, recipients ought to handle |
| 1228 | | "Set-Cookie" as a special case while processing header fields. (See Appendix A.2.3 of <a href="#Kri2001" id="rfc.xref.Kri2001.1"><cite title="HTTP Cookies: Standards, Privacy, and Politics">[Kri2001]</cite></a> for details.) |
| 1229 | | </p> |
| 1230 | | </div> |
| 1231 | | <h3 id="rfc.section.3.2.3"><a href="#rfc.section.3.2.3">3.2.3</a> <a id="whitespace" href="#whitespace">Whitespace</a></h3> |
| 1232 | | <div id="rule.LWS"> |
| 1233 | | <p id="rfc.section.3.2.3.p.1">This specification uses three rules to denote the use of linear whitespace: OWS (optional whitespace), RWS (required whitespace), |
| 1234 | | and BWS ("bad" whitespace). |
| 1235 | | </p> |
| 1236 | | </div> |
| 1237 | | <div id="rule.OWS"> |
| 1238 | | <p id="rfc.section.3.2.3.p.2">The OWS rule is used where zero or more linear whitespace octets might appear. OWS <em class="bcp14">SHOULD</em> either not be generated or be generated as a single SP. Multiple OWS octets that occur within field-content <em class="bcp14">SHOULD</em> either be replaced with a single SP or transformed to all SP octets (each octet other than SP replaced with SP) before interpreting |
| 1239 | | the field value or forwarding the message downstream. |
| 1240 | | </p> |
| 1241 | | </div> |
| 1242 | | <div id="rule.RWS"> |
| 1243 | | <p id="rfc.section.3.2.3.p.3">RWS is used when at least one linear whitespace octet is required to separate field tokens. RWS <em class="bcp14">SHOULD</em> be generated as a single SP. Multiple RWS octets that occur within field-content <em class="bcp14">SHOULD</em> either be replaced with a single SP or transformed to all SP octets before interpreting the field value or forwarding the |
| 1244 | | message downstream. |
| 1245 | | </p> |
| 1246 | | </div> |
| 1247 | | <div id="rule.BWS"> |
| 1248 | | <p id="rfc.section.3.2.3.p.4">BWS is used where the grammar allows optional whitespace, for historical reasons, but senders <em class="bcp14">SHOULD NOT</em> generate it in messages; recipients <em class="bcp14">MUST</em> accept such bad optional whitespace and remove it before interpreting the field value or forwarding the message downstream. |
| 1249 | | </p> |
| 1250 | | </div> |
| 1251 | | <div id="rule.whitespace"> |
| 1252 | | <p id="rfc.section.3.2.3.p.5"> </p> |
| 1253 | | </div> |
| 1254 | | <div id="rfc.figure.u.19"></div><pre class="inline"><span id="rfc.iref.g.39"></span><span id="rfc.iref.g.40"></span><span id="rfc.iref.g.41"></span> <a href="#rule.whitespace" class="smpl">OWS</a> = *( <a href="#core.rules" class="smpl">SP</a> / <a href="#core.rules" class="smpl">HTAB</a> ) |
| | 1256 | the <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field is defined in <a href="p2-semantics.html#header.date" title="Date">Section 7.1.1.2</a> of <a href="#Part2" id="rfc.xref.Part2.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> as containing the origination timestamp for the message in which it appears. |
| | 1257 | </p> |
| | 1258 | <div id="field.extensibility"> |
| | 1259 | <h3 id="rfc.section.3.2.1"><a href="#rfc.section.3.2.1">3.2.1</a> <a href="#field.extensibility">Field Extensibility</a></h3> |
| | 1260 | <p id="rfc.section.3.2.1.p.1">HTTP header fields are fully extensible: there is no limit on the introduction of new field names, each presumably defining |
| | 1261 | new semantics, nor on the number of header fields used in a given message. Existing fields are defined in each part of this |
| | 1262 | specification and in many other specifications outside the core standard. New header fields can be introduced without changing |
| | 1263 | the protocol version if their defined semantics allow them to be safely ignored by recipients that do not recognize them. |
| | 1264 | </p> |
| | 1265 | <p id="rfc.section.3.2.1.p.2">New HTTP header fields ought to be be registered with IANA in the Message Header Field Registry, as described in <a href="p2-semantics.html#header.field.registry" title="Header Field Registry">Section 8.3</a> of <a href="#Part2" id="rfc.xref.Part2.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>. A proxy <em class="bcp14">MUST</em> forward unrecognized header fields unless the field-name is listed in the <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.3" title="Connection">Section 6.1</a>) or the proxy is specifically configured to block, or otherwise transform, such fields. Other recipients <em class="bcp14">SHOULD</em> ignore unrecognized header fields. |
| | 1266 | </p> |
| | 1267 | </div> |
| | 1268 | <div id="field.order"> |
| | 1269 | <h3 id="rfc.section.3.2.2"><a href="#rfc.section.3.2.2">3.2.2</a> <a href="#field.order">Field Order</a></h3> |
| | 1270 | <p id="rfc.section.3.2.2.p.1">The order in which header fields with differing field names are received is not significant. However, it is "good practice" |
| | 1271 | to send header fields that contain control data first, such as <a href="#header.host" class="smpl">Host</a> on requests and <a href="p2-semantics.html#header.date" class="smpl">Date</a> on responses, so that implementations can decide when not to handle a message as early as possible. A server <em class="bcp14">MUST</em> wait until the entire header section is received before interpreting a request message, since later header fields might include |
| | 1272 | conditionals, authentication credentials, or deliberately misleading duplicate header fields that would impact request processing. |
| | 1273 | </p> |
| | 1274 | <p id="rfc.section.3.2.2.p.2">A sender <em class="bcp14">MUST NOT</em> generate multiple header fields with the same field name in a message unless either the entire field value for that header |
| | 1275 | field is defined as a comma-separated list [i.e., #(values)] or the header field is a well-known exception (as noted below). |
| | 1276 | </p> |
| | 1277 | <p id="rfc.section.3.2.2.p.3">Multiple header fields with the same field name can be combined into one "field-name: field-value" pair, without changing |
| | 1278 | the semantics of the message, by appending each subsequent field value to the combined field value in order, separated by |
| | 1279 | a comma. The order in which header fields with the same field name are received is therefore significant to the interpretation |
| | 1280 | of the combined field value; a proxy <em class="bcp14">MUST NOT</em> change the order of these field values when forwarding a message. |
| | 1281 | </p> |
| | 1282 | <div class="note" id="rfc.section.3.2.2.p.4"> |
| | 1283 | <p><b>Note:</b> In practice, the "Set-Cookie" header field (<a href="#RFC6265" id="rfc.xref.RFC6265.2"><cite title="HTTP State Management Mechanism">[RFC6265]</cite></a>) often appears multiple times in a response message and does not use the list syntax, violating the above requirements on |
| | 1284 | multiple header fields with the same name. Since it cannot be combined into a single field-value, recipients ought to handle |
| | 1285 | "Set-Cookie" as a special case while processing header fields. (See Appendix A.2.3 of <a href="#Kri2001" id="rfc.xref.Kri2001.1"><cite title="HTTP Cookies: Standards, Privacy, and Politics">[Kri2001]</cite></a> for details.) |
| | 1286 | </p> |
| | 1287 | </div> |
| | 1288 | </div> |
| | 1289 | <div id="whitespace"> |
| | 1290 | <h3 id="rfc.section.3.2.3"><a href="#rfc.section.3.2.3">3.2.3</a> <a href="#whitespace">Whitespace</a></h3> |
| | 1291 | <div id="rule.LWS"> |
| | 1292 | <p id="rfc.section.3.2.3.p.1">This specification uses three rules to denote the use of linear whitespace: OWS (optional whitespace), RWS (required whitespace), |
| | 1293 | and BWS ("bad" whitespace). |
| | 1294 | </p> |
| | 1295 | </div> |
| | 1296 | <div id="rule.OWS"> |
| | 1297 | <p id="rfc.section.3.2.3.p.2">The OWS rule is used where zero or more linear whitespace octets might appear. OWS <em class="bcp14">SHOULD</em> either not be generated or be generated as a single SP. Multiple OWS octets that occur within field-content <em class="bcp14">SHOULD</em> either be replaced with a single SP or transformed to all SP octets (each octet other than SP replaced with SP) before interpreting |
| | 1298 | the field value or forwarding the message downstream. |
| | 1299 | </p> |
| | 1300 | </div> |
| | 1301 | <div id="rule.RWS"> |
| | 1302 | <p id="rfc.section.3.2.3.p.3">RWS is used when at least one linear whitespace octet is required to separate field tokens. RWS <em class="bcp14">SHOULD</em> be generated as a single SP. Multiple RWS octets that occur within field-content <em class="bcp14">SHOULD</em> either be replaced with a single SP or transformed to all SP octets before interpreting the field value or forwarding the |
| | 1303 | message downstream. |
| | 1304 | </p> |
| | 1305 | </div> |
| | 1306 | <div id="rule.BWS"> |
| | 1307 | <p id="rfc.section.3.2.3.p.4">BWS is used where the grammar allows optional whitespace, for historical reasons, but senders <em class="bcp14">SHOULD NOT</em> generate it in messages; recipients <em class="bcp14">MUST</em> accept such bad optional whitespace and remove it before interpreting the field value or forwarding the message downstream. |
| | 1308 | </p> |
| | 1309 | </div> |
| | 1310 | <div id="rule.whitespace"> |
| | 1311 | <p id="rfc.section.3.2.3.p.5"> </p> |
| | 1312 | </div> |
| | 1313 | <div id="rfc.figure.u.19"></div><pre class="inline"><span id="rfc.iref.g.39"></span><span id="rfc.iref.g.40"></span><span id="rfc.iref.g.41"></span> <a href="#rule.whitespace" class="smpl">OWS</a> = *( <a href="#core.rules" class="smpl">SP</a> / <a href="#core.rules" class="smpl">HTAB</a> ) |
| 1260 | | </pre><h3 id="rfc.section.3.2.4"><a href="#rfc.section.3.2.4">3.2.4</a> <a id="field.parsing" href="#field.parsing">Field Parsing</a></h3> |
| 1261 | | <p id="rfc.section.3.2.4.p.1">No whitespace is allowed between the header field-name and colon. In the past, differences in the handling of such whitespace |
| 1262 | | have led to security vulnerabilities in request routing and response handling. A server <em class="bcp14">MUST</em> reject any received request message that contains whitespace between a header field-name and colon with a response code of <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a>. A proxy <em class="bcp14">MUST</em> remove any such whitespace from a response message before forwarding the message downstream. |
| 1263 | | </p> |
| 1264 | | <p id="rfc.section.3.2.4.p.2">A field value is preceded by optional whitespace (OWS); a single SP is preferred. The field value does not include any leading |
| 1265 | | or trailing white space: OWS occurring before the first non-whitespace octet of the field value or after the last non-whitespace |
| 1266 | | octet of the field value is ignored and <em class="bcp14">SHOULD</em> be removed before further processing (as this does not change the meaning of the header field). |
| 1267 | | </p> |
| 1268 | | <p id="rfc.section.3.2.4.p.3">Historically, HTTP header field values could be extended over multiple lines by preceding each extra line with at least one |
| 1269 | | space or horizontal tab (obs-fold). This specification deprecates such line folding except within the message/http media type |
| 1270 | | (<a href="#internet.media.type.message.http" title="Internet Media Type message/http">Section 7.3.1</a>). Senders <em class="bcp14">MUST NOT</em> generate messages that include line folding (i.e., that contain any field-value that contains a match to the <a href="#header.fields" class="smpl">obs-fold</a> rule) unless the message is intended for packaging within the message/http media type. When an <a href="#header.fields" class="smpl">obs-fold</a> is received in a message, recipients <em class="bcp14">MUST</em> do one of: |
| 1271 | | </p> |
| 1272 | | <ul> |
| 1273 | | <li>accept the message and replace any embedded <a href="#header.fields" class="smpl">obs-fold</a> whitespace with either a single <a href="#core.rules" class="smpl">SP</a> or a matching number of <a href="#core.rules" class="smpl">SP</a> octets (to avoid buffer copying) prior to interpreting the field value or forwarding the message downstream; |
| 1274 | | </li> |
| 1275 | | <li>if it is a request, reject the message by sending a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> response with a representation explaining that obsolete line folding is unacceptable; or, |
| 1276 | | </li> |
| 1277 | | <li>if it is a response, discard the message and generate a <a href="p2-semantics.html#status.502" class="smpl">502 (Bad Gateway)</a> response with a representation explaining that unacceptable line folding was received. |
| 1278 | | </li> |
| 1279 | | </ul> |
| 1280 | | <p> Recipients that choose not to implement <a href="#header.fields" class="smpl">obs-fold</a> processing (as described above) <em class="bcp14">MUST NOT</em> accept messages containing header fields with leading whitespace, as this can expose them to attacks that exploit this difference |
| 1281 | | in processing. |
| 1282 | | </p> |
| 1283 | | <p id="rfc.section.3.2.4.p.4">Historically, HTTP has allowed field content with text in the ISO-8859-1 <a href="#ISO-8859-1" id="rfc.xref.ISO-8859-1.1"><cite title="Information technology -- 8-bit single-byte coded graphic character sets -- Part 1: Latin alphabet No. 1">[ISO-8859-1]</cite></a> charset, supporting other charsets only through use of <a href="#RFC2047" id="rfc.xref.RFC2047.1"><cite title="MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text">[RFC2047]</cite></a> encoding. In practice, most HTTP header field values use only a subset of the US-ASCII charset <a href="#USASCII" id="rfc.xref.USASCII.3"><cite title="Coded Character Set -- 7-bit American Standard Code for Information Interchange">[USASCII]</cite></a>. Newly defined header fields <em class="bcp14">SHOULD</em> limit their field values to US-ASCII octets. Recipients <em class="bcp14">SHOULD</em> treat other octets in field content (obs-text) as opaque data. |
| 1284 | | </p> |
| 1285 | | <h3 id="rfc.section.3.2.5"><a href="#rfc.section.3.2.5">3.2.5</a> <a id="field.limits" href="#field.limits">Field Limits</a></h3> |
| 1286 | | <p id="rfc.section.3.2.5.p.1">HTTP does not place a pre-defined limit on the length of each header field or on the length of the header block as a whole. |
| 1287 | | Various ad-hoc limitations on individual header field length are found in practice, often depending on the specific field |
| 1288 | | semantics. |
| 1289 | | </p> |
| 1290 | | <p id="rfc.section.3.2.5.p.2">A server <em class="bcp14">MUST</em> be prepared to receive request header fields of unbounded length and respond with an appropriate <a href="p2-semantics.html#status.4xx" class="smpl">4xx (Client Error)</a> status code if the received header field(s) are larger than the server wishes to process. |
| 1291 | | </p> |
| 1292 | | <p id="rfc.section.3.2.5.p.3">A client <em class="bcp14">MUST</em> be prepared to receive response header fields of unbounded length. A client <em class="bcp14">MAY</em> discard or truncate received header fields that are larger than the client wishes to process if the field semantics are such |
| 1293 | | that the dropped value(s) can be safely ignored without changing the response semantics. |
| 1294 | | </p> |
| 1295 | | <h3 id="rfc.section.3.2.6"><a href="#rfc.section.3.2.6">3.2.6</a> <a id="field.components" href="#field.components">Field value components</a></h3> |
| 1296 | | <div id="rule.token.separators"> |
| 1297 | | <p id="rfc.section.3.2.6.p.1"> Many HTTP header field values consist of words (token or quoted-string) separated by whitespace or special characters. These |
| 1298 | | special characters <em class="bcp14">MUST</em> be in a quoted string to be used within a parameter value (as defined in <a href="#transfer.codings" title="Transfer Codings">Section 4</a>). |
| 1299 | | </p> |
| 1300 | | </div> |
| 1301 | | <div id="rfc.figure.u.20"></div><pre class="inline"><span id="rfc.iref.g.42"></span><span id="rfc.iref.g.43"></span><span id="rfc.iref.g.44"></span><span id="rfc.iref.g.45"></span> <a href="#rule.token.separators" class="smpl">word</a> = <a href="#rule.token.separators" class="smpl">token</a> / <a href="#rule.quoted-string" class="smpl">quoted-string</a> |
| | 1319 | </pre></div> |
| | 1320 | <div id="field.parsing"> |
| | 1321 | <h3 id="rfc.section.3.2.4"><a href="#rfc.section.3.2.4">3.2.4</a> <a href="#field.parsing">Field Parsing</a></h3> |
| | 1322 | <p id="rfc.section.3.2.4.p.1">No whitespace is allowed between the header field-name and colon. In the past, differences in the handling of such whitespace |
| | 1323 | have led to security vulnerabilities in request routing and response handling. A server <em class="bcp14">MUST</em> reject any received request message that contains whitespace between a header field-name and colon with a response code of <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a>. A proxy <em class="bcp14">MUST</em> remove any such whitespace from a response message before forwarding the message downstream. |
| | 1324 | </p> |
| | 1325 | <p id="rfc.section.3.2.4.p.2">A field value is preceded by optional whitespace (OWS); a single SP is preferred. The field value does not include any leading |
| | 1326 | or trailing white space: OWS occurring before the first non-whitespace octet of the field value or after the last non-whitespace |
| | 1327 | octet of the field value is ignored and <em class="bcp14">SHOULD</em> be removed before further processing (as this does not change the meaning of the header field). |
| | 1328 | </p> |
| | 1329 | <p id="rfc.section.3.2.4.p.3">Historically, HTTP header field values could be extended over multiple lines by preceding each extra line with at least one |
| | 1330 | space or horizontal tab (obs-fold). This specification deprecates such line folding except within the message/http media type |
| | 1331 | (<a href="#internet.media.type.message.http" title="Internet Media Type message/http">Section 7.3.1</a>). Senders <em class="bcp14">MUST NOT</em> generate messages that include line folding (i.e., that contain any field-value that contains a match to the <a href="#header.fields" class="smpl">obs-fold</a> rule) unless the message is intended for packaging within the message/http media type. When an <a href="#header.fields" class="smpl">obs-fold</a> is received in a message, recipients <em class="bcp14">MUST</em> do one of: |
| | 1332 | </p> |
| | 1333 | <ul> |
| | 1334 | <li>accept the message and replace any embedded <a href="#header.fields" class="smpl">obs-fold</a> whitespace with either a single <a href="#core.rules" class="smpl">SP</a> or a matching number of <a href="#core.rules" class="smpl">SP</a> octets (to avoid buffer copying) prior to interpreting the field value or forwarding the message downstream; |
| | 1335 | </li> |
| | 1336 | <li>if it is a request, reject the message by sending a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> response with a representation explaining that obsolete line folding is unacceptable; or, |
| | 1337 | </li> |
| | 1338 | <li>if it is a response, discard the message and generate a <a href="p2-semantics.html#status.502" class="smpl">502 (Bad Gateway)</a> response with a representation explaining that unacceptable line folding was received. |
| | 1339 | </li> |
| | 1340 | </ul> |
| | 1341 | <p> Recipients that choose not to implement <a href="#header.fields" class="smpl">obs-fold</a> processing (as described above) <em class="bcp14">MUST NOT</em> accept messages containing header fields with leading whitespace, as this can expose them to attacks that exploit this difference |
| | 1342 | in processing. |
| | 1343 | </p> |
| | 1344 | <p id="rfc.section.3.2.4.p.4">Historically, HTTP has allowed field content with text in the ISO-8859-1 <a href="#ISO-8859-1" id="rfc.xref.ISO-8859-1.1"><cite title="Information technology -- 8-bit single-byte coded graphic character sets -- Part 1: Latin alphabet No. 1">[ISO-8859-1]</cite></a> charset, supporting other charsets only through use of <a href="#RFC2047" id="rfc.xref.RFC2047.1"><cite title="MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text">[RFC2047]</cite></a> encoding. In practice, most HTTP header field values use only a subset of the US-ASCII charset <a href="#USASCII" id="rfc.xref.USASCII.3"><cite title="Coded Character Set -- 7-bit American Standard Code for Information Interchange">[USASCII]</cite></a>. Newly defined header fields <em class="bcp14">SHOULD</em> limit their field values to US-ASCII octets. Recipients <em class="bcp14">SHOULD</em> treat other octets in field content (obs-text) as opaque data. |
| | 1345 | </p> |
| | 1346 | </div> |
| | 1347 | <div id="field.limits"> |
| | 1348 | <h3 id="rfc.section.3.2.5"><a href="#rfc.section.3.2.5">3.2.5</a> <a href="#field.limits">Field Limits</a></h3> |
| | 1349 | <p id="rfc.section.3.2.5.p.1">HTTP does not place a pre-defined limit on the length of each header field or on the length of the header block as a whole. |
| | 1350 | Various ad-hoc limitations on individual header field length are found in practice, often depending on the specific field |
| | 1351 | semantics. |
| | 1352 | </p> |
| | 1353 | <p id="rfc.section.3.2.5.p.2">A server <em class="bcp14">MUST</em> be prepared to receive request header fields of unbounded length and respond with an appropriate <a href="p2-semantics.html#status.4xx" class="smpl">4xx (Client Error)</a> status code if the received header field(s) are larger than the server wishes to process. |
| | 1354 | </p> |
| | 1355 | <p id="rfc.section.3.2.5.p.3">A client <em class="bcp14">MUST</em> be prepared to receive response header fields of unbounded length. A client <em class="bcp14">MAY</em> discard or truncate received header fields that are larger than the client wishes to process if the field semantics are such |
| | 1356 | that the dropped value(s) can be safely ignored without changing the response semantics. |
| | 1357 | </p> |
| | 1358 | </div> |
| | 1359 | <div id="field.components"> |
| | 1360 | <h3 id="rfc.section.3.2.6"><a href="#rfc.section.3.2.6">3.2.6</a> <a href="#field.components">Field value components</a></h3> |
| | 1361 | <div id="rule.token.separators"> |
| | 1362 | <p id="rfc.section.3.2.6.p.1"> Many HTTP header field values consist of words (token or quoted-string) separated by whitespace or special characters. These |
| | 1363 | special characters <em class="bcp14">MUST</em> be in a quoted string to be used within a parameter value (as defined in <a href="#transfer.codings" title="Transfer Codings">Section 4</a>). |
| | 1364 | </p> |
| | 1365 | </div> |
| | 1366 | <div id="rfc.figure.u.20"></div><pre class="inline"><span id="rfc.iref.g.42"></span><span id="rfc.iref.g.43"></span><span id="rfc.iref.g.44"></span><span id="rfc.iref.g.45"></span> <a href="#rule.token.separators" class="smpl">word</a> = <a href="#rule.token.separators" class="smpl">token</a> / <a href="#rule.quoted-string" class="smpl">quoted-string</a> |
| 1336 | | <p id="rfc.section.3.2.6.p.11"> The backslash octet ("\") can be used as a single-octet quoting mechanism within comment constructs:</p> |
| | 1401 | <p id="rfc.section.3.2.6.p.11"> The backslash octet ("\") can be used as a single-octet quoting mechanism within comment constructs:</p> |
| | 1402 | </div> |
| | 1403 | <div id="rfc.figure.u.24"></div><pre class="inline"><span id="rfc.iref.g.52"></span> <a href="#rule.quoted-cpair" class="smpl">quoted-cpair</a> = "\" ( <a href="#core.rules" class="smpl">HTAB</a> / <a href="#core.rules" class="smpl">SP</a> / <a href="#core.rules" class="smpl">VCHAR</a> / <a href="#rule.quoted-string" class="smpl">obs-text</a> ) |
| | 1404 | </pre><p id="rfc.section.3.2.6.p.13">Senders <em class="bcp14">SHOULD NOT</em> escape octets in comments that do not require escaping (i.e., other than the backslash octet "\" and the parentheses "(" and |
| | 1405 | ")"). |
| | 1406 | </p> |
| | 1407 | </div> |
| | 1408 | </div> |
| | 1409 | <div id="message.body"> |
| | 1410 | <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a> <a href="#message.body">Message Body</a></h2> |
| | 1411 | <p id="rfc.section.3.3.p.1">The message body (if any) of an HTTP message is used to carry the payload body of that request or response. The message body |
| | 1412 | is identical to the payload body unless a transfer coding has been applied, as described in <a href="#header.transfer-encoding" id="rfc.xref.header.transfer-encoding.1" title="Transfer-Encoding">Section 3.3.1</a>. |
| | 1413 | </p> |
| | 1414 | <div id="rfc.figure.u.25"></div><pre class="inline"><span id="rfc.iref.g.53"></span> <a href="#message.body" class="smpl">message-body</a> = *OCTET |
| | 1415 | </pre><p id="rfc.section.3.3.p.3">The rules for when a message body is allowed in a message differ for requests and responses.</p> |
| | 1416 | <p id="rfc.section.3.3.p.4">The presence of a message body in a request is signaled by a <a href="#header.content-length" class="smpl">Content-Length</a> or <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field. Request message framing is independent of method semantics, even if the method does not define any use for a |
| | 1417 | message body. |
| | 1418 | </p> |
| | 1419 | <p id="rfc.section.3.3.p.5">The presence of a message body in a response depends on both the request method to which it is responding and the response |
| | 1420 | status code (<a href="#status.line" title="Status Line">Section 3.1.2</a>). Responses to the HEAD request method never include a message body because the associated response header fields (e.g., <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a>, <a href="#header.content-length" class="smpl">Content-Length</a>, etc.), if present, indicate only what their values would have been if the request method had been GET (<a href="p2-semantics.html#HEAD" title="HEAD">Section 4.3.2</a> of <a href="#Part2" id="rfc.xref.Part2.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> responses to CONNECT switch to tunnel mode instead of having a message body (<a href="p2-semantics.html#CONNECT" title="CONNECT">Section 4.3.6</a> of <a href="#Part2" id="rfc.xref.Part2.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). All <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a>, <a href="p2-semantics.html#status.204" class="smpl">204 (No Content)</a>, and <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> responses do not include a message body. All other responses do include a message body, although the body might be of zero |
| | 1421 | length. |
| | 1422 | </p> |
| | 1423 | <div id="header.transfer-encoding"> |
| | 1424 | <div id="rfc.iref.t.4"></div> |
| | 1425 | <div id="rfc.iref.c.6"></div> |
| | 1426 | <h3 id="rfc.section.3.3.1"><a href="#rfc.section.3.3.1">3.3.1</a> <a href="#header.transfer-encoding">Transfer-Encoding</a></h3> |
| | 1427 | <p id="rfc.section.3.3.1.p.1">The Transfer-Encoding header field lists the transfer coding names corresponding to the sequence of transfer codings that |
| | 1428 | have been (or will be) applied to the payload body in order to form the message body. Transfer codings are defined in <a href="#transfer.codings" title="Transfer Codings">Section 4</a>. |
| | 1429 | </p> |
| | 1430 | <div id="rfc.figure.u.26"></div><pre class="inline"><span id="rfc.iref.g.54"></span> <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> = 1#<a href="#transfer.codings" class="smpl">transfer-coding</a> |
| | 1431 | </pre><p id="rfc.section.3.3.1.p.3">Transfer-Encoding is analogous to the Content-Transfer-Encoding field of MIME, which was designed to enable safe transport |
| | 1432 | of binary data over a 7-bit transport service (<a href="#RFC2045" id="rfc.xref.RFC2045.2"><cite title="Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies">[RFC2045]</cite></a>, <a href="https://tools.ietf.org/html/rfc2045#section-6">Section 6</a>). However, safe transport has a different focus for an 8bit-clean transfer protocol. In HTTP's case, Transfer-Encoding is |
| | 1433 | primarily intended to accurately delimit a dynamically generated payload and to distinguish payload encodings that are only |
| | 1434 | applied for transport efficiency or security from those that are characteristics of the selected resource. |
| | 1435 | </p> |
| | 1436 | <p id="rfc.section.3.3.1.p.4">All HTTP/1.1 recipients <em class="bcp14">MUST</em> implement the chunked transfer coding (<a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a>) because it plays a crucial role in framing messages when the payload body size is not known in advance. If chunked is applied |
| | 1437 | to a payload body, the sender <em class="bcp14">MUST NOT</em> apply chunked more than once (i.e., chunking an already chunked message is not allowed). If any transfer coding is applied |
| | 1438 | to a request payload body, the sender <em class="bcp14">MUST</em> apply chunked as the final transfer coding to ensure that the message is properly framed. If any transfer coding is applied |
| | 1439 | to a response payload body, the sender <em class="bcp14">MUST</em> either apply chunked as the final transfer coding or terminate the message by closing the connection. |
| | 1440 | </p> |
| | 1441 | <div id="rfc.figure.u.27"></div> |
| | 1442 | <p>For example,</p><pre class="text"> Transfer-Encoding: gzip, chunked |
| | 1443 | </pre><p>indicates that the payload body has been compressed using the gzip coding and then chunked using the chunked coding while |
| | 1444 | forming the message body. |
| | 1445 | </p> |
| | 1446 | <p id="rfc.section.3.3.1.p.6">Unlike <a href="p2-semantics.html#header.content-encoding" class="smpl">Content-Encoding</a> (<a href="p2-semantics.html#content.codings" title="Content Codings">Section 3.1.2.1</a> of <a href="#Part2" id="rfc.xref.Part2.13"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>), Transfer-Encoding is a property of the message, not of the representation, and any recipient along the request/response |
| | 1447 | chain <em class="bcp14">MAY</em> decode the received transfer coding(s) or apply additional transfer coding(s) to the message body, assuming that corresponding |
| | 1448 | changes are made to the Transfer-Encoding field-value. Additional information about the encoding parameters <em class="bcp14">MAY</em> be provided by other header fields not defined by this specification. |
| | 1449 | </p> |
| | 1450 | <p id="rfc.section.3.3.1.p.7">Transfer-Encoding <em class="bcp14">MAY</em> be sent in a response to a HEAD request or in a <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> response (<a href="p4-conditional.html#status.304" title="304 Not Modified">Section 4.1</a> of <a href="#Part4" id="rfc.xref.Part4.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>) to a GET request, neither of which includes a message body, to indicate that the origin server would have applied a transfer |
| | 1451 | coding to the message body if the request had been an unconditional GET. This indication is not required, however, because |
| | 1452 | any recipient on the response chain (including the origin server) can remove transfer codings when they are not needed. |
| | 1453 | </p> |
| | 1454 | <p id="rfc.section.3.3.1.p.8">Transfer-Encoding was added in HTTP/1.1. It is generally assumed that implementations advertising only HTTP/1.0 support will |
| | 1455 | not understand how to process a transfer-encoded payload. A client <em class="bcp14">MUST NOT</em> send a request containing Transfer-Encoding unless it knows the server will handle HTTP/1.1 (or later) requests; such knowledge |
| | 1456 | might be in the form of specific user configuration or by remembering the version of a prior received response. A server <em class="bcp14">MUST NOT</em> send a response containing Transfer-Encoding unless the corresponding request indicates HTTP/1.1 (or later). |
| | 1457 | </p> |
| | 1458 | <p id="rfc.section.3.3.1.p.9">A server that receives a request message with a transfer coding it does not understand <em class="bcp14">SHOULD</em> respond with <a href="p2-semantics.html#status.501" class="smpl">501 (Not Implemented)</a>. |
| | 1459 | </p> |
| | 1460 | </div> |
| | 1461 | <div id="header.content-length"> |
| | 1462 | <div id="rfc.iref.c.7"></div> |
| | 1463 | <h3 id="rfc.section.3.3.2"><a href="#rfc.section.3.3.2">3.3.2</a> <a href="#header.content-length">Content-Length</a></h3> |
| | 1464 | <p id="rfc.section.3.3.2.p.1">When a message does not have a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field, a Content-Length header field can provide the anticipated size, as a decimal number of octets, for a potential |
| | 1465 | payload body. For messages that do include a payload body, the Content-Length field-value provides the framing information |
| | 1466 | necessary for determining where the body (and message) ends. For messages that do not include a payload body, the Content-Length |
| | 1467 | indicates the size of the selected representation (<a href="p2-semantics.html#representations" title="Representations">Section 3</a> of <a href="#Part2" id="rfc.xref.Part2.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). |
| | 1468 | </p> |
| | 1469 | <div id="rfc.figure.u.28"></div><pre class="inline"><span id="rfc.iref.g.55"></span> <a href="#header.content-length" class="smpl">Content-Length</a> = 1*<a href="#core.rules" class="smpl">DIGIT</a> |
| | 1470 | </pre><p id="rfc.section.3.3.2.p.3">An example is</p> |
| | 1471 | <div id="rfc.figure.u.29"></div><pre class="text"> Content-Length: 3495 |
| | 1472 | </pre><p id="rfc.section.3.3.2.p.5">A sender <em class="bcp14">MUST NOT</em> send a Content-Length header field in any message that contains a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field. |
| | 1473 | </p> |
| | 1474 | <p id="rfc.section.3.3.2.p.6">A user agent <em class="bcp14">SHOULD</em> send a Content-Length in a request message when no <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> is sent and the request method defines a meaning for an enclosed payload body. For example, a Content-Length header field |
| | 1475 | is normally sent in a POST request even when the value is 0 (indicating an empty payload body). A user agent <em class="bcp14">SHOULD NOT</em> send a Content-Length header field when the request message does not contain a payload body and the method semantics do not |
| | 1476 | anticipate such a body. |
| | 1477 | </p> |
| | 1478 | <p id="rfc.section.3.3.2.p.7">A server <em class="bcp14">MAY</em> send a Content-Length header field in a response to a HEAD request (<a href="p2-semantics.html#HEAD" title="HEAD">Section 4.3.2</a> of <a href="#Part2" id="rfc.xref.Part2.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>); a server <em class="bcp14">MUST NOT</em> send Content-Length in such a response unless its field-value equals the decimal number of octets that would have been sent |
| | 1479 | in the payload body of a response if the same request had used the GET method. |
| | 1480 | </p> |
| | 1481 | <p id="rfc.section.3.3.2.p.8">A server <em class="bcp14">MAY</em> send a Content-Length header field in a <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> response to a conditional GET request (<a href="p4-conditional.html#status.304" title="304 Not Modified">Section 4.1</a> of <a href="#Part4" id="rfc.xref.Part4.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>); a server <em class="bcp14">MUST NOT</em> send Content-Length in such a response unless its field-value equals the decimal number of octets that would have been sent |
| | 1482 | in the payload body of a <a href="p2-semantics.html#status.200" class="smpl">200 (OK)</a> response to the same request. |
| | 1483 | </p> |
| | 1484 | <p id="rfc.section.3.3.2.p.9">A server <em class="bcp14">MUST NOT</em> send a Content-Length header field in any response with a status code of <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a> or <a href="p2-semantics.html#status.204" class="smpl">204 (No Content)</a>. A server <em class="bcp14">SHOULD NOT</em> send a Content-Length header field in any <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> response to a CONNECT request (<a href="p2-semantics.html#CONNECT" title="CONNECT">Section 4.3.6</a> of <a href="#Part2" id="rfc.xref.Part2.16"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). |
| | 1485 | </p> |
| | 1486 | <p id="rfc.section.3.3.2.p.10">Aside from the cases defined above, in the absence of Transfer-Encoding, an origin server <em class="bcp14">SHOULD</em> send a Content-Length header field when the payload body size is known prior to sending the complete header block. This will |
| | 1487 | allow downstream recipients to measure transfer progress, know when a received message is complete, and potentially reuse |
| | 1488 | the connection for additional requests. |
| | 1489 | </p> |
| | 1490 | <p id="rfc.section.3.3.2.p.11">Any Content-Length field value greater than or equal to zero is valid. Since there is no predefined limit to the length of |
| | 1491 | a payload, recipients <em class="bcp14">SHOULD</em> anticipate potentially large decimal numerals and prevent parsing errors due to integer conversion overflows (<a href="#attack.protocol.element.size.overflows" title="Buffer Overflows">Section 8.3</a>). |
| | 1492 | </p> |
| | 1493 | <p id="rfc.section.3.3.2.p.12">If a message is received that has multiple Content-Length header fields with field-values consisting of the same decimal value, |
| | 1494 | or a single Content-Length header field with a field value containing a list of identical decimal values (e.g., "Content-Length: |
| | 1495 | 42, 42"), indicating that duplicate Content-Length header fields have been generated or combined by an upstream message processor, |
| | 1496 | then the recipient <em class="bcp14">MUST</em> either reject the message as invalid or replace the duplicated field-values with a single valid Content-Length field containing |
| | 1497 | that decimal value prior to determining the message body length. |
| | 1498 | </p> |
| | 1499 | <div class="note" id="rfc.section.3.3.2.p.13"> |
| | 1500 | <p><b>Note:</b> HTTP's use of Content-Length for message framing differs significantly from the same field's use in MIME, where it is an optional |
| | 1501 | field used only within the "message/external-body" media-type. |
| | 1502 | </p> |
| | 1503 | </div> |
| | 1504 | </div> |
| | 1505 | <div id="message.body.length"> |
| | 1506 | <div id="rfc.iref.c.8"></div> |
| | 1507 | <h3 id="rfc.section.3.3.3"><a href="#rfc.section.3.3.3">3.3.3</a> <a href="#message.body.length">Message Body Length</a></h3> |
| | 1508 | <p id="rfc.section.3.3.3.p.1">The length of a message body is determined by one of the following (in order of precedence):</p> |
| | 1509 | <p id="rfc.section.3.3.3.p.2"></p> |
| | 1510 | <ol> |
| | 1511 | <li> |
| | 1512 | <p>Any response to a HEAD request and any response with a <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a>, <a href="p2-semantics.html#status.204" class="smpl">204 (No Content)</a>, or <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> status code is always terminated by the first empty line after the header fields, regardless of the header fields present |
| | 1513 | in the message, and thus cannot contain a message body. |
| | 1514 | </p> |
| | 1515 | </li> |
| | 1516 | <li> |
| | 1517 | <p>Any <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> response to a CONNECT request implies that the connection will become a tunnel immediately after the empty line that concludes |
| | 1518 | the header fields. A client <em class="bcp14">MUST</em> ignore any <a href="#header.content-length" class="smpl">Content-Length</a> or <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header fields received in such a message. |
| | 1519 | </p> |
| | 1520 | </li> |
| | 1521 | <li> |
| | 1522 | <p>If a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field is present and the chunked transfer coding (<a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a>) is the final encoding, the message body length is determined by reading and decoding the chunked data until the transfer |
| | 1523 | coding indicates the data is complete. |
| | 1524 | </p> |
| | 1525 | <p>If a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field is present in a response and the chunked transfer coding is not the final encoding, the message body length is |
| | 1526 | determined by reading the connection until it is closed by the server. If a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field is present in a request and the chunked transfer coding is not the final encoding, the message body length cannot |
| | 1527 | be determined reliably; the server <em class="bcp14">MUST</em> respond with the <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> status code and then close the connection. |
| | 1528 | </p> |
| | 1529 | <p>If a message is received with both a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> and a <a href="#header.content-length" class="smpl">Content-Length</a> header field, the Transfer-Encoding overrides the Content-Length. Such a message might indicate an attempt to perform request |
| | 1530 | or response smuggling (bypass of security-related checks on message routing or content) and thus ought to be handled as an |
| | 1531 | error. A sender <em class="bcp14">MUST</em> remove the received Content-Length field prior to forwarding such a message downstream. |
| | 1532 | </p> |
| | 1533 | </li> |
| | 1534 | <li> |
| | 1535 | <p>If a message is received without <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> and with either multiple <a href="#header.content-length" class="smpl">Content-Length</a> header fields having differing field-values or a single Content-Length header field having an invalid value, then the message |
| | 1536 | framing is invalid and <em class="bcp14">MUST</em> be treated as an error to prevent request or response smuggling. If this is a request message, the server <em class="bcp14">MUST</em> respond with a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> status code and then close the connection. If this is a response message received by a proxy, the proxy <em class="bcp14">MUST</em> discard the received response, send a <a href="p2-semantics.html#status.502" class="smpl">502 (Bad Gateway)</a> status code as its downstream response, and then close the connection. If this is a response message received by a user agent, |
| | 1537 | it <em class="bcp14">MUST</em> be treated as an error by discarding the message and closing the connection. |
| | 1538 | </p> |
| | 1539 | </li> |
| | 1540 | <li> |
| | 1541 | <p>If a valid <a href="#header.content-length" class="smpl">Content-Length</a> header field is present without <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a>, its decimal value defines the expected message body length in octets. If the sender closes the connection or the recipient |
| | 1542 | times out before the indicated number of octets are received, the recipient <em class="bcp14">MUST</em> consider the message to be incomplete and close the connection. |
| | 1543 | </p> |
| | 1544 | </li> |
| | 1545 | <li> |
| | 1546 | <p>If this is a request message and none of the above are true, then the message body length is zero (no message body is present).</p> |
| | 1547 | </li> |
| | 1548 | <li> |
| | 1549 | <p>Otherwise, this is a response message without a declared message body length, so the message body length is determined by |
| | 1550 | the number of octets received prior to the server closing the connection. |
| | 1551 | </p> |
| | 1552 | </li> |
| | 1553 | </ol> |
| | 1554 | <p id="rfc.section.3.3.3.p.3">Since there is no way to distinguish a successfully completed, close-delimited message from a partially-received message interrupted |
| | 1555 | by network failure, a server <em class="bcp14">SHOULD</em> use encoding or length-delimited messages whenever possible. The close-delimiting feature exists primarily for backwards compatibility |
| | 1556 | with HTTP/1.0. |
| | 1557 | </p> |
| | 1558 | <p id="rfc.section.3.3.3.p.4">A server <em class="bcp14">MAY</em> reject a request that contains a message body but not a <a href="#header.content-length" class="smpl">Content-Length</a> by responding with <a href="p2-semantics.html#status.411" class="smpl">411 (Length Required)</a>. |
| | 1559 | </p> |
| | 1560 | <p id="rfc.section.3.3.3.p.5">Unless a transfer coding other than chunked has been applied, a client that sends a request containing a message body <em class="bcp14">SHOULD</em> use a valid <a href="#header.content-length" class="smpl">Content-Length</a> header field if the message body length is known in advance, rather than the chunked transfer coding, since some existing |
| | 1561 | services respond to chunked with a <a href="p2-semantics.html#status.411" class="smpl">411 (Length Required)</a> status code even though they understand the chunked transfer coding. This is typically because such services are implemented |
| | 1562 | via a gateway that requires a content-length in advance of being called and the server is unable or unwilling to buffer the |
| | 1563 | entire request before processing. |
| | 1564 | </p> |
| | 1565 | <p id="rfc.section.3.3.3.p.6">A user agent that sends a request containing a message body <em class="bcp14">MUST</em> send a valid <a href="#header.content-length" class="smpl">Content-Length</a> header field if it does not know the server will handle HTTP/1.1 (or later) requests; such knowledge can be in the form of |
| | 1566 | specific user configuration or by remembering the version of a prior received response. |
| | 1567 | </p> |
| | 1568 | <p id="rfc.section.3.3.3.p.7">If the final response to the last request on a connection has been completely received and there remains additional data to |
| | 1569 | read, a user agent <em class="bcp14">MAY</em> discard the remaining data or attempt to determine if that data belongs as part of the prior response body, which might be |
| | 1570 | the case if the prior message's Content-Length value is incorrect. A client <em class="bcp14">MUST NOT</em> process, cache, or forward such extra data as a separate response, since such behavior would be vulnerable to cache poisoning. |
| | 1571 | </p> |
| | 1572 | </div> |
| | 1573 | </div> |
| | 1574 | <div id="incomplete.messages"> |
| | 1575 | <h2 id="rfc.section.3.4"><a href="#rfc.section.3.4">3.4</a> <a href="#incomplete.messages">Handling Incomplete Messages</a></h2> |
| | 1576 | <p id="rfc.section.3.4.p.1">A server that receives an incomplete request message, usually due to a canceled request or a triggered time-out exception, <em class="bcp14">MAY</em> send an error response prior to closing the connection. |
| | 1577 | </p> |
| | 1578 | <p id="rfc.section.3.4.p.2">A client that receives an incomplete response message, which can occur when a connection is closed prematurely or when decoding |
| | 1579 | a supposedly chunked transfer coding fails, <em class="bcp14">MUST</em> record the message as incomplete. Cache requirements for incomplete responses are defined in <a href="p6-cache.html#response.cacheability" title="Storing Responses in Caches">Section 3</a> of <a href="#Part6" id="rfc.xref.Part6.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. |
| | 1580 | </p> |
| | 1581 | <p id="rfc.section.3.4.p.3">If a response terminates in the middle of the header block (before the empty line is received) and the status code might rely |
| | 1582 | on header fields to convey the full meaning of the response, then the client cannot assume that meaning has been conveyed; |
| | 1583 | the client might need to repeat the request in order to determine what action to take next. |
| | 1584 | </p> |
| | 1585 | <p id="rfc.section.3.4.p.4">A message body that uses the chunked transfer coding is incomplete if the zero-sized chunk that terminates the encoding has |
| | 1586 | not been received. A message that uses a valid <a href="#header.content-length" class="smpl">Content-Length</a> is incomplete if the size of the message body received (in octets) is less than the value given by Content-Length. A response |
| | 1587 | that has neither chunked transfer coding nor Content-Length is terminated by closure of the connection, and thus is considered |
| | 1588 | complete regardless of the number of message body octets received, provided that the header block was received intact. |
| | 1589 | </p> |
| | 1590 | </div> |
| | 1591 | <div id="message.robustness"> |
| | 1592 | <h2 id="rfc.section.3.5"><a href="#rfc.section.3.5">3.5</a> <a href="#message.robustness">Message Parsing Robustness</a></h2> |
| | 1593 | <p id="rfc.section.3.5.p.1">Older HTTP/1.0 user agent implementations might send an extra CRLF after a POST request as a lame workaround for some early |
| | 1594 | server applications that failed to read message body content that was not terminated by a line-ending. An HTTP/1.1 user agent <em class="bcp14">MUST NOT</em> preface or follow a request with an extra CRLF. If terminating the request message body with a line-ending is desired, then |
| | 1595 | the user agent <em class="bcp14">MUST</em> count the terminating CRLF octets as part of the message body length. |
| | 1596 | </p> |
| | 1597 | <p id="rfc.section.3.5.p.2">In the interest of robustness, servers <em class="bcp14">SHOULD</em> ignore at least one empty line received where a request-line is expected. In other words, if a server is reading the protocol |
| | 1598 | stream at the beginning of a message and receives a CRLF first, the server <em class="bcp14">SHOULD</em> ignore the CRLF. |
| | 1599 | </p> |
| | 1600 | <p id="rfc.section.3.5.p.3">Although the line terminator for the start-line and header fields is the sequence CRLF, recipients <em class="bcp14">MAY</em> recognize a single LF as a line terminator and ignore any preceding CR. |
| | 1601 | </p> |
| | 1602 | <p id="rfc.section.3.5.p.4">Although the request-line and status-line grammar rules require that each of the component elements be separated by a single |
| | 1603 | SP octet, recipients <em class="bcp14">MAY</em> instead parse on whitespace-delimited word boundaries and, aside from the CRLF terminator, treat any form of whitespace as |
| | 1604 | the SP separator while ignoring preceding or trailing whitespace; such whitespace includes one or more of the following octets: |
| | 1605 | SP, HTAB, VT (%x0B), FF (%x0C), or bare CR. |
| | 1606 | </p> |
| | 1607 | <p id="rfc.section.3.5.p.5">When a server listening only for HTTP request messages, or processing what appears from the start-line to be an HTTP request |
| | 1608 | message, receives a sequence of octets that does not match the HTTP-message grammar aside from the robustness exceptions listed |
| | 1609 | above, the server <em class="bcp14">SHOULD</em> respond with a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> response. |
| | 1610 | </p> |
| | 1611 | </div> |
| 1338 | | <div id="rfc.figure.u.24"></div><pre class="inline"><span id="rfc.iref.g.52"></span> <a href="#rule.quoted-cpair" class="smpl">quoted-cpair</a> = "\" ( <a href="#core.rules" class="smpl">HTAB</a> / <a href="#core.rules" class="smpl">SP</a> / <a href="#core.rules" class="smpl">VCHAR</a> / <a href="#rule.quoted-string" class="smpl">obs-text</a> ) |
| 1339 | | </pre><p id="rfc.section.3.2.6.p.13">Senders <em class="bcp14">SHOULD NOT</em> escape octets in comments that do not require escaping (i.e., other than the backslash octet "\" and the parentheses "(" and |
| 1340 | | ")"). |
| 1341 | | </p> |
| 1342 | | <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a> <a id="message.body" href="#message.body">Message Body</a></h2> |
| 1343 | | <p id="rfc.section.3.3.p.1">The message body (if any) of an HTTP message is used to carry the payload body of that request or response. The message body |
| 1344 | | is identical to the payload body unless a transfer coding has been applied, as described in <a href="#header.transfer-encoding" id="rfc.xref.header.transfer-encoding.1" title="Transfer-Encoding">Section 3.3.1</a>. |
| 1345 | | </p> |
| 1346 | | <div id="rfc.figure.u.25"></div><pre class="inline"><span id="rfc.iref.g.53"></span> <a href="#message.body" class="smpl">message-body</a> = *OCTET |
| 1347 | | </pre><p id="rfc.section.3.3.p.3">The rules for when a message body is allowed in a message differ for requests and responses.</p> |
| 1348 | | <p id="rfc.section.3.3.p.4">The presence of a message body in a request is signaled by a <a href="#header.content-length" class="smpl">Content-Length</a> or <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field. Request message framing is independent of method semantics, even if the method does not define any use for a |
| 1349 | | message body. |
| 1350 | | </p> |
| 1351 | | <p id="rfc.section.3.3.p.5">The presence of a message body in a response depends on both the request method to which it is responding and the response |
| 1352 | | status code (<a href="#status.line" title="Status Line">Section 3.1.2</a>). Responses to the HEAD request method never include a message body because the associated response header fields (e.g., <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a>, <a href="#header.content-length" class="smpl">Content-Length</a>, etc.), if present, indicate only what their values would have been if the request method had been GET (<a href="p2-semantics.html#HEAD" title="HEAD">Section 4.3.2</a> of <a href="#Part2" id="rfc.xref.Part2.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> responses to CONNECT switch to tunnel mode instead of having a message body (<a href="p2-semantics.html#CONNECT" title="CONNECT">Section 4.3.6</a> of <a href="#Part2" id="rfc.xref.Part2.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). All <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a>, <a href="p2-semantics.html#status.204" class="smpl">204 (No Content)</a>, and <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> responses do not include a message body. All other responses do include a message body, although the body might be of zero |
| 1353 | | length. |
| 1354 | | </p> |
| 1355 | | <div id="rfc.iref.t.4"></div> |
| 1356 | | <div id="rfc.iref.c.6"></div> |
| 1357 | | <h3 id="rfc.section.3.3.1"><a href="#rfc.section.3.3.1">3.3.1</a> <a id="header.transfer-encoding" href="#header.transfer-encoding">Transfer-Encoding</a></h3> |
| 1358 | | <p id="rfc.section.3.3.1.p.1">The Transfer-Encoding header field lists the transfer coding names corresponding to the sequence of transfer codings that |
| 1359 | | have been (or will be) applied to the payload body in order to form the message body. Transfer codings are defined in <a href="#transfer.codings" title="Transfer Codings">Section 4</a>. |
| 1360 | | </p> |
| 1361 | | <div id="rfc.figure.u.26"></div><pre class="inline"><span id="rfc.iref.g.54"></span> <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> = 1#<a href="#transfer.codings" class="smpl">transfer-coding</a> |
| 1362 | | </pre><p id="rfc.section.3.3.1.p.3">Transfer-Encoding is analogous to the Content-Transfer-Encoding field of MIME, which was designed to enable safe transport |
| 1363 | | of binary data over a 7-bit transport service (<a href="#RFC2045" id="rfc.xref.RFC2045.2"><cite title="Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies">[RFC2045]</cite></a>, <a href="http://tools.ietf.org/html/rfc2045#section-6">Section 6</a>). However, safe transport has a different focus for an 8bit-clean transfer protocol. In HTTP's case, Transfer-Encoding is |
| 1364 | | primarily intended to accurately delimit a dynamically generated payload and to distinguish payload encodings that are only |
| 1365 | | applied for transport efficiency or security from those that are characteristics of the selected resource. |
| 1366 | | </p> |
| 1367 | | <p id="rfc.section.3.3.1.p.4">All HTTP/1.1 recipients <em class="bcp14">MUST</em> implement the chunked transfer coding (<a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a>) because it plays a crucial role in framing messages when the payload body size is not known in advance. If chunked is applied |
| 1368 | | to a payload body, the sender <em class="bcp14">MUST NOT</em> apply chunked more than once (i.e., chunking an already chunked message is not allowed). If any transfer coding is applied |
| 1369 | | to a request payload body, the sender <em class="bcp14">MUST</em> apply chunked as the final transfer coding to ensure that the message is properly framed. If any transfer coding is applied |
| 1370 | | to a response payload body, the sender <em class="bcp14">MUST</em> either apply chunked as the final transfer coding or terminate the message by closing the connection. |
| 1371 | | </p> |
| 1372 | | <div id="rfc.figure.u.27"></div> |
| 1373 | | <p>For example,</p><pre class="text"> Transfer-Encoding: gzip, chunked |
| 1374 | | </pre><p>indicates that the payload body has been compressed using the gzip coding and then chunked using the chunked coding while |
| 1375 | | forming the message body. |
| 1376 | | </p> |
| 1377 | | <p id="rfc.section.3.3.1.p.6">Unlike <a href="p2-semantics.html#header.content-encoding" class="smpl">Content-Encoding</a> (<a href="p2-semantics.html#content.codings" title="Content Codings">Section 3.1.2.1</a> of <a href="#Part2" id="rfc.xref.Part2.13"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>), Transfer-Encoding is a property of the message, not of the representation, and any recipient along the request/response |
| 1378 | | chain <em class="bcp14">MAY</em> decode the received transfer coding(s) or apply additional transfer coding(s) to the message body, assuming that corresponding |
| 1379 | | changes are made to the Transfer-Encoding field-value. Additional information about the encoding parameters <em class="bcp14">MAY</em> be provided by other header fields not defined by this specification. |
| 1380 | | </p> |
| 1381 | | <p id="rfc.section.3.3.1.p.7">Transfer-Encoding <em class="bcp14">MAY</em> be sent in a response to a HEAD request or in a <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> response (<a href="p4-conditional.html#status.304" title="304 Not Modified">Section 4.1</a> of <a href="#Part4" id="rfc.xref.Part4.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>) to a GET request, neither of which includes a message body, to indicate that the origin server would have applied a transfer |
| 1382 | | coding to the message body if the request had been an unconditional GET. This indication is not required, however, because |
| 1383 | | any recipient on the response chain (including the origin server) can remove transfer codings when they are not needed. |
| 1384 | | </p> |
| 1385 | | <p id="rfc.section.3.3.1.p.8">Transfer-Encoding was added in HTTP/1.1. It is generally assumed that implementations advertising only HTTP/1.0 support will |
| 1386 | | not understand how to process a transfer-encoded payload. A client <em class="bcp14">MUST NOT</em> send a request containing Transfer-Encoding unless it knows the server will handle HTTP/1.1 (or later) requests; such knowledge |
| 1387 | | might be in the form of specific user configuration or by remembering the version of a prior received response. A server <em class="bcp14">MUST NOT</em> send a response containing Transfer-Encoding unless the corresponding request indicates HTTP/1.1 (or later). |
| 1388 | | </p> |
| 1389 | | <p id="rfc.section.3.3.1.p.9">A server that receives a request message with a transfer coding it does not understand <em class="bcp14">SHOULD</em> respond with <a href="p2-semantics.html#status.501" class="smpl">501 (Not Implemented)</a>. |
| 1390 | | </p> |
| 1391 | | <div id="rfc.iref.c.7"></div> |
| 1392 | | <h3 id="rfc.section.3.3.2"><a href="#rfc.section.3.3.2">3.3.2</a> <a id="header.content-length" href="#header.content-length">Content-Length</a></h3> |
| 1393 | | <p id="rfc.section.3.3.2.p.1">When a message does not have a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field, a Content-Length header field can provide the anticipated size, as a decimal number of octets, for a potential |
| 1394 | | payload body. For messages that do include a payload body, the Content-Length field-value provides the framing information |
| 1395 | | necessary for determining where the body (and message) ends. For messages that do not include a payload body, the Content-Length |
| 1396 | | indicates the size of the selected representation (<a href="p2-semantics.html#representations" title="Representations">Section 3</a> of <a href="#Part2" id="rfc.xref.Part2.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). |
| 1397 | | </p> |
| 1398 | | <div id="rfc.figure.u.28"></div><pre class="inline"><span id="rfc.iref.g.55"></span> <a href="#header.content-length" class="smpl">Content-Length</a> = 1*<a href="#core.rules" class="smpl">DIGIT</a> |
| 1399 | | </pre><p id="rfc.section.3.3.2.p.3">An example is</p> |
| 1400 | | <div id="rfc.figure.u.29"></div><pre class="text"> Content-Length: 3495 |
| 1401 | | </pre><p id="rfc.section.3.3.2.p.5">A sender <em class="bcp14">MUST NOT</em> send a Content-Length header field in any message that contains a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field. |
| 1402 | | </p> |
| 1403 | | <p id="rfc.section.3.3.2.p.6">A user agent <em class="bcp14">SHOULD</em> send a Content-Length in a request message when no <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> is sent and the request method defines a meaning for an enclosed payload body. For example, a Content-Length header field |
| 1404 | | is normally sent in a POST request even when the value is 0 (indicating an empty payload body). A user agent <em class="bcp14">SHOULD NOT</em> send a Content-Length header field when the request message does not contain a payload body and the method semantics do not |
| 1405 | | anticipate such a body. |
| 1406 | | </p> |
| 1407 | | <p id="rfc.section.3.3.2.p.7">A server <em class="bcp14">MAY</em> send a Content-Length header field in a response to a HEAD request (<a href="p2-semantics.html#HEAD" title="HEAD">Section 4.3.2</a> of <a href="#Part2" id="rfc.xref.Part2.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>); a server <em class="bcp14">MUST NOT</em> send Content-Length in such a response unless its field-value equals the decimal number of octets that would have been sent |
| 1408 | | in the payload body of a response if the same request had used the GET method. |
| 1409 | | </p> |
| 1410 | | <p id="rfc.section.3.3.2.p.8">A server <em class="bcp14">MAY</em> send a Content-Length header field in a <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> response to a conditional GET request (<a href="p4-conditional.html#status.304" title="304 Not Modified">Section 4.1</a> of <a href="#Part4" id="rfc.xref.Part4.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>); a server <em class="bcp14">MUST NOT</em> send Content-Length in such a response unless its field-value equals the decimal number of octets that would have been sent |
| 1411 | | in the payload body of a <a href="p2-semantics.html#status.200" class="smpl">200 (OK)</a> response to the same request. |
| 1412 | | </p> |
| 1413 | | <p id="rfc.section.3.3.2.p.9">A server <em class="bcp14">MUST NOT</em> send a Content-Length header field in any response with a status code of <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a> or <a href="p2-semantics.html#status.204" class="smpl">204 (No Content)</a>. A server <em class="bcp14">SHOULD NOT</em> send a Content-Length header field in any <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> response to a CONNECT request (<a href="p2-semantics.html#CONNECT" title="CONNECT">Section 4.3.6</a> of <a href="#Part2" id="rfc.xref.Part2.16"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). |
| 1414 | | </p> |
| 1415 | | <p id="rfc.section.3.3.2.p.10">Aside from the cases defined above, in the absence of Transfer-Encoding, an origin server <em class="bcp14">SHOULD</em> send a Content-Length header field when the payload body size is known prior to sending the complete header block. This will |
| 1416 | | allow downstream recipients to measure transfer progress, know when a received message is complete, and potentially reuse |
| 1417 | | the connection for additional requests. |
| 1418 | | </p> |
| 1419 | | <p id="rfc.section.3.3.2.p.11">Any Content-Length field value greater than or equal to zero is valid. Since there is no predefined limit to the length of |
| 1420 | | a payload, recipients <em class="bcp14">SHOULD</em> anticipate potentially large decimal numerals and prevent parsing errors due to integer conversion overflows (<a href="#attack.protocol.element.size.overflows" title="Buffer Overflows">Section 8.3</a>). |
| 1421 | | </p> |
| 1422 | | <p id="rfc.section.3.3.2.p.12">If a message is received that has multiple Content-Length header fields with field-values consisting of the same decimal value, |
| 1423 | | or a single Content-Length header field with a field value containing a list of identical decimal values (e.g., "Content-Length: |
| 1424 | | 42, 42"), indicating that duplicate Content-Length header fields have been generated or combined by an upstream message processor, |
| 1425 | | then the recipient <em class="bcp14">MUST</em> either reject the message as invalid or replace the duplicated field-values with a single valid Content-Length field containing |
| 1426 | | that decimal value prior to determining the message body length. |
| 1427 | | </p> |
| 1428 | | <div class="note" id="rfc.section.3.3.2.p.13"> |
| 1429 | | <p> <b>Note:</b> HTTP's use of Content-Length for message framing differs significantly from the same field's use in MIME, where it is an optional |
| 1430 | | field used only within the "message/external-body" media-type. |
| 1431 | | </p> |
| 1432 | | </div> |
| 1433 | | <div id="rfc.iref.c.8"></div> |
| 1434 | | <h3 id="rfc.section.3.3.3"><a href="#rfc.section.3.3.3">3.3.3</a> <a id="message.body.length" href="#message.body.length">Message Body Length</a></h3> |
| 1435 | | <p id="rfc.section.3.3.3.p.1">The length of a message body is determined by one of the following (in order of precedence):</p> |
| 1436 | | <p id="rfc.section.3.3.3.p.2"> </p> |
| 1437 | | <ol> |
| 1438 | | <li> |
| 1439 | | <p>Any response to a HEAD request and any response with a <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a>, <a href="p2-semantics.html#status.204" class="smpl">204 (No Content)</a>, or <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> status code is always terminated by the first empty line after the header fields, regardless of the header fields present |
| 1440 | | in the message, and thus cannot contain a message body. |
| 1441 | | </p> |
| 1442 | | </li> |
| 1443 | | <li> |
| 1444 | | <p>Any <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> response to a CONNECT request implies that the connection will become a tunnel immediately after the empty line that concludes |
| 1445 | | the header fields. A client <em class="bcp14">MUST</em> ignore any <a href="#header.content-length" class="smpl">Content-Length</a> or <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header fields received in such a message. |
| 1446 | | </p> |
| 1447 | | </li> |
| 1448 | | <li> |
| 1449 | | <p>If a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field is present and the chunked transfer coding (<a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a>) is the final encoding, the message body length is determined by reading and decoding the chunked data until the transfer |
| 1450 | | coding indicates the data is complete. |
| 1451 | | </p> |
| 1452 | | <p>If a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field is present in a response and the chunked transfer coding is not the final encoding, the message body length is |
| 1453 | | determined by reading the connection until it is closed by the server. If a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field is present in a request and the chunked transfer coding is not the final encoding, the message body length cannot |
| 1454 | | be determined reliably; the server <em class="bcp14">MUST</em> respond with the <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> status code and then close the connection. |
| 1455 | | </p> |
| 1456 | | <p>If a message is received with both a <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> and a <a href="#header.content-length" class="smpl">Content-Length</a> header field, the Transfer-Encoding overrides the Content-Length. Such a message might indicate an attempt to perform request |
| 1457 | | or response smuggling (bypass of security-related checks on message routing or content) and thus ought to be handled as an |
| 1458 | | error. A sender <em class="bcp14">MUST</em> remove the received Content-Length field prior to forwarding such a message downstream. |
| 1459 | | </p> |
| 1460 | | </li> |
| 1461 | | <li> |
| 1462 | | <p>If a message is received without <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a> and with either multiple <a href="#header.content-length" class="smpl">Content-Length</a> header fields having differing field-values or a single Content-Length header field having an invalid value, then the message |
| 1463 | | framing is invalid and <em class="bcp14">MUST</em> be treated as an error to prevent request or response smuggling. If this is a request message, the server <em class="bcp14">MUST</em> respond with a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> status code and then close the connection. If this is a response message received by a proxy, the proxy <em class="bcp14">MUST</em> discard the received response, send a <a href="p2-semantics.html#status.502" class="smpl">502 (Bad Gateway)</a> status code as its downstream response, and then close the connection. If this is a response message received by a user agent, |
| 1464 | | it <em class="bcp14">MUST</em> be treated as an error by discarding the message and closing the connection. |
| 1465 | | </p> |
| 1466 | | </li> |
| 1467 | | <li> |
| 1468 | | <p>If a valid <a href="#header.content-length" class="smpl">Content-Length</a> header field is present without <a href="#header.transfer-encoding" class="smpl">Transfer-Encoding</a>, its decimal value defines the expected message body length in octets. If the sender closes the connection or the recipient |
| 1469 | | times out before the indicated number of octets are received, the recipient <em class="bcp14">MUST</em> consider the message to be incomplete and close the connection. |
| 1470 | | </p> |
| 1471 | | </li> |
| 1472 | | <li> |
| 1473 | | <p>If this is a request message and none of the above are true, then the message body length is zero (no message body is present).</p> |
| 1474 | | </li> |
| 1475 | | <li> |
| 1476 | | <p>Otherwise, this is a response message without a declared message body length, so the message body length is determined by |
| 1477 | | the number of octets received prior to the server closing the connection. |
| 1478 | | </p> |
| 1479 | | </li> |
| 1480 | | </ol> |
| 1481 | | <p id="rfc.section.3.3.3.p.3">Since there is no way to distinguish a successfully completed, close-delimited message from a partially-received message interrupted |
| 1482 | | by network failure, a server <em class="bcp14">SHOULD</em> use encoding or length-delimited messages whenever possible. The close-delimiting feature exists primarily for backwards compatibility |
| 1483 | | with HTTP/1.0. |
| 1484 | | </p> |
| 1485 | | <p id="rfc.section.3.3.3.p.4">A server <em class="bcp14">MAY</em> reject a request that contains a message body but not a <a href="#header.content-length" class="smpl">Content-Length</a> by responding with <a href="p2-semantics.html#status.411" class="smpl">411 (Length Required)</a>. |
| 1486 | | </p> |
| 1487 | | <p id="rfc.section.3.3.3.p.5">Unless a transfer coding other than chunked has been applied, a client that sends a request containing a message body <em class="bcp14">SHOULD</em> use a valid <a href="#header.content-length" class="smpl">Content-Length</a> header field if the message body length is known in advance, rather than the chunked transfer coding, since some existing |
| 1488 | | services respond to chunked with a <a href="p2-semantics.html#status.411" class="smpl">411 (Length Required)</a> status code even though they understand the chunked transfer coding. This is typically because such services are implemented |
| 1489 | | via a gateway that requires a content-length in advance of being called and the server is unable or unwilling to buffer the |
| 1490 | | entire request before processing. |
| 1491 | | </p> |
| 1492 | | <p id="rfc.section.3.3.3.p.6">A user agent that sends a request containing a message body <em class="bcp14">MUST</em> send a valid <a href="#header.content-length" class="smpl">Content-Length</a> header field if it does not know the server will handle HTTP/1.1 (or later) requests; such knowledge can be in the form of |
| 1493 | | specific user configuration or by remembering the version of a prior received response. |
| 1494 | | </p> |
| 1495 | | <p id="rfc.section.3.3.3.p.7">If the final response to the last request on a connection has been completely received and there remains additional data to |
| 1496 | | read, a user agent <em class="bcp14">MAY</em> discard the remaining data or attempt to determine if that data belongs as part of the prior response body, which might be |
| 1497 | | the case if the prior message's Content-Length value is incorrect. A client <em class="bcp14">MUST NOT</em> process, cache, or forward such extra data as a separate response, since such behavior would be vulnerable to cache poisoning. |
| 1498 | | </p> |
| 1499 | | <h2 id="rfc.section.3.4"><a href="#rfc.section.3.4">3.4</a> <a id="incomplete.messages" href="#incomplete.messages">Handling Incomplete Messages</a></h2> |
| 1500 | | <p id="rfc.section.3.4.p.1">A server that receives an incomplete request message, usually due to a canceled request or a triggered time-out exception, <em class="bcp14">MAY</em> send an error response prior to closing the connection. |
| 1501 | | </p> |
| 1502 | | <p id="rfc.section.3.4.p.2">A client that receives an incomplete response message, which can occur when a connection is closed prematurely or when decoding |
| 1503 | | a supposedly chunked transfer coding fails, <em class="bcp14">MUST</em> record the message as incomplete. Cache requirements for incomplete responses are defined in <a href="p6-cache.html#response.cacheability" title="Storing Responses in Caches">Section 3</a> of <a href="#Part6" id="rfc.xref.Part6.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. |
| 1504 | | </p> |
| 1505 | | <p id="rfc.section.3.4.p.3">If a response terminates in the middle of the header block (before the empty line is received) and the status code might rely |
| 1506 | | on header fields to convey the full meaning of the response, then the client cannot assume that meaning has been conveyed; |
| 1507 | | the client might need to repeat the request in order to determine what action to take next. |
| 1508 | | </p> |
| 1509 | | <p id="rfc.section.3.4.p.4">A message body that uses the chunked transfer coding is incomplete if the zero-sized chunk that terminates the encoding has |
| 1510 | | not been received. A message that uses a valid <a href="#header.content-length" class="smpl">Content-Length</a> is incomplete if the size of the message body received (in octets) is less than the value given by Content-Length. A response |
| 1511 | | that has neither chunked transfer coding nor Content-Length is terminated by closure of the connection, and thus is considered |
| 1512 | | complete regardless of the number of message body octets received, provided that the header block was received intact. |
| 1513 | | </p> |
| 1514 | | <h2 id="rfc.section.3.5"><a href="#rfc.section.3.5">3.5</a> <a id="message.robustness" href="#message.robustness">Message Parsing Robustness</a></h2> |
| 1515 | | <p id="rfc.section.3.5.p.1">Older HTTP/1.0 user agent implementations might send an extra CRLF after a POST request as a lame workaround for some early |
| 1516 | | server applications that failed to read message body content that was not terminated by a line-ending. An HTTP/1.1 user agent <em class="bcp14">MUST NOT</em> preface or follow a request with an extra CRLF. If terminating the request message body with a line-ending is desired, then |
| 1517 | | the user agent <em class="bcp14">MUST</em> count the terminating CRLF octets as part of the message body length. |
| 1518 | | </p> |
| 1519 | | <p id="rfc.section.3.5.p.2">In the interest of robustness, servers <em class="bcp14">SHOULD</em> ignore at least one empty line received where a request-line is expected. In other words, if a server is reading the protocol |
| 1520 | | stream at the beginning of a message and receives a CRLF first, the server <em class="bcp14">SHOULD</em> ignore the CRLF. |
| 1521 | | </p> |
| 1522 | | <p id="rfc.section.3.5.p.3">Although the line terminator for the start-line and header fields is the sequence CRLF, recipients <em class="bcp14">MAY</em> recognize a single LF as a line terminator and ignore any preceding CR. |
| 1523 | | </p> |
| 1524 | | <p id="rfc.section.3.5.p.4">Although the request-line and status-line grammar rules require that each of the component elements be separated by a single |
| 1525 | | SP octet, recipients <em class="bcp14">MAY</em> instead parse on whitespace-delimited word boundaries and, aside from the CRLF terminator, treat any form of whitespace as |
| 1526 | | the SP separator while ignoring preceding or trailing whitespace; such whitespace includes one or more of the following octets: |
| 1527 | | SP, HTAB, VT (%x0B), FF (%x0C), or bare CR. |
| 1528 | | </p> |
| 1529 | | <p id="rfc.section.3.5.p.5">When a server listening only for HTTP request messages, or processing what appears from the start-line to be an HTTP request |
| 1530 | | message, receives a sequence of octets that does not match the HTTP-message grammar aside from the robustness exceptions listed |
| 1531 | | above, the server <em class="bcp14">SHOULD</em> respond with a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> response. |
| 1532 | | </p> |
| 1533 | | <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a id="transfer.codings" href="#transfer.codings">Transfer Codings</a></h1> |
| 1534 | | <p id="rfc.section.4.p.1">Transfer coding names are used to indicate an encoding transformation that has been, can be, or might need to be applied to |
| 1535 | | a payload body in order to ensure "safe transport" through the network. This differs from a content coding in that the transfer |
| 1536 | | coding is a property of the message rather than a property of the representation that is being transferred. |
| 1537 | | </p> |
| 1538 | | <div id="rfc.figure.u.30"></div><pre class="inline"><span id="rfc.iref.g.56"></span><span id="rfc.iref.g.57"></span> <a href="#transfer.codings" class="smpl">transfer-coding</a> = "chunked" ; <a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a> |
| | 1613 | <div id="transfer.codings"> |
| | 1614 | <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a href="#transfer.codings">Transfer Codings</a></h1> |
| | 1615 | <p id="rfc.section.4.p.1">Transfer coding names are used to indicate an encoding transformation that has been, can be, or might need to be applied to |
| | 1616 | a payload body in order to ensure "safe transport" through the network. This differs from a content coding in that the transfer |
| | 1617 | coding is a property of the message rather than a property of the representation that is being transferred. |
| | 1618 | </p> |
| | 1619 | <div id="rfc.figure.u.30"></div><pre class="inline"><span id="rfc.iref.g.56"></span><span id="rfc.iref.g.57"></span> <a href="#transfer.codings" class="smpl">transfer-coding</a> = "chunked" ; <a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a> |
| 1630 | | </p> |
| 1631 | | <h2 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2</a> <a id="compression.codings" href="#compression.codings">Compression Codings</a></h2> |
| 1632 | | <p id="rfc.section.4.2.p.1">The codings defined below can be used to compress the payload of a message.</p> |
| 1633 | | <div id="rfc.iref.c.10"></div> |
| 1634 | | <h3 id="rfc.section.4.2.1"><a href="#rfc.section.4.2.1">4.2.1</a> <a id="compress.coding" href="#compress.coding">Compress Coding</a></h3> |
| 1635 | | <p id="rfc.section.4.2.1.p.1">The "compress" format is produced by the common UNIX file compression program "compress". This format is an adaptive Lempel-Ziv-Welch |
| 1636 | | coding (LZW). Recipients <em class="bcp14">SHOULD</em> consider "x-compress" to be equivalent to "compress". |
| 1637 | | </p> |
| 1638 | | <div id="rfc.iref.d.2"></div> |
| 1639 | | <h3 id="rfc.section.4.2.2"><a href="#rfc.section.4.2.2">4.2.2</a> <a id="deflate.coding" href="#deflate.coding">Deflate Coding</a></h3> |
| 1640 | | <p id="rfc.section.4.2.2.p.1">The "deflate" format is defined as the "deflate" compression mechanism (described in <a href="#RFC1951" id="rfc.xref.RFC1951.1"><cite title="DEFLATE Compressed Data Format Specification version 1.3">[RFC1951]</cite></a>) used inside the "zlib" data format (<a href="#RFC1950" id="rfc.xref.RFC1950.1"><cite title="ZLIB Compressed Data Format Specification version 3.3">[RFC1950]</cite></a>). |
| 1641 | | </p> |
| 1642 | | <div class="note" id="rfc.section.4.2.2.p.2"> |
| 1643 | | <p> <b>Note:</b> Some incorrect implementations send the "deflate" compressed data without the zlib wrapper. |
| 1644 | | </p> |
| 1645 | | </div> |
| 1646 | | <div id="rfc.iref.g.75"></div> |
| 1647 | | <h3 id="rfc.section.4.2.3"><a href="#rfc.section.4.2.3">4.2.3</a> <a id="gzip.coding" href="#gzip.coding">Gzip Coding</a></h3> |
| 1648 | | <p id="rfc.section.4.2.3.p.1">The "gzip" format is produced by the file compression program "gzip" (GNU zip), as described in <a href="#RFC1952" id="rfc.xref.RFC1952.1"><cite title="GZIP file format specification version 4.3">[RFC1952]</cite></a>. This format is a Lempel-Ziv coding (LZ77) with a 32 bit CRC. Recipients <em class="bcp14">SHOULD</em> consider "x-gzip" to be equivalent to "gzip". |
| 1649 | | </p> |
| 1650 | | <div id="rfc.iref.t.6"></div> |
| 1651 | | <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a> <a id="header.te" href="#header.te">TE</a></h2> |
| 1652 | | <p id="rfc.section.4.3.p.1">The "TE" header field in a request indicates what transfer codings, besides chunked, the client is willing to accept in response, |
| 1653 | | and whether or not the client is willing to accept trailer fields in a chunked transfer coding. |
| 1654 | | </p> |
| 1655 | | <p id="rfc.section.4.3.p.2">The TE field-value consists of a comma-separated list of transfer coding names, each allowing for optional parameters (as |
| 1656 | | described in <a href="#transfer.codings" title="Transfer Codings">Section 4</a>), and/or the keyword "trailers". Clients <em class="bcp14">MUST NOT</em> send the chunked transfer coding name in TE; chunked is always acceptable for HTTP/1.1 recipients. |
| 1657 | | </p> |
| 1658 | | <div id="rfc.figure.u.35"></div><pre class="inline"><span id="rfc.iref.g.76"></span><span id="rfc.iref.g.77"></span><span id="rfc.iref.g.78"></span><span id="rfc.iref.g.79"></span> <a href="#header.te" class="smpl">TE</a> = #<a href="#header.te" class="smpl">t-codings</a> |
| | 1715 | </p> |
| | 1716 | </div> |
| | 1717 | </div> |
| | 1718 | <div id="compression.codings"> |
| | 1719 | <h2 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2</a> <a href="#compression.codings">Compression Codings</a></h2> |
| | 1720 | <p id="rfc.section.4.2.p.1">The codings defined below can be used to compress the payload of a message.</p> |
| | 1721 | <div id="compress.coding"> |
| | 1722 | <div id="rfc.iref.c.10"></div> |
| | 1723 | <h3 id="rfc.section.4.2.1"><a href="#rfc.section.4.2.1">4.2.1</a> <a href="#compress.coding">Compress Coding</a></h3> |
| | 1724 | <p id="rfc.section.4.2.1.p.1">The "compress" format is produced by the common UNIX file compression program "compress". This format is an adaptive Lempel-Ziv-Welch |
| | 1725 | coding (LZW). Recipients <em class="bcp14">SHOULD</em> consider "x-compress" to be equivalent to "compress". |
| | 1726 | </p> |
| | 1727 | </div> |
| | 1728 | <div id="deflate.coding"> |
| | 1729 | <div id="rfc.iref.d.2"></div> |
| | 1730 | <h3 id="rfc.section.4.2.2"><a href="#rfc.section.4.2.2">4.2.2</a> <a href="#deflate.coding">Deflate Coding</a></h3> |
| | 1731 | <p id="rfc.section.4.2.2.p.1">The "deflate" format is defined as the "deflate" compression mechanism (described in <a href="#RFC1951" id="rfc.xref.RFC1951.1"><cite title="DEFLATE Compressed Data Format Specification version 1.3">[RFC1951]</cite></a>) used inside the "zlib" data format (<a href="#RFC1950" id="rfc.xref.RFC1950.1"><cite title="ZLIB Compressed Data Format Specification version 3.3">[RFC1950]</cite></a>). |
| | 1732 | </p> |
| | 1733 | <div class="note" id="rfc.section.4.2.2.p.2"> |
| | 1734 | <p><b>Note:</b> Some incorrect implementations send the "deflate" compressed data without the zlib wrapper. |
| | 1735 | </p> |
| | 1736 | </div> |
| | 1737 | </div> |
| | 1738 | <div id="gzip.coding"> |
| | 1739 | <div id="rfc.iref.g.75"></div> |
| | 1740 | <h3 id="rfc.section.4.2.3"><a href="#rfc.section.4.2.3">4.2.3</a> <a href="#gzip.coding">Gzip Coding</a></h3> |
| | 1741 | <p id="rfc.section.4.2.3.p.1">The "gzip" format is produced by the file compression program "gzip" (GNU zip), as described in <a href="#RFC1952" id="rfc.xref.RFC1952.1"><cite title="GZIP file format specification version 4.3">[RFC1952]</cite></a>. This format is a Lempel-Ziv coding (LZ77) with a 32 bit CRC. Recipients <em class="bcp14">SHOULD</em> consider "x-gzip" to be equivalent to "gzip". |
| | 1742 | </p> |
| | 1743 | </div> |
| | 1744 | </div> |
| | 1745 | <div id="header.te"> |
| | 1746 | <div id="rfc.iref.t.6"></div> |
| | 1747 | <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a> <a href="#header.te">TE</a></h2> |
| | 1748 | <p id="rfc.section.4.3.p.1">The "TE" header field in a request indicates what transfer codings, besides chunked, the client is willing to accept in response, |
| | 1749 | and whether or not the client is willing to accept trailer fields in a chunked transfer coding. |
| | 1750 | </p> |
| | 1751 | <p id="rfc.section.4.3.p.2">The TE field-value consists of a comma-separated list of transfer coding names, each allowing for optional parameters (as |
| | 1752 | described in <a href="#transfer.codings" title="Transfer Codings">Section 4</a>), and/or the keyword "trailers". Clients <em class="bcp14">MUST NOT</em> send the chunked transfer coding name in TE; chunked is always acceptable for HTTP/1.1 recipients. |
| | 1753 | </p> |
| | 1754 | <div id="rfc.figure.u.35"></div><pre class="inline"><span id="rfc.iref.g.76"></span><span id="rfc.iref.g.77"></span><span id="rfc.iref.g.78"></span><span id="rfc.iref.g.79"></span> <a href="#header.te" class="smpl">TE</a> = #<a href="#header.te" class="smpl">t-codings</a> |
| 1668 | | coding, as defined in <a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a>, on behalf of itself and any downstream clients. For chained requests, this implies that either: (a) all downstream clients |
| 1669 | | are willing to accept trailer fields in the forwarded response; or, (b) the client will attempt to buffer the response on |
| 1670 | | behalf of downstream recipients. Note that HTTP/1.1 does not define any means to limit the size of a chunked response such |
| 1671 | | that a client can be assured of buffering the entire response. |
| 1672 | | </p> |
| 1673 | | <p id="rfc.section.4.3.p.7">When multiple transfer codings are acceptable, the client <em class="bcp14">MAY</em> rank the codings by preference using a case-insensitive "q" parameter (similar to the qvalues used in content negotiation |
| 1674 | | fields, <a href="p2-semantics.html#quality.values" title="Quality Values">Section 5.3.1</a> of <a href="#Part2" id="rfc.xref.Part2.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). The rank value is a real number in the range 0 through 1, where 0.001 is the least preferred and 1 is the most preferred; |
| 1675 | | a value of 0 means "not acceptable". |
| 1676 | | </p> |
| 1677 | | <p id="rfc.section.4.3.p.8">If the TE field-value is empty or if no TE field is present, the only acceptable transfer coding is chunked. A message with |
| 1678 | | no transfer coding is always acceptable. |
| 1679 | | </p> |
| 1680 | | <p id="rfc.section.4.3.p.9">Since the TE header field only applies to the immediate connection, a sender of TE <em class="bcp14">MUST</em> also send a "TE" connection option within the <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.4" title="Connection">Section 6.1</a>) in order to prevent the TE field from being forwarded by intermediaries that do not support its semantics. |
| 1681 | | </p> |
| 1682 | | <h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a id="message.routing" href="#message.routing">Message Routing</a></h1> |
| 1683 | | <p id="rfc.section.5.p.1">HTTP request message routing is determined by each client based on the target resource, the client's proxy configuration, |
| 1684 | | and establishment or reuse of an inbound connection. The corresponding response routing follows the same connection chain |
| 1685 | | back to the client. |
| 1686 | | </p> |
| 1687 | | <div id="rfc.iref.t.7"></div> |
| 1688 | | <div id="rfc.iref.t.8"></div> |
| 1689 | | <h2 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1</a> <a id="target-resource" href="#target-resource">Identifying a Target Resource</a></h2> |
| 1690 | | <p id="rfc.section.5.1.p.1">HTTP is used in a wide variety of applications, ranging from general-purpose computers to home appliances. In some cases, |
| 1691 | | communication options are hard-coded in a client's configuration. However, most HTTP clients rely on the same resource identification |
| 1692 | | mechanism and configuration techniques as general-purpose Web browsers. |
| 1693 | | </p> |
| 1694 | | <p id="rfc.section.5.1.p.2">HTTP communication is initiated by a user agent for some purpose. The purpose is a combination of request semantics, which |
| 1695 | | are defined in <a href="#Part2" id="rfc.xref.Part2.18"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>, and a target resource upon which to apply those semantics. A URI reference (<a href="#uri" title="Uniform Resource Identifiers">Section 2.7</a>) is typically used as an identifier for the "<dfn>target resource</dfn>", which a user agent would resolve to its absolute form in order to obtain the "<dfn>target URI</dfn>". The target URI excludes the reference's fragment identifier component, if any, since fragment identifiers are reserved |
| 1696 | | for client-side processing (<a href="#RFC3986" id="rfc.xref.RFC3986.16"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-3.5">Section 3.5</a>). |
| 1697 | | </p> |
| 1698 | | <h2 id="rfc.section.5.2"><a href="#rfc.section.5.2">5.2</a> <a id="connecting.inbound" href="#connecting.inbound">Connecting Inbound</a></h2> |
| 1699 | | <p id="rfc.section.5.2.p.1">Once the target URI is determined, a client needs to decide whether a network request is necessary to accomplish the desired |
| 1700 | | semantics and, if so, where that request is to be directed. |
| 1701 | | </p> |
| 1702 | | <p id="rfc.section.5.2.p.2">If the client has a response cache and the request semantics can be satisfied by a cache (<a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>), then the request is usually directed to the cache first. |
| 1703 | | </p> |
| 1704 | | <p id="rfc.section.5.2.p.3">If the request is not satisfied by a cache, then a typical client will check its configuration to determine whether a proxy |
| 1705 | | is to be used to satisfy the request. Proxy configuration is implementation-dependent, but is often based on URI prefix matching, |
| 1706 | | selective authority matching, or both, and the proxy itself is usually identified by an "http" or "https" URI. If a proxy |
| 1707 | | is applicable, the client connects inbound by establishing (or reusing) a connection to that proxy. |
| 1708 | | </p> |
| 1709 | | <p id="rfc.section.5.2.p.4">If no proxy is applicable, a typical client will invoke a handler routine, usually specific to the target URI's scheme, to |
| 1710 | | connect directly to an authority for the target resource. How that is accomplished is dependent on the target URI scheme and |
| 1711 | | defined by its associated specification, similar to how this specification defines origin server access for resolution of |
| 1712 | | the "http" (<a href="#http.uri" title="http URI scheme">Section 2.7.1</a>) and "https" (<a href="#https.uri" title="https URI scheme">Section 2.7.2</a>) schemes. |
| 1713 | | </p> |
| 1714 | | <p id="rfc.section.5.2.p.5">HTTP requirements regarding connection management are defined in <a href="#connection.management" title="Connection Management">Section 6</a>. |
| 1715 | | </p> |
| 1716 | | <h2 id="rfc.section.5.3"><a href="#rfc.section.5.3">5.3</a> <a id="request-target" href="#request-target">Request Target</a></h2> |
| 1717 | | <p id="rfc.section.5.3.p.1">Once an inbound connection is obtained, the client sends an HTTP request message (<a href="#http.message" title="Message Format">Section 3</a>) with a request-target derived from the target URI. There are four distinct formats for the request-target, depending on |
| 1718 | | both the method being requested and whether the request is to a proxy. |
| 1719 | | </p> |
| 1720 | | <div id="rfc.figure.u.37"></div><pre class="inline"><span id="rfc.iref.g.80"></span><span id="rfc.iref.g.81"></span><span id="rfc.iref.g.82"></span><span id="rfc.iref.g.83"></span><span id="rfc.iref.g.84"></span> <a href="#request-target" class="smpl">request-target</a> = <a href="#origin-form" class="smpl">origin-form</a> |
| | 1764 | coding, as defined in <a href="#chunked.encoding" title="Chunked Transfer Coding">Section 4.1</a>, on behalf of itself and any downstream clients. For chained requests, this implies that either: (a) all downstream clients |
| | 1765 | are willing to accept trailer fields in the forwarded response; or, (b) the client will attempt to buffer the response on |
| | 1766 | behalf of downstream recipients. Note that HTTP/1.1 does not define any means to limit the size of a chunked response such |
| | 1767 | that a client can be assured of buffering the entire response. |
| | 1768 | </p> |
| | 1769 | <p id="rfc.section.4.3.p.7">When multiple transfer codings are acceptable, the client <em class="bcp14">MAY</em> rank the codings by preference using a case-insensitive "q" parameter (similar to the qvalues used in content negotiation |
| | 1770 | fields, <a href="p2-semantics.html#quality.values" title="Quality Values">Section 5.3.1</a> of <a href="#Part2" id="rfc.xref.Part2.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). The rank value is a real number in the range 0 through 1, where 0.001 is the least preferred and 1 is the most preferred; |
| | 1771 | a value of 0 means "not acceptable". |
| | 1772 | </p> |
| | 1773 | <p id="rfc.section.4.3.p.8">If the TE field-value is empty or if no TE field is present, the only acceptable transfer coding is chunked. A message with |
| | 1774 | no transfer coding is always acceptable. |
| | 1775 | </p> |
| | 1776 | <p id="rfc.section.4.3.p.9">Since the TE header field only applies to the immediate connection, a sender of TE <em class="bcp14">MUST</em> also send a "TE" connection option within the <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.4" title="Connection">Section 6.1</a>) in order to prevent the TE field from being forwarded by intermediaries that do not support its semantics. |
| | 1777 | </p> |
| | 1778 | </div> |
| | 1779 | </div> |
| | 1780 | <div id="message.routing"> |
| | 1781 | <h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a href="#message.routing">Message Routing</a></h1> |
| | 1782 | <p id="rfc.section.5.p.1">HTTP request message routing is determined by each client based on the target resource, the client's proxy configuration, |
| | 1783 | and establishment or reuse of an inbound connection. The corresponding response routing follows the same connection chain |
| | 1784 | back to the client. |
| | 1785 | </p> |
| | 1786 | <div id="target-resource"> |
| | 1787 | <div id="rfc.iref.t.7"></div> |
| | 1788 | <div id="rfc.iref.t.8"></div> |
| | 1789 | <h2 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1</a> <a href="#target-resource">Identifying a Target Resource</a></h2> |
| | 1790 | <p id="rfc.section.5.1.p.1">HTTP is used in a wide variety of applications, ranging from general-purpose computers to home appliances. In some cases, |
| | 1791 | communication options are hard-coded in a client's configuration. However, most HTTP clients rely on the same resource identification |
| | 1792 | mechanism and configuration techniques as general-purpose Web browsers. |
| | 1793 | </p> |
| | 1794 | <p id="rfc.section.5.1.p.2">HTTP communication is initiated by a user agent for some purpose. The purpose is a combination of request semantics, which |
| | 1795 | are defined in <a href="#Part2" id="rfc.xref.Part2.18"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>, and a target resource upon which to apply those semantics. A URI reference (<a href="#uri" title="Uniform Resource Identifiers">Section 2.7</a>) is typically used as an identifier for the "<dfn>target resource</dfn>", which a user agent would resolve to its absolute form in order to obtain the "<dfn>target URI</dfn>". The target URI excludes the reference's fragment identifier component, if any, since fragment identifiers are reserved |
| | 1796 | for client-side processing (<a href="#RFC3986" id="rfc.xref.RFC3986.16"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="https://tools.ietf.org/html/rfc3986#section-3.5">Section 3.5</a>). |
| | 1797 | </p> |
| | 1798 | </div> |
| | 1799 | <div id="connecting.inbound"> |
| | 1800 | <h2 id="rfc.section.5.2"><a href="#rfc.section.5.2">5.2</a> <a href="#connecting.inbound">Connecting Inbound</a></h2> |
| | 1801 | <p id="rfc.section.5.2.p.1">Once the target URI is determined, a client needs to decide whether a network request is necessary to accomplish the desired |
| | 1802 | semantics and, if so, where that request is to be directed. |
| | 1803 | </p> |
| | 1804 | <p id="rfc.section.5.2.p.2">If the client has a response cache and the request semantics can be satisfied by a cache (<a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>), then the request is usually directed to the cache first. |
| | 1805 | </p> |
| | 1806 | <p id="rfc.section.5.2.p.3">If the request is not satisfied by a cache, then a typical client will check its configuration to determine whether a proxy |
| | 1807 | is to be used to satisfy the request. Proxy configuration is implementation-dependent, but is often based on URI prefix matching, |
| | 1808 | selective authority matching, or both, and the proxy itself is usually identified by an "http" or "https" URI. If a proxy |
| | 1809 | is applicable, the client connects inbound by establishing (or reusing) a connection to that proxy. |
| | 1810 | </p> |
| | 1811 | <p id="rfc.section.5.2.p.4">If no proxy is applicable, a typical client will invoke a handler routine, usually specific to the target URI's scheme, to |
| | 1812 | connect directly to an authority for the target resource. How that is accomplished is dependent on the target URI scheme and |
| | 1813 | defined by its associated specification, similar to how this specification defines origin server access for resolution of |
| | 1814 | the "http" (<a href="#http.uri" title="http URI scheme">Section 2.7.1</a>) and "https" (<a href="#https.uri" title="https URI scheme">Section 2.7.2</a>) schemes. |
| | 1815 | </p> |
| | 1816 | <p id="rfc.section.5.2.p.5">HTTP requirements regarding connection management are defined in <a href="#connection.management" title="Connection Management">Section 6</a>. |
| | 1817 | </p> |
| | 1818 | </div> |
| | 1819 | <div id="request-target"> |
| | 1820 | <h2 id="rfc.section.5.3"><a href="#rfc.section.5.3">5.3</a> <a href="#request-target">Request Target</a></h2> |
| | 1821 | <p id="rfc.section.5.3.p.1">Once an inbound connection is obtained, the client sends an HTTP request message (<a href="#http.message" title="Message Format">Section 3</a>) with a request-target derived from the target URI. There are four distinct formats for the request-target, depending on |
| | 1822 | both the method being requested and whether the request is to a proxy. |
| | 1823 | </p> |
| | 1824 | <div id="rfc.figure.u.37"></div><pre class="inline"><span id="rfc.iref.g.80"></span><span id="rfc.iref.g.81"></span><span id="rfc.iref.g.82"></span><span id="rfc.iref.g.83"></span><span id="rfc.iref.g.84"></span> <a href="#request-target" class="smpl">request-target</a> = <a href="#origin-form" class="smpl">origin-form</a> |
| 1795 | | to be forwarded through ancient HTTP/1.0 proxies that might not have implemented Host. |
| 1796 | | </p> |
| 1797 | | <p id="rfc.section.5.4.p.7">When a proxy receives a request with an absolute-form of request-target, the proxy <em class="bcp14">MUST</em> ignore the received Host header field (if any) and instead replace it with the host information of the request-target. If |
| 1798 | | the proxy forwards the request, it <em class="bcp14">MUST</em> generate a new Host field-value based on the received request-target rather than forward the received Host field-value. |
| 1799 | | </p> |
| 1800 | | <p id="rfc.section.5.4.p.8">Since the Host header field acts as an application-level routing mechanism, it is a frequent target for malware seeking to |
| 1801 | | poison a shared cache or redirect a request to an unintended server. An interception proxy is particularly vulnerable if it |
| 1802 | | relies on the Host field-value for redirecting requests to internal servers, or for use as a cache key in a shared cache, |
| 1803 | | without first verifying that the intercepted connection is targeting a valid IP address for that host. |
| 1804 | | </p> |
| 1805 | | <p id="rfc.section.5.4.p.9">A server <em class="bcp14">MUST</em> respond with a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> status code to any HTTP/1.1 request message that lacks a Host header field and to any request message that contains more than |
| 1806 | | one Host header field or a Host header field with an invalid field-value. |
| 1807 | | </p> |
| 1808 | | <div id="rfc.iref.e.1"></div> |
| 1809 | | <h2 id="rfc.section.5.5"><a href="#rfc.section.5.5">5.5</a> <a id="effective.request.uri" href="#effective.request.uri">Effective Request URI</a></h2> |
| 1810 | | <p id="rfc.section.5.5.p.1">A server that receives an HTTP request message <em class="bcp14">MUST</em> reconstruct the user agent's original target URI, based on the pieces of information learned from the request-target, <a href="#header.host" class="smpl">Host</a> header field, and connection context, in order to identify the intended target resource and properly service the request. |
| 1811 | | The URI derived from this reconstruction process is referred to as the "<dfn>effective request URI</dfn>". |
| 1812 | | </p> |
| 1813 | | <p id="rfc.section.5.5.p.2">For a user agent, the effective request URI is the target URI.</p> |
| 1814 | | <p id="rfc.section.5.5.p.3">If the request-target is in absolute-form, then the effective request URI is the same as the request-target. Otherwise, the |
| 1815 | | effective request URI is constructed as follows. |
| 1816 | | </p> |
| 1817 | | <p id="rfc.section.5.5.p.4">If the request is received over a TLS-secured TCP connection, then the effective request URI's scheme is "https"; otherwise, |
| 1818 | | the scheme is "http". |
| 1819 | | </p> |
| 1820 | | <p id="rfc.section.5.5.p.5">If the request-target is in authority-form, then the effective request URI's authority component is the same as the request-target. |
| 1821 | | Otherwise, if a <a href="#header.host" class="smpl">Host</a> header field is supplied with a non-empty field-value, then the authority component is the same as the Host field-value. Otherwise, |
| 1822 | | the authority component is the concatenation of the default host name configured for the server, a colon (":"), and the connection's |
| 1823 | | incoming TCP port number in decimal form. |
| 1824 | | </p> |
| 1825 | | <p id="rfc.section.5.5.p.6">If the request-target is in authority-form or asterisk-form, then the effective request URI's combined path and query component |
| 1826 | | is empty. Otherwise, the combined path and query component is the same as the request-target. |
| 1827 | | </p> |
| 1828 | | <p id="rfc.section.5.5.p.7">The components of the effective request URI, once determined as above, can be combined into absolute-URI form by concatenating |
| 1829 | | the scheme, "://", authority, and combined path and query component. |
| 1830 | | </p> |
| 1831 | | <div id="rfc.figure.u.47"></div> |
| 1832 | | <p>Example 1: the following message received over an insecure TCP connection</p> <pre class="text">GET /pub/WWW/TheProject.html HTTP/1.1 |
| | 1901 | to be forwarded through ancient HTTP/1.0 proxies that might not have implemented Host. |
| | 1902 | </p> |
| | 1903 | <p id="rfc.section.5.4.p.7">When a proxy receives a request with an absolute-form of request-target, the proxy <em class="bcp14">MUST</em> ignore the received Host header field (if any) and instead replace it with the host information of the request-target. If |
| | 1904 | the proxy forwards the request, it <em class="bcp14">MUST</em> generate a new Host field-value based on the received request-target rather than forward the received Host field-value. |
| | 1905 | </p> |
| | 1906 | <p id="rfc.section.5.4.p.8">Since the Host header field acts as an application-level routing mechanism, it is a frequent target for malware seeking to |
| | 1907 | poison a shared cache or redirect a request to an unintended server. An interception proxy is particularly vulnerable if it |
| | 1908 | relies on the Host field-value for redirecting requests to internal servers, or for use as a cache key in a shared cache, |
| | 1909 | without first verifying that the intercepted connection is targeting a valid IP address for that host. |
| | 1910 | </p> |
| | 1911 | <p id="rfc.section.5.4.p.9">A server <em class="bcp14">MUST</em> respond with a <a href="p2-semantics.html#status.400" class="smpl">400 (Bad Request)</a> status code to any HTTP/1.1 request message that lacks a Host header field and to any request message that contains more than |
| | 1912 | one Host header field or a Host header field with an invalid field-value. |
| | 1913 | </p> |
| | 1914 | </div> |
| | 1915 | <div id="effective.request.uri"> |
| | 1916 | <div id="rfc.iref.e.1"></div> |
| | 1917 | <h2 id="rfc.section.5.5"><a href="#rfc.section.5.5">5.5</a> <a href="#effective.request.uri">Effective Request URI</a></h2> |
| | 1918 | <p id="rfc.section.5.5.p.1">A server that receives an HTTP request message <em class="bcp14">MUST</em> reconstruct the user agent's original target URI, based on the pieces of information learned from the request-target, <a href="#header.host" class="smpl">Host</a> header field, and connection context, in order to identify the intended target resource and properly service the request. |
| | 1919 | The URI derived from this reconstruction process is referred to as the "<dfn>effective request URI</dfn>". |
| | 1920 | </p> |
| | 1921 | <p id="rfc.section.5.5.p.2">For a user agent, the effective request URI is the target URI.</p> |
| | 1922 | <p id="rfc.section.5.5.p.3">If the request-target is in absolute-form, then the effective request URI is the same as the request-target. Otherwise, the |
| | 1923 | effective request URI is constructed as follows. |
| | 1924 | </p> |
| | 1925 | <p id="rfc.section.5.5.p.4">If the request is received over a TLS-secured TCP connection, then the effective request URI's scheme is "https"; otherwise, |
| | 1926 | the scheme is "http". |
| | 1927 | </p> |
| | 1928 | <p id="rfc.section.5.5.p.5">If the request-target is in authority-form, then the effective request URI's authority component is the same as the request-target. |
| | 1929 | Otherwise, if a <a href="#header.host" class="smpl">Host</a> header field is supplied with a non-empty field-value, then the authority component is the same as the Host field-value. Otherwise, |
| | 1930 | the authority component is the concatenation of the default host name configured for the server, a colon (":"), and the connection's |
| | 1931 | incoming TCP port number in decimal form. |
| | 1932 | </p> |
| | 1933 | <p id="rfc.section.5.5.p.6">If the request-target is in authority-form or asterisk-form, then the effective request URI's combined path and query component |
| | 1934 | is empty. Otherwise, the combined path and query component is the same as the request-target. |
| | 1935 | </p> |
| | 1936 | <p id="rfc.section.5.5.p.7">The components of the effective request URI, once determined as above, can be combined into absolute-URI form by concatenating |
| | 1937 | the scheme, "://", authority, and combined path and query component. |
| | 1938 | </p> |
| | 1939 | <div id="rfc.figure.u.47"></div> |
| | 1940 | <p>Example 1: the following message received over an insecure TCP connection</p><pre class="text">GET /pub/WWW/TheProject.html HTTP/1.1 |
| 1839 | | </pre> <div id="rfc.figure.u.50"></div> |
| 1840 | | <p>has an effective request URI of</p> <pre class="text">https://www.example.org |
| 1841 | | </pre> <p id="rfc.section.5.5.p.12">An origin server that does not allow resources to differ by requested host <em class="bcp14">MAY</em> ignore the <a href="#header.host" class="smpl">Host</a> field-value and instead replace it with a configured server name when constructing the effective request URI. |
| 1842 | | </p> |
| 1843 | | <p id="rfc.section.5.5.p.13">Recipients of an HTTP/1.0 request that lacks a <a href="#header.host" class="smpl">Host</a> header field <em class="bcp14">MAY</em> attempt to use heuristics (e.g., examination of the URI path for something unique to a particular host) in order to guess |
| 1844 | | the effective request URI's authority component. |
| 1845 | | </p> |
| 1846 | | <h2 id="rfc.section.5.6"><a href="#rfc.section.5.6">5.6</a> <a id="associating.response.to.request" href="#associating.response.to.request">Associating a Response to a Request</a></h2> |
| 1847 | | <p id="rfc.section.5.6.p.1">HTTP does not include a request identifier for associating a given request message with its corresponding one or more response |
| 1848 | | messages. Hence, it relies on the order of response arrival to correspond exactly to the order in which requests are made |
| 1849 | | on the same connection. More than one response message per request only occurs when one or more informational responses (<a href="p2-semantics.html#status.1xx" class="smpl">1xx</a>, see <a href="p2-semantics.html#status.1xx" title="Informational 1xx">Section 6.2</a> of <a href="#Part2" id="rfc.xref.Part2.21"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) precede a final response to the same request. |
| 1850 | | </p> |
| 1851 | | <p id="rfc.section.5.6.p.2">A client that has more than one outstanding request on a connection <em class="bcp14">MUST</em> maintain a list of outstanding requests in the order sent and <em class="bcp14">MUST</em> associate each received response message on that connection to the highest ordered request that has not yet received a final |
| 1852 | | (non-<a href="p2-semantics.html#status.1xx" class="smpl">1xx</a>) response. |
| 1853 | | </p> |
| 1854 | | <h2 id="rfc.section.5.7"><a href="#rfc.section.5.7">5.7</a> <a id="message.forwarding" href="#message.forwarding">Message Forwarding</a></h2> |
| 1855 | | <p id="rfc.section.5.7.p.1">As described in <a href="#intermediaries" title="Intermediaries">Section 2.3</a>, intermediaries can serve a variety of roles in the processing of HTTP requests and responses. Some intermediaries are used |
| 1856 | | to improve performance or availability. Others are used for access control or to filter content. Since an HTTP stream has |
| 1857 | | characteristics similar to a pipe-and-filter architecture, there are no inherent limits to the extent an intermediary can |
| 1858 | | enhance (or interfere) with either direction of the stream. |
| 1859 | | </p> |
| 1860 | | <p id="rfc.section.5.7.p.2">Intermediaries that forward a message <em class="bcp14">MUST</em> implement the <a href="#header.connection" class="smpl">Connection</a> header field, as specified in <a href="#header.connection" id="rfc.xref.header.connection.5" title="Connection">Section 6.1</a>, to exclude fields that are only intended for the incoming connection. |
| 1861 | | </p> |
| 1862 | | <p id="rfc.section.5.7.p.3">In order to avoid request loops, a proxy that forwards requests to other proxies <em class="bcp14">MUST</em> be able to recognize and exclude all of its own server names, including any aliases, local variations, or literal IP addresses. |
| 1863 | | </p> |
| 1864 | | <div id="rfc.iref.v.1"></div> |
| 1865 | | <h3 id="rfc.section.5.7.1"><a href="#rfc.section.5.7.1">5.7.1</a> <a id="header.via" href="#header.via">Via</a></h3> |
| 1866 | | <p id="rfc.section.5.7.1.p.1">The "Via" header field <em class="bcp14">MUST</em> be sent by a proxy or gateway in forwarded messages to indicate the intermediate protocols and recipients between the user |
| 1867 | | agent and the server on requests, and between the origin server and the client on responses. It is analogous to the "Received" |
| 1868 | | field used by email systems (<a href="http://tools.ietf.org/html/rfc5322#section-3.6.7">Section 3.6.7</a> of <a href="#RFC5322" id="rfc.xref.RFC5322.3"><cite title="Internet Message Format">[RFC5322]</cite></a>). Via is used in HTTP for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of |
| 1869 | | all senders along the request/response chain. |
| 1870 | | </p> |
| 1871 | | <div id="rfc.figure.u.51"></div><pre class="inline"><span id="rfc.iref.g.86"></span><span id="rfc.iref.g.87"></span><span id="rfc.iref.g.88"></span><span id="rfc.iref.g.89"></span><span id="rfc.iref.g.90"></span><span id="rfc.iref.g.91"></span> <a href="#header.via" class="smpl">Via</a> = 1#( <a href="#header.via" class="smpl">received-protocol</a> <a href="#rule.whitespace" class="smpl">RWS</a> <a href="#header.via" class="smpl">received-by</a> |
| | 1947 | </pre><div id="rfc.figure.u.50"></div> |
| | 1948 | <p>has an effective request URI of</p><pre class="text">https://www.example.org |
| | 1949 | </pre><p id="rfc.section.5.5.p.12">An origin server that does not allow resources to differ by requested host <em class="bcp14">MAY</em> ignore the <a href="#header.host" class="smpl">Host</a> field-value and instead replace it with a configured server name when constructing the effective request URI. |
| | 1950 | </p> |
| | 1951 | <p id="rfc.section.5.5.p.13">Recipients of an HTTP/1.0 request that lacks a <a href="#header.host" class="smpl">Host</a> header field <em class="bcp14">MAY</em> attempt to use heuristics (e.g., examination of the URI path for something unique to a particular host) in order to guess |
| | 1952 | the effective request URI's authority component. |
| | 1953 | </p> |
| | 1954 | </div> |
| | 1955 | <div id="associating.response.to.request"> |
| | 1956 | <h2 id="rfc.section.5.6"><a href="#rfc.section.5.6">5.6</a> <a href="#associating.response.to.request">Associating a Response to a Request</a></h2> |
| | 1957 | <p id="rfc.section.5.6.p.1">HTTP does not include a request identifier for associating a given request message with its corresponding one or more response |
| | 1958 | messages. Hence, it relies on the order of response arrival to correspond exactly to the order in which requests are made |
| | 1959 | on the same connection. More than one response message per request only occurs when one or more informational responses (<a href="p2-semantics.html#status.1xx" class="smpl">1xx</a>, see <a href="p2-semantics.html#status.1xx" title="Informational 1xx">Section 6.2</a> of <a href="#Part2" id="rfc.xref.Part2.21"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) precede a final response to the same request. |
| | 1960 | </p> |
| | 1961 | <p id="rfc.section.5.6.p.2">A client that has more than one outstanding request on a connection <em class="bcp14">MUST</em> maintain a list of outstanding requests in the order sent and <em class="bcp14">MUST</em> associate each received response message on that connection to the highest ordered request that has not yet received a final |
| | 1962 | (non-<a href="p2-semantics.html#status.1xx" class="smpl">1xx</a>) response. |
| | 1963 | </p> |
| | 1964 | </div> |
| | 1965 | <div id="message.forwarding"> |
| | 1966 | <h2 id="rfc.section.5.7"><a href="#rfc.section.5.7">5.7</a> <a href="#message.forwarding">Message Forwarding</a></h2> |
| | 1967 | <p id="rfc.section.5.7.p.1">As described in <a href="#intermediaries" title="Intermediaries">Section 2.3</a>, intermediaries can serve a variety of roles in the processing of HTTP requests and responses. Some intermediaries are used |
| | 1968 | to improve performance or availability. Others are used for access control or to filter content. Since an HTTP stream has |
| | 1969 | characteristics similar to a pipe-and-filter architecture, there are no inherent limits to the extent an intermediary can |
| | 1970 | enhance (or interfere) with either direction of the stream. |
| | 1971 | </p> |
| | 1972 | <p id="rfc.section.5.7.p.2">Intermediaries that forward a message <em class="bcp14">MUST</em> implement the <a href="#header.connection" class="smpl">Connection</a> header field, as specified in <a href="#header.connection" id="rfc.xref.header.connection.5" title="Connection">Section 6.1</a>, to exclude fields that are only intended for the incoming connection. |
| | 1973 | </p> |
| | 1974 | <p id="rfc.section.5.7.p.3">In order to avoid request loops, a proxy that forwards requests to other proxies <em class="bcp14">MUST</em> be able to recognize and exclude all of its own server names, including any aliases, local variations, or literal IP addresses. |
| | 1975 | </p> |
| | 1976 | <div id="header.via"> |
| | 1977 | <div id="rfc.iref.v.1"></div> |
| | 1978 | <h3 id="rfc.section.5.7.1"><a href="#rfc.section.5.7.1">5.7.1</a> <a href="#header.via">Via</a></h3> |
| | 1979 | <p id="rfc.section.5.7.1.p.1">The "Via" header field <em class="bcp14">MUST</em> be sent by a proxy or gateway in forwarded messages to indicate the intermediate protocols and recipients between the user |
| | 1980 | agent and the server on requests, and between the origin server and the client on responses. It is analogous to the "Received" |
| | 1981 | field used by email systems (<a href="https://tools.ietf.org/html/rfc5322#section-3.6.7">Section 3.6.7</a> of <a href="#RFC5322" id="rfc.xref.RFC5322.3"><cite title="Internet Message Format">[RFC5322]</cite></a>). Via is used in HTTP for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of |
| | 1982 | all senders along the request/response chain. |
| | 1983 | </p> |
| | 1984 | <div id="rfc.figure.u.51"></div><pre class="inline"><span id="rfc.iref.g.86"></span><span id="rfc.iref.g.87"></span><span id="rfc.iref.g.88"></span><span id="rfc.iref.g.89"></span><span id="rfc.iref.g.90"></span><span id="rfc.iref.g.91"></span> <a href="#header.via" class="smpl">Via</a> = 1#( <a href="#header.via" class="smpl">received-protocol</a> <a href="#rule.whitespace" class="smpl">RWS</a> <a href="#header.via" class="smpl">received-by</a> |
| 1904 | | by pseudonyms. Senders <em class="bcp14">MUST NOT</em> combine entries that have different received-protocol values. |
| 1905 | | </p> |
| 1906 | | <h3 id="rfc.section.5.7.2"><a href="#rfc.section.5.7.2">5.7.2</a> <a id="message.transformations" href="#message.transformations">Transformations</a></h3> |
| 1907 | | <p id="rfc.section.5.7.2.p.1">Some intermediaries include features for transforming messages and their payloads. A transforming proxy might, for example, |
| 1908 | | convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. However, operational |
| 1909 | | problems might occur when these transformations are applied to payloads intended for critical applications, such as medical |
| 1910 | | imaging or scientific data analysis, particularly when integrity checks or digital signatures are used to ensure that the |
| 1911 | | payload received is identical to the original. |
| 1912 | | </p> |
| 1913 | | <p id="rfc.section.5.7.2.p.2">If a proxy receives a request-target with a host name that is not a fully qualified domain name, it <em class="bcp14">MAY</em> add its own domain to the host name it received when forwarding the request. A proxy <em class="bcp14">MUST NOT</em> change the host name if it is a fully qualified domain name. |
| 1914 | | </p> |
| 1915 | | <p id="rfc.section.5.7.2.p.3">A proxy <em class="bcp14">MUST NOT</em> modify the "absolute-path" and "query" parts of the received request-target when forwarding it to the next inbound server, |
| 1916 | | except as noted above to replace an empty path with "/" or "*". |
| 1917 | | </p> |
| 1918 | | <p id="rfc.section.5.7.2.p.4">A proxy <em class="bcp14">MUST NOT</em> modify header fields that provide information about the end points of the communication chain, the resource state, or the |
| 1919 | | selected representation. A proxy <em class="bcp14">MAY</em> change the message body through application or removal of a transfer coding (<a href="#transfer.codings" title="Transfer Codings">Section 4</a>). |
| 1920 | | </p> |
| 1921 | | <p id="rfc.section.5.7.2.p.5">A non-transforming proxy <em class="bcp14">MUST</em> preserve the message payload (<a href="p2-semantics.html#payload" title="Payload Semantics">Section 3.3</a> of <a href="#Part2" id="rfc.xref.Part2.22"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). A transforming proxy <em class="bcp14">MUST</em> preserve the payload of a message that contains the no-transform cache-control directive. |
| 1922 | | </p> |
| 1923 | | <p id="rfc.section.5.7.2.p.6">A transforming proxy <em class="bcp14">MAY</em> transform the payload of a message that does not contain the no-transform cache-control directive; if the payload is transformed, |
| 1924 | | the transforming proxy <em class="bcp14">MUST</em> add a Warning 214 (Transformation applied) header field if one does not already appear in the message (see <a href="p6-cache.html#header.warning" title="Warning">Section 7.5</a> of <a href="#Part6" id="rfc.xref.Part6.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 1925 | | </p> |
| 1926 | | <h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a> <a id="connection.management" href="#connection.management">Connection Management</a></h1> |
| 1927 | | <p id="rfc.section.6.p.1">HTTP messaging is independent of the underlying transport or session-layer connection protocol(s). HTTP only presumes a reliable |
| 1928 | | transport with in-order delivery of requests and the corresponding in-order delivery of responses. The mapping of HTTP request |
| 1929 | | and response structures onto the data units of an underlying transport protocol is outside the scope of this specification. |
| 1930 | | </p> |
| 1931 | | <p id="rfc.section.6.p.2">As described in <a href="#connecting.inbound" title="Connecting Inbound">Section 5.2</a>, the specific connection protocols to be used for an HTTP interaction are determined by client configuration and the <a href="#target-resource" class="smpl">target URI</a>. For example, the "http" URI scheme (<a href="#http.uri" title="http URI scheme">Section 2.7.1</a>) indicates a default connection of TCP over IP, with a default TCP port of 80, but the client might be configured to use |
| 1932 | | a proxy via some other connection, port, or protocol. |
| 1933 | | </p> |
| 1934 | | <p id="rfc.section.6.p.3">HTTP implementations are expected to engage in connection management, which includes maintaining the state of current connections, |
| 1935 | | establishing a new connection or reusing an existing connection, processing messages received on a connection, detecting connection |
| 1936 | | failures, and closing each connection. Most clients maintain multiple connections in parallel, including more than one connection |
| 1937 | | per server endpoint. Most servers are designed to maintain thousands of concurrent connections, while controlling request |
| 1938 | | queues to enable fair use and detect denial of service attacks. |
| 1939 | | </p> |
| 1940 | | <div id="rfc.iref.c.11"></div> |
| 1941 | | <div id="rfc.iref.c.12"></div> |
| 1942 | | <h2 id="rfc.section.6.1"><a href="#rfc.section.6.1">6.1</a> <a id="header.connection" href="#header.connection">Connection</a></h2> |
| 1943 | | <p id="rfc.section.6.1.p.1">The "Connection" header field allows the sender to indicate desired control options for the current connection. In order to |
| 1944 | | avoid confusing downstream recipients, a proxy or gateway <em class="bcp14">MUST</em> remove or replace any received connection options before forwarding the message. |
| 1945 | | </p> |
| 1946 | | <p id="rfc.section.6.1.p.2">When a header field aside from Connection is used to supply control information for or about the current connection, the sender <em class="bcp14">MUST</em> list the corresponding field-name within the "Connection" header field. A proxy or gateway <em class="bcp14">MUST</em> parse a received Connection header field before a message is forwarded and, for each connection-option in this field, remove |
| 1947 | | any header field(s) from the message with the same name as the connection-option, and then remove the Connection header field |
| 1948 | | itself (or replace it with the intermediary's own connection options for the forwarded message). |
| 1949 | | </p> |
| 1950 | | <p id="rfc.section.6.1.p.3">Hence, the Connection header field provides a declarative way of distinguishing header fields that are only intended for the |
| 1951 | | immediate recipient ("hop-by-hop") from those fields that are intended for all recipients on the chain ("end-to-end"), enabling |
| 1952 | | the message to be self-descriptive and allowing future connection-specific extensions to be deployed without fear that they |
| 1953 | | will be blindly forwarded by older intermediaries. |
| 1954 | | </p> |
| 1955 | | <p id="rfc.section.6.1.p.4">The Connection header field's value has the following grammar:</p> |
| 1956 | | <div id="rfc.figure.u.55"></div><pre class="inline"><span id="rfc.iref.g.92"></span><span id="rfc.iref.g.93"></span> <a href="#header.connection" class="smpl">Connection</a> = 1#<a href="#header.connection" class="smpl">connection-option</a> |
| | 2017 | by pseudonyms. Senders <em class="bcp14">MUST NOT</em> combine entries that have different received-protocol values. |
| | 2018 | </p> |
| | 2019 | </div> |
| | 2020 | <div id="message.transformations"> |
| | 2021 | <h3 id="rfc.section.5.7.2"><a href="#rfc.section.5.7.2">5.7.2</a> <a href="#message.transformations">Transformations</a></h3> |
| | 2022 | <p id="rfc.section.5.7.2.p.1">Some intermediaries include features for transforming messages and their payloads. A transforming proxy might, for example, |
| | 2023 | convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. However, operational |
| | 2024 | problems might occur when these transformations are applied to payloads intended for critical applications, such as medical |
| | 2025 | imaging or scientific data analysis, particularly when integrity checks or digital signatures are used to ensure that the |
| | 2026 | payload received is identical to the original. |
| | 2027 | </p> |
| | 2028 | <p id="rfc.section.5.7.2.p.2">If a proxy receives a request-target with a host name that is not a fully qualified domain name, it <em class="bcp14">MAY</em> add its own domain to the host name it received when forwarding the request. A proxy <em class="bcp14">MUST NOT</em> change the host name if it is a fully qualified domain name. |
| | 2029 | </p> |
| | 2030 | <p id="rfc.section.5.7.2.p.3">A proxy <em class="bcp14">MUST NOT</em> modify the "absolute-path" and "query" parts of the received request-target when forwarding it to the next inbound server, |
| | 2031 | except as noted above to replace an empty path with "/" or "*". |
| | 2032 | </p> |
| | 2033 | <p id="rfc.section.5.7.2.p.4">A proxy <em class="bcp14">MUST NOT</em> modify header fields that provide information about the end points of the communication chain, the resource state, or the |
| | 2034 | selected representation. A proxy <em class="bcp14">MAY</em> change the message body through application or removal of a transfer coding (<a href="#transfer.codings" title="Transfer Codings">Section 4</a>). |
| | 2035 | </p> |
| | 2036 | <p id="rfc.section.5.7.2.p.5">A non-transforming proxy <em class="bcp14">MUST</em> preserve the message payload (<a href="p2-semantics.html#payload" title="Payload Semantics">Section 3.3</a> of <a href="#Part2" id="rfc.xref.Part2.22"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). A transforming proxy <em class="bcp14">MUST</em> preserve the payload of a message that contains the no-transform cache-control directive. |
| | 2037 | </p> |
| | 2038 | <p id="rfc.section.5.7.2.p.6">A transforming proxy <em class="bcp14">MAY</em> transform the payload of a message that does not contain the no-transform cache-control directive; if the payload is transformed, |
| | 2039 | the transforming proxy <em class="bcp14">MUST</em> add a Warning 214 (Transformation applied) header field if one does not already appear in the message (see <a href="p6-cache.html#header.warning" title="Warning">Section 7.5</a> of <a href="#Part6" id="rfc.xref.Part6.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| | 2040 | </p> |
| | 2041 | </div> |
| | 2042 | </div> |
| | 2043 | </div> |
| | 2044 | <div id="connection.management"> |
| | 2045 | <h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a> <a href="#connection.management">Connection Management</a></h1> |
| | 2046 | <p id="rfc.section.6.p.1">HTTP messaging is independent of the underlying transport or session-layer connection protocol(s). HTTP only presumes a reliable |
| | 2047 | transport with in-order delivery of requests and the corresponding in-order delivery of responses. The mapping of HTTP request |
| | 2048 | and response structures onto the data units of an underlying transport protocol is outside the scope of this specification. |
| | 2049 | </p> |
| | 2050 | <p id="rfc.section.6.p.2">As described in <a href="#connecting.inbound" title="Connecting Inbound">Section 5.2</a>, the specific connection protocols to be used for an HTTP interaction are determined by client configuration and the <a href="#target-resource" class="smpl">target URI</a>. For example, the "http" URI scheme (<a href="#http.uri" title="http URI scheme">Section 2.7.1</a>) indicates a default connection of TCP over IP, with a default TCP port of 80, but the client might be configured to use |
| | 2051 | a proxy via some other connection, port, or protocol. |
| | 2052 | </p> |
| | 2053 | <p id="rfc.section.6.p.3">HTTP implementations are expected to engage in connection management, which includes maintaining the state of current connections, |
| | 2054 | establishing a new connection or reusing an existing connection, processing messages received on a connection, detecting connection |
| | 2055 | failures, and closing each connection. Most clients maintain multiple connections in parallel, including more than one connection |
| | 2056 | per server endpoint. Most servers are designed to maintain thousands of concurrent connections, while controlling request |
| | 2057 | queues to enable fair use and detect denial of service attacks. |
| | 2058 | </p> |
| | 2059 | <div id="header.connection"> |
| | 2060 | <div id="rfc.iref.c.11"></div> |
| | 2061 | <div id="rfc.iref.c.12"></div> |
| | 2062 | <h2 id="rfc.section.6.1"><a href="#rfc.section.6.1">6.1</a> <a href="#header.connection">Connection</a></h2> |
| | 2063 | <p id="rfc.section.6.1.p.1">The "Connection" header field allows the sender to indicate desired control options for the current connection. In order to |
| | 2064 | avoid confusing downstream recipients, a proxy or gateway <em class="bcp14">MUST</em> remove or replace any received connection options before forwarding the message. |
| | 2065 | </p> |
| | 2066 | <p id="rfc.section.6.1.p.2">When a header field aside from Connection is used to supply control information for or about the current connection, the sender <em class="bcp14">MUST</em> list the corresponding field-name within the "Connection" header field. A proxy or gateway <em class="bcp14">MUST</em> parse a received Connection header field before a message is forwarded and, for each connection-option in this field, remove |
| | 2067 | any header field(s) from the message with the same name as the connection-option, and then remove the Connection header field |
| | 2068 | itself (or replace it with the intermediary's own connection options for the forwarded message). |
| | 2069 | </p> |
| | 2070 | <p id="rfc.section.6.1.p.3">Hence, the Connection header field provides a declarative way of distinguishing header fields that are only intended for the |
| | 2071 | immediate recipient ("hop-by-hop") from those fields that are intended for all recipients on the chain ("end-to-end"), enabling |
| | 2072 | the message to be self-descriptive and allowing future connection-specific extensions to be deployed without fear that they |
| | 2073 | will be blindly forwarded by older intermediaries. |
| | 2074 | </p> |
| | 2075 | <p id="rfc.section.6.1.p.4">The Connection header field's value has the following grammar:</p> |
| | 2076 | <div id="rfc.figure.u.55"></div><pre class="inline"><span id="rfc.iref.g.92"></span><span id="rfc.iref.g.93"></span> <a href="#header.connection" class="smpl">Connection</a> = 1#<a href="#header.connection" class="smpl">connection-option</a> |
| 1978 | | </p> |
| 1979 | | <p id="rfc.section.6.1.p.13">A client that does not support <a href="#persistent.connections" class="smpl">persistent connections</a> <em class="bcp14">MUST</em> send the "close" connection option in every request message. |
| 1980 | | </p> |
| 1981 | | <p id="rfc.section.6.1.p.14">A server that does not support <a href="#persistent.connections" class="smpl">persistent connections</a> <em class="bcp14">MUST</em> send the "close" connection option in every response message that does not have a <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a> status code. |
| 1982 | | </p> |
| 1983 | | <h2 id="rfc.section.6.2"><a href="#rfc.section.6.2">6.2</a> <a id="persistent.establishment" href="#persistent.establishment">Establishment</a></h2> |
| 1984 | | <p id="rfc.section.6.2.p.1">It is beyond the scope of this specification to describe how connections are established via various transport or session-layer |
| 1985 | | protocols. Each connection applies to only one transport link. |
| 1986 | | </p> |
| 1987 | | <h2 id="rfc.section.6.3"><a href="#rfc.section.6.3">6.3</a> <a id="persistent.connections" href="#persistent.connections">Persistence</a></h2> |
| 1988 | | <p id="rfc.section.6.3.p.1">HTTP/1.1 defaults to the use of "<dfn>persistent connections</dfn>", allowing multiple requests and responses to be carried over a single connection. The "<a href="#header.connection" class="smpl">close</a>" connection-option is used to signal that a connection will not persist after the current request/response. HTTP implementations <em class="bcp14">SHOULD</em> support persistent connections. |
| 1989 | | </p> |
| 1990 | | <p id="rfc.section.6.3.p.2">A recipient determines whether a connection is persistent or not based on the most recently received message's protocol version |
| 1991 | | and <a href="#header.connection" class="smpl">Connection</a> header field (if any): |
| 1992 | | </p> |
| 1993 | | <ul> |
| 1994 | | <li>If the <a href="#header.connection" class="smpl">close</a> connection option is present, the connection will not persist after the current response; else, |
| 1995 | | </li> |
| 1996 | | <li>If the received protocol is HTTP/1.1 (or later), the connection will persist after the current response; else,</li> |
| 1997 | | <li>If the received protocol is HTTP/1.0, the "keep-alive" connection option is present, the recipient is not a proxy, and the |
| 1998 | | recipient wishes to honor the HTTP/1.0 "keep-alive" mechanism, the connection will persist after the current response; otherwise, |
| 1999 | | </li> |
| 2000 | | <li>The connection will close after the current response.</li> |
| 2001 | | </ul> |
| 2002 | | <p id="rfc.section.6.3.p.3">A server <em class="bcp14">MAY</em> assume that an HTTP/1.1 client intends to maintain a persistent connection until a <a href="#header.connection" class="smpl">close</a> connection option is received in a request. |
| 2003 | | </p> |
| 2004 | | <p id="rfc.section.6.3.p.4">A client <em class="bcp14">MAY</em> reuse a persistent connection until it sends or receives a <a href="#header.connection" class="smpl">close</a> connection option or receives an HTTP/1.0 response without a "keep-alive" connection option. |
| 2005 | | </p> |
| 2006 | | <p id="rfc.section.6.3.p.5">In order to remain persistent, all messages on a connection <em class="bcp14">MUST</em> have a self-defined message length (i.e., one not defined by closure of the connection), as described in <a href="#message.body" title="Message Body">Section 3.3</a>. A server <em class="bcp14">MUST</em> read the entire request message body or close the connection after sending its response, since otherwise the remaining data |
| 2007 | | on a persistent connection would be misinterpreted as the next request. Likewise, a client <em class="bcp14">MUST</em> read the entire response message body if it intends to reuse the same connection for a subsequent request. |
| 2008 | | </p> |
| 2009 | | <p id="rfc.section.6.3.p.6">A proxy server <em class="bcp14">MUST NOT</em> maintain a persistent connection with an HTTP/1.0 client (see <a href="http://tools.ietf.org/html/rfc2068#section-19.7.1">Section 19.7.1</a> of <a href="#RFC2068" id="rfc.xref.RFC2068.3"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2068]</cite></a> for information and discussion of the problems with the Keep-Alive header field implemented by many HTTP/1.0 clients). |
| 2010 | | </p> |
| 2011 | | <p id="rfc.section.6.3.p.7">Clients and servers <em class="bcp14">SHOULD NOT</em> assume that a persistent connection is maintained for HTTP versions less than 1.1 unless it is explicitly signaled. See <a href="#compatibility.with.http.1.0.persistent.connections" title="Keep-Alive Connections">Appendix A.1.2</a> for more information on backward compatibility with HTTP/1.0 clients. |
| 2012 | | </p> |
| 2013 | | <h3 id="rfc.section.6.3.1"><a href="#rfc.section.6.3.1">6.3.1</a> <a id="persistent.retrying.requests" href="#persistent.retrying.requests">Retrying Requests</a></h3> |
| 2014 | | <p id="rfc.section.6.3.1.p.1">Connections can be closed at any time, with or without intention. Implementations ought to anticipate the need to recover |
| 2015 | | from asynchronous close events. |
| 2016 | | </p> |
| 2017 | | <p id="rfc.section.6.3.1.p.2">When an inbound connection is closed prematurely, a client <em class="bcp14">MAY</em> open a new connection and automatically retransmit an aborted sequence of requests if all of those requests have idempotent |
| 2018 | | methods (<a href="p2-semantics.html#idempotent.methods" title="Idempotent Methods">Section 4.2.2</a> of <a href="#Part2" id="rfc.xref.Part2.23"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). A proxy <em class="bcp14">MUST NOT</em> automatically retry non-idempotent requests. |
| 2019 | | </p> |
| 2020 | | <p id="rfc.section.6.3.1.p.3">A user agent <em class="bcp14">MUST NOT</em> automatically retry a request with a non-idempotent method unless it has some means to know that the request semantics are |
| 2021 | | actually idempotent, regardless of the method, or some means to detect that the original request was never applied. For example, |
| 2022 | | a user agent that knows (through design or configuration) that a POST request to a given resource is safe can repeat that |
| 2023 | | request automatically. Likewise, a user agent designed specifically to operate on a version control repository might be able |
| 2024 | | to recover from partial failure conditions by checking the target resource revision(s) after a failed connection, reverting |
| 2025 | | or fixing any changes that were partially applied, and then automatically retrying the requests that failed. |
| 2026 | | </p> |
| 2027 | | <p id="rfc.section.6.3.1.p.4">An automatic retry <em class="bcp14">SHOULD NOT</em> be repeated if it fails. |
| 2028 | | </p> |
| 2029 | | <h3 id="rfc.section.6.3.2"><a href="#rfc.section.6.3.2">6.3.2</a> <a id="pipelining" href="#pipelining">Pipelining</a></h3> |
| 2030 | | <p id="rfc.section.6.3.2.p.1">A client that supports persistent connections <em class="bcp14">MAY</em> "<dfn>pipeline</dfn>" its requests (i.e., send multiple requests without waiting for each response). A server <em class="bcp14">MAY</em> process a sequence of pipelined requests in parallel if they all have safe methods (<a href="p2-semantics.html#safe.methods" title="Safe Methods">Section 4.2.1</a> of <a href="#Part2" id="rfc.xref.Part2.24"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>), but <em class="bcp14">MUST</em> send the corresponding responses in the same order that the requests were received. |
| 2031 | | </p> |
| 2032 | | <p id="rfc.section.6.3.2.p.2">A client that pipelines requests <em class="bcp14">MUST</em> be prepared to retry those requests if the connection closes before it receives all of the corresponding responses. A client |
| 2033 | | that assumes a persistent connection and pipelines immediately after connection establishment <em class="bcp14">MUST NOT</em> pipeline on a retry connection until it knows the connection is persistent. |
| 2034 | | </p> |
| 2035 | | <p id="rfc.section.6.3.2.p.3">Idempotent methods (<a href="p2-semantics.html#idempotent.methods" title="Idempotent Methods">Section 4.2.2</a> of <a href="#Part2" id="rfc.xref.Part2.25"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) are significant to pipelining because they can be automatically retried after a connection failure. A user agent <em class="bcp14">SHOULD NOT</em> pipeline requests after a non-idempotent method until the final response status code for that method has been received, unless |
| 2036 | | the user agent has a means to detect and recover from partial failure conditions involving the pipelined sequence. |
| 2037 | | </p> |
| 2038 | | <p id="rfc.section.6.3.2.p.4">An intermediary that receives pipelined requests <em class="bcp14">MAY</em> pipeline those requests when forwarding them inbound, since it can rely on the outbound user agent(s) to determine what requests |
| 2039 | | can be safely pipelined. If the inbound connection fails before receiving a response, the pipelining intermediary <em class="bcp14">MAY</em> attempt to retry a sequence of requests that have yet to receive a response if the requests all have idempotent methods; otherwise, |
| 2040 | | the pipelining intermediary <em class="bcp14">SHOULD</em> forward any received responses and then close the corresponding outbound connection(s) so that the outbound user agent(s) |
| 2041 | | can recover accordingly. |
| 2042 | | </p> |
| 2043 | | <h2 id="rfc.section.6.4"><a href="#rfc.section.6.4">6.4</a> <a id="persistent.concurrency" href="#persistent.concurrency">Concurrency</a></h2> |
| 2044 | | <p id="rfc.section.6.4.p.1">Clients <em class="bcp14">SHOULD</em> limit the number of simultaneous connections that they maintain to a given server. |
| 2045 | | </p> |
| 2046 | | <p id="rfc.section.6.4.p.2">Previous revisions of HTTP gave a specific number of connections as a ceiling, but this was found to be impractical for many |
| 2047 | | applications. As a result, this specification does not mandate a particular maximum number of connections, but instead encourages |
| 2048 | | clients to be conservative when opening multiple connections. |
| 2049 | | </p> |
| 2050 | | <p id="rfc.section.6.4.p.3">Multiple connections are typically used to avoid the "head-of-line blocking" problem, wherein a request that takes significant |
| 2051 | | server-side processing and/or has a large payload blocks subsequent requests on the same connection. However, each connection |
| 2052 | | consumes server resources. Furthermore, using multiple connections can cause undesirable side effects in congested networks. |
| 2053 | | </p> |
| 2054 | | <p id="rfc.section.6.4.p.4">Note that servers might reject traffic that they deem abusive, including an excessive number of connections from a client.</p> |
| 2055 | | <h2 id="rfc.section.6.5"><a href="#rfc.section.6.5">6.5</a> <a id="persistent.failures" href="#persistent.failures">Failures and Time-outs</a></h2> |
| 2056 | | <p id="rfc.section.6.5.p.1">Servers will usually have some time-out value beyond which they will no longer maintain an inactive connection. Proxy servers |
| 2057 | | might make this a higher value since it is likely that the client will be making more connections through the same server. |
| 2058 | | The use of persistent connections places no requirements on the length (or existence) of this time-out for either the client |
| 2059 | | or the server. |
| 2060 | | </p> |
| 2061 | | <p id="rfc.section.6.5.p.2">When a client or server wishes to time-out it <em class="bcp14">SHOULD</em> issue a graceful close on the transport connection. Clients and servers <em class="bcp14">SHOULD</em> both constantly watch for the other side of the transport close, and respond to it as appropriate. If a client or server does |
| 2062 | | not detect the other side's close promptly it could cause unnecessary resource drain on the network. |
| 2063 | | </p> |
| 2064 | | <p id="rfc.section.6.5.p.3">A client, server, or proxy <em class="bcp14">MAY</em> close the transport connection at any time. For example, a client might have started to send a new request at the same time |
| 2065 | | that the server has decided to close the "idle" connection. From the server's point of view, the connection is being closed |
| 2066 | | while it was idle, but from the client's point of view, a request is in progress. |
| 2067 | | </p> |
| 2068 | | <p id="rfc.section.6.5.p.4">Servers <em class="bcp14">SHOULD</em> maintain persistent connections and allow the underlying transport's flow control mechanisms to resolve temporary overloads, |
| 2069 | | rather than terminate connections with the expectation that clients will retry. The latter technique can exacerbate network |
| 2070 | | congestion. |
| 2071 | | </p> |
| 2072 | | <p id="rfc.section.6.5.p.5">A client sending a message body <em class="bcp14">SHOULD</em> monitor the network connection for an error status code while it is transmitting the request. If the client sees an error |
| 2073 | | status code, it <em class="bcp14">SHOULD</em> immediately cease transmitting the body and close the connection. |
| 2074 | | </p> |
| 2075 | | <div id="rfc.iref.c.13"></div> |
| 2076 | | <div id="rfc.iref.c.14"></div> |
| 2077 | | <h2 id="rfc.section.6.6"><a href="#rfc.section.6.6">6.6</a> <a id="persistent.tear-down" href="#persistent.tear-down">Tear-down</a></h2> |
| 2078 | | <p id="rfc.section.6.6.p.1">The <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.6" title="Connection">Section 6.1</a>) provides a "<a href="#header.connection" class="smpl">close</a>" connection option that a sender <em class="bcp14">SHOULD</em> send when it wishes to close the connection after the current request/response pair. |
| 2079 | | </p> |
| 2080 | | <p id="rfc.section.6.6.p.2">A client that sends a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST NOT</em> send further requests on that connection (after the one containing <a href="#header.connection" class="smpl">close</a>) and <em class="bcp14">MUST</em> close the connection after reading the final response message corresponding to this request. |
| 2081 | | </p> |
| 2082 | | <p id="rfc.section.6.6.p.3">A server that receives a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST</em> initiate a lingering close (see below) of the connection after it sends the final response to the request that contained <a href="#header.connection" class="smpl">close</a>. The server <em class="bcp14">SHOULD</em> send a <a href="#header.connection" class="smpl">close</a> connection option in its final response on that connection. The server <em class="bcp14">MUST NOT</em> process any further requests received on that connection. |
| 2083 | | </p> |
| 2084 | | <p id="rfc.section.6.6.p.4">A server that sends a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST</em> initiate a lingering close of the connection after it sends the response containing <a href="#header.connection" class="smpl">close</a>. The server <em class="bcp14">MUST NOT</em> process any further requests received on that connection. |
| 2085 | | </p> |
| 2086 | | <p id="rfc.section.6.6.p.5">A client that receives a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST</em> cease sending requests on that connection and close the connection after reading the response message containing the close; |
| 2087 | | if additional pipelined requests had been sent on the connection, the client <em class="bcp14">SHOULD</em> assume that they will not be processed by the server. |
| 2088 | | </p> |
| 2089 | | <p id="rfc.section.6.6.p.6">If a server performs an immediate close of a TCP connection, there is a significant risk that the client will not be able |
| 2090 | | to read the last HTTP response. If the server receives additional data from the client on a fully-closed connection, such |
| 2091 | | as another request that was sent by the client before receiving the server's response, the server's TCP stack will send a |
| 2092 | | reset packet to the client; unfortunately, the reset packet might erase the client's unacknowledged input buffers before they |
| 2093 | | can be read and interpreted by the client's HTTP parser. |
| 2094 | | </p> |
| 2095 | | <p id="rfc.section.6.6.p.7">To avoid the TCP reset problem, a server can perform a lingering close on a connection by closing only the write side of the |
| 2096 | | read/write connection (a half-close) and continuing to read from the connection until the connection is closed by the client |
| 2097 | | or the server is reasonably certain that its own TCP stack has received the client's acknowledgement of the packet(s) containing |
| 2098 | | the server's last response. It is then safe for the server to fully close the connection. |
| 2099 | | </p> |
| 2100 | | <p id="rfc.section.6.6.p.8">It is unknown whether the reset problem is exclusive to TCP or might also be found in other transport connection protocols.</p> |
| 2101 | | <div id="rfc.iref.u.5"></div> |
| 2102 | | <h2 id="rfc.section.6.7"><a href="#rfc.section.6.7">6.7</a> <a id="header.upgrade" href="#header.upgrade">Upgrade</a></h2> |
| 2103 | | <p id="rfc.section.6.7.p.1">The "Upgrade" header field is intended to provide a simple mechanism for transitioning from HTTP/1.1 to some other protocol |
| 2104 | | on the same connection. A client <em class="bcp14">MAY</em> send a list of protocols in the Upgrade header field of a request to invite the server to switch to one or more of those protocols |
| 2105 | | before sending the final response. A server <em class="bcp14">MUST</em> send an Upgrade header field in <a href="p2-semantics.html#status.101" class="smpl">101 (Switching |
| 2106 | | Protocols)</a> responses to indicate which protocol(s) are being switched to, and <em class="bcp14">MUST</em> send it in <a href="p2-semantics.html#status.426" class="smpl">426 (Upgrade Required)</a> responses to indicate acceptable protocols. A server <em class="bcp14">MAY</em> send an Upgrade header field in any other response to indicate that they might be willing to upgrade to one of the specified |
| 2107 | | protocols for a future request. |
| 2108 | | </p> |
| 2109 | | <div id="rfc.figure.u.57"></div><pre class="inline"><span id="rfc.iref.g.94"></span> <a href="#header.upgrade" class="smpl">Upgrade</a> = 1#<a href="#header.upgrade" class="smpl">protocol</a> |
| | 2098 | </p> |
| | 2099 | <p id="rfc.section.6.1.p.13">A client that does not support <a href="#persistent.connections" class="smpl">persistent connections</a> <em class="bcp14">MUST</em> send the "close" connection option in every request message. |
| | 2100 | </p> |
| | 2101 | <p id="rfc.section.6.1.p.14">A server that does not support <a href="#persistent.connections" class="smpl">persistent connections</a> <em class="bcp14">MUST</em> send the "close" connection option in every response message that does not have a <a href="p2-semantics.html#status.1xx" class="smpl">1xx (Informational)</a> status code. |
| | 2102 | </p> |
| | 2103 | </div> |
| | 2104 | <div id="persistent.establishment"> |
| | 2105 | <h2 id="rfc.section.6.2"><a href="#rfc.section.6.2">6.2</a> <a href="#persistent.establishment">Establishment</a></h2> |
| | 2106 | <p id="rfc.section.6.2.p.1">It is beyond the scope of this specification to describe how connections are established via various transport or session-layer |
| | 2107 | protocols. Each connection applies to only one transport link. |
| | 2108 | </p> |
| | 2109 | </div> |
| | 2110 | <div id="persistent.connections"> |
| | 2111 | <h2 id="rfc.section.6.3"><a href="#rfc.section.6.3">6.3</a> <a href="#persistent.connections">Persistence</a></h2> |
| | 2112 | <p id="rfc.section.6.3.p.1">HTTP/1.1 defaults to the use of "<dfn>persistent connections</dfn>", allowing multiple requests and responses to be carried over a single connection. The "<a href="#header.connection" class="smpl">close</a>" connection-option is used to signal that a connection will not persist after the current request/response. HTTP implementations <em class="bcp14">SHOULD</em> support persistent connections. |
| | 2113 | </p> |
| | 2114 | <p id="rfc.section.6.3.p.2">A recipient determines whether a connection is persistent or not based on the most recently received message's protocol version |
| | 2115 | and <a href="#header.connection" class="smpl">Connection</a> header field (if any): |
| | 2116 | </p> |
| | 2117 | <ul> |
| | 2118 | <li>If the <a href="#header.connection" class="smpl">close</a> connection option is present, the connection will not persist after the current response; else, |
| | 2119 | </li> |
| | 2120 | <li>If the received protocol is HTTP/1.1 (or later), the connection will persist after the current response; else,</li> |
| | 2121 | <li>If the received protocol is HTTP/1.0, the "keep-alive" connection option is present, the recipient is not a proxy, and the |
| | 2122 | recipient wishes to honor the HTTP/1.0 "keep-alive" mechanism, the connection will persist after the current response; otherwise, |
| | 2123 | </li> |
| | 2124 | <li>The connection will close after the current response.</li> |
| | 2125 | </ul> |
| | 2126 | <p id="rfc.section.6.3.p.3">A server <em class="bcp14">MAY</em> assume that an HTTP/1.1 client intends to maintain a persistent connection until a <a href="#header.connection" class="smpl">close</a> connection option is received in a request. |
| | 2127 | </p> |
| | 2128 | <p id="rfc.section.6.3.p.4">A client <em class="bcp14">MAY</em> reuse a persistent connection until it sends or receives a <a href="#header.connection" class="smpl">close</a> connection option or receives an HTTP/1.0 response without a "keep-alive" connection option. |
| | 2129 | </p> |
| | 2130 | <p id="rfc.section.6.3.p.5">In order to remain persistent, all messages on a connection <em class="bcp14">MUST</em> have a self-defined message length (i.e., one not defined by closure of the connection), as described in <a href="#message.body" title="Message Body">Section 3.3</a>. A server <em class="bcp14">MUST</em> read the entire request message body or close the connection after sending its response, since otherwise the remaining data |
| | 2131 | on a persistent connection would be misinterpreted as the next request. Likewise, a client <em class="bcp14">MUST</em> read the entire response message body if it intends to reuse the same connection for a subsequent request. |
| | 2132 | </p> |
| | 2133 | <p id="rfc.section.6.3.p.6">A proxy server <em class="bcp14">MUST NOT</em> maintain a persistent connection with an HTTP/1.0 client (see <a href="https://tools.ietf.org/html/rfc2068#section-19.7.1">Section 19.7.1</a> of <a href="#RFC2068" id="rfc.xref.RFC2068.3"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2068]</cite></a> for information and discussion of the problems with the Keep-Alive header field implemented by many HTTP/1.0 clients). |
| | 2134 | </p> |
| | 2135 | <p id="rfc.section.6.3.p.7">Clients and servers <em class="bcp14">SHOULD NOT</em> assume that a persistent connection is maintained for HTTP versions less than 1.1 unless it is explicitly signaled. See <a href="#compatibility.with.http.1.0.persistent.connections" title="Keep-Alive Connections">Appendix A.1.2</a> for more information on backward compatibility with HTTP/1.0 clients. |
| | 2136 | </p> |
| | 2137 | <div id="persistent.retrying.requests"> |
| | 2138 | <h3 id="rfc.section.6.3.1"><a href="#rfc.section.6.3.1">6.3.1</a> <a href="#persistent.retrying.requests">Retrying Requests</a></h3> |
| | 2139 | <p id="rfc.section.6.3.1.p.1">Connections can be closed at any time, with or without intention. Implementations ought to anticipate the need to recover |
| | 2140 | from asynchronous close events. |
| | 2141 | </p> |
| | 2142 | <p id="rfc.section.6.3.1.p.2">When an inbound connection is closed prematurely, a client <em class="bcp14">MAY</em> open a new connection and automatically retransmit an aborted sequence of requests if all of those requests have idempotent |
| | 2143 | methods (<a href="p2-semantics.html#idempotent.methods" title="Idempotent Methods">Section 4.2.2</a> of <a href="#Part2" id="rfc.xref.Part2.23"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). A proxy <em class="bcp14">MUST NOT</em> automatically retry non-idempotent requests. |
| | 2144 | </p> |
| | 2145 | <p id="rfc.section.6.3.1.p.3">A user agent <em class="bcp14">MUST NOT</em> automatically retry a request with a non-idempotent method unless it has some means to know that the request semantics are |
| | 2146 | actually idempotent, regardless of the method, or some means to detect that the original request was never applied. For example, |
| | 2147 | a user agent that knows (through design or configuration) that a POST request to a given resource is safe can repeat that |
| | 2148 | request automatically. Likewise, a user agent designed specifically to operate on a version control repository might be able |
| | 2149 | to recover from partial failure conditions by checking the target resource revision(s) after a failed connection, reverting |
| | 2150 | or fixing any changes that were partially applied, and then automatically retrying the requests that failed. |
| | 2151 | </p> |
| | 2152 | <p id="rfc.section.6.3.1.p.4">An automatic retry <em class="bcp14">SHOULD NOT</em> be repeated if it fails. |
| | 2153 | </p> |
| | 2154 | </div> |
| | 2155 | <div id="pipelining"> |
| | 2156 | <h3 id="rfc.section.6.3.2"><a href="#rfc.section.6.3.2">6.3.2</a> <a href="#pipelining">Pipelining</a></h3> |
| | 2157 | <p id="rfc.section.6.3.2.p.1">A client that supports persistent connections <em class="bcp14">MAY</em> "<dfn>pipeline</dfn>" its requests (i.e., send multiple requests without waiting for each response). A server <em class="bcp14">MAY</em> process a sequence of pipelined requests in parallel if they all have safe methods (<a href="p2-semantics.html#safe.methods" title="Safe Methods">Section 4.2.1</a> of <a href="#Part2" id="rfc.xref.Part2.24"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>), but <em class="bcp14">MUST</em> send the corresponding responses in the same order that the requests were received. |
| | 2158 | </p> |
| | 2159 | <p id="rfc.section.6.3.2.p.2">A client that pipelines requests <em class="bcp14">MUST</em> be prepared to retry those requests if the connection closes before it receives all of the corresponding responses. A client |
| | 2160 | that assumes a persistent connection and pipelines immediately after connection establishment <em class="bcp14">MUST NOT</em> pipeline on a retry connection until it knows the connection is persistent. |
| | 2161 | </p> |
| | 2162 | <p id="rfc.section.6.3.2.p.3">Idempotent methods (<a href="p2-semantics.html#idempotent.methods" title="Idempotent Methods">Section 4.2.2</a> of <a href="#Part2" id="rfc.xref.Part2.25"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) are significant to pipelining because they can be automatically retried after a connection failure. A user agent <em class="bcp14">SHOULD NOT</em> pipeline requests after a non-idempotent method until the final response status code for that method has been received, unless |
| | 2163 | the user agent has a means to detect and recover from partial failure conditions involving the pipelined sequence. |
| | 2164 | </p> |
| | 2165 | <p id="rfc.section.6.3.2.p.4">An intermediary that receives pipelined requests <em class="bcp14">MAY</em> pipeline those requests when forwarding them inbound, since it can rely on the outbound user agent(s) to determine what requests |
| | 2166 | can be safely pipelined. If the inbound connection fails before receiving a response, the pipelining intermediary <em class="bcp14">MAY</em> attempt to retry a sequence of requests that have yet to receive a response if the requests all have idempotent methods; otherwise, |
| | 2167 | the pipelining intermediary <em class="bcp14">SHOULD</em> forward any received responses and then close the corresponding outbound connection(s) so that the outbound user agent(s) |
| | 2168 | can recover accordingly. |
| | 2169 | </p> |
| | 2170 | </div> |
| | 2171 | </div> |
| | 2172 | <div id="persistent.concurrency"> |
| | 2173 | <h2 id="rfc.section.6.4"><a href="#rfc.section.6.4">6.4</a> <a href="#persistent.concurrency">Concurrency</a></h2> |
| | 2174 | <p id="rfc.section.6.4.p.1">Clients <em class="bcp14">SHOULD</em> limit the number of simultaneous connections that they maintain to a given server. |
| | 2175 | </p> |
| | 2176 | <p id="rfc.section.6.4.p.2">Previous revisions of HTTP gave a specific number of connections as a ceiling, but this was found to be impractical for many |
| | 2177 | applications. As a result, this specification does not mandate a particular maximum number of connections, but instead encourages |
| | 2178 | clients to be conservative when opening multiple connections. |
| | 2179 | </p> |
| | 2180 | <p id="rfc.section.6.4.p.3">Multiple connections are typically used to avoid the "head-of-line blocking" problem, wherein a request that takes significant |
| | 2181 | server-side processing and/or has a large payload blocks subsequent requests on the same connection. However, each connection |
| | 2182 | consumes server resources. Furthermore, using multiple connections can cause undesirable side effects in congested networks. |
| | 2183 | </p> |
| | 2184 | <p id="rfc.section.6.4.p.4">Note that servers might reject traffic that they deem abusive, including an excessive number of connections from a client.</p> |
| | 2185 | </div> |
| | 2186 | <div id="persistent.failures"> |
| | 2187 | <h2 id="rfc.section.6.5"><a href="#rfc.section.6.5">6.5</a> <a href="#persistent.failures">Failures and Time-outs</a></h2> |
| | 2188 | <p id="rfc.section.6.5.p.1">Servers will usually have some time-out value beyond which they will no longer maintain an inactive connection. Proxy servers |
| | 2189 | might make this a higher value since it is likely that the client will be making more connections through the same server. |
| | 2190 | The use of persistent connections places no requirements on the length (or existence) of this time-out for either the client |
| | 2191 | or the server. |
| | 2192 | </p> |
| | 2193 | <p id="rfc.section.6.5.p.2">When a client or server wishes to time-out it <em class="bcp14">SHOULD</em> issue a graceful close on the transport connection. Clients and servers <em class="bcp14">SHOULD</em> both constantly watch for the other side of the transport close, and respond to it as appropriate. If a client or server does |
| | 2194 | not detect the other side's close promptly it could cause unnecessary resource drain on the network. |
| | 2195 | </p> |
| | 2196 | <p id="rfc.section.6.5.p.3">A client, server, or proxy <em class="bcp14">MAY</em> close the transport connection at any time. For example, a client might have started to send a new request at the same time |
| | 2197 | that the server has decided to close the "idle" connection. From the server's point of view, the connection is being closed |
| | 2198 | while it was idle, but from the client's point of view, a request is in progress. |
| | 2199 | </p> |
| | 2200 | <p id="rfc.section.6.5.p.4">Servers <em class="bcp14">SHOULD</em> maintain persistent connections and allow the underlying transport's flow control mechanisms to resolve temporary overloads, |
| | 2201 | rather than terminate connections with the expectation that clients will retry. The latter technique can exacerbate network |
| | 2202 | congestion. |
| | 2203 | </p> |
| | 2204 | <p id="rfc.section.6.5.p.5">A client sending a message body <em class="bcp14">SHOULD</em> monitor the network connection for an error status code while it is transmitting the request. If the client sees an error |
| | 2205 | status code, it <em class="bcp14">SHOULD</em> immediately cease transmitting the body and close the connection. |
| | 2206 | </p> |
| | 2207 | </div> |
| | 2208 | <div id="persistent.tear-down"> |
| | 2209 | <div id="rfc.iref.c.13"></div> |
| | 2210 | <div id="rfc.iref.c.14"></div> |
| | 2211 | <h2 id="rfc.section.6.6"><a href="#rfc.section.6.6">6.6</a> <a href="#persistent.tear-down">Tear-down</a></h2> |
| | 2212 | <p id="rfc.section.6.6.p.1">The <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.6" title="Connection">Section 6.1</a>) provides a "<a href="#header.connection" class="smpl">close</a>" connection option that a sender <em class="bcp14">SHOULD</em> send when it wishes to close the connection after the current request/response pair. |
| | 2213 | </p> |
| | 2214 | <p id="rfc.section.6.6.p.2">A client that sends a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST NOT</em> send further requests on that connection (after the one containing <a href="#header.connection" class="smpl">close</a>) and <em class="bcp14">MUST</em> close the connection after reading the final response message corresponding to this request. |
| | 2215 | </p> |
| | 2216 | <p id="rfc.section.6.6.p.3">A server that receives a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST</em> initiate a lingering close (see below) of the connection after it sends the final response to the request that contained <a href="#header.connection" class="smpl">close</a>. The server <em class="bcp14">SHOULD</em> send a <a href="#header.connection" class="smpl">close</a> connection option in its final response on that connection. The server <em class="bcp14">MUST NOT</em> process any further requests received on that connection. |
| | 2217 | </p> |
| | 2218 | <p id="rfc.section.6.6.p.4">A server that sends a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST</em> initiate a lingering close of the connection after it sends the response containing <a href="#header.connection" class="smpl">close</a>. The server <em class="bcp14">MUST NOT</em> process any further requests received on that connection. |
| | 2219 | </p> |
| | 2220 | <p id="rfc.section.6.6.p.5">A client that receives a <a href="#header.connection" class="smpl">close</a> connection option <em class="bcp14">MUST</em> cease sending requests on that connection and close the connection after reading the response message containing the close; |
| | 2221 | if additional pipelined requests had been sent on the connection, the client <em class="bcp14">SHOULD</em> assume that they will not be processed by the server. |
| | 2222 | </p> |
| | 2223 | <p id="rfc.section.6.6.p.6">If a server performs an immediate close of a TCP connection, there is a significant risk that the client will not be able |
| | 2224 | to read the last HTTP response. If the server receives additional data from the client on a fully-closed connection, such |
| | 2225 | as another request that was sent by the client before receiving the server's response, the server's TCP stack will send a |
| | 2226 | reset packet to the client; unfortunately, the reset packet might erase the client's unacknowledged input buffers before they |
| | 2227 | can be read and interpreted by the client's HTTP parser. |
| | 2228 | </p> |
| | 2229 | <p id="rfc.section.6.6.p.7">To avoid the TCP reset problem, a server can perform a lingering close on a connection by closing only the write side of the |
| | 2230 | read/write connection (a half-close) and continuing to read from the connection until the connection is closed by the client |
| | 2231 | or the server is reasonably certain that its own TCP stack has received the client's acknowledgement of the packet(s) containing |
| | 2232 | the server's last response. It is then safe for the server to fully close the connection. |
| | 2233 | </p> |
| | 2234 | <p id="rfc.section.6.6.p.8">It is unknown whether the reset problem is exclusive to TCP or might also be found in other transport connection protocols.</p> |
| | 2235 | </div> |
| | 2236 | <div id="header.upgrade"> |
| | 2237 | <div id="rfc.iref.u.5"></div> |
| | 2238 | <h2 id="rfc.section.6.7"><a href="#rfc.section.6.7">6.7</a> <a href="#header.upgrade">Upgrade</a></h2> |
| | 2239 | <p id="rfc.section.6.7.p.1">The "Upgrade" header field is intended to provide a simple mechanism for transitioning from HTTP/1.1 to some other protocol |
| | 2240 | on the same connection. A client <em class="bcp14">MAY</em> send a list of protocols in the Upgrade header field of a request to invite the server to switch to one or more of those protocols |
| | 2241 | before sending the final response. A server <em class="bcp14">MUST</em> send an Upgrade header field in <a href="p2-semantics.html#status.101" class="smpl">101 (Switching |
| | 2242 | Protocols)</a> responses to indicate which protocol(s) are being switched to, and <em class="bcp14">MUST</em> send it in <a href="p2-semantics.html#status.426" class="smpl">426 (Upgrade Required)</a> responses to indicate acceptable protocols. A server <em class="bcp14">MAY</em> send an Upgrade header field in any other response to indicate that they might be willing to upgrade to one of the specified |
| | 2243 | protocols for a future request. |
| | 2244 | </p> |
| | 2245 | <div id="rfc.figure.u.57"></div><pre class="inline"><span id="rfc.iref.g.94"></span> <a href="#header.upgrade" class="smpl">Upgrade</a> = 1#<a href="#header.upgrade" class="smpl">protocol</a> |
| 2117 | | more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if available |
| 2118 | | (where "better" is determined by the server, possibly according to the nature of the request method or target resource). |
| 2119 | | </p> |
| 2120 | | <p id="rfc.section.6.7.p.6">Upgrade cannot be used to insist on a protocol change; its acceptance and use by the server is optional. The capabilities |
| 2121 | | and nature of the application-level communication after the protocol change is entirely dependent upon the new protocol chosen, |
| 2122 | | although the first action after changing the protocol <em class="bcp14">MUST</em> be a response to the initial HTTP request that contained the Upgrade header field. |
| 2123 | | </p> |
| 2124 | | <p id="rfc.section.6.7.p.7">For example, if the Upgrade header field is received in a GET request and the server decides to switch protocols, then it |
| 2125 | | first responds with a <a href="p2-semantics.html#status.101" class="smpl">101 (Switching Protocols)</a> message in HTTP/1.1 and then immediately follows that with the new protocol's equivalent of a response to a GET on the target |
| 2126 | | resource. This allows a connection to be upgraded to protocols with the same semantics as HTTP without the latency cost of |
| 2127 | | an additional round-trip. A server <em class="bcp14">MUST NOT</em> switch protocols unless the received message semantics can be honored by the new protocol; an OPTIONS request can be honored |
| 2128 | | by any protocol. |
| 2129 | | </p> |
| 2130 | | <p id="rfc.section.6.7.p.8">When Upgrade is sent, a sender <em class="bcp14">MUST</em> also send a <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.7" title="Connection">Section 6.1</a>) that contains the "upgrade" connection option, in order to prevent Upgrade from being accidentally forwarded by intermediaries |
| 2131 | | that might not implement the listed protocols. A server <em class="bcp14">MUST</em> ignore an Upgrade header field that is received in an HTTP/1.0 request. |
| 2132 | | </p> |
| 2133 | | <p id="rfc.section.6.7.p.9">The Upgrade header field only applies to switching application-level protocols on the existing connection; it cannot be used |
| 2134 | | to switch to a protocol on a different connection. For that purpose, it is more appropriate to use a <a href="p2-semantics.html#status.3xx" class="smpl">3xx (Redirection)</a> response (<a href="p2-semantics.html#status.3xx" title="Redirection 3xx">Section 6.4</a> of <a href="#Part2" id="rfc.xref.Part2.26"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). |
| 2135 | | </p> |
| 2136 | | <p id="rfc.section.6.7.p.10">This specification only defines the protocol name "HTTP" for use by the family of Hypertext Transfer Protocols, as defined |
| 2137 | | by the HTTP version rules of <a href="#http.version" title="Protocol Versioning">Section 2.6</a> and future updates to this specification. Additional tokens ought to be registered with IANA using the registration procedure |
| 2138 | | defined in <a href="#upgrade.token.registry" title="Upgrade Token Registry">Section 7.6</a>. |
| 2139 | | </p> |
| 2140 | | <h1 id="rfc.section.7"><a href="#rfc.section.7">7.</a> <a id="IANA.considerations" href="#IANA.considerations">IANA Considerations</a></h1> |
| 2141 | | <h2 id="rfc.section.7.1"><a href="#rfc.section.7.1">7.1</a> <a id="header.field.registration" href="#header.field.registration">Header Field Registration</a></h2> |
| 2142 | | <p id="rfc.section.7.1.p.1">HTTP header fields are registered within the Message Header Field Registry <a href="#BCP90" id="rfc.xref.BCP90.1"><cite title="Registration Procedures for Message Header Fields">[BCP90]</cite></a> maintained by IANA at <<a href="http://www.iana.org/assignments/message-headers/message-header-index.html">http://www.iana.org/assignments/message-headers/message-header-index.html</a>>. |
| 2143 | | </p> |
| 2144 | | <p id="rfc.section.7.1.p.2">This document defines the following HTTP header fields, so their associated registry entries shall be updated according to |
| 2145 | | the permanent registrations below: |
| 2146 | | </p> |
| 2147 | | <div id="rfc.table.1"> |
| 2148 | | <div id="iana.header.registration.table"></div> |
| 2149 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 2150 | | <thead> |
| 2151 | | <tr> |
| 2152 | | <th>Header Field Name</th> |
| 2153 | | <th>Protocol</th> |
| 2154 | | <th>Status</th> |
| 2155 | | <th>Reference</th> |
| 2156 | | </tr> |
| 2157 | | </thead> |
| 2158 | | <tbody> |
| 2159 | | <tr> |
| 2160 | | <td class="left">Connection</td> |
| 2161 | | <td class="left">http</td> |
| 2162 | | <td class="left">standard</td> |
| 2163 | | <td class="left"> <a href="#header.connection" id="rfc.xref.header.connection.8" title="Connection">Section 6.1</a> |
| 2164 | | </td> |
| 2165 | | </tr> |
| 2166 | | <tr> |
| 2167 | | <td class="left">Content-Length</td> |
| 2168 | | <td class="left">http</td> |
| 2169 | | <td class="left">standard</td> |
| 2170 | | <td class="left"> <a href="#header.content-length" id="rfc.xref.header.content-length.1" title="Content-Length">Section 3.3.2</a> |
| 2171 | | </td> |
| 2172 | | </tr> |
| 2173 | | <tr> |
| 2174 | | <td class="left">Host</td> |
| 2175 | | <td class="left">http</td> |
| 2176 | | <td class="left">standard</td> |
| 2177 | | <td class="left"> <a href="#header.host" id="rfc.xref.header.host.2" title="Host">Section 5.4</a> |
| 2178 | | </td> |
| 2179 | | </tr> |
| 2180 | | <tr> |
| 2181 | | <td class="left">TE</td> |
| 2182 | | <td class="left">http</td> |
| 2183 | | <td class="left">standard</td> |
| 2184 | | <td class="left"> <a href="#header.te" id="rfc.xref.header.te.3" title="TE">Section 4.3</a> |
| 2185 | | </td> |
| 2186 | | </tr> |
| 2187 | | <tr> |
| 2188 | | <td class="left">Trailer</td> |
| 2189 | | <td class="left">http</td> |
| 2190 | | <td class="left">standard</td> |
| 2191 | | <td class="left"> <a href="#header.trailer" id="rfc.xref.header.trailer.1" title="Trailer">Section 4.1.1</a> |
| 2192 | | </td> |
| 2193 | | </tr> |
| 2194 | | <tr> |
| 2195 | | <td class="left">Transfer-Encoding</td> |
| 2196 | | <td class="left">http</td> |
| 2197 | | <td class="left">standard</td> |
| 2198 | | <td class="left"> <a href="#header.transfer-encoding" id="rfc.xref.header.transfer-encoding.3" title="Transfer-Encoding">Section 3.3.1</a> |
| 2199 | | </td> |
| 2200 | | </tr> |
| 2201 | | <tr> |
| 2202 | | <td class="left">Upgrade</td> |
| 2203 | | <td class="left">http</td> |
| 2204 | | <td class="left">standard</td> |
| 2205 | | <td class="left"> <a href="#header.upgrade" id="rfc.xref.header.upgrade.2" title="Upgrade">Section 6.7</a> |
| 2206 | | </td> |
| 2207 | | </tr> |
| 2208 | | <tr> |
| 2209 | | <td class="left">Via</td> |
| 2210 | | <td class="left">http</td> |
| 2211 | | <td class="left">standard</td> |
| 2212 | | <td class="left"> <a href="#header.via" id="rfc.xref.header.via.2" title="Via">Section 5.7.1</a> |
| 2213 | | </td> |
| 2214 | | </tr> |
| 2215 | | </tbody> |
| 2216 | | </table> |
| | 2253 | more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if available |
| | 2254 | (where "better" is determined by the server, possibly according to the nature of the request method or target resource). |
| | 2255 | </p> |
| | 2256 | <p id="rfc.section.6.7.p.6">Upgrade cannot be used to insist on a protocol change; its acceptance and use by the server is optional. The capabilities |
| | 2257 | and nature of the application-level communication after the protocol change is entirely dependent upon the new protocol chosen, |
| | 2258 | although the first action after changing the protocol <em class="bcp14">MUST</em> be a response to the initial HTTP request that contained the Upgrade header field. |
| | 2259 | </p> |
| | 2260 | <p id="rfc.section.6.7.p.7">For example, if the Upgrade header field is received in a GET request and the server decides to switch protocols, then it |
| | 2261 | first responds with a <a href="p2-semantics.html#status.101" class="smpl">101 (Switching Protocols)</a> message in HTTP/1.1 and then immediately follows that with the new protocol's equivalent of a response to a GET on the target |
| | 2262 | resource. This allows a connection to be upgraded to protocols with the same semantics as HTTP without the latency cost of |
| | 2263 |
![(please configure the [header_logo] section in trac.ini)](https://www.ietf.org/images/ietflogotrans.gif)