| 567 | | between HTTP and MIME is described in <xref target="differences.between.http.entities.and.rfc.2045.entities"/>. |
| 568 | | </t> |
| 569 | | <t> |
| 570 | | Most HTTP communication is initiated by a user agent and consists of |
| 571 | | a request to be applied to a resource on some origin server. In the |
| 572 | | simplest case, this may be accomplished via a single connection (v) |
| 573 | | between the user agent (UA) and the origin server (O). |
| 574 | | </t> |
| 575 | | <figure><artwork type="drawing"> |
| 576 | | request chain ------------------------> |
| 577 | | UA -------------------v------------------- O |
| 578 | | <----------------------- response chain |
| 579 | | </artwork></figure> |
| 580 | | <t> |
| 581 | | A more complicated situation occurs when one or more intermediaries |
| 582 | | are present in the request/response chain. There are three common |
| 583 | | forms of intermediary: proxy, gateway, and tunnel. A proxy is a |
| 584 | | forwarding agent, receiving requests for a URI in its absolute form, |
| 585 | | rewriting all or part of the message, and forwarding the reformatted |
| 586 | | request toward the server identified by the URI. A gateway is a |
| 587 | | receiving agent, acting as a layer above some other server(s) and, if |
| 588 | | necessary, translating the requests to the underlying server's |
| 589 | | protocol. A tunnel acts as a relay point between two connections |
| 590 | | without changing the messages; tunnels are used when the |
| 591 | | communication needs to pass through an intermediary (such as a |
| 592 | | firewall) even when the intermediary cannot understand the contents |
| 593 | | of the messages. |
| 594 | | </t> |
| 595 | | <figure><artwork type="drawing"> |
| 596 | | request chain --------------------------------------> |
| 597 | | UA -----v----- A -----v----- B -----v----- C -----v----- O |
| 598 | | <------------------------------------- response chain |
| 599 | | </artwork></figure> |
| 600 | | <t> |
| 601 | | The figure above shows three intermediaries (A, B, and C) between the |
| 602 | | user agent and origin server. A request or response message that |
| 603 | | travels the whole chain will pass through four separate connections. |
| 604 | | This distinction is important because some HTTP communication options |
| 605 | | may apply only to the connection with the nearest, non-tunnel |
| 606 | | neighbor, only to the end-points of the chain, or to all connections |
| 607 | | along the chain. Although the diagram is linear, each participant may |
| 608 | | be engaged in multiple, simultaneous communications. For example, B |
| 609 | | may be receiving requests from many clients other than A, and/or |
| 610 | | forwarding requests to servers other than C, at the same time that it |
| 611 | | is handling A's request. |
| 612 | | </t> |
| 613 | | <t> |
| 614 | | Any party to the communication which is not acting as a tunnel may |
| 615 | | employ an internal cache for handling requests. The effect of a cache |
| 616 | | is that the request/response chain is shortened if one of the |
| 617 | | participants along the chain has a cached response applicable to that |
| 618 | | request. The following illustrates the resulting chain if B has a |
| 619 | | cached copy of an earlier response from O (via C) for a request which |
| 620 | | has not been cached by UA or A. |
| 621 | | </t> |
| 622 | | <figure><artwork type="drawing"> |
| 623 | | request chain ----------> |
| 624 | | UA -----v----- A -----v----- B - - - - - - C - - - - - - O |
| 625 | | <--------- response chain |
| 626 | | </artwork></figure> |
| 627 | | <t> |
| 628 | | Not all responses are usefully cacheable, and some requests may |
| 629 | | contain modifiers which place special requirements on cache behavior. |
| 630 | | HTTP requirements for cache behavior and cacheable responses are |
| 631 | | defined in <xref target="caching"/>. |
| 632 | | </t> |
| 633 | | <t> |
| 634 | | In fact, there are a wide variety of architectures and configurations |
| 635 | | of caches and proxies currently being experimented with or deployed |
| 636 | | across the World Wide Web. These systems include national hierarchies |
| 637 | | of proxy caches to save transoceanic bandwidth, systems that |
| 638 | | broadcast or multicast cache entries, organizations that distribute |
| 639 | | subsets of cached data via CD-ROM, and so on. HTTP systems are used |
| 640 | | in corporate intranets over high-bandwidth links, and for access via |
| 641 | | PDAs with low-power radio links and intermittent connectivity. The |
| 642 | | goal of HTTP/1.1 is to support the wide diversity of configurations |
| 643 | | already deployed while introducing protocol constructs that meet the |
| 644 | | needs of those who build web applications that require high |
| 645 | | reliability and, failing that, at least reliable indications of |
| 646 | | failure. |
| 647 | | </t> |
| 648 | | <t> |
| 649 | | HTTP communication usually takes place over TCP/IP connections. The |
| 650 | | default port is TCP 80 <xref target="RFC1700"/>, but other ports can be used. This does |
| 651 | | not preclude HTTP from being implemented on top of any other protocol |
| 652 | | on the Internet, or on other networks. HTTP only presumes a reliable |
| 653 | | transport; any protocol that provides such guarantees can be used; |
| 654 | | the mapping of the HTTP/1.1 request and response structures onto the |
| 655 | | transport data units of the protocol in question is outside the scope |
| 656 | | of this specification. |
| 657 | | </t> |
| 658 | | <t> |
| 659 | | In HTTP/1.0, most implementations used a new connection for each |
| 660 | | request/response exchange. In HTTP/1.1, a connection may be used for |
| 661 | | one or more request/response exchanges, although connections may be |
| 662 | | closed for a variety of reasons (see <xref target="persistent.connections"/>). |
| 663 | | </t> |
| 664 | | </section> |
| 665 | | </section> |
| 666 | | |
| 667 | | <section title="Notational Conventions and Generic Grammar" anchor="notation"> |
| 668 | | |
| 669 | | <section title="Augmented BNF" anchor="notation.abnf"> |
| 670 | | <t> |
| 671 | | All of the mechanisms specified in this document are described in |
| 672 | | both prose and an augmented Backus-Naur Form (BNF) similar to that |
| 673 | | used by RFC 822 <xref target="RFC822"/>. Implementors will need to be familiar with the |
| 674 | | notation in order to understand this specification. The augmented BNF |
| 675 | | includes the following constructs: |
| 676 | | </t> |
| 677 | | <t> |
| 678 | | name = definition |
| 679 | | <list> |
| 680 | | <t> |
| 681 | | The name of a rule is simply the name itself (without any |
| 682 | | enclosing "<" and ">") and is separated from its definition by the |
| 683 | | equal "=" character. White space is only significant in that |
| 684 | | indentation of continuation lines is used to indicate a rule |
| 685 | | definition that spans more than one line. Certain basic rules are |
| 686 | | in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle |
| 687 | | brackets are used within definitions whenever their presence will |
| 688 | | facilitate discerning the use of rule names. |
| 689 | | </t> |
| 690 | | </list> |
| 691 | | </t> |
| 692 | | <t> |
| 693 | | "literal" |
| 694 | | <list> |
| 695 | | <t> |
| 696 | | Quotation marks surround literal text. Unless stated otherwise, |
| 697 | | the text is case-insensitive. |
| 698 | | </t> |
| 699 | | </list> |
| 700 | | </t> |
| 701 | | <t> |
| 702 | | rule1 | rule2 |
| 703 | | <list> |
| 704 | | <t> |
| 705 | | Elements separated by a bar ("|") are alternatives, e.g., "yes | |
| 706 | | no" will accept yes or no. |
| 707 | | </t> |
| 708 | | </list> |
| 709 | | </t> |
| 710 | | <t> |
| 711 | | (rule1 rule2) |
| 712 | | <list> |
| 713 | | <t> |
| 714 | | Elements enclosed in parentheses are treated as a single element. |
| 715 | | Thus, "(elem (foo | bar) elem)" allows the token sequences "elem |
| 716 | | foo elem" and "elem bar elem". |
| 717 | | </t> |
| 718 | | </list> |
| 719 | | </t> |
| 720 | | <t> |
| 721 | | *rule |
| 722 | | <list> |
| 723 | | <t> |
| 724 | | The character "*" preceding an element indicates repetition. The |
| 725 | | full form is "<n>*<m>element" indicating at least <n> and at most |
| 726 | | <m> occurrences of element. Default values are 0 and infinity so |
| 727 | | that "*(element)" allows any number, including zero; "1*element" |
| 728 | | requires at least one; and "1*2element" allows one or two. |
| 729 | | </t> |
| 730 | | </list> |
| 731 | | </t> |
| 732 | | <t> |
| 733 | | [rule] |
| 734 | | <list> |
| 735 | | <t> |
| 736 | | Square brackets enclose optional elements; "[foo bar]" is |
| 737 | | equivalent to "*1(foo bar)". |
| 738 | | </t> |
| 739 | | </list> |
| 740 | | </t> |
| 741 | | <t> |
| 742 | | N rule |
| 743 | | <list> |
| 744 | | <t> |
| 745 | | Specific repetition: "<n>(element)" is equivalent to |
| 746 | | "<n>*<n>(element)"; that is, exactly <n> occurrences of (element). |
| 747 | | Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three |
| 748 | | alphabetic characters. |
| 749 | | </t> |
| 750 | | </list> |
| 751 | | </t> |
| 752 | | <t> |
| 753 | | #rule |
| 754 | | <list> |
| 755 | | <t> |
| 756 | | A construct "#" is defined, similar to "*", for defining lists of |
| 757 | | elements. The full form is "<n>#<m>element" indicating at least |
| 758 | | <n> and at most <m> elements, each separated by one or more commas |
| 759 | | (",") and &OPTIONAL; linear white space (LWS). This makes the usual |
| 760 | | form of lists very easy; a rule such as |
| 761 | | </t> |
| 762 | | <t> |
| 763 | | ( *LWS element *( *LWS "," *LWS element )) |
| 764 | | </t> |
| 765 | | <t> |
| 766 | | can be shown as |
| 767 | | </t> |
| 768 | | <t> |
| 769 | | 1#element |
| 770 | | </t> |
| 771 | | <t> |
| 772 | | Wherever this construct is used, null elements are allowed, but do |
| 773 | | not contribute to the count of elements present. That is, |
| 774 | | "(element), , (element) " is permitted, but counts as only two |
| 775 | | elements. Therefore, where at least one element is required, at |
| 776 | | least one non-null element &MUST; be present. Default values are 0 |
| 777 | | and infinity so that "#element" allows any number, including zero; |
| 778 | | "1#element" requires at least one; and "1#2element" allows one or |
| 779 | | two. |
| 780 | | </t> |
| 781 | | </list> |
| 782 | | </t> |
| 783 | | <t> |
| 784 | | ; comment |
| 785 | | <list> |
| 786 | | <t> |
| 787 | | A semi-colon, set off some distance to the right of rule text, |
| 788 | | starts a comment that continues to the end of line. This is a |
| 789 | | simple way of including useful notes in parallel with the |
| 790 | | specifications. |
| 791 | | </t> |
| 792 | | </list> |
| 793 | | </t> |
| 794 | | <t> |
| 795 | | implied *LWS |
| 796 | | <list> |
| 797 | | <t> |
| 798 | | The grammar described by this specification is word-based. Except |
| 799 | | where noted otherwise, linear white space (LWS) can be included |
| 800 | | between any two adjacent words (token or quoted-string), and |
| 801 | | between adjacent words and separators, without changing the |
| 802 | | interpretation of a field. At least one delimiter (LWS and/or |
| 803 | | separators) &MUST; exist between any two tokens (for the definition |
| 804 | | of "token" below), since they would otherwise be interpreted as a |
| 805 | | single token. |
| 806 | | </t> |
| 807 | | </list> |
| 808 | | </t> |
| 809 | | </section> |
| 810 | | |
| 811 | | <section title="Basic Rules" anchor="basic.rules"> |
| 812 | | <x:anchor-alias value="OCTET"/> |
| 813 | | <x:anchor-alias value="CHAR"/> |
| 814 | | <x:anchor-alias value="UPALPHA"/> |
| 815 | | <x:anchor-alias value="LOALPHA"/> |
| 816 | | <x:anchor-alias value="ALPHA"/> |
| 817 | | <x:anchor-alias value="DIGIT"/> |
| 818 | | <x:anchor-alias value="CTL"/> |
| 819 | | <x:anchor-alias value="CR"/> |
| 820 | | <x:anchor-alias value="LF"/> |
| 821 | | <x:anchor-alias value="SP"/> |
| 822 | | <x:anchor-alias value="HT"/> |
| 823 | | <x:anchor-alias value="CRLF"/> |
| 824 | | <x:anchor-alias value="LWS"/> |
| 825 | | <x:anchor-alias value="TEXT"/> |
| 826 | | <x:anchor-alias value="HEX"/> |
| 827 | | <x:anchor-alias value="token"/> |
| 828 | | <x:anchor-alias value="separators"/> |
| 829 | | <x:anchor-alias value="comment"/> |
| 830 | | <x:anchor-alias value="ctext"/> |
| 831 | | <x:anchor-alias value="quoted-string"/> |
| 832 | | <x:anchor-alias value="qdtext"/> |
| 833 | | <x:anchor-alias value="quoted-pair"/> |
| 834 | | <t> |
| 835 | | The following rules are used throughout this specification to |
| 836 | | describe basic parsing constructs. The US-ASCII coded character set |
| 837 | | is defined by ANSI X3.4-1986 <xref target="USASCII"/>. |
| 838 | | </t> |
| 839 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="OCTET"/><iref primary="true" item="Grammar" subitem="CHAR"/><iref primary="true" item="Grammar" subitem="UPALPHA"/><iref primary="true" item="Grammar" subitem="LOALPHA"/><iref primary="true" item="Grammar" subitem="ALPHA"/><iref primary="true" item="Grammar" subitem="DIGIT"/><iref primary="true" item="Grammar" subitem="CTL"/><iref primary="true" item="Grammar" subitem="CR"/><iref primary="true" item="Grammar" subitem="LF"/><iref primary="true" item="Grammar" subitem="SP"/><iref primary="true" item="Grammar" subitem="HT"/> |
| 840 | | OCTET = <any 8-bit sequence of data> |
| 841 | | CHAR = <any US-ASCII character (octets 0 - 127)> |
| 842 | | UPALPHA = <any US-ASCII uppercase letter "A".."Z"> |
| 843 | | LOALPHA = <any US-ASCII lowercase letter "a".."z"> |
| 844 | | ALPHA = UPALPHA | LOALPHA |
| 845 | | DIGIT = <any US-ASCII digit "0".."9"> |
| 846 | | CTL = <any US-ASCII control character |
| 847 | | (octets 0 - 31) and DEL (127)> |
| 848 | | CR = <US-ASCII CR, carriage return (13)> |
| 849 | | LF = <US-ASCII LF, linefeed (10)> |
| 850 | | SP = <US-ASCII SP, space (32)> |
| 851 | | HT = <US-ASCII HT, horizontal-tab (9)> |
| 852 | | <"> = <US-ASCII double-quote mark (34)> |
| 853 | | </artwork></figure> |
| 854 | | <t> |
| 855 | | HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all |
| 856 | | protocol elements except the entity-body (see <xref target="tolerant.applications"/> for |
| 857 | | tolerant applications). The end-of-line marker within an entity-body |
| 858 | | is defined by its associated media type, as described in <xref target="media.types"/>. |
| 859 | | </t> |
| 860 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="CRLF"/> |
| 861 | | CRLF = CR LF |
| 862 | | </artwork></figure> |
| 863 | | <t> |
| 864 | | HTTP/1.1 header field values can be folded onto multiple lines if the |
| 865 | | continuation line begins with a space or horizontal tab. All linear |
| 866 | | white space, including folding, has the same semantics as SP. A |
| 867 | | recipient &MAY; replace any linear white space with a single SP before |
| 868 | | interpreting the field value or forwarding the message downstream. |
| 869 | | </t> |
| 870 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="LWS"/> |
| 871 | | LWS = [CRLF] 1*( SP | HT ) |
| 872 | | </artwork></figure> |
| 873 | | <t> |
| 874 | | The TEXT rule is only used for descriptive field contents and values |
| 875 | | that are not intended to be interpreted by the message parser. Words |
| 876 | | of *TEXT &MAY; contain characters from character sets other than ISO-8859-1 |
| 877 | | <xref target="ISO-8859"/> only when encoded according to the rules of RFC 2047 |
| 878 | | <xref target="RFC2047"/>. |
| 879 | | </t> |
| 880 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="TEXT"/> |
| 881 | | TEXT = <any OCTET except CTLs, |
| 882 | | but including LWS> |
| 883 | | </artwork></figure> |
| 884 | | <t> |
| 885 | | A CRLF is allowed in the definition of TEXT only as part of a header |
| 886 | | field continuation. It is expected that the folding LWS will be |
| 887 | | replaced with a single SP before interpretation of the TEXT value. |
| 888 | | </t> |
| 889 | | <t> |
| 890 | | Hexadecimal numeric characters are used in several protocol elements. |
| 891 | | </t> |
| 892 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="HEX"/> |
| 893 | | HEX = "A" | "B" | "C" | "D" | "E" | "F" |
| 894 | | | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT |
| 895 | | </artwork></figure> |
| 896 | | <t> |
| 897 | | Many HTTP/1.1 header field values consist of words separated by LWS |
| 898 | | or special characters. These special characters &MUST; be in a quoted |
| 899 | | string to be used within a parameter value (as defined in |
| 900 | | <xref target="transfer.codings"/>). |
| 901 | | </t> |
| 902 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="token"/><iref primary="true" item="Grammar" subitem="separators"/> |
| 903 | | token = 1*<any CHAR except CTLs or separators> |
| 904 | | separators = "(" | ")" | "<" | ">" | "@" |
| 905 | | | "," | ";" | ":" | "\" | <"> |
| 906 | | | "/" | "[" | "]" | "?" | "=" |
| 907 | | | "{" | "}" | SP | HT |
| 908 | | </artwork></figure> |
| 909 | | <t> |
| 910 | | Comments can be included in some HTTP header fields by surrounding |
| 911 | | the comment text with parentheses. Comments are only allowed in |
| 912 | | fields containing "comment" as part of their field value definition. |
| 913 | | In all other fields, parentheses are considered part of the field |
| 914 | | value. |
| 915 | | </t> |
| 916 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="comment"/><iref primary="true" item="Grammar" subitem="ctext"/> |
| 917 | | comment = "(" *( ctext | quoted-pair | comment ) ")" |
| 918 | | ctext = <any TEXT excluding "(" and ")"> |
| 919 | | </artwork></figure> |
| 920 | | <t> |
| 921 | | A string of text is parsed as a single word if it is quoted using |
| 922 | | double-quote marks. |
| 923 | | </t> |
| 924 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="quoted-string"/><iref primary="true" item="Grammar" subitem="qdtext"/> |
| 925 | | quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) |
| 926 | | qdtext = <any TEXT except <">> |
| 927 | | </artwork></figure> |
| 928 | | <t> |
| 929 | | The backslash character ("\") &MAY; be used as a single-character |
| 930 | | quoting mechanism only within quoted-string and comment constructs. |
| 931 | | </t> |
| 932 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="quoted-pair"/> |
| 933 | | quoted-pair = "\" CHAR |
| 934 | | </artwork></figure> |
| 935 | | </section> |
| 936 | | </section> |
| 937 | | |
| 938 | | <section title="Protocol Parameters" anchor="protocol.parameters"> |
| 939 | | |
| 940 | | <section title="HTTP Version" anchor="http.version"> |
| 941 | | <t> |
| 942 | | HTTP uses a "<major>.<minor>" numbering scheme to indicate versions |
| 943 | | of the protocol. The protocol versioning policy is intended to allow |
| 944 | | the sender to indicate the format of a message and its capacity for |
| 945 | | understanding further HTTP communication, rather than the features |
| 946 | | obtained via that communication. No change is made to the version |
| 947 | | number for the addition of message components which do not affect |
| 948 | | communication behavior or which only add to extensible field values. |
| 949 | | The <minor> number is incremented when the changes made to the |
| 950 | | protocol add features which do not change the general message parsing |
| 951 | | algorithm, but which may add to the message semantics and imply |
| 952 | | additional capabilities of the sender. The <major> number is |
| 953 | | incremented when the format of a message within the protocol is |
| 954 | | changed. See RFC 2145 <xref target="RFC2145"/> for a fuller explanation. |
| 955 | | </t> |
| 956 | | <t> |
| 957 | | The version of an HTTP message is indicated by an HTTP-Version field |
| 958 | | in the first line of the message. |
| 959 | | </t> |
| 960 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="HTTP-Version"/> |
| 961 | | HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT |
| 962 | | </artwork></figure> |
| 963 | | <t> |
| 964 | | Note that the major and minor numbers &MUST; be treated as separate |
| 965 | | integers and that each &MAY; be incremented higher than a single digit. |
| 966 | | Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is |
| 967 | | lower than HTTP/12.3. Leading zeros &MUST; be ignored by recipients and |
| 968 | | &MUST-NOT; be sent. |
| 969 | | </t> |
| 970 | | <t> |
| 971 | | An application that sends a request or response message that includes |
| 972 | | HTTP-Version of "HTTP/1.1" &MUST; be at least conditionally compliant |
| 973 | | with this specification. Applications that are at least conditionally |
| 974 | | compliant with this specification &SHOULD; use an HTTP-Version of |
| 975 | | "HTTP/1.1" in their messages, and &MUST; do so for any message that is |
| 976 | | not compatible with HTTP/1.0. For more details on when to send |
| 977 | | specific HTTP-Version values, see RFC 2145 <xref target="RFC2145"/>. |
| 978 | | </t> |
| 979 | | <t> |
| 980 | | The HTTP version of an application is the highest HTTP version for |
| 981 | | which the application is at least conditionally compliant. |
| 982 | | </t> |
| 983 | | <t> |
| 984 | | Proxy and gateway applications need to be careful when forwarding |
| 985 | | messages in protocol versions different from that of the application. |
| 986 | | Since the protocol version indicates the protocol capability of the |
| 987 | | sender, a proxy/gateway &MUST-NOT; send a message with a version |
| 988 | | indicator which is greater than its actual version. If a higher |
| 989 | | version request is received, the proxy/gateway &MUST; either downgrade |
| 990 | | the request version, or respond with an error, or switch to tunnel |
| 991 | | behavior. |
| 992 | | </t> |
| 993 | | <t> |
| 994 | | Due to interoperability problems with HTTP/1.0 proxies discovered |
| 995 | | since the publication of RFC 2068 <xref target="RFC2068"/>, caching proxies MUST, gateways |
| 996 | | &MAY;, and tunnels &MUST-NOT; upgrade the request to the highest version |
| 997 | | they support. The proxy/gateway's response to that request &MUST; be in |
| 998 | | the same major version as the request. |
| 999 | | </t> |
| 1000 | | <t> |
| 1001 | | <list> |
| 1002 | | <t> |
| 1003 | | <x:h>Note:</x:h> Converting between versions of HTTP may involve modification |
| 1004 | | of header fields required or forbidden by the versions involved. |
| 1005 | | </t> |
| 1006 | | </list> |
| 1007 | | </t> |
| 1008 | | </section> |
| 1009 | | |
| 1010 | | <section title="Uniform Resource Identifiers" anchor="uri"> |
| 1011 | | <t> |
| 1012 | | URIs have been known by many names: WWW addresses, Universal Document |
| 1013 | | Identifiers, Universal Resource Identifiers <xref target="RFC1630"/>, and finally the |
| 1014 | | combination of Uniform Resource Locators (URL) <xref target="RFC1738"/> and Names (URN) |
| 1015 | | <xref target="RFC1737"/>. As far as HTTP is concerned, Uniform Resource Identifiers are |
| 1016 | | simply formatted strings which identify--via name, location, or any |
| 1017 | | other characteristic--a resource. |
| 1018 | | </t> |
| 1019 | | |
| 1020 | | <section title="General Syntax" anchor="general.syntax"> |
| 1021 | | <t> |
| 1022 | | URIs in HTTP can be represented in absolute form or relative to some |
| 1023 | | known base URI <xref target="RFC1808"/>, depending upon the context of their use. The two |
| 1024 | | forms are differentiated by the fact that absolute URIs always begin |
| 1025 | | with a scheme name followed by a colon. For definitive information on |
| 1026 | | URL syntax and semantics, see "Uniform Resource Identifiers (URI): |
| 1027 | | Generic Syntax and Semantics," RFC 2396 <xref target="RFC2396"/> (which replaces RFCs |
| 1028 | | 1738 <xref target="RFC1738"/> and RFC 1808 <xref target="RFC1808"/>). This specification adopts the |
| 1029 | | definitions of "URI-reference", "absoluteURI", "relativeURI", "port", |
| 1030 | | "host","abs_path", "rel_path", and "authority" from that |
| 1031 | | specification. |
| 1032 | | </t> |
| 1033 | | <t> |
| 1034 | | The HTTP protocol does not place any a priori limit on the length of |
| 1035 | | a URI. Servers &MUST; be able to handle the URI of any resource they |
| 1036 | | serve, and &SHOULD; be able to handle URIs of unbounded length if they |
| 1037 | | provide GET-based forms that could generate such URIs. A server |
| 1038 | | &SHOULD; return 414 (Request-URI Too Long) status if a URI is longer |
| 1039 | | than the server can handle (see <xref target="status.414"/>). |
| 1040 | | </t> |
| 1041 | | <t> |
| 1042 | | <list> |
| 1043 | | <t> |
| 1044 | | <x:h>Note:</x:h> Servers ought to be cautious about depending on URI lengths |
| 1045 | | above 255 bytes, because some older client or proxy |
| 1046 | | implementations might not properly support these lengths. |
| 1047 | | </t> |
| 1048 | | </list> |
| 1049 | | </t> |
| 1050 | | </section> |
| 1051 | | |
| 1052 | | <section title="http URL" anchor="http.url"> |
| 1053 | | <t> |
| 1054 | | The "http" scheme is used to locate network resources via the HTTP |
| 1055 | | protocol. This section defines the scheme-specific syntax and |
| 1056 | | semantics for http URLs. |
| 1057 | | </t> |
| 1058 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="http_URL"/> |
| 1059 | | http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]] |
| 1060 | | </artwork></figure> |
| 1061 | | <t> |
| 1062 | | If the port is empty or not given, port 80 is assumed. The semantics |
| 1063 | | are that the identified resource is located at the server listening |
| 1064 | | for TCP connections on that port of that host, and the Request-URI |
| 1065 | | for the resource is abs_path (<xref target="request-uri"/>). The use of IP addresses |
| 1066 | | in URLs &SHOULD; be avoided whenever possible (see RFC 1900 <xref target="RFC1900"/>). If |
| 1067 | | the abs_path is not present in the URL, it &MUST; be given as "/" when |
| 1068 | | used as a Request-URI for a resource (<xref target="request-uri"/>). If a proxy |
| 1069 | | |
| 1070 | | receives a host name which is not a fully qualified domain name, it |
| 1071 | | &MAY; add its domain to the host name it received. If a proxy receives |
| 1072 | | a fully qualified domain name, the proxy &MUST-NOT; change the host |
| 1073 | | name. |
| 1074 | | </t> |
| 1075 | | </section> |
| 1076 | | |
| 1077 | | <section title="URI Comparison" anchor="uri.comparison"> |
| 1078 | | <t> |
| 1079 | | When comparing two URIs to decide if they match or not, a client |
| 1080 | | &SHOULD; use a case-sensitive octet-by-octet comparison of the entire |
| 1081 | | URIs, with these exceptions: |
| 1082 | | <list style="symbols"> |
| 1083 | | <t>A port that is empty or not given is equivalent to the default |
| 1084 | | port for that URI-reference;</t> |
| 1085 | | <t>Comparisons of host names &MUST; be case-insensitive;</t> |
| 1086 | | <t>Comparisons of scheme names &MUST; be case-insensitive;</t> |
| 1087 | | <t>An empty abs_path is equivalent to an abs_path of "/".</t> |
| 1088 | | </list> |
| 1089 | | </t> |
| 1090 | | <t> |
| 1091 | | Characters other than those in the "reserved" and "unsafe" sets (see |
| 1092 | | RFC 2396 <xref target="RFC2396"/>) are equivalent to their ""%" HEX HEX" encoding. |
| 1093 | | </t> |
| 1094 | | <t> |
| 1095 | | For example, the following three URIs are equivalent: |
| 1096 | | </t> |
| 1097 | | <figure><artwork type="example"> |
| 1098 | | http://abc.com:80/~smith/home.html |
| 1099 | | http://ABC.com/%7Esmith/home.html |
| 1100 | | http://ABC.com:/%7esmith/home.html |
| 1101 | | </artwork></figure> |
| 1102 | | </section> |
| 1103 | | </section> |
| 1104 | | |
| 1105 | | <section title="Date/Time Formats" anchor="date.time.formats"> |
| 1106 | | |
| 1107 | | <section title="Full Date" anchor="full.date"> |
| 1108 | | <t> |
| 1109 | | HTTP applications have historically allowed three different formats |
| 1110 | | for the representation of date/time stamps: |
| 1111 | | </t> |
| 1112 | | <figure><artwork type="example"> |
| 1113 | | Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 |
| 1114 | | Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 |
| 1115 | | Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format |
| 1116 | | </artwork></figure> |
| 1117 | | <t> |
| 1118 | | The first format is preferred as an Internet standard and represents |
| 1119 | | a fixed-length subset of that defined by RFC 1123 <xref target="RFC1123"/> (an update to |
| 1120 | | RFC 822 <xref target="RFC822"/>). The second format is in common use, but is based on the |
| 1121 | | obsolete RFC 850 <xref target="RFC1036"/> date format and lacks a four-digit year. |
| 1122 | | HTTP/1.1 clients and servers that parse the date value &MUST; accept |
| 1123 | | all three formats (for compatibility with HTTP/1.0), though they &MUST; |
| 1124 | | only generate the RFC 1123 format for representing HTTP-date values |
| 1125 | | in header fields. See <xref target="tolerant.applications"/> for further information. |
| 1126 | | </t> |
| 1127 | | <t><list><t> |
| 1128 | | <x:h>Note:</x:h> Recipients of date values are encouraged to be robust in |
| 1129 | | accepting date values that may have been sent by non-HTTP |
| 1130 | | applications, as is sometimes the case when retrieving or posting |
| 1131 | | messages via proxies/gateways to SMTP or NNTP. |
| 1132 | | </t></list></t> |
| 1133 | | <t> |
| 1134 | | All HTTP date/time stamps &MUST; be represented in Greenwich Mean Time |
| 1135 | | (GMT), without exception. For the purposes of HTTP, GMT is exactly |
| 1136 | | equal to UTC (Coordinated Universal Time). This is indicated in the |
| 1137 | | first two formats by the inclusion of "GMT" as the three-letter |
| 1138 | | abbreviation for time zone, and &MUST; be assumed when reading the |
| 1139 | | asctime format. HTTP-date is case sensitive and &MUST-NOT; include |
| 1140 | | additional LWS beyond that specifically included as SP in the |
| 1141 | | grammar. |
| 1142 | | </t> |
| 1143 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="HTTP-date"/><iref primary="true" item="Grammar" subitem="rfc1123-date"/><iref primary="true" item="Grammar" subitem="rfc850-date"/><iref primary="true" item="Grammar" subitem="asctime-date"/><iref primary="true" item="Grammar" subitem="date1"/><iref primary="true" item="Grammar" subitem="date2"/><iref primary="true" item="Grammar" subitem="date3"/><iref primary="true" item="Grammar" subitem="time"/><iref primary="true" item="Grammar" subitem="wkday"/><iref primary="true" item="Grammar" subitem="weekday"/><iref primary="true" item="Grammar" subitem="month"/> |
| 1144 | | HTTP-date = rfc1123-date | rfc850-date | asctime-date |
| 1145 | | rfc1123-date = wkday "," SP date1 SP time SP "GMT" |
| 1146 | | rfc850-date = weekday "," SP date2 SP time SP "GMT" |
| 1147 | | asctime-date = wkday SP date3 SP time SP 4DIGIT |
| 1148 | | date1 = 2DIGIT SP month SP 4DIGIT |
| 1149 | | ; day month year (e.g., 02 Jun 1982) |
| 1150 | | date2 = 2DIGIT "-" month "-" 2DIGIT |
| 1151 | | ; day-month-year (e.g., 02-Jun-82) |
| 1152 | | date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) |
| 1153 | | ; month day (e.g., Jun 2) |
| 1154 | | time = 2DIGIT ":" 2DIGIT ":" 2DIGIT |
| 1155 | | ; 00:00:00 - 23:59:59 |
| 1156 | | wkday = "Mon" | "Tue" | "Wed" |
| 1157 | | | "Thu" | "Fri" | "Sat" | "Sun" |
| 1158 | | weekday = "Monday" | "Tuesday" | "Wednesday" |
| 1159 | | | "Thursday" | "Friday" | "Saturday" | "Sunday" |
| 1160 | | month = "Jan" | "Feb" | "Mar" | "Apr" |
| 1161 | | | "May" | "Jun" | "Jul" | "Aug" |
| 1162 | | | "Sep" | "Oct" | "Nov" | "Dec" |
| 1163 | | </artwork></figure> |
| 1164 | | <t> |
| 1165 | | <x:h>Note:</x:h> HTTP requirements for the date/time stamp format apply only |
| 1166 | | to their usage within the protocol stream. Clients and servers are |
| 1167 | | not required to use these formats for user presentation, request |
| 1168 | | logging, etc. |
| 1169 | | </t> |
| 1170 | | </section> |
| 1171 | | |
| 1172 | | <section title="Delta Seconds" anchor="delta.seconds"> |
| 1173 | | <t> |
| 1174 | | Some HTTP header fields allow a time value to be specified as an |
| 1175 | | integer number of seconds, represented in decimal, after the time |
| 1176 | | that the message was received. |
| 1177 | | </t> |
| 1178 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="delta-seconds"/> |
| 1179 | | delta-seconds = 1*DIGIT |
| 1180 | | </artwork></figure> |
| 1181 | | </section> |
| 1182 | | </section> |
| 1183 | | |
| 1184 | | <section title="Character Sets" anchor="character.sets"> |
| 1185 | | <t> |
| 1186 | | HTTP uses the same definition of the term "character set" as that |
| 1187 | | described for MIME: |
| 1188 | | </t> |
| 1189 | | <t> |
| 1190 | | The term "character set" is used in this document to refer to a |
| 1191 | | method used with one or more tables to convert a sequence of octets |
| 1192 | | into a sequence of characters. Note that unconditional conversion in |
| 1193 | | the other direction is not required, in that not all characters may |
| 1194 | | be available in a given character set and a character set may provide |
| 1195 | | more than one sequence of octets to represent a particular character. |
| 1196 | | This definition is intended to allow various kinds of character |
| 1197 | | encoding, from simple single-table mappings such as US-ASCII to |
| 1198 | | complex table switching methods such as those that use ISO-2022's |
| 1199 | | techniques. However, the definition associated with a MIME character |
| 1200 | | set name &MUST; fully specify the mapping to be performed from octets |
| 1201 | | to characters. In particular, use of external profiling information |
| 1202 | | to determine the exact mapping is not permitted. |
| 1203 | | </t> |
| 1204 | | <t><list><t> |
| 1205 | | <x:h>Note:</x:h> This use of the term "character set" is more commonly |
| 1206 | | referred to as a "character encoding." However, since HTTP and |
| 1207 | | MIME share the same registry, it is important that the terminology |
| 1208 | | also be shared. |
| 1209 | | </t></list></t> |
| 1210 | | <t> |
| 1211 | | HTTP character sets are identified by case-insensitive tokens. The |
| 1212 | | complete set of tokens is defined by the IANA Character Set registry |
| 1213 | | <xref target="RFC1700"/>. |
| 1214 | | </t> |
| 1215 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="charset"/> |
| 1216 | | charset = token |
| 1217 | | </artwork></figure> |
| 1218 | | <t> |
| 1219 | | Although HTTP allows an arbitrary token to be used as a charset |
| 1220 | | value, any token that has a predefined value within the IANA |
| 1221 | | Character Set registry <xref target="RFC1700"/> &MUST; represent the character set defined |
| 1222 | | by that registry. Applications &SHOULD; limit their use of character |
| 1223 | | sets to those defined by the IANA registry. |
| 1224 | | </t> |
| 1225 | | <t> |
| 1226 | | Implementors should be aware of IETF character set requirements <xref target="RFC2279"/> |
| 1227 | | <xref target="RFC2277"/>. |
| 1228 | | </t> |
| 1229 | | |
| 1230 | | <section title="Missing Charset" anchor="missing.charset"> |
| 1231 | | <t> |
| 1232 | | Some HTTP/1.0 software has interpreted a Content-Type header without |
| 1233 | | charset parameter incorrectly to mean "recipient should guess." |
| 1234 | | Senders wishing to defeat this behavior &MAY; include a charset |
| 1235 | | parameter even when the charset is ISO-8859-1 and &SHOULD; do so when |
| 1236 | | it is known that it will not confuse the recipient. |
| 1237 | | </t> |
| 1238 | | <t> |
| 1239 | | Unfortunately, some older HTTP/1.0 clients did not deal properly with |
| 1240 | | an explicit charset parameter. HTTP/1.1 recipients &MUST; respect the |
| 1241 | | charset label provided by the sender; and those user agents that have |
| 1242 | | a provision to "guess" a charset &MUST; use the charset from the |
| 1243 | | content-type field if they support that charset, rather than the |
| 1244 | | recipient's preference, when initially displaying a document. See |
| 1245 | | <xref target="canonicalization.and.text.defaults"/>. |
| 1246 | | </t> |
| 1247 | | </section> |
| 1248 | | </section> |
| 1249 | | |
| 1250 | | <section title="Content Codings" anchor="content.codings"> |
| 1251 | | <t> |
| 1252 | | Content coding values indicate an encoding transformation that has |
| 1253 | | been or can be applied to an entity. Content codings are primarily |
| 1254 | | used to allow a document to be compressed or otherwise usefully |
| 1255 | | transformed without losing the identity of its underlying media type |
| 1256 | | and without loss of information. Frequently, the entity is stored in |
| 1257 | | coded form, transmitted directly, and only decoded by the recipient. |
| 1258 | | </t> |
| 1259 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="content-coding"/> |
| 1260 | | content-coding = token |
| 1261 | | </artwork></figure> |
| 1262 | | <t> |
| 1263 | | All content-coding values are case-insensitive. HTTP/1.1 uses |
| 1264 | | content-coding values in the Accept-Encoding (<xref target="header.accept-encoding"/>) and |
| 1265 | | Content-Encoding (<xref target="header.content-encoding"/>) header fields. Although the value |
| 1266 | | describes the content-coding, what is more important is that it |
| 1267 | | indicates what decoding mechanism will be required to remove the |
| 1268 | | encoding. |
| 1269 | | </t> |
| 1270 | | <t> |
| 1271 | | The Internet Assigned Numbers Authority (IANA) acts as a registry for |
| 1272 | | content-coding value tokens. Initially, the registry contains the |
| 1273 | | following tokens: |
| 1274 | | </t> |
| 1275 | | <t> |
| 1276 | | gzip<iref item="gzip"/> |
| 1277 | | <list> |
| 1278 | | <t> |
| 1279 | | An encoding format produced by the file compression program |
| 1280 | | "gzip" (GNU zip) as described in RFC 1952 <xref target="RFC1952"/>. This format is a |
| 1281 | | Lempel-Ziv coding (LZ77) with a 32 bit CRC. |
| 1282 | | </t> |
| 1283 | | </list> |
| 1284 | | </t> |
| 1285 | | <t> |
| 1286 | | compress<iref item="compress"/> |
| 1287 | | <list><t> |
| 1288 | | The encoding format produced by the common UNIX file compression |
| 1289 | | program "compress". This format is an adaptive Lempel-Ziv-Welch |
| 1290 | | coding (LZW). |
| 1291 | | </t><t> |
| 1292 | | Use of program names for the identification of encoding formats |
| 1293 | | is not desirable and is discouraged for future encodings. Their |
| 1294 | | use here is representative of historical practice, not good |
| 1295 | | design. For compatibility with previous implementations of HTTP, |
| 1296 | | applications &SHOULD; consider "x-gzip" and "x-compress" to be |
| 1297 | | equivalent to "gzip" and "compress" respectively. |
| 1298 | | </t></list> |
| 1299 | | </t> |
| 1300 | | <t> |
| 1301 | | deflate<iref item="deflate"/> |
| 1302 | | <list><t> |
| 1303 | | The "zlib" format defined in RFC 1950 <xref target="RFC1950"/> in combination with |
| 1304 | | the "deflate" compression mechanism described in RFC 1951 <xref target="RFC1951"/>. |
| 1305 | | </t></list> |
| 1306 | | </t> |
| 1307 | | <t> |
| 1308 | | identity<iref item="identity"/> |
| 1309 | | <list><t> |
| 1310 | | The default (identity) encoding; the use of no transformation |
| 1311 | | whatsoever. This content-coding is used only in the Accept-Encoding |
| 1312 | | header, and &SHOULD-NOT; be used in the Content-Encoding |
| 1313 | | header. |
| 1314 | | </t></list> |
| 1315 | | </t> |
| 1316 | | <t> |
| 1317 | | New content-coding value tokens &SHOULD; be registered; to allow |
| 1318 | | interoperability between clients and servers, specifications of the |
| 1319 | | content coding algorithms needed to implement a new value &SHOULD; be |
| 1320 | | publicly available and adequate for independent implementation, and |
| 1321 | | conform to the purpose of content coding defined in this section. |
| 1322 | | </t> |
| 1323 | | </section> |
| 1324 | | |
| 1325 | | <section title="Transfer Codings" anchor="transfer.codings"> |
| 1326 | | <t> |
| 1327 | | Transfer-coding values are used to indicate an encoding |
| 1328 | | transformation that has been, can be, or may need to be applied to an |
| 1329 | | entity-body in order to ensure "safe transport" through the network. |
| 1330 | | This differs from a content coding in that the transfer-coding is a |
| 1331 | | property of the message, not of the original entity. |
| 1332 | | </t> |
| 1333 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="transfer-coding"/><iref primary="true" item="Grammar" subitem="transfer-extension"/> |
| 1334 | | transfer-coding = "chunked" | transfer-extension |
| 1335 | | transfer-extension = token *( ";" parameter ) |
| 1336 | | </artwork></figure> |
| 1337 | | <t> |
| 1338 | | Parameters are in the form of attribute/value pairs. |
| 1339 | | </t> |
| 1340 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="parameter"/><iref primary="true" item="Grammar" subitem="attribute"/><iref primary="true" item="Grammar" subitem="value"/> |
| 1341 | | parameter = attribute "=" value |
| 1342 | | attribute = token |
| 1343 | | value = token | quoted-string |
| 1344 | | </artwork></figure> |
| 1345 | | <t> |
| 1346 | | All transfer-coding values are case-insensitive. HTTP/1.1 uses |
| 1347 | | transfer-coding values in the TE header field (<xref target="header.te"/>) and in |
| 1348 | | the Transfer-Encoding header field (<xref target="header.transfer-encoding"/>). |
| 1349 | | </t> |
| 1350 | | <t> |
| 1351 | | Whenever a transfer-coding is applied to a message-body, the set of |
| 1352 | | transfer-codings &MUST; include "chunked", unless the message is |
| 1353 | | terminated by closing the connection. When the "chunked" transfer-coding |
| 1354 | | is used, it &MUST; be the last transfer-coding applied to the |
| 1355 | | message-body. The "chunked" transfer-coding &MUST-NOT; be applied more |
| 1356 | | than once to a message-body. These rules allow the recipient to |
| 1357 | | determine the transfer-length of the message (<xref target="message.length"/>). |
| 1358 | | </t> |
| 1359 | | <t> |
| 1360 | | Transfer-codings are analogous to the Content-Transfer-Encoding |
| 1361 | | values of MIME <xref target="RFC2045"/>, which were designed to enable safe transport of |
| 1362 | | binary data over a 7-bit transport service. However, safe transport |
| 1363 | | has a different focus for an 8bit-clean transfer protocol. In HTTP, |
| 1364 | | the only unsafe characteristic of message-bodies is the difficulty in |
| 1365 | | determining the exact body length (<xref target="entity.length"/>), or the desire to |
| 1366 | | encrypt data over a shared transport. |
| 1367 | | </t> |
| 1368 | | <t> |
| 1369 | | The Internet Assigned Numbers Authority (IANA) acts as a registry for |
| 1370 | | transfer-coding value tokens. Initially, the registry contains the |
| 1371 | | following tokens: "chunked" (<xref target="chunked.transfer.encoding"/>), "identity" (section |
| 1372 | | 3.6.2), "gzip" (<xref target="content.codings"/>), "compress" (<xref target="content.codings"/>), and "deflate" |
| 1373 | | (<xref target="content.codings"/>). |
| 1374 | | </t> |
| 1375 | | <t> |
| 1376 | | New transfer-coding value tokens &SHOULD; be registered in the same way |
| 1377 | | as new content-coding value tokens (<xref target="content.codings"/>). |
| 1378 | | </t> |
| 1379 | | <t> |
| 1380 | | A server which receives an entity-body with a transfer-coding it does |
| 1381 | | not understand &SHOULD; return 501 (Unimplemented), and close the |
| 1382 | | connection. A server &MUST-NOT; send transfer-codings to an HTTP/1.0 |
| 1383 | | client. |
| 1384 | | </t> |
| 1385 | | |
| 1386 | | <section title="Chunked Transfer Coding" anchor="chunked.transfer.encoding"> |
| 1387 | | <t> |
| 1388 | | The chunked encoding modifies the body of a message in order to |
| 1389 | | transfer it as a series of chunks, each with its own size indicator, |
| 1390 | | followed by an &OPTIONAL; trailer containing entity-header fields. This |
| 1391 | | allows dynamically produced content to be transferred along with the |
| 1392 | | information necessary for the recipient to verify that it has |
| 1393 | | received the full message. |
| 1394 | | </t> |
| 1395 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Chunked-Body"/><iref primary="true" item="Grammar" subitem="chunk"/><iref primary="true" item="Grammar" subitem="chunk-size"/><iref primary="true" item="Grammar" subitem="last-chunk"/><iref primary="true" item="Grammar" subitem="chunk-extension"/><iref primary="true" item="Grammar" subitem="chunk-ext-name"/><iref primary="true" item="Grammar" subitem="chunk-ext-val"/><iref primary="true" item="Grammar" subitem="chunk-data"/><iref primary="true" item="Grammar" subitem="trailer"/> |
| 1396 | | Chunked-Body = *chunk |
| 1397 | | last-chunk |
| 1398 | | trailer |
| 1399 | | CRLF |
| 1400 | | |
| 1401 | | chunk = chunk-size [ chunk-extension ] CRLF |
| 1402 | | chunk-data CRLF |
| 1403 | | chunk-size = 1*HEX |
| 1404 | | last-chunk = 1*("0") [ chunk-extension ] CRLF |
| 1405 | | |
| 1406 | | chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) |
| 1407 | | chunk-ext-name = token |
| 1408 | | chunk-ext-val = token | quoted-string |
| 1409 | | chunk-data = chunk-size(OCTET) |
| 1410 | | trailer = *(entity-header CRLF) |
| 1411 | | </artwork></figure> |
| 1412 | | <t> |
| 1413 | | The chunk-size field is a string of hex digits indicating the size of |
| 1414 | | the chunk. The chunked encoding is ended by any chunk whose size is |
| 1415 | | zero, followed by the trailer, which is terminated by an empty line. |
| 1416 | | </t> |
| 1417 | | <t> |
| 1418 | | The trailer allows the sender to include additional HTTP header |
| 1419 | | fields at the end of the message. The Trailer header field can be |
| 1420 | | used to indicate which header fields are included in a trailer (see |
| 1421 | | <xref target="header.trailer"/>). |
| 1422 | | </t> |
| 1423 | | <t> |
| 1424 | | A server using chunked transfer-coding in a response &MUST-NOT; use the |
| 1425 | | trailer for any header fields unless at least one of the following is |
| 1426 | | true: |
| 1427 | | <list style="numbers"> |
| 1428 | | <t>the request included a TE header field that indicates "trailers" is |
| 1429 | | acceptable in the transfer-coding of the response, as described in |
| 1430 | | <xref target="header.te"/>; or,</t> |
| 1431 | | |
| 1432 | | <t>the server is the origin server for the response, the trailer |
| 1433 | | fields consist entirely of optional metadata, and the recipient |
| 1434 | | could use the message (in a manner acceptable to the origin server) |
| 1435 | | without receiving this metadata. In other words, the origin server |
| 1436 | | is willing to accept the possibility that the trailer fields might |
| 1437 | | be silently discarded along the path to the client.</t> |
| 1438 | | </list> |
| 1439 | | </t> |
| 1440 | | <t> |
| 1441 | | This requirement prevents an interoperability failure when the |
| 1442 | | message is being received by an HTTP/1.1 (or later) proxy and |
| 1443 | | forwarded to an HTTP/1.0 recipient. It avoids a situation where |
| 1444 | | compliance with the protocol would have necessitated a possibly |
| 1445 | | infinite buffer on the proxy. |
| 1446 | | </t> |
| 1447 | | <t> |
| 1448 | | An example process for decoding a Chunked-Body is presented in |
| 1449 | | <xref target="introduction.of.transfer-encoding"/>. |
| 1450 | | </t> |
| 1451 | | <t> |
| 1452 | | All HTTP/1.1 applications &MUST; be able to receive and decode the |
| 1453 | | "chunked" transfer-coding, and &MUST; ignore chunk-extension extensions |
| 1454 | | they do not understand. |
| 1455 | | </t> |
| 1456 | | </section> |
| 1457 | | </section> |
| 1458 | | |
| 1459 | | <section title="Media Types" anchor="media.types"> |
| 1460 | | <t> |
| 1461 | | HTTP uses Internet Media Types <xref target="RFC1590"/> in the Content-Type (<xref target="header.content-type"/>) |
| 1462 | | and Accept (<xref target="header.accept"/>) header fields in order to provide |
| 1463 | | open and extensible data typing and type negotiation. |
| 1464 | | </t> |
| 1465 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="media-type"/><iref primary="true" item="Grammar" subitem="type"/><iref primary="true" item="Grammar" subitem="subtype"/> |
| 1466 | | media-type = type "/" subtype *( ";" parameter ) |
| 1467 | | type = token |
| 1468 | | subtype = token |
| 1469 | | </artwork></figure> |
| 1470 | | <t> |
| 1471 | | Parameters &MAY; follow the type/subtype in the form of attribute/value |
| 1472 | | pairs (as defined in <xref target="transfer.codings"/>). |
| 1473 | | </t> |
| 1474 | | <t> |
| 1475 | | The type, subtype, and parameter attribute names are case-insensitive. |
| 1476 | | Parameter values might or might not be case-sensitive, |
| 1477 | | depending on the semantics of the parameter name. Linear white space |
| 1478 | | (LWS) &MUST-NOT; be used between the type and subtype, nor between an |
| 1479 | | attribute and its value. The presence or absence of a parameter might |
| 1480 | | be significant to the processing of a media-type, depending on its |
| 1481 | | definition within the media type registry. |
| 1482 | | </t> |
| 1483 | | <t> |
| 1484 | | Note that some older HTTP applications do not recognize media type |
| 1485 | | parameters. When sending data to older HTTP applications, |
| 1486 | | implementations &SHOULD; only use media type parameters when they are |
| 1487 | | required by that type/subtype definition. |
| 1488 | | </t> |
| 1489 | | <t> |
| 1490 | | Media-type values are registered with the Internet Assigned Number |
| 1491 | | Authority (IANA <xref target="RFC1700"/>). The media type registration process is |
| 1492 | | outlined in RFC 1590 <xref target="RFC1590"/>. Use of non-registered media types is |
| 1493 | | discouraged. |
| 1494 | | </t> |
| 1495 | | |
| 1496 | | <section title="Canonicalization and Text Defaults" anchor="canonicalization.and.text.defaults"> |
| 1497 | | <t> |
| 1498 | | Internet media types are registered with a canonical form. An |
| 1499 | | entity-body transferred via HTTP messages &MUST; be represented in the |
| 1500 | | appropriate canonical form prior to its transmission except for |
| 1501 | | "text" types, as defined in the next paragraph. |
| 1502 | | </t> |
| 1503 | | <t> |
| 1504 | | When in canonical form, media subtypes of the "text" type use CRLF as |
| 1505 | | the text line break. HTTP relaxes this requirement and allows the |
| 1506 | | transport of text media with plain CR or LF alone representing a line |
| 1507 | | break when it is done consistently for an entire entity-body. HTTP |
| 1508 | | applications &MUST; accept CRLF, bare CR, and bare LF as being |
| 1509 | | representative of a line break in text media received via HTTP. In |
| 1510 | | addition, if the text is represented in a character set that does not |
| 1511 | | use octets 13 and 10 for CR and LF respectively, as is the case for |
| 1512 | | some multi-byte character sets, HTTP allows the use of whatever octet |
| 1513 | | sequences are defined by that character set to represent the |
| 1514 | | equivalent of CR and LF for line breaks. This flexibility regarding |
| 1515 | | line breaks applies only to text media in the entity-body; a bare CR |
| 1516 | | or LF &MUST-NOT; be substituted for CRLF within any of the HTTP control |
| 1517 | | structures (such as header fields and multipart boundaries). |
| 1518 | | </t> |
| 1519 | | <t> |
| 1520 | | If an entity-body is encoded with a content-coding, the underlying |
| 1521 | | data &MUST; be in a form defined above prior to being encoded. |
| 1522 | | </t> |
| 1523 | | <t> |
| 1524 | | The "charset" parameter is used with some media types to define the |
| 1525 | | character set (<xref target="character.sets"/>) of the data. When no explicit charset |
| 1526 | | parameter is provided by the sender, media subtypes of the "text" |
| 1527 | | type are defined to have a default charset value of "ISO-8859-1" when |
| 1528 | | received via HTTP. Data in character sets other than "ISO-8859-1" or |
| 1529 | | its subsets &MUST; be labeled with an appropriate charset value. See |
| 1530 | | <xref target="missing.charset"/> for compatibility problems. |
| 1531 | | </t> |
| 1532 | | </section> |
| 1533 | | |
| 1534 | | <section title="Multipart Types" anchor="multipart.types"> |
| 1535 | | <t> |
| 1536 | | MIME provides for a number of "multipart" types -- encapsulations of |
| 1537 | | one or more entities within a single message-body. All multipart |
| 1538 | | types share a common syntax, as defined in section <xref target="RFC2046" x:sec="5.1.1" x:fmt="number"/> of RFC 2046 |
| 1539 | | <xref target="RFC2046"/>, and &MUST; include a boundary parameter as part of the media type |
| 1540 | | value. The message body is itself a protocol element and &MUST; |
| 1541 | | therefore use only CRLF to represent line breaks between body-parts. |
| 1542 | | Unlike in RFC 2046, the epilogue of any multipart message &MUST; be |
| 1543 | | empty; HTTP applications &MUST-NOT; transmit the epilogue (even if the |
| 1544 | | original multipart contains an epilogue). These restrictions exist in |
| 1545 | | order to preserve the self-delimiting nature of a multipart message-body, |
| 1546 | | wherein the "end" of the message-body is indicated by the |
| 1547 | | ending multipart boundary. |
| 1548 | | </t> |
| 1549 | | <t> |
| 1550 | | In general, HTTP treats a multipart message-body no differently than |
| 1551 | | any other media type: strictly as payload. The one exception is the |
| 1552 | | "multipart/byteranges" type (<xref target="internet.media.type.multipart.byteranges"/>) when it appears in a 206 |
| 1553 | | (Partial Content) response, which will be interpreted by some HTTP |
| 1554 | | caching mechanisms as described in sections <xref target="combining.byte.ranges" format="counter"/> |
| 1555 | | and <xref target="header.content-range" format="counter"/>. In all |
| 1556 | | other cases, an HTTP user agent &SHOULD; follow the same or similar |
| 1557 | | behavior as a MIME user agent would upon receipt of a multipart type. |
| 1558 | | The MIME header fields within each body-part of a multipart message-body |
| 1559 | | do not have any significance to HTTP beyond that defined by |
| 1560 | | their MIME semantics. |
| 1561 | | </t> |
| 1562 | | <t> |
| 1563 | | In general, an HTTP user agent &SHOULD; follow the same or similar |
| 1564 | | behavior as a MIME user agent would upon receipt of a multipart type. |
| 1565 | | If an application receives an unrecognized multipart subtype, the |
| 1566 | | application &MUST; treat it as being equivalent to "multipart/mixed". |
| 1567 | | </t> |
| 1568 | | <t><list><t> |
| 1569 | | <x:h>Note:</x:h> The "multipart/form-data" type has been specifically defined |
| 1570 | | for carrying form data suitable for processing via the POST |
| 1571 | | request method, as described in RFC 1867 <xref target="RFC1867"/>. |
| 1572 | | </t></list></t> |
| 1573 | | </section> |
| | 209 | between HTTP and MIME is described in &diff2045entity;. |
| | 210 | </t> |
| 1605 | | |
| 1606 | | <section title="Quality Values" anchor="quality.values"> |
| 1607 | | <t> |
| 1608 | | HTTP content negotiation (<xref target="content.negotiation"/>) uses short "floating point" |
| 1609 | | numbers to indicate the relative importance ("weight") of various |
| 1610 | | negotiable parameters. A weight is normalized to a real number in |
| 1611 | | the range 0 through 1, where 0 is the minimum and 1 the maximum |
| 1612 | | value. If a parameter has a quality value of 0, then content with |
| 1613 | | this parameter is `not acceptable' for the client. HTTP/1.1 |
| 1614 | | applications &MUST-NOT; generate more than three digits after the |
| 1615 | | decimal point. User configuration of these values &SHOULD; also be |
| 1616 | | limited in this fashion. |
| 1617 | | </t> |
| 1618 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="qvalue"/> |
| 1619 | | qvalue = ( "0" [ "." 0*3DIGIT ] ) |
| 1620 | | | ( "1" [ "." 0*3("0") ] ) |
| 1621 | | </artwork></figure> |
| 1622 | | <t> |
| 1623 | | "Quality values" is a misnomer, since these values merely represent |
| 1624 | | relative degradation in desired quality. |
| 1625 | | </t> |
| 1626 | | </section> |
| 1627 | | |
| 1628 | | <section title="Language Tags" anchor="language.tags"> |
| 1629 | | <t> |
| 1630 | | A language tag identifies a natural language spoken, written, or |
| 1631 | | otherwise conveyed by human beings for communication of information |
| 1632 | | to other human beings. Computer languages are explicitly excluded. |
| 1633 | | HTTP uses language tags within the Accept-Language and Content-Language |
| 1634 | | fields. |
| 1635 | | </t> |
| 1636 | | <t> |
| 1637 | | The syntax and registry of HTTP language tags is the same as that |
| 1638 | | defined by RFC 1766 <xref target="RFC1766"/>. In summary, a language tag is composed of 1 |
| 1639 | | or more parts: A primary language tag and a possibly empty series of |
| 1640 | | subtags: |
| 1641 | | </t> |
| 1642 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="language-tag"/><iref primary="true" item="Grammar" subitem="primary-tag"/><iref primary="true" item="Grammar" subitem="subtag"/> |
| 1643 | | language-tag = primary-tag *( "-" subtag ) |
| 1644 | | primary-tag = 1*8ALPHA |
| 1645 | | subtag = 1*8ALPHA |
| 1646 | | </artwork></figure> |
| 1647 | | <t> |
| 1648 | | White space is not allowed within the tag and all tags are case-insensitive. |
| 1649 | | The name space of language tags is administered by the |
| 1650 | | IANA. Example tags include: |
| 1651 | | </t> |
| 1652 | | <figure><artwork type="example"> |
| 1653 | | en, en-US, en-cockney, i-cherokee, x-pig-latin |
| 1654 | | </artwork></figure> |
| 1655 | | <t> |
| 1656 | | where any two-letter primary-tag is an ISO-639 language abbreviation |
| 1657 | | and any two-letter initial subtag is an ISO-3166 country code. (The |
| 1658 | | last three tags above are not registered tags; all but the last are |
| 1659 | | examples of tags which could be registered in future.) |
| 1660 | | </t> |
| 1661 | | </section> |
| 1662 | | |
| 1663 | | <section title="Entity Tags" anchor="entity.tags"> |
| 1664 | | <t> |
| 1665 | | Entity tags are used for comparing two or more entities from the same |
| 1666 | | requested resource. HTTP/1.1 uses entity tags in the ETag (<xref target="header.etag"/>), |
| 1667 | | If-Match (<xref target="header.if-match"/>), If-None-Match (<xref target="header.if-none-match"/>), and |
| 1668 | | If-Range (<xref target="header.if-range"/>) header fields. The definition of how they |
| 1669 | | are used and compared as cache validators is in <xref target="weak.and.strong.validators"/>. An |
| 1670 | | entity tag consists of an opaque quoted string, possibly prefixed by |
| 1671 | | a weakness indicator. |
| 1672 | | </t> |
| 1673 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="entity-tag"/><iref primary="true" item="Grammar" subitem="weak"/><iref primary="true" item="Grammar" subitem="opaque-tag"/> |
| 1674 | | entity-tag = [ weak ] opaque-tag |
| 1675 | | weak = "W/" |
| 1676 | | opaque-tag = quoted-string |
| 1677 | | </artwork></figure> |
| 1678 | | <t> |
| 1679 | | A "strong entity tag" &MAY; be shared by two entities of a resource |
| 1680 | | only if they are equivalent by octet equality. |
| 1681 | | </t> |
| 1682 | | <t> |
| 1683 | | A "weak entity tag," indicated by the "W/" prefix, &MAY; be shared by |
| 1684 | | two entities of a resource only if the entities are equivalent and |
| 1685 | | could be substituted for each other with no significant change in |
| 1686 | | semantics. A weak entity tag can only be used for weak comparison. |
| 1687 | | </t> |
| 1688 | | <t> |
| 1689 | | An entity tag &MUST; be unique across all versions of all entities |
| 1690 | | associated with a particular resource. A given entity tag value &MAY; |
| 1691 | | be used for entities obtained by requests on different URIs. The use |
| 1692 | | of the same entity tag value in conjunction with entities obtained by |
| 1693 | | requests on different URIs does not imply the equivalence of those |
| 1694 | | entities. |
| 1695 | | </t> |
| 1696 | | </section> |
| 1697 | | |
| 1698 | | <section title="Range Units" anchor="range.units"> |
| 1699 | | <t> |
| 1700 | | HTTP/1.1 allows a client to request that only part (a range of) the |
| 1701 | | response entity be included within the response. HTTP/1.1 uses range |
| 1702 | | units in the Range (<xref target="header.range"/>) and Content-Range (<xref target="header.content-range"/>) |
| 1703 | | header fields. An entity can be broken down into subranges according |
| 1704 | | to various structural units. |
| 1705 | | </t> |
| 1706 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="range-unit"/><iref primary="true" item="Grammar" subitem="bytes-unit"/><iref primary="true" item="Grammar" subitem="other-range-unit"/> |
| 1707 | | range-unit = bytes-unit | other-range-unit |
| 1708 | | bytes-unit = "bytes" |
| 1709 | | other-range-unit = token |
| 1710 | | </artwork></figure> |
| 1711 | | <t> |
| 1712 | | The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 |
| 1713 | | implementations &MAY; ignore ranges specified using other units. |
| 1714 | | </t> |
| 1715 | | <t> |
| 1716 | | HTTP/1.1 has been designed to allow implementations of applications |
| 1717 | | that do not depend on knowledge of ranges. |
| 1718 | | </t> |
| 1719 | | </section> |
| 1720 | | </section> |
| 1721 | | |
| 1722 | | |
| 1723 | | |
| 1724 | | |
| 1725 | | <section title="HTTP Message" anchor="http.message"> |
| 1726 | | |
| 1727 | | <section title="Message Types" anchor="message.types"> |
| 1728 | | <t> |
| 1729 | | HTTP messages consist of requests from client to server and responses |
| 1730 | | from server to client. |
| 1731 | | </t> |
| 1732 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="HTTP-message"/> |
| 1733 | | HTTP-message = Request | Response ; HTTP/1.1 messages |
| 1734 | | </artwork></figure> |
| 1735 | | <t> |
| 1736 | | Request (<xref target="request"/>) and Response (<xref target="response"/>) messages use the generic |
| 1737 | | message format of RFC 822 <xref target="RFC822"/> for transferring entities (the payload |
| 1738 | | of the message). Both types of message consist of a start-line, zero |
| 1739 | | or more header fields (also known as "headers"), an empty line (i.e., |
| 1740 | | a line with nothing preceding the CRLF) indicating the end of the |
| 1741 | | header fields, and possibly a message-body. |
| 1742 | | </t> |
| 1743 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="generic-message"/><iref primary="true" item="Grammar" subitem="start-line"/> |
| 1744 | | generic-message = start-line |
| 1745 | | *(message-header CRLF) |
| 1746 | | CRLF |
| 1747 | | [ message-body ] |
| 1748 | | start-line = Request-Line | Status-Line |
| 1749 | | </artwork></figure> |
| 1750 | | <t> |
| 1751 | | In the interest of robustness, servers &SHOULD; ignore any empty |
| 1752 | | line(s) received where a Request-Line is expected. In other words, if |
| 1753 | | the server is reading the protocol stream at the beginning of a |
| 1754 | | message and receives a CRLF first, it should ignore the CRLF. |
| 1755 | | </t> |
| 1756 | | <t> |
| 1757 | | Certain buggy HTTP/1.0 client implementations generate extra CRLF's |
| 1758 | | after a POST request. To restate what is explicitly forbidden by the |
| 1759 | | BNF, an HTTP/1.1 client &MUST-NOT; preface or follow a request with an |
| 1760 | | extra CRLF. |
| 1761 | | </t> |
| 1762 | | </section> |
| 1763 | | |
| 1764 | | <section title="Message Headers" anchor="message.headers"> |
| 1765 | | <t> |
| 1766 | | HTTP header fields, which include general-header (<xref target="general.header.fields"/>), |
| 1767 | | request-header (<xref target="request.header.fields"/>), response-header (<xref target="response.header.fields"/>), and |
| 1768 | | entity-header (<xref target="entity.header.fields"/>) fields, follow the same generic format as |
| 1769 | | that given in <xref target="RFC822" x:fmt="sec" x:sec="3.1"/> of RFC 822 <xref target="RFC822"/>. Each header field consists |
| 1770 | | of a name followed by a colon (":") and the field value. Field names |
| 1771 | | are case-insensitive. The field value &MAY; be preceded by any amount |
| 1772 | | of LWS, though a single SP is preferred. Header fields can be |
| 1773 | | extended over multiple lines by preceding each extra line with at |
| 1774 | | least one SP or HT. Applications ought to follow "common form", where |
| 1775 | | one is known or indicated, when generating HTTP constructs, since |
| 1776 | | there might exist some implementations that fail to accept anything |
| 1777 | | beyond the common forms. |
| 1778 | | </t> |
| 1779 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="message-header"/><iref primary="true" item="Grammar" subitem="field-name"/><iref primary="true" item="Grammar" subitem="field-value"/><iref primary="true" item="Grammar" subitem="field-content"/> |
| 1780 | | message-header = field-name ":" [ field-value ] |
| 1781 | | field-name = token |
| 1782 | | field-value = *( field-content | LWS ) |
| 1783 | | field-content = <the OCTETs making up the field-value |
| 1784 | | and consisting of either *TEXT or combinations |
| 1785 | | of token, separators, and quoted-string> |
| 1786 | | </artwork></figure> |
| 1787 | | <t> |
| 1788 | | The field-content does not include any leading or trailing LWS: |
| 1789 | | linear white space occurring before the first non-whitespace |
| 1790 | | character of the field-value or after the last non-whitespace |
| 1791 | | character of the field-value. Such leading or trailing LWS &MAY; be |
| 1792 | | removed without changing the semantics of the field value. Any LWS |
| 1793 | | that occurs between field-content &MAY; be replaced with a single SP |
| 1794 | | before interpreting the field value or forwarding the message |
| 1795 | | downstream. |
| 1796 | | </t> |
| 1797 | | <t> |
| 1798 | | The order in which header fields with differing field names are |
| 1799 | | received is not significant. However, it is "good practice" to send |
| 1800 | | general-header fields first, followed by request-header or response-header |
| 1801 | | fields, and ending with the entity-header fields. |
| 1802 | | </t> |
| 1803 | | <t> |
| 1804 | | Multiple message-header fields with the same field-name &MAY; be |
| 1805 | | present in a message if and only if the entire field-value for that |
| 1806 | | header field is defined as a comma-separated list [i.e., #(values)]. |
| 1807 | | It &MUST; be possible to combine the multiple header fields into one |
| 1808 | | "field-name: field-value" pair, without changing the semantics of the |
| 1809 | | message, by appending each subsequent field-value to the first, each |
| 1810 | | separated by a comma. The order in which header fields with the same |
| 1811 | | field-name are received is therefore significant to the |
| 1812 | | interpretation of the combined field value, and thus a proxy &MUST-NOT; |
| 1813 | | change the order of these field values when a message is forwarded. |
| 1814 | | </t> |
| 1815 | | </section> |
| 1816 | | |
| 1817 | | <section title="Message Body" anchor="message.body"> |
| 1818 | | <t> |
| 1819 | | The message-body (if any) of an HTTP message is used to carry the |
| 1820 | | entity-body associated with the request or response. The message-body |
| 1821 | | differs from the entity-body only when a transfer-coding has been |
| 1822 | | applied, as indicated by the Transfer-Encoding header field (<xref target="header.transfer-encoding"/>). |
| 1823 | | </t> |
| 1824 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="message-body"/> |
| 1825 | | message-body = entity-body |
| 1826 | | | <entity-body encoded as per Transfer-Encoding> |
| 1827 | | </artwork></figure> |
| 1828 | | <t> |
| 1829 | | Transfer-Encoding &MUST; be used to indicate any transfer-codings |
| 1830 | | applied by an application to ensure safe and proper transfer of the |
| 1831 | | message. Transfer-Encoding is a property of the message, not of the |
| 1832 | | entity, and thus &MAY; be added or removed by any application along the |
| 1833 | | request/response chain. (However, <xref target="transfer.codings"/> places restrictions on |
| 1834 | | when certain transfer-codings may be used.) |
| 1835 | | </t> |
| 1836 | | <t> |
| 1837 | | The rules for when a message-body is allowed in a message differ for |
| 1838 | | requests and responses. |
| 1839 | | </t> |
| 1840 | | <t> |
| 1841 | | The presence of a message-body in a request is signaled by the |
| 1842 | | inclusion of a Content-Length or Transfer-Encoding header field in |
| 1843 | | the request's message-headers. A message-body &MUST-NOT; be included in |
| 1844 | | a request if the specification of the request method (<xref target="method"/>) |
| 1845 | | does not allow sending an entity-body in requests. A server &SHOULD; |
| 1846 | | read and forward a message-body on any request; if the request method |
| 1847 | | does not include defined semantics for an entity-body, then the |
| 1848 | | message-body &SHOULD; be ignored when handling the request. |
| 1849 | | </t> |
| 1850 | | <t> |
| 1851 | | For response messages, whether or not a message-body is included with |
| 1852 | | a message is dependent on both the request method and the response |
| 1853 | | status code (<xref target="status.code.and.reason.phrase"/>). All responses to the HEAD request method |
| 1854 | | &MUST-NOT; include a message-body, even though the presence of entity-header |
| 1855 | | fields might lead one to believe they do. All 1xx |
| 1856 | | (informational), 204 (no content), and 304 (not modified) responses |
| 1857 | | &MUST-NOT; include a message-body. All other responses do include a |
| 1858 | | message-body, although it &MAY; be of zero length. |
| 1859 | | </t> |
| 1860 | | </section> |
| 1861 | | |
| 1862 | | <section title="Message Length" anchor="message.length"> |
| 1863 | | <t> |
| 1864 | | The transfer-length of a message is the length of the message-body as |
| 1865 | | it appears in the message; that is, after any transfer-codings have |
| 1866 | | been applied. When a message-body is included with a message, the |
| 1867 | | transfer-length of that body is determined by one of the following |
| 1868 | | (in order of precedence): |
| 1869 | | </t> |
| 1870 | | <t> |
| 1871 | | <list style="numbers"> |
| 1872 | | <x:lt><t> |
| 1873 | | Any response message which "&MUST-NOT;" include a message-body (such |
| 1874 | | as the 1xx, 204, and 304 responses and any response to a HEAD |
| 1875 | | request) is always terminated by the first empty line after the |
| 1876 | | header fields, regardless of the entity-header fields present in |
| 1877 | | the message. |
| 1878 | | </t></x:lt> |
| 1879 | | <x:lt><t> |
| 1880 | | If a Transfer-Encoding header field (<xref target="header.transfer-encoding"/>) is present and |
| 1881 | | has any value other than "identity", then the transfer-length is |
| 1882 | | defined by use of the "chunked" transfer-coding (<xref target="transfer.codings"/>), |
| 1883 | | unless the message is terminated by closing the connection. |
| 1884 | | </t></x:lt> |
| 1885 | | <x:lt><t> |
| 1886 | | If a Content-Length header field (<xref target="header.content-length"/>) is present, its |
| 1887 | | decimal value in OCTETs represents both the entity-length and the |
| 1888 | | transfer-length. The Content-Length header field &MUST-NOT; be sent |
| 1889 | | if these two lengths are different (i.e., if a Transfer-Encoding |
| 1890 | | header field is present). If a message is received with both a |
| 1891 | | Transfer-Encoding header field and a Content-Length header field, |
| 1892 | | the latter &MUST; be ignored. |
| 1893 | | </t></x:lt> |
| 1894 | | <x:lt><t> |
| 1895 | | If the message uses the media type "multipart/byteranges", and the |
| 1896 | | ransfer-length is not otherwise specified, then this self-elimiting |
| 1897 | | media type defines the transfer-length. This media type |
| 1898 | | UST NOT be used unless the sender knows that the recipient can arse |
| 1899 | | it; the presence in a request of a Range header with ultiple byte-range |
| 1900 | | specifiers from a 1.1 client implies that the lient can parse |
| 1901 | | multipart/byteranges responses. |
| 1902 | | <list style="empty"><t> |
| 1903 | | A range header might be forwarded by a 1.0 proxy that does not |
| 1904 | | understand multipart/byteranges; in this case the server &MUST; |
| 1905 | | delimit the message using methods defined in items 1, 3 or 5 of |
| 1906 | | this section. |
| 1907 | | </t></list> |
| 1908 | | </t></x:lt> |
| 1909 | | <x:lt><t> |
| 1910 | | By the server closing the connection. (Closing the connection |
| 1911 | | cannot be used to indicate the end of a request body, since that |
| 1912 | | would leave no possibility for the server to send back a response.) |
| 1913 | | </t></x:lt> |
| 1914 | | </list> |
| 1915 | | </t> |
| 1916 | | <t> |
| 1917 | | For compatibility with HTTP/1.0 applications, HTTP/1.1 requests |
| 1918 | | containing a message-body &MUST; include a valid Content-Length header |
| 1919 | | field unless the server is known to be HTTP/1.1 compliant. If a |
| 1920 | | request contains a message-body and a Content-Length is not given, |
| 1921 | | the server &SHOULD; respond with 400 (bad request) if it cannot |
| 1922 | | determine the length of the message, or with 411 (length required) if |
| 1923 | | it wishes to insist on receiving a valid Content-Length. |
| 1924 | | </t> |
| 1925 | | <t> |
| 1926 | | All HTTP/1.1 applications that receive entities &MUST; accept the |
| 1927 | | "chunked" transfer-coding (<xref target="transfer.codings"/>), thus allowing this mechanism |
| 1928 | | to be used for messages when the message length cannot be determined |
| 1929 | | in advance. |
| 1930 | | </t> |
| 1931 | | <t> |
| 1932 | | Messages &MUST-NOT; include both a Content-Length header field and a |
| 1933 | | non-identity transfer-coding. If the message does include a non-identity |
| 1934 | | transfer-coding, the Content-Length &MUST; be ignored. |
| 1935 | | </t> |
| 1936 | | <t> |
| 1937 | | When a Content-Length is given in a message where a message-body is |
| 1938 | | allowed, its field value &MUST; exactly match the number of OCTETs in |
| 1939 | | the message-body. HTTP/1.1 user agents &MUST; notify the user when an |
| 1940 | | invalid length is received and detected. |
| 1941 | | </t> |
| 1942 | | </section> |
| 1943 | | |
| 1944 | | <section title="General Header Fields" anchor="general.header.fields"> |
| 1945 | | <t> |
| 1946 | | There are a few header fields which have general applicability for |
| 1947 | | both request and response messages, but which do not apply to the |
| 1948 | | entity being transferred. These header fields apply only to the |
| 1949 | | message being transmitted. |
| 1950 | | </t> |
| 1951 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="general-header"/> |
| 1952 | | general-header = Cache-Control ; <xref target="header.cache-control"/> |
| 1953 | | | Connection ; <xref target="header.connection"/> |
| 1954 | | | Date ; <xref target="header.date"/> |
| 1955 | | | Pragma ; <xref target="header.pragma"/> |
| 1956 | | | Trailer ; <xref target="header.trailer"/> |
| 1957 | | | Transfer-Encoding ; <xref target="header.transfer-encoding"/> |
| 1958 | | | Upgrade ; <xref target="header.upgrade"/> |
| 1959 | | | Via ; <xref target="header.via"/> |
| 1960 | | | Warning ; <xref target="header.warning"/> |
| 1961 | | </artwork></figure> |
| 1962 | | <t> |
| 1963 | | General-header field names can be extended reliably only in |
| 1964 | | combination with a change in the protocol version. However, new or |
| 1965 | | experimental header fields may be given the semantics of general |
| 1966 | | header fields if all parties in the communication recognize them to |
| 1967 | | be general-header fields. Unrecognized header fields are treated as |
| 1968 | | entity-header fields. |
| 1969 | | </t> |
| 1970 | | </section> |
| 1971 | | </section> |
| 1972 | | |
| 1973 | | <section title="Request" anchor="request"> |
| 1974 | | <t> |
| 1975 | | A request message from a client to a server includes, within the |
| 1976 | | first line of that message, the method to be applied to the resource, |
| 1977 | | the identifier of the resource, and the protocol version in use. |
| 1978 | | </t> |
| 1979 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Request"/> |
| 1980 | | Request = Request-Line ; <xref target="request-line"/> |
| 1981 | | *(( general-header ; <xref target="general.header.fields"/> |
| 1982 | | | request-header ; <xref target="request.header.fields"/> |
| 1983 | | | entity-header ) CRLF) ; <xref target="entity.header.fields"/> |
| 1984 | | CRLF |
| 1985 | | [ message-body ] ; <xref target="message.body"/> |
| 1986 | | </artwork></figure> |
| 1987 | | |
| 1988 | | <section title="Request-Line" anchor="request-line"> |
| 1989 | | <t> |
| 1990 | | The Request-Line begins with a method token, followed by the |
| 1991 | | Request-URI and the protocol version, and ending with CRLF. The |
| 1992 | | elements are separated by SP characters. No CR or LF is allowed |
| 1993 | | except in the final CRLF sequence. |
| 1994 | | </t> |
| 1995 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Request-Line"/> |
| 1996 | | Request-Line = Method SP Request-URI SP HTTP-Version CRLF |
| 1997 | | </artwork></figure> |
| 2411 | | |
| 2412 | | <section title="Type" anchor="type"> |
| 2413 | | <t> |
| 2414 | | When an entity-body is included with a message, the data type of that |
| 2415 | | body is determined via the header fields Content-Type and Content-Encoding. |
| 2416 | | These define a two-layer, ordered encoding model: |
| 2417 | | </t> |
| 2418 | | <figure><artwork type="example"> |
| 2419 | | entity-body := Content-Encoding( Content-Type( data ) ) |
| 2420 | | </artwork></figure> |
| 2421 | | <t> |
| 2422 | | Content-Type specifies the media type of the underlying data. |
| 2423 | | Content-Encoding may be used to indicate any additional content |
| 2424 | | codings applied to the data, usually for the purpose of data |
| 2425 | | compression, that are a property of the requested resource. There is |
| 2426 | | no default encoding. |
| 2427 | | </t> |
| 2428 | | <t> |
| 2429 | | Any HTTP/1.1 message containing an entity-body &SHOULD; include a |
| 2430 | | Content-Type header field defining the media type of that body. If |
| 2431 | | and only if the media type is not given by a Content-Type field, the |
| 2432 | | recipient &MAY; attempt to guess the media type via inspection of its |
| 2433 | | content and/or the name extension(s) of the URI used to identify the |
| 2434 | | resource. If the media type remains unknown, the recipient &SHOULD; |
| 2435 | | treat it as type "application/octet-stream". |
| 2436 | | </t> |
| 2437 | | </section> |
| 2438 | | |
| 2439 | | <section title="Entity Length" anchor="entity.length"> |
| 2440 | | <t> |
| 2441 | | The entity-length of a message is the length of the message-body |
| 2442 | | before any transfer-codings have been applied. <xref target="message.length"/> defines |
| 2443 | | how the transfer-length of a message-body is determined. |
| 2444 | | </t> |
| 2445 | | </section> |
| 2446 | | </section> |
| 2447 | | </section> |
| 2448 | | |
| 2449 | | |
| 2450 | | |
| 2451 | | <section title="Connections" anchor="connections"> |
| 2452 | | |
| 2453 | | <section title="Persistent Connections" anchor="persistent.connections"> |
| 2454 | | |
| 2455 | | <section title="Purpose" anchor="persistent.purpose"> |
| 2456 | | <t> |
| 2457 | | Prior to persistent connections, a separate TCP connection was |
| 2458 | | established to fetch each URL, increasing the load on HTTP servers |
| 2459 | | and causing congestion on the Internet. The use of inline images and |
| 2460 | | other associated data often require a client to make multiple |
| 2461 | | requests of the same server in a short amount of time. Analysis of |
| 2462 | | these performance problems and results from a prototype |
| 2463 | | implementation are available <xref target="Pad1995"/> <xref target="Spe"/>. Implementation experience and |
| 2464 | | measurements of actual HTTP/1.1 (RFC 2068) implementations show good |
| 2465 | | results <xref target="Nie1997"/>. Alternatives have also been explored, for example, |
| 2466 | | T/TCP <xref target="Tou1998"/>. |
| 2467 | | </t> |
| 2468 | | <t> |
| 2469 | | Persistent HTTP connections have a number of advantages: |
| 2470 | | <list style="symbols"> |
| 2471 | | <t> |
| 2472 | | By opening and closing fewer TCP connections, CPU time is saved |
| 2473 | | in routers and hosts (clients, servers, proxies, gateways, |
| 2474 | | tunnels, or caches), and memory used for TCP protocol control |
| 2475 | | blocks can be saved in hosts. |
| 2476 | | </t> |
| 2477 | | <t> |
| 2478 | | HTTP requests and responses can be pipelined on a connection. |
| 2479 | | Pipelining allows a client to make multiple requests without |
| 2480 | | waiting for each response, allowing a single TCP connection to |
| 2481 | | be used much more efficiently, with much lower elapsed time. |
| 2482 | | </t> |
| 2483 | | <t> |
| 2484 | | Network congestion is reduced by reducing the number of packets |
| 2485 | | caused by TCP opens, and by allowing TCP sufficient time to |
| 2486 | | determine the congestion state of the network. |
| 2487 | | </t> |
| 2488 | | <t> |
| 2489 | | Latency on subsequent requests is reduced since there is no time |
| 2490 | | spent in TCP's connection opening handshake. |
| 2491 | | </t> |
| 2492 | | <t> |
| 2493 | | HTTP can evolve more gracefully, since errors can be reported |
| 2494 | | without the penalty of closing the TCP connection. Clients using |
| 2495 | | future versions of HTTP might optimistically try a new feature, |
| 2496 | | but if communicating with an older server, retry with old |
| 2497 | | semantics after an error is reported. |
| 2498 | | </t> |
| 2499 | | </list> |
| 2500 | | </t> |
| 2501 | | <t> |
| 2502 | | HTTP implementations &SHOULD; implement persistent connections. |
| 2503 | | </t> |
| 2504 | | </section> |
| 2505 | | |
| 2506 | | <section title="Overall Operation" anchor="persistent.overall"> |
| 2507 | | <t> |
| 2508 | | A significant difference between HTTP/1.1 and earlier versions of |
| 2509 | | HTTP is that persistent connections are the default behavior of any |
| 2510 | | HTTP connection. That is, unless otherwise indicated, the client |
| 2511 | | &SHOULD; assume that the server will maintain a persistent connection, |
| 2512 | | even after error responses from the server. |
| 2513 | | </t> |
| 2514 | | <t> |
| 2515 | | Persistent connections provide a mechanism by which a client and a |
| 2516 | | server can signal the close of a TCP connection. This signaling takes |
| 2517 | | place using the Connection header field (<xref target="header.connection"/>). Once a close |
| 2518 | | has been signaled, the client &MUST-NOT; send any more requests on that |
| 2519 | | connection. |
| 2520 | | </t> |
| 2521 | | |
| 2522 | | <section title="Negotiation" anchor="persistent.negotiation"> |
| 2523 | | <t> |
| 2524 | | An HTTP/1.1 server &MAY; assume that a HTTP/1.1 client intends to |
| 2525 | | maintain a persistent connection unless a Connection header including |
| 2526 | | the connection-token "close" was sent in the request. If the server |
| 2527 | | chooses to close the connection immediately after sending the |
| 2528 | | response, it &SHOULD; send a Connection header including the |
| 2529 | | connection-token close. |
| 2530 | | </t> |
| 2531 | | <t> |
| 2532 | | An HTTP/1.1 client &MAY; expect a connection to remain open, but would |
| 2533 | | decide to keep it open based on whether the response from a server |
| 2534 | | contains a Connection header with the connection-token close. In case |
| 2535 | | the client does not want to maintain a connection for more than that |
| 2536 | | request, it &SHOULD; send a Connection header including the |
| 2537 | | connection-token close. |
| 2538 | | </t> |
| 2539 | | <t> |
| 2540 | | If either the client or the server sends the close token in the |
| 2541 | | Connection header, that request becomes the last one for the |
| 2542 | | connection. |
| 2543 | | </t> |
| 2544 | | <t> |
| 2545 | | Clients and servers &SHOULD-NOT; assume that a persistent connection is |
| 2546 | | maintained for HTTP versions less than 1.1 unless it is explicitly |
| 2547 | | signaled. See <xref target="compatibility.with.http.1.0.persistent.connections"/> for more information on backward |
| 2548 | | compatibility with HTTP/1.0 clients. |
| 2549 | | </t> |
| 2550 | | <t> |
| 2551 | | In order to remain persistent, all messages on the connection &MUST; |
| 2552 | | have a self-defined message length (i.e., one not defined by closure |
| 2553 | | of the connection), as described in <xref target="message.length"/>. |
| 2554 | | </t> |
| 2555 | | </section> |
| 2556 | | |
| 2557 | | <section title="Pipelining" anchor="pipelining"> |
| 2558 | | <t> |
| 2559 | | A client that supports persistent connections &MAY; "pipeline" its |
| 2560 | | requests (i.e., send multiple requests without waiting for each |
| 2561 | | response). A server &MUST; send its responses to those requests in the |
| 2562 | | same order that the requests were received. |
| 2563 | | </t> |
| 2564 | | <t> |
| 2565 | | Clients which assume persistent connections and pipeline immediately |
| 2566 | | after connection establishment &SHOULD; be prepared to retry their |
| 2567 | | connection if the first pipelined attempt fails. If a client does |
| 2568 | | such a retry, it &MUST-NOT; pipeline before it knows the connection is |
| 2569 | | persistent. Clients &MUST; also be prepared to resend their requests if |
| 2570 | | the server closes the connection before sending all of the |
| 2571 | | corresponding responses. |
| 2572 | | </t> |
| 2573 | | <t> |
| 2574 | | Clients &SHOULD-NOT; pipeline requests using non-idempotent methods or |
| 2575 | | non-idempotent sequences of methods (see <xref target="idempotent.methods"/>). Otherwise, a |
| 2576 | | premature termination of the transport connection could lead to |
| 2577 | | indeterminate results. A client wishing to send a non-idempotent |
| 2578 | | request &SHOULD; wait to send that request until it has received the |
| 2579 | | response status for the previous request. |
| 2580 | | </t> |
| 2581 | | </section> |
| 2582 | | </section> |
| 2583 | | |
| 2584 | | <section title="Proxy Servers" anchor="persistent.proxy"> |
| 2585 | | <t> |
| 2586 | | It is especially important that proxies correctly implement the |
| 2587 | | properties of the Connection header field as specified in <xref target="header.connection"/>. |
| 2588 | | </t> |
| 2589 | | <t> |
| 2590 | | The proxy server &MUST; signal persistent connections separately with |
| 2591 | | its clients and the origin servers (or other proxy servers) that it |
| 2592 | | connects to. Each persistent connection applies to only one transport |
| 2593 | | link. |
| 2594 | | </t> |
| 2595 | | <t> |
| 2596 | | A proxy server &MUST-NOT; establish a HTTP/1.1 persistent connection |
| 2597 | | with an HTTP/1.0 client (but see RFC 2068 <xref target="RFC2068"/> for information and |
| 2598 | | discussion of the problems with the Keep-Alive header implemented by |
| 2599 | | many HTTP/1.0 clients). |
| 2600 | | </t> |
| 2601 | | </section> |
| 2602 | | |
| 2603 | | <section title="Practical Considerations" anchor="persistent.practical"> |
| 2604 | | <t> |
| 2605 | | Servers will usually have some time-out value beyond which they will |
| 2606 | | no longer maintain an inactive connection. Proxy servers might make |
| 2607 | | this a higher value since it is likely that the client will be making |
| 2608 | | more connections through the same server. The use of persistent |
| 2609 | | connections places no requirements on the length (or existence) of |
| 2610 | | this time-out for either the client or the server. |
| 2611 | | </t> |
| 2612 | | <t> |
| 2613 | | When a client or server wishes to time-out it &SHOULD; issue a graceful |
| 2614 | | close on the transport connection. Clients and servers &SHOULD; both |
| 2615 | | constantly watch for the other side of the transport close, and |
| 2616 | | respond to it as appropriate. If a client or server does not detect |
| 2617 | | the other side's close promptly it could cause unnecessary resource |
| 2618 | | drain on the network. |
| 2619 | | </t> |
| 2620 | | <t> |
| 2621 | | A client, server, or proxy &MAY; close the transport connection at any |
| 2622 | | time. For example, a client might have started to send a new request |
| 2623 | | at the same time that the server has decided to close the "idle" |
| 2624 | | connection. From the server's point of view, the connection is being |
| 2625 | | closed while it was idle, but from the client's point of view, a |
| 2626 | | request is in progress. |
| 2627 | | </t> |
| 2628 | | <t> |
| 2629 | | This means that clients, servers, and proxies &MUST; be able to recover |
| 2630 | | from asynchronous close events. Client software &SHOULD; reopen the |
| 2631 | | transport connection and retransmit the aborted sequence of requests |
| 2632 | | without user interaction so long as the request sequence is |
| 2633 | | idempotent (see <xref target="idempotent.methods"/>). Non-idempotent methods or sequences |
| 2634 | | &MUST-NOT; be automatically retried, although user agents &MAY; offer a |
| 2635 | | human operator the choice of retrying the request(s). Confirmation by |
| 2636 | | user-agent software with semantic understanding of the application |
| 2637 | | &MAY; substitute for user confirmation. The automatic retry &SHOULD-NOT; |
| 2638 | | be repeated if the second sequence of requests fails. |
| 2639 | | </t> |
| 2640 | | <t> |
| 2641 | | Servers &SHOULD; always respond to at least one request per connection, |
| 2642 | | if at all possible. Servers &SHOULD-NOT; close a connection in the |
| 2643 | | middle of transmitting a response, unless a network or client failure |
| 2644 | | is suspected. |
| 2645 | | </t> |
| 2646 | | <t> |
| 2647 | | Clients that use persistent connections &SHOULD; limit the number of |
| 2648 | | simultaneous connections that they maintain to a given server. A |
| 2649 | | single-user client &SHOULD-NOT; maintain more than 2 connections with |
| 2650 | | any server or proxy. A proxy &SHOULD; use up to 2*N connections to |
| 2651 | | another server or proxy, where N is the number of simultaneously |
| 2652 | | active users. These guidelines are intended to improve HTTP response |
| 2653 | | times and avoid congestion. |
| 2654 | | </t> |
| 2655 | | </section> |
| 2656 | | </section> |
| 2657 | | |
| 2658 | | <section title="Message Transmission Requirements" anchor="message.transmission.requirements"> |
| 2659 | | |
| 2660 | | <section title="Persistent Connections and Flow Control" anchor="persistent.flow"> |
| 2661 | | <t> |
| 2662 | | HTTP/1.1 servers &SHOULD; maintain persistent connections and use TCP's |
| 2663 | | flow control mechanisms to resolve temporary overloads, rather than |
| 2664 | | terminating connections with the expectation that clients will retry. |
| 2665 | | The latter technique can exacerbate network congestion. |
| 2666 | | </t> |
| 2667 | | </section> |
| 2668 | | |
| 2669 | | <section title="Monitoring Connections for Error Status Messages" anchor="persistent.monitor"> |
| 2670 | | <t> |
| 2671 | | An HTTP/1.1 (or later) client sending a message-body &SHOULD; monitor |
| 2672 | | the network connection for an error status while it is transmitting |
| 2673 | | the request. If the client sees an error status, it &SHOULD; |
| 2674 | | immediately cease transmitting the body. If the body is being sent |
| 2675 | | using a "chunked" encoding (<xref target="transfer.codings"/>), a zero length chunk and |
| 2676 | | empty trailer &MAY; be used to prematurely mark the end of the message. |
| 2677 | | If the body was preceded by a Content-Length header, the client &MUST; |
| 2678 | | close the connection. |
| 2679 | | </t> |
| 2680 | | </section> |
| 2681 | | |
| 2682 | | <section title="Use of the 100 (Continue) Status" anchor="use.of.the.100.status"> |
| 2683 | | <t> |
| 2684 | | The purpose of the 100 (Continue) status (see <xref target="status.100"/>) is to |
| 2685 | | allow a client that is sending a request message with a request body |
| 2686 | | to determine if the origin server is willing to accept the request |
| 2687 | | (based on the request headers) before the client sends the request |
| 2688 | | body. In some cases, it might either be inappropriate or highly |
| 2689 | | inefficient for the client to send the body if the server will reject |
| 2690 | | the message without looking at the body. |
| 2691 | | </t> |
| 2692 | | <t> |
| 2693 | | Requirements for HTTP/1.1 clients: |
| 2694 | | <list style="symbols"> |
| 2695 | | <t> |
| 2696 | | If a client will wait for a 100 (Continue) response before |
| 2697 | | sending the request body, it &MUST; send an Expect request-header |
| 2698 | | field (<xref target="header.expect"/>) with the "100-continue" expectation. |
| 2699 | | </t> |
| 2700 | | <t> |
| 2701 | | A client &MUST-NOT; send an Expect request-header field (<xref target="header.expect"/>) |
| 2702 | | with the "100-continue" expectation if it does not intend |
| 2703 | | to send a request body. |
| 2704 | | </t> |
| 2705 | | </list> |
| 2706 | | </t> |
| 2707 | | <t> |
| 2708 | | Because of the presence of older implementations, the protocol allows |
| 2709 | | ambiguous situations in which a client may send "Expect: 100-continue" |
| 2710 | | without receiving either a 417 (Expectation Failed) status |
| 2711 | | or a 100 (Continue) status. Therefore, when a client sends this |
| 2712 | | header field to an origin server (possibly via a proxy) from which it |
| 2713 | | has never seen a 100 (Continue) status, the client &SHOULD-NOT; wait |
| 2714 | | for an indefinite period before sending the request body. |
| 2715 | | </t> |
| 2716 | | <t> |
| 2717 | | Requirements for HTTP/1.1 origin servers: |
| 2718 | | <list style="symbols"> |
| 2719 | | <t> Upon receiving a request which includes an Expect request-header |
| 2720 | | field with the "100-continue" expectation, an origin server &MUST; |
| 2721 | | either respond with 100 (Continue) status and continue to read |
| 2722 | | from the input stream, or respond with a final status code. The |
| 2723 | | origin server &MUST-NOT; wait for the request body before sending |
| 2724 | | the 100 (Continue) response. If it responds with a final status |
| 2725 | | code, it &MAY; close the transport connection or it &MAY; continue |
| 2726 | | to read and discard the rest of the request. It &MUST-NOT; |
| 2727 | | perform the requested method if it returns a final status code. |
| 2728 | | </t> |
| 2729 | | <t> An origin server &SHOULD-NOT; send a 100 (Continue) response if |
| 2730 | | the request message does not include an Expect request-header |
| 2731 | | field with the "100-continue" expectation, and &MUST-NOT; send a |
| 2732 | | 100 (Continue) response if such a request comes from an HTTP/1.0 |
| 2733 | | (or earlier) client. There is an exception to this rule: for |
| 2734 | | compatibility with RFC 2068, a server &MAY; send a 100 (Continue) |
| 2735 | | status in response to an HTTP/1.1 PUT or POST request that does |
| 2736 | | not include an Expect request-header field with the "100-continue" |
| 2737 | | expectation. This exception, the purpose of which is |
| 2738 | | to minimize any client processing delays associated with an |
| 2739 | | undeclared wait for 100 (Continue) status, applies only to |
| 2740 | | HTTP/1.1 requests, and not to requests with any other HTTP-version |
| 2741 | | value. |
| 2742 | | </t> |
| 2743 | | <t> An origin server &MAY; omit a 100 (Continue) response if it has |
| 2744 | | already received some or all of the request body for the |
| 2745 | | corresponding request. |
| 2746 | | </t> |
| 2747 | | <t> An origin server that sends a 100 (Continue) response &MUST; |
| 2748 | | ultimately send a final status code, once the request body is |
| 2749 | | received and processed, unless it terminates the transport |
| 2750 | | connection prematurely. |
| 2751 | | </t> |
| 2752 | | <t> If an origin server receives a request that does not include an |
| 2753 | | Expect request-header field with the "100-continue" expectation, |
| 2754 | | the request includes a request body, and the server responds |
| 2755 | | with a final status code before reading the entire request body |
| 2756 | | from the transport connection, then the server &SHOULD-NOT; close |
| 2757 | | the transport connection until it has read the entire request, |
| 2758 | | or until the client closes the connection. Otherwise, the client |
| 2759 | | might not reliably receive the response message. However, this |
| 2760 | | requirement is not be construed as preventing a server from |
| 2761 | | defending itself against denial-of-service attacks, or from |
| 2762 | | badly broken client implementations. |
| 2763 | | </t> |
| 2764 | | </list> |
| 2765 | | </t> |
| 2766 | | <t> |
| 2767 | | Requirements for HTTP/1.1 proxies: |
| 2768 | | <list style="symbols"> |
| 2769 | | <t> If a proxy receives a request that includes an Expect request-header |
| 2770 | | field with the "100-continue" expectation, and the proxy |
| 2771 | | either knows that the next-hop server complies with HTTP/1.1 or |
| 2772 | | higher, or does not know the HTTP version of the next-hop |
| 2773 | | server, it &MUST; forward the request, including the Expect header |
| 2774 | | field. |
| 2775 | | </t> |
| 2776 | | <t> If the proxy knows that the version of the next-hop server is |
| 2777 | | HTTP/1.0 or lower, it &MUST-NOT; forward the request, and it &MUST; |
| 2778 | | respond with a 417 (Expectation Failed) status. |
| 2779 | | </t> |
| 2780 | | <t> Proxies &SHOULD; maintain a cache recording the HTTP version |
| 2781 | | numbers received from recently-referenced next-hop servers. |
| 2782 | | </t> |
| 2783 | | <t> A proxy &MUST-NOT; forward a 100 (Continue) response if the |
| 2784 | | request message was received from an HTTP/1.0 (or earlier) |
| 2785 | | client and did not include an Expect request-header field with |
| 2786 | | the "100-continue" expectation. This requirement overrides the |
| 2787 | | general rule for forwarding of 1xx responses (see <xref target="status.1xx"/>). |
| 2788 | | </t> |
| 2789 | | </list> |
| 2790 | | </t> |
| 2791 | | </section> |
| 2792 | | |
| 2793 | | <section title="Client Behavior if Server Prematurely Closes Connection" anchor="connection.premature"> |
| 2794 | | <t> |
| 2795 | | If an HTTP/1.1 client sends a request which includes a request body, |
| 2796 | | but which does not include an Expect request-header field with the |
| 2797 | | "100-continue" expectation, and if the client is not directly |
| 2798 | | connected to an HTTP/1.1 origin server, and if the client sees the |
| 2799 | | connection close before receiving any status from the server, the |
| 2800 | | client &SHOULD; retry the request. If the client does retry this |
| 2801 | | request, it &MAY; use the following "binary exponential backoff" |
| 2802 | | algorithm to be assured of obtaining a reliable response: |
| 2803 | | <list style="numbers"> |
| 2804 | | <t> |
| 2805 | | Initiate a new connection to the server |
| 2806 | | </t> |
| 2807 | | <t> |
| 2808 | | Transmit the request-headers |
| 2809 | | </t> |
| 2810 | | <t> |
| 2811 | | Initialize a variable R to the estimated round-trip time to the |
| 2812 | | server (e.g., based on the time it took to establish the |
| 2813 | | connection), or to a constant value of 5 seconds if the round-trip |
| 2814 | | time is not available. |
| 2815 | | </t> |
| 2816 | | <t> |
| 2817 | | Compute T = R * (2**N), where N is the number of previous |
| 2818 | | retries of this request. |
| 2819 | | </t> |
| 2820 | | <t> |
| 2821 | | Wait either for an error response from the server, or for T |
| 2822 | | seconds (whichever comes first) |
| 2823 | | </t> |
| 2824 | | <t> |
| 2825 | | If no error response is received, after T seconds transmit the |
| 2826 | | body of the request. |
| 2827 | | </t> |
| 2828 | | <t> |
| 2829 | | If client sees that the connection is closed prematurely, |
| 2830 | | repeat from step 1 until the request is accepted, an error |
| 2831 | | response is received, or the user becomes impatient and |
| 2832 | | terminates the retry process. |
| 2833 | | </t> |
| 2834 | | </list> |
| 2835 | | </t> |
| 2836 | | <t> |
| 2837 | | If at any point an error status is received, the client |
| 2838 | | <list style="symbols"> |
| 2839 | | <t>&SHOULD-NOT; continue and</t> |
| 2840 | | |
| 2841 | | <t>&SHOULD; close the connection if it has not completed sending the |
| 2842 | | request message.</t> |
| 2843 | | </list> |
| 2844 | | </t> |
| 2845 | | </section> |
| 2846 | | </section> |
| 2847 | | </section> |
| 2848 | | |
| | 437 | </section> |
| 4103 | | |
| 4104 | | |
| 4105 | | <section title="Access Authentication" anchor="access.authentication"> |
| 4106 | | <t> |
| 4107 | | HTTP provides several &OPTIONAL; challenge-response authentication |
| 4108 | | |
| 4109 | | mechanisms which can be used by a server to challenge a client |
| 4110 | | request and by a client to provide authentication information. The |
| 4111 | | general framework for access authentication, and the specification of |
| 4112 | | "basic" and "digest" authentication, are specified in "HTTP |
| 4113 | | Authentication: Basic and Digest Access Authentication" <xref target="RFC2617"/>. This |
| 4114 | | specification adopts the definitions of "challenge" and "credentials" |
| 4115 | | from that specification. |
| 4116 | | </t> |
| 4117 | | </section> |
| 4118 | | |
| 4119 | | <section title="Content Negotiation" anchor="content.negotiation"> |
| 4120 | | <t> |
| 4121 | | Most HTTP responses include an entity which contains information for |
| 4122 | | interpretation by a human user. Naturally, it is desirable to supply |
| 4123 | | the user with the "best available" entity corresponding to the |
| 4124 | | request. Unfortunately for servers and caches, not all users have the |
| 4125 | | same preferences for what is "best," and not all user agents are |
| 4126 | | equally capable of rendering all entity types. For that reason, HTTP |
| 4127 | | has provisions for several mechanisms for "content negotiation" -- |
| 4128 | | the process of selecting the best representation for a given response |
| 4129 | | when there are multiple representations available. |
| 4130 | | <list><t> |
| 4131 | | <x:h>Note:</x:h> This is not called "format negotiation" because the |
| 4132 | | alternate representations may be of the same media type, but use |
| 4133 | | different capabilities of that type, be in different languages, |
| 4134 | | etc. |
| 4135 | | </t></list> |
| 4136 | | </t> |
| 4137 | | <t> |
| 4138 | | Any response containing an entity-body &MAY; be subject to negotiation, |
| 4139 | | including error responses. |
| 4140 | | </t> |
| 4141 | | <t> |
| 4142 | | There are two kinds of content negotiation which are possible in |
| 4143 | | HTTP: server-driven and agent-driven negotiation. These two kinds of |
| 4144 | | negotiation are orthogonal and thus may be used separately or in |
| 4145 | | combination. One method of combination, referred to as transparent |
| 4146 | | negotiation, occurs when a cache uses the agent-driven negotiation |
| 4147 | | information provided by the origin server in order to provide |
| 4148 | | server-driven negotiation for subsequent requests. |
| 4149 | | </t> |
| 4150 | | |
| 4151 | | <section title="Server-driven Negotiation" anchor="server-driven.negotiation"> |
| 4152 | | <t> |
| 4153 | | If the selection of the best representation for a response is made by |
| 4154 | | an algorithm located at the server, it is called server-driven |
| 4155 | | negotiation. Selection is based on the available representations of |
| 4156 | | the response (the dimensions over which it can vary; e.g. language, |
| 4157 | | content-coding, etc.) and the contents of particular header fields in |
| 4158 | | the request message or on other information pertaining to the request |
| 4159 | | (such as the network address of the client). |
| 4160 | | </t> |
| 4161 | | <t> |
| 4162 | | Server-driven negotiation is advantageous when the algorithm for |
| 4163 | | selecting from among the available representations is difficult to |
| 4164 | | describe to the user agent, or when the server desires to send its |
| 4165 | | "best guess" to the client along with the first response (hoping to |
| 4166 | | avoid the round-trip delay of a subsequent request if the "best |
| 4167 | | guess" is good enough for the user). In order to improve the server's |
| 4168 | | guess, the user agent &MAY; include request header fields (Accept, |
| 4169 | | Accept-Language, Accept-Encoding, etc.) which describe its |
| 4170 | | preferences for such a response. |
| 4171 | | </t> |
| 4172 | | <t> |
| 4173 | | Server-driven negotiation has disadvantages: |
| 4174 | | <list style="numbers"> |
| 4175 | | <t> |
| 4176 | | It is impossible for the server to accurately determine what |
| 4177 | | might be "best" for any given user, since that would require |
| 4178 | | complete knowledge of both the capabilities of the user agent |
| 4179 | | and the intended use for the response (e.g., does the user want |
| 4180 | | to view it on screen or print it on paper?). |
| 4181 | | </t> |
| 4182 | | <t> |
| 4183 | | Having the user agent describe its capabilities in every |
| 4184 | | request can be both very inefficient (given that only a small |
| 4185 | | percentage of responses have multiple representations) and a |
| 4186 | | potential violation of the user's privacy. |
| 4187 | | </t> |
| 4188 | | <t> |
| 4189 | | It complicates the implementation of an origin server and the |
| 4190 | | algorithms for generating responses to a request. |
| 4191 | | </t> |
| 4192 | | <t> |
| 4193 | | It may limit a public cache's ability to use the same response |
| 4194 | | for multiple user's requests. |
| 4195 | | </t> |
| 4196 | | </list> |
| 4197 | | </t> |
| 4198 | | <t> |
| 4199 | | HTTP/1.1 includes the following request-header fields for enabling |
| 4200 | | server-driven negotiation through description of user agent |
| 4201 | | capabilities and user preferences: Accept (<xref target="header.accept"/>), Accept-Charset |
| 4202 | | (<xref target="header.accept-charset"/>), Accept-Encoding (<xref target="header.accept-encoding"/>), Accept-Language |
| 4203 | | (<xref target="header.accept-language"/>), and User-Agent (<xref target="header.user-agent"/>). However, an |
| 4204 | | origin server is not limited to these dimensions and &MAY; vary the |
| 4205 | | response based on any aspect of the request, including information |
| 4206 | | outside the request-header fields or within extension header fields |
| 4207 | | not defined by this specification. |
| 4208 | | </t> |
| 4209 | | <t> |
| 4210 | | The Vary header field can be used to express the parameters the |
| 4211 | | server uses to select a representation that is subject to server-driven |
| 4212 | | negotiation. See <xref target="caching.negotiated.responses"/> for use of the Vary header field |
| 4213 | | by caches and <xref target="header.vary"/> for use of the Vary header field by |
| 4214 | | servers. |
| 4215 | | </t> |
| 4216 | | </section> |
| 4217 | | |
| 4218 | | <section title="Agent-driven Negotiation" anchor="agent-driven.negotiation"> |
| 4219 | | <t> |
| 4220 | | With agent-driven negotiation, selection of the best representation |
| 4221 | | for a response is performed by the user agent after receiving an |
| 4222 | | initial response from the origin server. Selection is based on a list |
| 4223 | | of the available representations of the response included within the |
| 4224 | | header fields or entity-body of the initial response, with each |
| 4225 | | representation identified by its own URI. Selection from among the |
| 4226 | | representations may be performed automatically (if the user agent is |
| 4227 | | capable of doing so) or manually by the user selecting from a |
| 4228 | | generated (possibly hypertext) menu. |
| 4229 | | </t> |
| 4230 | | <t> |
| 4231 | | Agent-driven negotiation is advantageous when the response would vary |
| 4232 | | over commonly-used dimensions (such as type, language, or encoding), |
| 4233 | | when the origin server is unable to determine a user agent's |
| 4234 | | capabilities from examining the request, and generally when public |
| 4235 | | caches are used to distribute server load and reduce network usage. |
| 4236 | | </t> |
| 4237 | | <t> |
| 4238 | | Agent-driven negotiation suffers from the disadvantage of needing a |
| 4239 | | second request to obtain the best alternate representation. This |
| 4240 | | second request is only efficient when caching is used. In addition, |
| 4241 | | this specification does not define any mechanism for supporting |
| 4242 | | automatic selection, though it also does not prevent any such |
| 4243 | | mechanism from being developed as an extension and used within |
| 4244 | | HTTP/1.1. |
| 4245 | | </t> |
| 4246 | | <t> |
| 4247 | | HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) |
| 4248 | | status codes for enabling agent-driven negotiation when the server is |
| 4249 | | unwilling or unable to provide a varying response using server-driven |
| 4250 | | negotiation. |
| 4251 | | </t> |
| 4252 | | </section> |
| 4253 | | |
| 4254 | | <section title="Transparent Negotiation" anchor="transparent.negotiation"> |
| 4255 | | <t> |
| 4256 | | Transparent negotiation is a combination of both server-driven and |
| 4257 | | agent-driven negotiation. When a cache is supplied with a form of the |
| 4258 | | list of available representations of the response (as in agent-driven |
| 4259 | | negotiation) and the dimensions of variance are completely understood |
| 4260 | | by the cache, then the cache becomes capable of performing server-driven |
| 4261 | | negotiation on behalf of the origin server for subsequent |
| 4262 | | requests on that resource. |
| 4263 | | </t> |
| 4264 | | <t> |
| 4265 | | Transparent negotiation has the advantage of distributing the |
| 4266 | | negotiation work that would otherwise be required of the origin |
| 4267 | | server and also removing the second request delay of agent-driven |
| 4268 | | negotiation when the cache is able to correctly guess the right |
| 4269 | | response. |
| 4270 | | </t> |
| 4271 | | <t> |
| 4272 | | This specification does not define any mechanism for transparent |
| 4273 | | negotiation, though it also does not prevent any such mechanism from |
| 4274 | | being developed as an extension that could be used within HTTP/1.1. |
| 4275 | | </t> |
| 4276 | | </section> |
| 4277 | | </section> |
| 4278 | | |
| 4279 | | |
| 4280 | | <section title="Caching in HTTP" anchor="caching"> |
| 4281 | | |
| 4282 | | <t> |
| 4283 | | HTTP is typically used for distributed information systems, where |
| 4284 | | performance can be improved by the use of response caches. The |
| 4285 | | HTTP/1.1 protocol includes a number of elements intended to make |
| 4286 | | caching work as well as possible. Because these elements are |
| 4287 | | inextricable from other aspects of the protocol, and because they |
| 4288 | | interact with each other, it is useful to describe the basic caching |
| 4289 | | design of HTTP separately from the detailed descriptions of methods, |
| 4290 | | headers, response codes, etc. |
| 4291 | | </t> |
| 4292 | | <t> |
| 4293 | | Caching would be useless if it did not significantly improve |
| 4294 | | performance. The goal of caching in HTTP/1.1 is to eliminate the need |
| 4295 | | to send requests in many cases, and to eliminate the need to send |
| 4296 | | full responses in many other cases. The former reduces the number of |
| 4297 | | network round-trips required for many operations; we use an |
| 4298 | | "expiration" mechanism for this purpose (see <xref target="expiration.model"/>). The |
| 4299 | | latter reduces network bandwidth requirements; we use a "validation" |
| 4300 | | mechanism for this purpose (see <xref target="validation.model"/>). |
| 4301 | | </t> |
| 4302 | | <t> |
| 4303 | | Requirements for performance, availability, and disconnected |
| 4304 | | operation require us to be able to relax the goal of semantic |
| 4305 | | transparency. The HTTP/1.1 protocol allows origin servers, caches, |
| 4306 | | and clients to explicitly reduce transparency when necessary. |
| 4307 | | However, because non-transparent operation may confuse non-expert |
| 4308 | | users, and might be incompatible with certain server applications |
| 4309 | | (such as those for ordering merchandise), the protocol requires that |
| 4310 | | transparency be relaxed |
| 4311 | | <list style="symbols"> |
| 4312 | | <t>only by an explicit protocol-level request when relaxed by |
| 4313 | | client or origin server</t> |
| 4314 | | |
| 4315 | | <t>only with an explicit warning to the end user when relaxed by |
| 4316 | | cache or client</t> |
| 4317 | | </list> |
| 4318 | | </t> |
| 4319 | | <t> |
| 4320 | | Therefore, the HTTP/1.1 protocol provides these important elements: |
| 4321 | | <list style="numbers"> |
| 4322 | | <t>Protocol features that provide full semantic transparency when |
| 4323 | | this is required by all parties.</t> |
| 4324 | | |
| 4325 | | <t>Protocol features that allow an origin server or user agent to |
| 4326 | | explicitly request and control non-transparent operation.</t> |
| 4327 | | |
| 4328 | | <t>Protocol features that allow a cache to attach warnings to |
| 4329 | | responses that do not preserve the requested approximation of |
| 4330 | | semantic transparency.</t> |
| 4331 | | </list> |
| 4332 | | </t> |
| 4333 | | <t> |
| 4334 | | A basic principle is that it must be possible for the clients to |
| 4335 | | detect any potential relaxation of semantic transparency. |
| 4336 | | <list><t> |
| 4337 | | <x:h>Note:</x:h> The server, cache, or client implementor might be faced with |
| 4338 | | design decisions not explicitly discussed in this specification. |
| 4339 | | If a decision might affect semantic transparency, the implementor |
| 4340 | | ought to err on the side of maintaining transparency unless a |
| 4341 | | careful and complete analysis shows significant benefits in |
| 4342 | | breaking transparency. |
| 4343 | | </t></list> |
| 4344 | | </t> |
| 4345 | | |
| 4346 | | <section title=""> |
| 4347 | | |
| 4348 | | <section title="Cache Correctness" anchor="cache.correctness"> |
| 4349 | | <t> |
| 4350 | | A correct cache &MUST; respond to a request with the most up-to-date |
| 4351 | | response held by the cache that is appropriate to the request (see |
| 4352 | | sections <xref target="disambiguating.expiration.values" format="counter"/>, |
| 4353 | | <xref target="disambiguating.multiple.responses" format="counter"/>, |
| 4354 | | and <xref target="cache.replacement" format="counter"/>) which meets one of the following |
| 4355 | | conditions: |
| 4356 | | <list style="numbers"> |
| 4357 | | <t>It has been checked for equivalence with what the origin server |
| 4358 | | would have returned by revalidating the response with the |
| 4359 | | origin server (<xref target="validation.model"/>);</t> |
| 4360 | | |
| 4361 | | <t>It is "fresh enough" (see <xref target="expiration.model"/>). In the default case, |
| 4362 | | this means it meets the least restrictive freshness requirement |
| 4363 | | of the client, origin server, and cache (see <xref target="header.cache-control"/>); if |
| 4364 | | the origin server so specifies, it is the freshness requirement |
| 4365 | | of the origin server alone. |
| 4366 | | |
| 4367 | | If a stored response is not "fresh enough" by the most |
| 4368 | | restrictive freshness requirement of both the client and the |
| 4369 | | origin server, in carefully considered circumstances the cache |
| 4370 | | &MAY; still return the response with the appropriate Warning |
| 4371 | | header (see section <xref target="exceptions.to.the.rules.and.warnings" format="counter"/> |
| 4372 | | and <xref target="header.warning" format="counter"/>), unless such a response |
| 4373 | | is prohibited (e.g., by a "no-store" cache-directive, or by a |
| 4374 | | "no-cache" cache-request-directive; see <xref target="header.cache-control"/>).</t> |
| 4375 | | |
| 4376 | | <t>It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), |
| 4377 | | or error (4xx or 5xx) response message.</t> |
| 4378 | | </list> |
| 4379 | | </t> |
| 4380 | | <t> |
| 4381 | | If the cache can not communicate with the origin server, then a |
| 4382 | | correct cache &SHOULD; respond as above if the response can be |
| 4383 | | correctly served from the cache; if not it &MUST; return an error or |
| 4384 | | warning indicating that there was a communication failure. |
| 4385 | | </t> |
| 4386 | | <t> |
| 4387 | | If a cache receives a response (either an entire response, or a 304 |
| 4388 | | (Not Modified) response) that it would normally forward to the |
| 4389 | | requesting client, and the received response is no longer fresh, the |
| 4390 | | cache &SHOULD; forward it to the requesting client without adding a new |
| 4391 | | Warning (but without removing any existing Warning headers). A cache |
| 4392 | | &SHOULD-NOT; attempt to revalidate a response simply because that |
| 4393 | | response became stale in transit; this might lead to an infinite |
| 4394 | | loop. A user agent that receives a stale response without a Warning |
| 4395 | | &MAY; display a warning indication to the user. |
| 4396 | | </t> |
| 4397 | | </section> |
| 4398 | | |
| 4399 | | <section title="Warnings" anchor="warnings"> |
| 4400 | | <t> |
| 4401 | | Whenever a cache returns a response that is neither first-hand nor |
| 4402 | | "fresh enough" (in the sense of condition 2 in <xref target="cache.correctness"/>), it |
| 4403 | | &MUST; attach a warning to that effect, using a Warning general-header. |
| 4404 | | The Warning header and the currently defined warnings are described |
| 4405 | | in <xref target="header.warning"/>. The warning allows clients to take appropriate |
| 4406 | | action. |
| 4407 | | </t> |
| 4408 | | <t> |
| 4409 | | Warnings &MAY; be used for other purposes, both cache-related and |
| 4410 | | otherwise. The use of a warning, rather than an error status code, |
| 4411 | | distinguish these responses from true failures. |
| 4412 | | </t> |
| 4413 | | <t> |
| 4414 | | Warnings are assigned three digit warn-codes. The first digit |
| 4415 | | indicates whether the Warning &MUST; or &MUST-NOT; be deleted from a |
| 4416 | | stored cache entry after a successful revalidation: |
| 4417 | | </t> |
| 4418 | | <t> |
| 4419 | | <list style="hanging"> |
| 4420 | | <t hangText="1xx">Warnings that describe the freshness or revalidation status of |
| 4421 | | the response, and so &MUST; be deleted after a successful |
| 4422 | | revalidation. 1XX warn-codes &MAY; be generated by a cache only when |
| 4423 | | validating a cached entry. It &MUST-NOT; be generated by clients.</t> |
| 4424 | | |
| 4425 | | <t hangText="2xx">Warnings that describe some aspect of the entity body or entity |
| 4426 | | headers that is not rectified by a revalidation (for example, a |
| 4427 | | lossy compression of the entity bodies) and which &MUST-NOT; be |
| 4428 | | deleted after a successful revalidation.</t> |
| 4429 | | </list> |
| 4430 | | </t> |
| 4431 | | <t> |
| 4432 | | See <xref target="header.warning"/> for the definitions of the codes themselves. |
| 4433 | | </t> |
| 4434 | | <t> |
| 4435 | | HTTP/1.0 caches will cache all Warnings in responses, without |
| 4436 | | deleting the ones in the first category. Warnings in responses that |
| 4437 | | are passed to HTTP/1.0 caches carry an extra warning-date field, |
| 4438 | | which prevents a future HTTP/1.1 recipient from believing an |
| 4439 | | erroneously cached Warning. |
| 4440 | | </t> |
| 4441 | | <t> |
| 4442 | | Warnings also carry a warning text. The text &MAY; be in any |
| 4443 | | appropriate natural language (perhaps based on the client's Accept |
| 4444 | | headers), and include an &OPTIONAL; indication of what character set is |
| 4445 | | used. |
| 4446 | | </t> |
| 4447 | | <t> |
| 4448 | | Multiple warnings &MAY; be attached to a response (either by the origin |
| 4449 | | server or by a cache), including multiple warnings with the same code |
| 4450 | | number. For example, a server might provide the same warning with |
| 4451 | | texts in both English and Basque. |
| 4452 | | </t> |
| 4453 | | <t> |
| 4454 | | When multiple warnings are attached to a response, it might not be |
| 4455 | | practical or reasonable to display all of them to the user. This |
| 4456 | | version of HTTP does not specify strict priority rules for deciding |
| 4457 | | which warnings to display and in what order, but does suggest some |
| 4458 | | heuristics. |
| 4459 | | </t> |
| 4460 | | </section> |
| 4461 | | |
| 4462 | | <section title="Cache-control Mechanisms" anchor="cache-control.mechanisms"> |
| 4463 | | <t> |
| 4464 | | The basic cache mechanisms in HTTP/1.1 (server-specified expiration |
| 4465 | | times and validators) are implicit directives to caches. In some |
| 4466 | | cases, a server or client might need to provide explicit directives |
| 4467 | | to the HTTP caches. We use the Cache-Control header for this purpose. |
| 4468 | | </t> |
| 4469 | | <t> |
| 4470 | | The Cache-Control header allows a client or server to transmit a |
| 4471 | | variety of directives in either requests or responses. These |
| 4472 | | directives typically override the default caching algorithms. As a |
| 4473 | | general rule, if there is any apparent conflict between header |
| 4474 | | values, the most restrictive interpretation is applied (that is, the |
| 4475 | | one that is most likely to preserve semantic transparency). However, |
| 4476 | | in some cases, cache-control directives are explicitly specified as |
| 4477 | | weakening the approximation of semantic transparency (for example, |
| 4478 | | "max-stale" or "public"). |
| 4479 | | </t> |
| 4480 | | <t> |
| 4481 | | The cache-control directives are described in detail in <xref target="header.cache-control"/>. |
| 4482 | | </t> |
| 4483 | | </section> |
| 4484 | | |
| 4485 | | <section title="Explicit User Agent Warnings" anchor="explicit.ua.warnings"> |
| 4486 | | <t> |
| 4487 | | Many user agents make it possible for users to override the basic |
| 4488 | | caching mechanisms. For example, the user agent might allow the user |
| 4489 | | to specify that cached entities (even explicitly stale ones) are |
| 4490 | | never validated. Or the user agent might habitually add "Cache-Control: |
| 4491 | | max-stale=3600" to every request. The user agent &SHOULD-NOT; |
| 4492 | | default to either non-transparent behavior, or behavior that results |
| 4493 | | in abnormally ineffective caching, but &MAY; be explicitly configured |
| 4494 | | to do so by an explicit action of the user. |
| 4495 | | </t> |
| 4496 | | <t> |
| 4497 | | If the user has overridden the basic caching mechanisms, the user |
| 4498 | | agent &SHOULD; explicitly indicate to the user whenever this results in |
| 4499 | | the display of information that might not meet the server's |
| 4500 | | transparency requirements (in particular, if the displayed entity is |
| 4501 | | known to be stale). Since the protocol normally allows the user agent |
| 4502 | | to determine if responses are stale or not, this indication need only |
| 4503 | | be displayed when this actually happens. The indication need not be a |
| 4504 | | dialog box; it could be an icon (for example, a picture of a rotting |
| 4505 | | fish) or some other indicator. |
| 4506 | | </t> |
| 4507 | | <t> |
| 4508 | | If the user has overridden the caching mechanisms in a way that would |
| 4509 | | abnormally reduce the effectiveness of caches, the user agent &SHOULD; |
| 4510 | | continually indicate this state to the user (for example, by a |
| 4511 | | display of a picture of currency in flames) so that the user does not |
| 4512 | | inadvertently consume excess resources or suffer from excessive |
| 4513 | | latency. |
| 4514 | | </t> |
| 4515 | | </section> |
| 4516 | | |
| 4517 | | <section title="Exceptions to the Rules and Warnings" anchor="exceptions.to.the.rules.and.warnings"> |
| 4518 | | <t> |
| 4519 | | In some cases, the operator of a cache &MAY; choose to configure it to |
| 4520 | | return stale responses even when not requested by clients. This |
| 4521 | | decision ought not be made lightly, but may be necessary for reasons |
| 4522 | | of availability or performance, especially when the cache is poorly |
| 4523 | | connected to the origin server. Whenever a cache returns a stale |
| 4524 | | response, it &MUST; mark it as such (using a Warning header) enabling |
| 4525 | | the client software to alert the user that there might be a potential |
| 4526 | | problem. |
| 4527 | | </t> |
| 4528 | | <t> |
| 4529 | | It also allows the user agent to take steps to obtain a first-hand or |
| 4530 | | fresh response. For this reason, a cache &SHOULD-NOT; return a stale |
| 4531 | | response if the client explicitly requests a first-hand or fresh one, |
| 4532 | | unless it is impossible to comply for technical or policy reasons. |
| 4533 | | </t> |
| 4534 | | </section> |
| 4535 | | |
| 4536 | | <section title="Client-controlled Behavior" anchor="client-controlled.behavior"> |
| 4537 | | <t> |
| 4538 | | While the origin server (and to a lesser extent, intermediate caches, |
| 4539 | | by their contribution to the age of a response) are the primary |
| 4540 | | source of expiration information, in some cases the client might need |
| 4541 | | to control a cache's decision about whether to return a cached |
| 4542 | | response without validating it. Clients do this using several |
| 4543 | | directives of the Cache-Control header. |
| 4544 | | </t> |
| 4545 | | <t> |
| 4546 | | A client's request &MAY; specify the maximum age it is willing to |
| 4547 | | accept of an unvalidated response; specifying a value of zero forces |
| 4548 | | the cache(s) to revalidate all responses. A client &MAY; also specify |
| 4549 | | the minimum time remaining before a response expires. Both of these |
| 4550 | | options increase constraints on the behavior of caches, and so cannot |
| 4551 | | further relax the cache's approximation of semantic transparency. |
| 4552 | | </t> |
| 4553 | | <t> |
| 4554 | | A client &MAY; also specify that it will accept stale responses, up to |
| 4555 | | some maximum amount of staleness. This loosens the constraints on the |
| 4556 | | caches, and so might violate the origin server's specified |
| 4557 | | constraints on semantic transparency, but might be necessary to |
| 4558 | | support disconnected operation, or high availability in the face of |
| 4559 | | poor connectivity. |
| 4560 | | </t> |
| 4561 | | </section> |
| 4562 | | </section> |
| 4563 | | |
| 4564 | | <section title="Expiration Model" anchor="expiration.model"> |
| 4565 | | |
| 4566 | | <section title="Server-Specified Expiration" anchor="server-specified.expiration"> |
| 4567 | | <t> |
| 4568 | | HTTP caching works best when caches can entirely avoid making |
| 4569 | | requests to the origin server. The primary mechanism for avoiding |
| 4570 | | requests is for an origin server to provide an explicit expiration |
| 4571 | | time in the future, indicating that a response &MAY; be used to satisfy |
| 4572 | | subsequent requests. In other words, a cache can return a fresh |
| 4573 | | response without first contacting the server. |
| 4574 | | </t> |
| 4575 | | <t> |
| 4576 | | Our expectation is that servers will assign future explicit |
| 4577 | | expiration times to responses in the belief that the entity is not |
| 4578 | | likely to change, in a semantically significant way, before the |
| 4579 | | expiration time is reached. This normally preserves semantic |
| 4580 | | transparency, as long as the server's expiration times are carefully |
| 4581 | | chosen. |
| 4582 | | </t> |
| 4583 | | <t> |
| 4584 | | The expiration mechanism applies only to responses taken from a cache |
| 4585 | | and not to first-hand responses forwarded immediately to the |
| 4586 | | requesting client. |
| 4587 | | </t> |
| 4588 | | <t> |
| 4589 | | If an origin server wishes to force a semantically transparent cache |
| 4590 | | to validate every request, it &MAY; assign an explicit expiration time |
| 4591 | | in the past. This means that the response is always stale, and so the |
| 4592 | | cache &SHOULD; validate it before using it for subsequent requests. See |
| 4593 | | <xref target="cache.revalidation.and.reload.controls"/> for a more restrictive way to force revalidation. |
| 4594 | | </t> |
| 4595 | | <t> |
| 4596 | | If an origin server wishes to force any HTTP/1.1 cache, no matter how |
| 4597 | | it is configured, to validate every request, it &SHOULD; use the "must-revalidate" |
| 4598 | | cache-control directive (see <xref target="header.cache-control"/>). |
| 4599 | | </t> |
| 4600 | | <t> |
| 4601 | | Servers specify explicit expiration times using either the Expires |
| 4602 | | header, or the max-age directive of the Cache-Control header. |
| 4603 | | </t> |
| 4604 | | <t> |
| 4605 | | An expiration time cannot be used to force a user agent to refresh |
| 4606 | | its display or reload a resource; its semantics apply only to caching |
| 4607 | | mechanisms, and such mechanisms need only check a resource's |
| 4608 | | expiration status when a new request for that resource is initiated. |
| 4609 | | See <xref target="history.lists"/> for an explanation of the difference between caches |
| 4610 | | and history mechanisms. |
| 4611 | | </t> |
| 4612 | | </section> |
| 4613 | | |
| 4614 | | <section title="Heuristic Expiration" anchor="heuristic.expiration"> |
| 4615 | | <t> |
| 4616 | | Since origin servers do not always provide explicit expiration times, |
| 4617 | | HTTP caches typically assign heuristic expiration times, employing |
| 4618 | | algorithms that use other header values (such as the Last-Modified |
| 4619 | | time) to estimate a plausible expiration time. The HTTP/1.1 |
| 4620 | | specification does not provide specific algorithms, but does impose |
| 4621 | | worst-case constraints on their results. Since heuristic expiration |
| 4622 | | times might compromise semantic transparency, they ought to used |
| 4623 | | cautiously, and we encourage origin servers to provide explicit |
| 4624 | | expiration times as much as possible. |
| 4625 | | </t> |
| 4626 | | </section> |
| 4627 | | |
| 4628 | | <section title="Age Calculations" anchor="age.calculations"> |
| 4629 | | <t> |
| 4630 | | In order to know if a cached entry is fresh, a cache needs to know if |
| 4631 | | its age exceeds its freshness lifetime. We discuss how to calculate |
| 4632 | | the latter in <xref target="expiration.calculations"/>; this section describes how to calculate |
| 4633 | | the age of a response or cache entry. |
| 4634 | | </t> |
| 4635 | | <t> |
| 4636 | | In this discussion, we use the term "now" to mean "the current value |
| 4637 | | of the clock at the host performing the calculation." Hosts that use |
| 4638 | | HTTP, but especially hosts running origin servers and caches, &SHOULD; |
| 4639 | | use NTP <xref target="RFC1305"/> or some similar protocol to synchronize their clocks to |
| 4640 | | a globally accurate time standard. |
| 4641 | | </t> |
| 4642 | | <t> |
| 4643 | | HTTP/1.1 requires origin servers to send a Date header, if possible, |
| 4644 | | with every response, giving the time at which the response was |
| 4645 | | generated (see <xref target="header.date"/>). We use the term "date_value" to denote |
| 4646 | | the value of the Date header, in a form appropriate for arithmetic |
| 4647 | | operations. |
| 4648 | | </t> |
| 4649 | | <t> |
| 4650 | | HTTP/1.1 uses the Age response-header to convey the estimated age of |
| 4651 | | the response message when obtained from a cache. The Age field value |
| 4652 | | is the cache's estimate of the amount of time since the response was |
| 4653 | | generated or revalidated by the origin server. |
| 4654 | | </t> |
| 4655 | | <t> |
| 4656 | | In essence, the Age value is the sum of the time that the response |
| 4657 | | has been resident in each of the caches along the path from the |
| 4658 | | origin server, plus the amount of time it has been in transit along |
| 4659 | | network paths. |
| 4660 | | </t> |
| 4661 | | <t> |
| 4662 | | We use the term "age_value" to denote the value of the Age header, in |
| 4663 | | a form appropriate for arithmetic operations. |
| 4664 | | </t> |
| 4665 | | <t> |
| 4666 | | A response's age can be calculated in two entirely independent ways: |
| 4667 | | <list style="numbers"> |
| 4668 | | <t>now minus date_value, if the local clock is reasonably well |
| 4669 | | synchronized to the origin server's clock. If the result is |
| 4670 | | negative, the result is replaced by zero.</t> |
| 4671 | | |
| 4672 | | <t>age_value, if all of the caches along the response path |
| 4673 | | implement HTTP/1.1.</t> |
| 4674 | | </list> |
| 4675 | | </t> |
| 4676 | | <t> |
| 4677 | | Given that we have two independent ways to compute the age of a |
| 4678 | | response when it is received, we can combine these as |
| 4679 | | </t> |
| 4680 | | <figure><artwork type="code"> |
| 4681 | | corrected_received_age = max(now - date_value, age_value) |
| 4682 | | </artwork></figure> |
| 4683 | | <t> |
| 4684 | | and as long as we have either nearly synchronized clocks or all-HTTP/1.1 |
| 4685 | | paths, one gets a reliable (conservative) result. |
| 4686 | | </t> |
| 4687 | | <t> |
| 4688 | | Because of network-imposed delays, some significant interval might |
| 4689 | | pass between the time that a server generates a response and the time |
| 4690 | | it is received at the next outbound cache or client. If uncorrected, |
| 4691 | | this delay could result in improperly low ages. |
| 4692 | | </t> |
| 4693 | | <t> |
| 4694 | | Because the request that resulted in the returned Age value must have |
| 4695 | | been initiated prior to that Age value's generation, we can correct |
| 4696 | | for delays imposed by the network by recording the time at which the |
| 4697 | | request was initiated. Then, when an Age value is received, it &MUST; |
| 4698 | | be interpreted relative to the time the request was initiated, not |
| 4699 | | the time that the response was received. This algorithm results in |
| 4700 | | conservative behavior no matter how much delay is experienced. So, we |
| 4701 | | compute: |
| 4702 | | </t> |
| 4703 | | <figure><artwork type="code"> |
| 4704 | | corrected_initial_age = corrected_received_age |
| 4705 | | + (now - request_time) |
| 4706 | | </artwork></figure> |
| 4707 | | <t> |
| 4708 | | where "request_time" is the time (according to the local clock) when |
| 4709 | | the request that elicited this response was sent. |
| 4710 | | </t> |
| 4711 | | <t> |
| 4712 | | Summary of age calculation algorithm, when a cache receives a |
| 4713 | | response: |
| 4714 | | </t> |
| 4715 | | <figure><artwork type="code"> |
| 4716 | | /* |
| 4717 | | * age_value |
| 4718 | | * is the value of Age: header received by the cache with |
| 4719 | | * this response. |
| 4720 | | * date_value |
| 4721 | | * is the value of the origin server's Date: header |
| 4722 | | * request_time |
| 4723 | | * is the (local) time when the cache made the request |
| 4724 | | * that resulted in this cached response |
| 4725 | | * response_time |
| 4726 | | * is the (local) time when the cache received the |
| 4727 | | * response |
| 4728 | | * now |
| 4729 | | * is the current (local) time |
| 4730 | | */ |
| 4731 | | |
| 4732 | | apparent_age = max(0, response_time - date_value); |
| 4733 | | corrected_received_age = max(apparent_age, age_value); |
| 4734 | | response_delay = response_time - request_time; |
| 4735 | | corrected_initial_age = corrected_received_age + response_delay; |
| 4736 | | resident_time = now - response_time; |
| 4737 | | current_age = corrected_initial_age + resident_time; |
| 4738 | | </artwork></figure> |
| 4739 | | <t> |
| 4740 | | The current_age of a cache entry is calculated by adding the amount |
| 4741 | | of time (in seconds) since the cache entry was last validated by the |
| 4742 | | origin server to the corrected_initial_age. When a response is |
| 4743 | | generated from a cache entry, the cache &MUST; include a single Age |
| 4744 | | header field in the response with a value equal to the cache entry's |
| 4745 | | current_age. |
| 4746 | | </t> |
| 4747 | | <t> |
| 4748 | | The presence of an Age header field in a response implies that a |
| 4749 | | response is not first-hand. However, the converse is not true, since |
| 4750 | | the lack of an Age header field in a response does not imply that the |
| 4751 | | response is first-hand unless all caches along the request path are |
| 4752 | | compliant with HTTP/1.1 (i.e., older HTTP caches did not implement |
| 4753 | | the Age header field). |
| 4754 | | </t> |
| 4755 | | </section> |
| 4756 | | |
| 4757 | | <section title="Expiration Calculations" anchor="expiration.calculations"> |
| 4758 | | <t> |
| 4759 | | In order to decide whether a response is fresh or stale, we need to |
| 4760 | | compare its freshness lifetime to its age. The age is calculated as |
| 4761 | | described in <xref target="age.calculations"/>; this section describes how to calculate |
| 4762 | | the freshness lifetime, and to determine if a response has expired. |
| 4763 | | In the discussion below, the values can be represented in any form |
| 4764 | | appropriate for arithmetic operations. |
| 4765 | | </t> |
| 4766 | | <t> |
| 4767 | | We use the term "expires_value" to denote the value of the Expires |
| 4768 | | header. We use the term "max_age_value" to denote an appropriate |
| 4769 | | value of the number of seconds carried by the "max-age" directive of |
| 4770 | | the Cache-Control header in a response (see <xref target="modifications.of.the.basic.expiration.mechanism"/>). |
| 4771 | | </t> |
| 4772 | | <t> |
| 4773 | | The max-age directive takes priority over Expires, so if max-age is |
| 4774 | | present in a response, the calculation is simply: |
| 4775 | | </t> |
| 4776 | | <figure><artwork type="code"> |
| 4777 | | freshness_lifetime = max_age_value |
| 4778 | | </artwork></figure> |
| 4779 | | <t> |
| 4780 | | Otherwise, if Expires is present in the response, the calculation is: |
| 4781 | | </t> |
| 4782 | | <figure><artwork type="code"> |
| 4783 | | freshness_lifetime = expires_value - date_value |
| 4784 | | </artwork></figure> |
| 4785 | | <t> |
| 4786 | | Note that neither of these calculations is vulnerable to clock skew, |
| 4787 | | since all of the information comes from the origin server. |
| 4788 | | </t> |
| 4789 | | <t> |
| 4790 | | If none of Expires, Cache-Control: max-age, or Cache-Control: s-maxage |
| 4791 | | (see <xref target="modifications.of.the.basic.expiration.mechanism"/>) appears in the response, and the response |
| 4792 | | does not include other restrictions on caching, the cache &MAY; compute |
| 4793 | | a freshness lifetime using a heuristic. The cache &MUST; attach Warning |
| 4794 | | 113 to any response whose age is more than 24 hours if such warning |
| 4795 | | has not already been added. |
| 4796 | | </t> |
| 4797 | | <t> |
| 4798 | | Also, if the response does have a Last-Modified time, the heuristic |
| 4799 | | expiration value &SHOULD; be no more than some fraction of the interval |
| 4800 | | since that time. A typical setting of this fraction might be 10%. |
| 4801 | | </t> |
| 4802 | | <t> |
| 4803 | | The calculation to determine if a response has expired is quite |
| 4804 | | simple: |
| 4805 | | </t> |
| 4806 | | <figure><artwork type="code"> |
| 4807 | | response_is_fresh = (freshness_lifetime > current_age) |
| 4808 | | </artwork></figure> |
| 4809 | | </section> |
| 4810 | | |
| 4811 | | <section title="Disambiguating Expiration Values" anchor="disambiguating.expiration.values"> |
| 4812 | | <t> |
| 4813 | | Because expiration values are assigned optimistically, it is possible |
| 4814 | | for two caches to contain fresh values for the same resource that are |
| 4815 | | different. |
| 4816 | | </t> |
| 4817 | | <t> |
| 4818 | | If a client performing a retrieval receives a non-first-hand response |
| 4819 | | for a request that was already fresh in its own cache, and the Date |
| 4820 | | header in its existing cache entry is newer than the Date on the new |
| 4821 | | response, then the client &MAY; ignore the response. If so, it &MAY; |
| 4822 | | retry the request with a "Cache-Control: max-age=0" directive (see |
| 4823 | | <xref target="header.cache-control"/>), to force a check with the origin server. |
| 4824 | | </t> |
| 4825 | | <t> |
| 4826 | | If a cache has two fresh responses for the same representation with |
| 4827 | | different validators, it &MUST; use the one with the more recent Date |
| 4828 | | header. This situation might arise because the cache is pooling |
| 4829 | | responses from other caches, or because a client has asked for a |
| 4830 | | reload or a revalidation of an apparently fresh cache entry. |
| 4831 | | </t> |
| 4832 | | </section> |
| 4833 | | |
| 4834 | | <section title="Disambiguating Multiple Responses" anchor="disambiguating.multiple.responses"> |
| 4835 | | <t> |
| 4836 | | Because a client might be receiving responses via multiple paths, so |
| 4837 | | that some responses flow through one set of caches and other |
| 4838 | | responses flow through a different set of caches, a client might |
| 4839 | | receive responses in an order different from that in which the origin |
| 4840 | | server sent them. We would like the client to use the most recently |
| 4841 | | generated response, even if older responses are still apparently |
| 4842 | | fresh. |
| 4843 | | </t> |
| 4844 | | <t> |
| 4845 | | Neither the entity tag nor the expiration value can impose an |
| 4846 | | ordering on responses, since it is possible that a later response |
| 4847 | | intentionally carries an earlier expiration time. The Date values are |
| 4848 | | ordered to a granularity of one second. |
| 4849 | | </t> |
| 4850 | | <t> |
| 4851 | | When a client tries to revalidate a cache entry, and the response it |
| 4852 | | receives contains a Date header that appears to be older than the one |
| 4853 | | for the existing entry, then the client &SHOULD; repeat the request |
| 4854 | | unconditionally, and include |
| 4855 | | </t> |
| 4856 | | <figure><artwork type="example"> |
| 4857 | | Cache-Control: max-age=0 |
| 4858 | | </artwork></figure> |
| 4859 | | <t> |
| 4860 | | to force any intermediate caches to validate their copies directly |
| 4861 | | with the origin server, or |
| 4862 | | </t> |
| 4863 | | <figure><artwork type="example"> |
| 4864 | | Cache-Control: no-cache |
| 4865 | | </artwork></figure> |
| 4866 | | <t> |
| 4867 | | to force any intermediate caches to obtain a new copy from the origin |
| 4868 | | server. |
| 4869 | | </t> |
| 4870 | | <t> |
| 4871 | | If the Date values are equal, then the client &MAY; use either response |
| 4872 | | (or &MAY;, if it is being extremely prudent, request a new response). |
| 4873 | | Servers &MUST-NOT; depend on clients being able to choose |
| 4874 | | deterministically between responses generated during the same second, |
| 4875 | | if their expiration times overlap. |
| 4876 | | </t> |
| 4877 | | </section> |
| 4878 | | </section> |
| 4879 | | |
| 4880 | | <section title="Validation Model" anchor="validation.model"> |
| 4881 | | <t> |
| 4882 | | When a cache has a stale entry that it would like to use as a |
| 4883 | | response to a client's request, it first has to check with the origin |
| 4884 | | server (or possibly an intermediate cache with a fresh response) to |
| 4885 | | see if its cached entry is still usable. We call this "validating" |
| 4886 | | the cache entry. Since we do not want to have to pay the overhead of |
| 4887 | | retransmitting the full response if the cached entry is good, and we |
| 4888 | | do not want to pay the overhead of an extra round trip if the cached |
| 4889 | | entry is invalid, the HTTP/1.1 protocol supports the use of |
| 4890 | | conditional methods. |
| 4891 | | </t> |
| 4892 | | <t> |
| 4893 | | The key protocol features for supporting conditional methods are |
| 4894 | | those concerned with "cache validators." When an origin server |
| 4895 | | generates a full response, it attaches some sort of validator to it, |
| 4896 | | which is kept with the cache entry. When a client (user agent or |
| 4897 | | proxy cache) makes a conditional request for a resource for which it |
| 4898 | | has a cache entry, it includes the associated validator in the |
| 4899 | | request. |
| 4900 | | </t> |
| 4901 | | <t> |
| 4902 | | The server then checks that validator against the current validator |
| 4903 | | for the entity, and, if they match (see <xref target="weak.and.strong.validators"/>), it responds |
| 4904 | | with a special status code (usually, 304 (Not Modified)) and no |
| 4905 | | entity-body. Otherwise, it returns a full response (including |
| 4906 | | entity-body). Thus, we avoid transmitting the full response if the |
| 4907 | | validator matches, and we avoid an extra round trip if it does not |
| 4908 | | match. |
| 4909 | | </t> |
| 4910 | | <t> |
| 4911 | | In HTTP/1.1, a conditional request looks exactly the same as a normal |
| 4912 | | request for the same resource, except that it carries a special |
| 4913 | | header (which includes the validator) that implicitly turns the |
| 4914 | | method (usually, GET) into a conditional. |
| 4915 | | </t> |
| 4916 | | <t> |
| 4917 | | The protocol includes both positive and negative senses of cache-validating |
| 4918 | | conditions. That is, it is possible to request either that |
| 4919 | | a method be performed if and only if a validator matches or if and |
| 4920 | | only if no validators match. |
| 4921 | | <list><t> |
| 4922 | | <x:h>Note:</x:h> a response that lacks a validator may still be cached, and |
| 4923 | | served from cache until it expires, unless this is explicitly |
| 4924 | | prohibited by a cache-control directive. However, a cache cannot |
| 4925 | | do a conditional retrieval if it does not have a validator for the |
| 4926 | | entity, which means it will not be refreshable after it expires. |
| 4927 | | </t></list> |
| 4928 | | </t> |
| 4929 | | |
| 4930 | | <section title="Last-Modified Dates" anchor="last-modified.dates"> |
| 4931 | | <t> |
| 4932 | | The Last-Modified entity-header field value is often used as a cache |
| 4933 | | validator. In simple terms, a cache entry is considered to be valid |
| 4934 | | if the entity has not been modified since the Last-Modified value. |
| 4935 | | </t> |
| 4936 | | </section> |
| 4937 | | |
| 4938 | | <section title="Entity Tag Cache Validators" anchor="entity.tag.cache.validators"> |
| 4939 | | <t> |
| 4940 | | The ETag response-header field value, an entity tag, provides for an |
| 4941 | | "opaque" cache validator. This might allow more reliable validation |
| 4942 | | in situations where it is inconvenient to store modification dates, |
| 4943 | | where the one-second resolution of HTTP date values is not |
| 4944 | | sufficient, or where the origin server wishes to avoid certain |
| 4945 | | paradoxes that might arise from the use of modification dates. |
| 4946 | | </t> |
| 4947 | | <t> |
| 4948 | | Entity Tags are described in <xref target="entity.tags"/>. The headers used with |
| 4949 | | entity tags are described in sections <xref target="header.etag" format="counter"/>, |
| 4950 | | <xref target="header.if-match" format="counter"/>, <xref target="header.if-none-match" format="counter"/> |
| 4951 | | and <xref target="header.vary" format="counter"/>. |
| 4952 | | </t> |
| 4953 | | </section> |
| 4954 | | |
| 4955 | | <section title="Weak and Strong Validators" anchor="weak.and.strong.validators"> |
| 4956 | | <t> |
| 4957 | | Since both origin servers and caches will compare two validators to |
| 4958 | | decide if they represent the same or different entities, one normally |
| 4959 | | would expect that if the entity (the entity-body or any entity-headers) |
| 4960 | | changes in any way, then the associated validator would |
| 4961 | | change as well. If this is true, then we call this validator a |
| 4962 | | "strong validator." |
| 4963 | | </t> |
| 4964 | | <t> |
| 4965 | | However, there might be cases when a server prefers to change the |
| 4966 | | validator only on semantically significant changes, and not when |
| 4967 | | insignificant aspects of the entity change. A validator that does not |
| 4968 | | always change when the resource changes is a "weak validator." |
| 4969 | | </t> |
| 4970 | | <t> |
| 4971 | | Entity tags are normally "strong validators," but the protocol |
| 4972 | | provides a mechanism to tag an entity tag as "weak." One can think of |
| 4973 | | a strong validator as one that changes whenever the bits of an entity |
| 4974 | | changes, while a weak value changes whenever the meaning of an entity |
| 4975 | | changes. Alternatively, one can think of a strong validator as part |
| 4976 | | of an identifier for a specific entity, while a weak validator is |
| 4977 | | part of an identifier for a set of semantically equivalent entities. |
| 4978 | | <list><t> |
| 4979 | | <x:h>Note:</x:h> One example of a strong validator is an integer that is |
| 4980 | | incremented in stable storage every time an entity is changed. |
| 4981 | | </t><t> |
| 4982 | | An entity's modification time, if represented with one-second |
| 4983 | | resolution, could be a weak validator, since it is possible that |
| 4984 | | the resource might be modified twice during a single second. |
| 4985 | | </t><t> |
| 4986 | | Support for weak validators is optional. However, weak validators |
| 4987 | | allow for more efficient caching of equivalent objects; for |
| 4988 | | example, a hit counter on a site is probably good enough if it is |
| 4989 | | updated every few days or weeks, and any value during that period |
| 4990 | | is likely "good enough" to be equivalent. |
| 4991 | | </t></list> |
| 4992 | | </t> |
| 4993 | | <t> |
| 4994 | | A "use" of a validator is either when a client generates a request |
| 4995 | | and includes the validator in a validating header field, or when a |
| 4996 | | server compares two validators. |
| 4997 | | </t> |
| 4998 | | <t> |
| 4999 | | Strong validators are usable in any context. Weak validators are only |
| 5000 | | usable in contexts that do not depend on exact equality of an entity. |
| 5001 | | For example, either kind is usable for a conditional GET of a full |
| 5002 | | entity. However, only a strong validator is usable for a sub-range |
| 5003 | | retrieval, since otherwise the client might end up with an internally |
| 5004 | | inconsistent entity. |
| 5005 | | </t> |
| 5006 | | <t> |
| 5007 | | Clients &MAY; issue simple (non-subrange) GET requests with either weak |
| 5008 | | validators or strong validators. Clients &MUST-NOT; use weak validators |
| 5009 | | in other forms of request. |
| 5010 | | </t> |
| 5011 | | <t> |
| 5012 | | The only function that the HTTP/1.1 protocol defines on validators is |
| 5013 | | comparison. There are two validator comparison functions, depending |
| 5014 | | on whether the comparison context allows the use of weak validators |
| 5015 | | or not: |
| 5016 | | <list style="symbols"> |
| 5017 | | <t>The strong comparison function: in order to be considered equal, |
| 5018 | | both validators &MUST; be identical in every way, and both &MUST-NOT; |
| 5019 | | be weak.</t> |
| 5020 | | <t>The weak comparison function: in order to be considered equal, |
| 5021 | | both validators &MUST; be identical in every way, but either or |
| 5022 | | both of them &MAY; be tagged as "weak" without affecting the |
| 5023 | | result.</t> |
| 5024 | | </list> |
| 5025 | | </t> |
| 5026 | | <t> |
| 5027 | | An entity tag is strong unless it is explicitly tagged as weak. |
| 5028 | | <xref target="entity.tags"/> gives the syntax for entity tags. |
| 5029 | | </t> |
| 5030 | | <t> |
| 5031 | | A Last-Modified time, when used as a validator in a request, is |
| 5032 | | implicitly weak unless it is possible to deduce that it is strong, |
| 5033 | | using the following rules: |
| 5034 | | <list style="symbols"> |
| 5035 | | <t>The validator is being compared by an origin server to the |
| 5036 | | actual current validator for the entity and,</t> |
| 5037 | | <t>That origin server reliably knows that the associated entity did |
| 5038 | | not change twice during the second covered by the presented |
| 5039 | | validator.</t> |
| 5040 | | </list> |
| 5041 | | </t> |
| 5042 | | <t> |
| 5043 | | or |
| 5044 | | <list style="symbols"> |
| 5045 | | <t>The validator is about to be used by a client in an If-Modified-Since |
| 5046 | | or If-Unmodified-Since header, because the client |
| 5047 | | has a cache entry for the associated entity, and</t> |
| 5048 | | <t>That cache entry includes a Date value, which gives the time |
| 5049 | | when the origin server sent the original response, and</t> |
| 5050 | | <t>The presented Last-Modified time is at least 60 seconds before |
| 5051 | | the Date value.</t> |
| 5052 | | </list> |
| 5053 | | </t> |
| 5054 | | <t> |
| 5055 | | or |
| 5056 | | <list style="symbols"> |
| 5057 | | <t>The validator is being compared by an intermediate cache to the |
| 5058 | | validator stored in its cache entry for the entity, and</t> |
| 5059 | | <t>That cache entry includes a Date value, which gives the time |
| 5060 | | when the origin server sent the original response, and</t> |
| 5061 | | <t>The presented Last-Modified time is at least 60 seconds before |
| 5062 | | the Date value.</t> |
| 5063 | | </list> |
| 5064 | | </t> |
| 5065 | | <t> |
| 5066 | | This method relies on the fact that if two different responses were |
| 5067 | | sent by the origin server during the same second, but both had the |
| 5068 | | same Last-Modified time, then at least one of those responses would |
| 5069 | | have a Date value equal to its Last-Modified time. The arbitrary 60-second |
| 5070 | | limit guards against the possibility that the Date and Last-Modified |
| 5071 | | values are generated from different clocks, or at somewhat |
| 5072 | | different times during the preparation of the response. An |
| 5073 | | implementation &MAY; use a value larger than 60 seconds, if it is |
| 5074 | | believed that 60 seconds is too short. |
| 5075 | | </t> |
| 5076 | | <t> |
| 5077 | | If a client wishes to perform a sub-range retrieval on a value for |
| 5078 | | which it has only a Last-Modified time and no opaque validator, it |
| 5079 | | &MAY; do this only if the Last-Modified time is strong in the sense |
| 5080 | | described here. |
| 5081 | | </t> |
| 5082 | | <t> |
| 5083 | | A cache or origin server receiving a conditional request, other than |
| 5084 | | a full-body GET request, &MUST; use the strong comparison function to |
| 5085 | | evaluate the condition. |
| 5086 | | </t> |
| 5087 | | <t> |
| 5088 | | These rules allow HTTP/1.1 caches and clients to safely perform sub-range |
| 5089 | | retrievals on values that have been obtained from HTTP/1.0 |
| 5090 | | servers. |
| 5091 | | </t> |
| 5092 | | </section> |
| 5093 | | |
| 5094 | | <section title="Rules for When to Use Entity Tags and Last-Modified Dates" anchor="rules.for.when.to.use.entity.tags.and.last-modified.dates"> |
| 5095 | | <t> |
| 5096 | | We adopt a set of rules and recommendations for origin servers, |
| 5097 | | clients, and caches regarding when various validator types ought to |
| 5098 | | be used, and for what purposes. |
| 5099 | | </t> |
| 5100 | | <t> |
| 5101 | | HTTP/1.1 origin servers: |
| 5102 | | <list style="symbols"> |
| 5103 | | <t>&SHOULD; send an entity tag validator unless it is not feasible to |
| 5104 | | generate one.</t> |
| 5105 | | |
| 5106 | | <t>&MAY; send a weak entity tag instead of a strong entity tag, if |
| 5107 | | performance considerations support the use of weak entity tags, |
| 5108 | | or if it is unfeasible to send a strong entity tag.</t> |
| 5109 | | |
| 5110 | | <t>&SHOULD; send a Last-Modified value if it is feasible to send one, |
| 5111 | | unless the risk of a breakdown in semantic transparency that |
| 5112 | | could result from using this date in an If-Modified-Since header |
| 5113 | | would lead to serious problems.</t> |
| 5114 | | </list> |
| 5115 | | </t> |
| 5116 | | <t> |
| 5117 | | In other words, the preferred behavior for an HTTP/1.1 origin server |
| 5118 | | is to send both a strong entity tag and a Last-Modified value. |
| 5119 | | </t> |
| 5120 | | <t> |
| 5121 | | In order to be legal, a strong entity tag &MUST; change whenever the |
| 5122 | | associated entity value changes in any way. A weak entity tag &SHOULD; |
| 5123 | | change whenever the associated entity changes in a semantically |
| 5124 | | significant way. |
| 5125 | | <list><t> |
| 5126 | | <x:h>Note:</x:h> in order to provide semantically transparent caching, an |
| 5127 | | origin server must avoid reusing a specific strong entity tag |
| 5128 | | value for two different entities, or reusing a specific weak |
| 5129 | | entity tag value for two semantically different entities. Cache |
| 5130 | | entries might persist for arbitrarily long periods, regardless of |
| 5131 | | expiration times, so it might be inappropriate to expect that a |
| 5132 | | cache will never again attempt to validate an entry using a |
| 5133 | | validator that it obtained at some point in the past. |
| 5134 | | </t></list> |
| 5135 | | </t> |
| 5136 | | <t> |
| 5137 | | HTTP/1.1 clients: |
| 5138 | | <list style="symbols"> |
| 5139 | | <t>If an entity tag has been provided by the origin server, &MUST; |
| 5140 | | use that entity tag in any cache-conditional request (using If-Match |
| 5141 | | or If-None-Match).</t> |
| 5142 | | |
| 5143 | | <t>If only a Last-Modified value has been provided by the origin |
| 5144 | | server, &SHOULD; use that value in non-subrange cache-conditional |
| 5145 | | requests (using If-Modified-Since).</t> |
| 5146 | | |
| 5147 | | <t>If only a Last-Modified value has been provided by an HTTP/1.0 |
| 5148 | | origin server, &MAY; use that value in subrange cache-conditional |
| 5149 | | requests (using If-Unmodified-Since:). The user agent &SHOULD; |
| 5150 | | provide a way to disable this, in case of difficulty.</t> |
| 5151 | | |
| 5152 | | <t>If both an entity tag and a Last-Modified value have been |
| 5153 | | provided by the origin server, &SHOULD; use both validators in |
| 5154 | | cache-conditional requests. This allows both HTTP/1.0 and |
| 5155 | | HTTP/1.1 caches to respond appropriately.</t> |
| 5156 | | </list> |
| 5157 | | </t> |
| 5158 | | <t> |
| 5159 | | An HTTP/1.1 origin server, upon receiving a conditional request that |
| 5160 | | includes both a Last-Modified date (e.g., in an If-Modified-Since or |
| 5161 | | If-Unmodified-Since header field) and one or more entity tags (e.g., |
| 5162 | | in an If-Match, If-None-Match, or If-Range header field) as cache |
| 5163 | | validators, &MUST-NOT; return a response status of 304 (Not Modified) |
| 5164 | | unless doing so is consistent with all of the conditional header |
| 5165 | | fields in the request. |
| 5166 | | </t> |
| 5167 | | <t> |
| 5168 | | An HTTP/1.1 caching proxy, upon receiving a conditional request that |
| 5169 | | includes both a Last-Modified date and one or more entity tags as |
| 5170 | | cache validators, &MUST-NOT; return a locally cached response to the |
| 5171 | | client unless that cached response is consistent with all of the |
| 5172 | | conditional header fields in the request. |
| 5173 | | <list><t> |
| 5174 | | <x:h>Note:</x:h> The general principle behind these rules is that HTTP/1.1 |
| 5175 | | servers and clients should transmit as much non-redundant |
| 5176 | | information as is available in their responses and requests. |
| 5177 | | HTTP/1.1 systems receiving this information will make the most |
| 5178 | | conservative assumptions about the validators they receive. |
| 5179 | | </t><t> |
| 5180 | | HTTP/1.0 clients and caches will ignore entity tags. Generally, |
| 5181 | | last-modified values received or used by these systems will |
| 5182 | | support transparent and efficient caching, and so HTTP/1.1 origin |
| 5183 | | servers should provide Last-Modified values. In those rare cases |
| 5184 | | where the use of a Last-Modified value as a validator by an |
| 5185 | | HTTP/1.0 system could result in a serious problem, then HTTP/1.1 |
| 5186 | | origin servers should not provide one. |
| 5187 | | </t></list> |
| 5188 | | </t> |
| 5189 | | </section> |
| 5190 | | |
| 5191 | | <section title="Non-validating Conditionals" anchor="non-validating.conditionals"> |
| 5192 | | <t> |
| 5193 | | The principle behind entity tags is that only the service author |
| 5194 | | knows the semantics of a resource well enough to select an |
| 5195 | | appropriate cache validation mechanism, and the specification of any |
| 5196 | | validator comparison function more complex than byte-equality would |
| 5197 | | open up a can of worms. Thus, comparisons of any other headers |
| 5198 | | (except Last-Modified, for compatibility with HTTP/1.0) are never |
| 5199 | | used for purposes of validating a cache entry. |
| 5200 | | </t> |
| 5201 | | </section> |
| 5202 | | </section> |
| 5203 | | |
| 5204 | | <section title="Response Cacheability" anchor="response.cacheability"> |
| 5205 | | <t> |
| 5206 | | Unless specifically constrained by a cache-control (<xref target="header.cache-control"/>) |
| 5207 | | directive, a caching system &MAY; always store a successful response |
| 5208 | | (see <xref target="errors.or.incomplete.response.cache.behavior"/>) as a cache entry, &MAY; return it without validation |
| 5209 | | if it is fresh, and &MAY; return it after successful validation. If |
| 5210 | | there is neither a cache validator nor an explicit expiration time |
| 5211 | | associated with a response, we do not expect it to be cached, but |
| 5212 | | certain caches &MAY; violate this expectation (for example, when little |
| 5213 | | or no network connectivity is available). A client can usually detect |
| 5214 | | that such a response was taken from a cache by comparing the Date |
| 5215 | | header to the current time. |
| 5216 | | <list><t> |
| 5217 | | <x:h>Note:</x:h> some HTTP/1.0 caches are known to violate this expectation |
| 5218 | | without providing any Warning. |
| 5219 | | </t></list> |
| 5220 | | </t> |
| 5221 | | <t> |
| 5222 | | However, in some cases it might be inappropriate for a cache to |
| 5223 | | retain an entity, or to return it in response to a subsequent |
| 5224 | | request. This might be because absolute semantic transparency is |
| 5225 | | deemed necessary by the service author, or because of security or |
| 5226 | | privacy considerations. Certain cache-control directives are |
| 5227 | | therefore provided so that the server can indicate that certain |
| 5228 | | resource entities, or portions thereof, are not to be cached |
| 5229 | | regardless of other considerations. |
| 5230 | | </t> |
| 5231 | | <t> |
| 5232 | | Note that <xref target="header.authorization"/> normally prevents a shared cache from saving |
| 5233 | | and returning a response to a previous request if that request |
| 5234 | | included an Authorization header. |
| 5235 | | </t> |
| 5236 | | <t> |
| 5237 | | A response received with a status code of 200, 203, 206, 300, 301 or |
| 5238 | | 410 &MAY; be stored by a cache and used in reply to a subsequent |
| 5239 | | request, subject to the expiration mechanism, unless a cache-control |
| 5240 | | directive prohibits caching. However, a cache that does not support |
| 5241 | | the Range and Content-Range headers &MUST-NOT; cache 206 (Partial |
| 5242 | | Content) responses. |
| 5243 | | </t> |
| 5244 | | <t> |
| 5245 | | A response received with any other status code (e.g. status codes 302 |
| 5246 | | and 307) &MUST-NOT; be returned in a reply to a subsequent request |
| 5247 | | unless there are cache-control directives or another header(s) that |
| 5248 | | explicitly allow it. For example, these include the following: an |
| 5249 | | Expires header (<xref target="header.expires"/>); a "max-age", "s-maxage", "must-revalidate", |
| 5250 | | "proxy-revalidate", "public" or "private" cache-control |
| 5251 | | directive (<xref target="header.cache-control"/>). |
| 5252 | | </t> |
| 5253 | | </section> |
| 5254 | | |
| 5255 | | <section title="Constructing Responses From Caches" anchor="constructing.responses.from.caches"> |
| 5256 | | <t> |
| 5257 | | The purpose of an HTTP cache is to store information received in |
| 5258 | | response to requests for use in responding to future requests. In |
| 5259 | | many cases, a cache simply returns the appropriate parts of a |
| 5260 | | response to the requester. However, if the cache holds a cache entry |
| 5261 | | based on a previous response, it might have to combine parts of a new |
| 5262 | | response with what is held in the cache entry. |
| 5263 | | </t> |
| 5264 | | |
| 5265 | | <section title="End-to-end and Hop-by-hop Headers" anchor="end-to-end.and.hop-by-hop.headers"> |
| 5266 | | <t> |
| 5267 | | For the purpose of defining the behavior of caches and non-caching |
| 5268 | | proxies, we divide HTTP headers into two categories: |
| 5269 | | <list style="symbols"> |
| 5270 | | <t>End-to-end headers, which are transmitted to the ultimate |
| 5271 | | recipient of a request or response. End-to-end headers in |
| 5272 | | responses &MUST; be stored as part of a cache entry and &MUST; be |
| 5273 | | transmitted in any response formed from a cache entry.</t> |
| 5274 | | |
| 5275 | | <t>Hop-by-hop headers, which are meaningful only for a single |
| 5276 | | transport-level connection, and are not stored by caches or |
| 5277 | | forwarded by proxies.</t> |
| 5278 | | </list> |
| 5279 | | </t> |
| 5280 | | <t> |
| 5281 | | The following HTTP/1.1 headers are hop-by-hop headers: |
| 5282 | | <list style="symbols"> |
| 5283 | | <t>Connection</t> |
| 5284 | | <t>Keep-Alive</t> |
| 5285 | | <t>Proxy-Authenticate</t> |
| 5286 | | <t>Proxy-Authorization</t> |
| 5287 | | <t>TE</t> |
| 5288 | | <t>Trailers</t> |
| 5289 | | <t>Transfer-Encoding</t> |
| 5290 | | <t>Upgrade</t> |
| 5291 | | </list> |
| 5292 | | </t> |
| 5293 | | <t> |
| 5294 | | All other headers defined by HTTP/1.1 are end-to-end headers. |
| 5295 | | </t> |
| 5296 | | <t> |
| 5297 | | Other hop-by-hop headers &MUST; be listed in a Connection header, |
| 5298 | | (<xref target="header.connection"/>) to be introduced into HTTP/1.1 (or later). |
| 5299 | | </t> |
| 5300 | | </section> |
| 5301 | | |
| 5302 | | <section title="Non-modifiable Headers" anchor="non-modifiable.headers"> |
| 5303 | | <t> |
| 5304 | | Some features of the HTTP/1.1 protocol, such as Digest |
| 5305 | | Authentication, depend on the value of certain end-to-end headers. A |
| 5306 | | transparent proxy &SHOULD-NOT; modify an end-to-end header unless the |
| 5307 | | definition of that header requires or specifically allows that. |
| 5308 | | </t> |
| 5309 | | <t> |
| 5310 | | A transparent proxy &MUST-NOT; modify any of the following fields in a |
| 5311 | | request or response, and it &MUST-NOT; add any of these fields if not |
| 5312 | | already present: |
| 5313 | | <list style="symbols"> |
| 5314 | | <t>Content-Location</t> |
| 5315 | | <t>Content-MD5</t> |
| 5316 | | <t>ETag</t> |
| 5317 | | <t>Last-Modified</t> |
| 5318 | | </list> |
| 5319 | | </t> |
| 5320 | | <t> |
| 5321 | | A transparent proxy &MUST-NOT; modify any of the following fields in a |
| 5322 | | response: |
| 5323 | | <list style="symbols"> |
| 5324 | | <t>Expires</t> |
| 5325 | | </list> |
| 5326 | | </t> |
| 5327 | | <t> |
| 5328 | | but it &MAY; add any of these fields if not already present. If an |
| 5329 | | Expires header is added, it &MUST; be given a field-value identical to |
| 5330 | | that of the Date header in that response. |
| 5331 | | </t> |
| 5332 | | <t> |
| 5333 | | A proxy &MUST-NOT; modify or add any of the following fields in a |
| 5334 | | message that contains the no-transform cache-control directive, or in |
| 5335 | | any request: |
| 5336 | | <list style="symbols"> |
| 5337 | | <t>Content-Encoding</t> |
| 5338 | | <t>Content-Range</t> |
| 5339 | | <t>Content-Type</t> |
| 5340 | | </list> |
| 5341 | | </t> |
| 5342 | | <t> |
| 5343 | | A non-transparent proxy &MAY; modify or add these fields to a message |
| 5344 | | that does not include no-transform, but if it does so, it &MUST; add a |
| 5345 | | Warning 214 (Transformation applied) if one does not already appear |
| 5346 | | in the message (see <xref target="header.warning"/>). |
| 5347 | | <list><t> |
| 5348 | | Warning: unnecessary modification of end-to-end headers might |
| 5349 | | cause authentication failures if stronger authentication |
| 5350 | | mechanisms are introduced in later versions of HTTP. Such |
| 5351 | | authentication mechanisms &MAY; rely on the values of header fields |
| 5352 | | not listed here. |
| 5353 | | </t></list> |
| 5354 | | </t> |
| 5355 | | <t> |
| 5356 | | The Content-Length field of a request or response is added or deleted |
| 5357 | | according to the rules in <xref target="message.length"/>. A transparent proxy &MUST; |
| 5358 | | preserve the entity-length (<xref target="entity.length"/>) of the entity-body, |
| 5359 | | although it &MAY; change the transfer-length (<xref target="message.length"/>). |
| 5360 | | </t> |
| 5361 | | </section> |
| 5362 | | |
| 5363 | | <section title="Combining Headers" anchor="combining.headers"> |
| 5364 | | <t> |
| 5365 | | When a cache makes a validating request to a server, and the server |
| 5366 | | provides a 304 (Not Modified) response or a 206 (Partial Content) |
| 5367 | | response, the cache then constructs a response to send to the |
| 5368 | | requesting client. |
| 5369 | | </t> |
| 5370 | | <t> |
| 5371 | | If the status code is 304 (Not Modified), the cache uses the entity-body |
| 5372 | | stored in the cache entry as the entity-body of this outgoing |
| 5373 | | response. If the status code is 206 (Partial Content) and the ETag or |
| 5374 | | Last-Modified headers match exactly, the cache &MAY; combine the |
| 5375 | | contents stored in the cache entry with the new contents received in |
| 5376 | | the response and use the result as the entity-body of this outgoing |
| 5377 | | response, (see <xref target="combining.byte.ranges" format="counter"/>). |
| 5378 | | </t> |
| 5379 | | <t> |
| 5380 | | The end-to-end headers stored in the cache entry are used for the |
| 5381 | | constructed response, except that |
| 5382 | | <list style="symbols"> |
| 5383 | | <t>any stored Warning headers with warn-code 1xx (see <xref target="header.warning"/>) |
| 5384 | | &MUST; be deleted from the cache entry and the forwarded response.</t> |
| 5385 | | <t>any stored Warning headers with warn-code 2xx &MUST; be retained |
| 5386 | | in the cache entry and the forwarded response.</t> |
| 5387 | | <t>any end-to-end headers provided in the 304 or 206 response &MUST; |
| 5388 | | replace the corresponding headers from the cache entry.</t> |
| 5389 | | </list> |
| 5390 | | </t> |
| 5391 | | <t> |
| 5392 | | Unless the cache decides to remove the cache entry, it &MUST; also |
| 5393 | | replace the end-to-end headers stored with the cache entry with |
| 5394 | | corresponding headers received in the incoming response, except for |
| 5395 | | Warning headers as described immediately above. If a header field-name |
| 5396 | | in the incoming response matches more than one header in the |
| 5397 | | cache entry, all such old headers &MUST; be replaced. |
| 5398 | | </t> |
| 5399 | | <t> |
| 5400 | | In other words, the set of end-to-end headers received in the |
| 5401 | | incoming response overrides all corresponding end-to-end headers |
| 5402 | | stored with the cache entry (except for stored Warning headers with |
| 5403 | | warn-code 1xx, which are deleted even if not overridden). |
| 5404 | | <list><t> |
| 5405 | | <x:h>Note:</x:h> this rule allows an origin server to use a 304 (Not |
| 5406 | | Modified) or a 206 (Partial Content) response to update any header |
| 5407 | | associated with a previous response for the same entity or sub-ranges |
| 5408 | | thereof, although it might not always be meaningful or |
| 5409 | | correct to do so. This rule does not allow an origin server to use |
| 5410 | | a 304 (Not Modified) or a 206 (Partial Content) response to |
| 5411 | | entirely delete a header that it had provided with a previous |
| 5412 | | response. |
| 5413 | | </t></list> |
| 5414 | | </t> |
| 5415 | | </section> |
| 5416 | | |
| 5417 | | <section title="Combining Byte Ranges" anchor="combining.byte.ranges"> |
| 5418 | | <t> |
| 5419 | | A response might transfer only a subrange of the bytes of an entity-body, |
| 5420 | | either because the request included one or more Range |
| 5421 | | specifications, or because a connection was broken prematurely. After |
| 5422 | | several such transfers, a cache might have received several ranges of |
| 5423 | | the same entity-body. |
| 5424 | | </t> |
| 5425 | | <t> |
| 5426 | | If a cache has a stored non-empty set of subranges for an entity, and |
| 5427 | | an incoming response transfers another subrange, the cache &MAY; |
| 5428 | | combine the new subrange with the existing set if both the following |
| 5429 | | conditions are met: |
| 5430 | | <list style="symbols"> |
| 5431 | | <t>Both the incoming response and the cache entry have a cache |
| 5432 | | validator.</t> |
| 5433 | | <t>The two cache validators match using the strong comparison |
| 5434 | | function (see <xref target="weak.and.strong.validators"/>).</t> |
| 5435 | | </list> |
| 5436 | | </t> |
| 5437 | | <t> |
| 5438 | | If either requirement is not met, the cache &MUST; use only the most |
| 5439 | | recent partial response (based on the Date values transmitted with |
| 5440 | | every response, and using the incoming response if these values are |
| 5441 | | equal or missing), and &MUST; discard the other partial information. |
| 5442 | | </t> |
| 5443 | | </section> |
| 5444 | | </section> |
| 5445 | | |
| 5446 | | <section title="Caching Negotiated Responses" anchor="caching.negotiated.responses"> |
| 5447 | | <t> |
| 5448 | | Use of server-driven content negotiation (<xref target="server-driven.negotiation"/>), as indicated |
| 5449 | | by the presence of a Vary header field in a response, alters the |
| 5450 | | conditions and procedure by which a cache can use the response for |
| 5451 | | subsequent requests. See <xref target="header.vary"/> for use of the Vary header |
| 5452 | | field by servers. |
| 5453 | | </t> |
| 5454 | | <t> |
| 5455 | | A server &SHOULD; use the Vary header field to inform a cache of what |
| 5456 | | request-header fields were used to select among multiple |
| 5457 | | representations of a cacheable response subject to server-driven |
| 5458 | | negotiation. The set of header fields named by the Vary field value |
| 5459 | | is known as the "selecting" request-headers. |
| 5460 | | </t> |
| 5461 | | <t> |
| 5462 | | When the cache receives a subsequent request whose Request-URI |
| 5463 | | specifies one or more cache entries including a Vary header field, |
| 5464 | | the cache &MUST-NOT; use such a cache entry to construct a response to |
| 5465 | | the new request unless all of the selecting request-headers present |
| 5466 | | in the new request match the corresponding stored request-headers in |
| 5467 | | the original request. |
| 5468 | | </t> |
| 5469 | | <t> |
| 5470 | | The selecting request-headers from two requests are defined to match |
| 5471 | | if and only if the selecting request-headers in the first request can |
| 5472 | | be transformed to the selecting request-headers in the second request |
| 5473 | | by adding or removing linear white space (LWS) at places where this |
| 5474 | | is allowed by the corresponding BNF, and/or combining multiple |
| 5475 | | message-header fields with the same field name following the rules |
| 5476 | | about message headers in <xref target="message.headers"/>. |
| 5477 | | </t> |
| 5478 | | <t> |
| 5479 | | A Vary header field-value of "*" always fails to match and subsequent |
| 5480 | | requests on that resource can only be properly interpreted by the |
| 5481 | | origin server. |
| 5482 | | </t> |
| 5483 | | <t> |
| 5484 | | If the selecting request header fields for the cached entry do not |
| 5485 | | match the selecting request header fields of the new request, then |
| 5486 | | the cache &MUST-NOT; use a cached entry to satisfy the request unless |
| 5487 | | it first relays the new request to the origin server in a conditional |
| 5488 | | request and the server responds with 304 (Not Modified), including an |
| 5489 | | entity tag or Content-Location that indicates the entity to be used. |
| 5490 | | </t> |
| 5491 | | <t> |
| 5492 | | If an entity tag was assigned to a cached representation, the |
| 5493 | | forwarded request &SHOULD; be conditional and include the entity tags |
| 5494 | | in an If-None-Match header field from all its cache entries for the |
| 5495 | | resource. This conveys to the server the set of entities currently |
| 5496 | | held by the cache, so that if any one of these entities matches the |
| 5497 | | requested entity, the server can use the ETag header field in its 304 |
| 5498 | | (Not Modified) response to tell the cache which entry is appropriate. |
| 5499 | | If the entity-tag of the new response matches that of an existing |
| 5500 | | entry, the new response &SHOULD; be used to update the header fields of |
| 5501 | | the existing entry, and the result &MUST; be returned to the client. |
| 5502 | | </t> |
| 5503 | | <t> |
| 5504 | | If any of the existing cache entries contains only partial content |
| 5505 | | for the associated entity, its entity-tag &SHOULD-NOT; be included in |
| 5506 | | the If-None-Match header field unless the request is for a range that |
| 5507 | | would be fully satisfied by that entry. |
| 5508 | | </t> |
| 5509 | | <t> |
| 5510 | | If a cache receives a successful response whose Content-Location |
| 5511 | | field matches that of an existing cache entry for the same Request-URI, |
| 5512 | | whose entity-tag differs from that of the existing entry, and |
| 5513 | | whose Date is more recent than that of the existing entry, the |
| 5514 | | existing entry &SHOULD-NOT; be returned in response to future requests |
| 5515 | | and &SHOULD; be deleted from the cache. |
| 5516 | | </t> |
| 5517 | | </section> |
| 5518 | | |
| 5519 | | <section title="Shared and Non-Shared Caches" anchor="shared.and.non-shared.caches"> |
| 5520 | | <t> |
| 5521 | | For reasons of security and privacy, it is necessary to make a |
| 5522 | | distinction between "shared" and "non-shared" caches. A non-shared |
| 5523 | | cache is one that is accessible only to a single user. Accessibility |
| 5524 | | in this case &SHOULD; be enforced by appropriate security mechanisms. |
| 5525 | | All other caches are considered to be "shared." Other sections of |
| 5526 | | this specification place certain constraints on the operation of |
| 5527 | | shared caches in order to prevent loss of privacy or failure of |
| 5528 | | access controls. |
| 5529 | | </t> |
| 5530 | | </section> |
| 5531 | | |
| 5532 | | <section title="Errors or Incomplete Response Cache Behavior" anchor="errors.or.incomplete.response.cache.behavior"> |
| 5533 | | <t> |
| 5534 | | A cache that receives an incomplete response (for example, with fewer |
| 5535 | | bytes of data than specified in a Content-Length header) &MAY; store |
| 5536 | | the response. However, the cache &MUST; treat this as a partial |
| 5537 | | response. Partial responses &MAY; be combined as described in <xref target="combining.byte.ranges"/>; |
| 5538 | | the result might be a full response or might still be |
| 5539 | | partial. A cache &MUST-NOT; return a partial response to a client |
| 5540 | | without explicitly marking it as such, using the 206 (Partial |
| 5541 | | Content) status code. A cache &MUST-NOT; return a partial response |
| 5542 | | using a status code of 200 (OK). |
| 5543 | | </t> |
| 5544 | | <t> |
| 5545 | | If a cache receives a 5xx response while attempting to revalidate an |
| 5546 | | entry, it &MAY; either forward this response to the requesting client, |
| 5547 | | or act as if the server failed to respond. In the latter case, it &MAY; |
| 5548 | | return a previously received response unless the cached entry |
| 5549 | | includes the "must-revalidate" cache-control directive (see <xref target="header.cache-control"/>). |
| 5550 | | </t> |
| 5551 | | </section> |
| 5552 | | |
| 5553 | | <section title="Side Effects of GET and HEAD" anchor="side.effects.of.get.and.head"> |
| 5554 | | <t> |
| 5555 | | Unless the origin server explicitly prohibits the caching of their |
| 5556 | | responses, the application of GET and HEAD methods to any resources |
| 5557 | | &SHOULD-NOT; have side effects that would lead to erroneous behavior if |
| 5558 | | these responses are taken from a cache. They &MAY; still have side |
| 5559 | | effects, but a cache is not required to consider such side effects in |
| 5560 | | its caching decisions. Caches are always expected to observe an |
| 5561 | | origin server's explicit restrictions on caching. |
| 5562 | | </t> |
| 5563 | | <t> |
| 5564 | | We note one exception to this rule: since some applications have |
| 5565 | | traditionally used GETs and HEADs with query URLs (those containing a |
| 5566 | | "?" in the rel_path part) to perform operations with significant side |
| 5567 | | effects, caches &MUST-NOT; treat responses to such URIs as fresh unless |
| 5568 | | the server provides an explicit expiration time. This specifically |
| 5569 | | means that responses from HTTP/1.0 servers for such URIs &SHOULD-NOT; |
| 5570 | | be taken from a cache. See <xref target="safe.methods"/> for related information. |
| 5571 | | </t> |
| 5572 | | </section> |
| 5573 | | |
| 5574 | | <section title="Invalidation After Updates or Deletions" anchor="invalidation.after.updates.or.deletions"> |
| 5575 | | <t> |
| 5576 | | The effect of certain methods performed on a resource at the origin |
| 5577 | | server might cause one or more existing cache entries to become non-transparently |
| 5578 | | invalid. That is, although they might continue to be |
| 5579 | | "fresh," they do not accurately reflect what the origin server would |
| 5580 | | return for a new request on that resource. |
| 5581 | | </t> |
| 5582 | | <t> |
| 5583 | | There is no way for the HTTP protocol to guarantee that all such |
| 5584 | | cache entries are marked invalid. For example, the request that |
| 5585 | | caused the change at the origin server might not have gone through |
| 5586 | | the proxy where a cache entry is stored. However, several rules help |
| 5587 | | reduce the likelihood of erroneous behavior. |
| 5588 | | </t> |
| 5589 | | <t> |
| 5590 | | In this section, the phrase "invalidate an entity" means that the |
| 5591 | | cache will either remove all instances of that entity from its |
| 5592 | | storage, or will mark these as "invalid" and in need of a mandatory |
| 5593 | | revalidation before they can be returned in response to a subsequent |
| 5594 | | request. |
| 5595 | | </t> |
| 5596 | | <t> |
| 5597 | | Some HTTP methods &MUST; cause a cache to invalidate an entity. This is |
| 5598 | | either the entity referred to by the Request-URI, or by the Location |
| 5599 | | or Content-Location headers (if present). These methods are: |
| 5600 | | <list style="symbols"> |
| 5601 | | <t>PUT</t> |
| 5602 | | <t>DELETE</t> |
| 5603 | | <t>POST</t> |
| 5604 | | </list> |
| 5605 | | </t> |
| 5606 | | <t> |
| 5607 | | In order to prevent denial of service attacks, an invalidation based |
| 5608 | | on the URI in a Location or Content-Location header &MUST; only be |
| 5609 | | performed if the host part is the same as in the Request-URI. |
| 5610 | | </t> |
| 5611 | | <t> |
| 5612 | | A cache that passes through requests for methods it does not |
| 5613 | | understand &SHOULD; invalidate any entities referred to by the |
| 5614 | | Request-URI. |
| 5615 | | </t> |
| 5616 | | </section> |
| 5617 | | |
| 5618 | | <section title="Write-Through Mandatory" anchor="write-through.mandatory"> |
| 5619 | | <t> |
| 5620 | | All methods that might be expected to cause modifications to the |
| 5621 | | origin server's resources &MUST; be written through to the origin |
| 5622 | | server. This currently includes all methods except for GET and HEAD. |
| 5623 | | A cache &MUST-NOT; reply to such a request from a client before having |
| 5624 | | transmitted the request to the inbound server, and having received a |
| 5625 | | corresponding response from the inbound server. This does not prevent |
| 5626 | | a proxy cache from sending a 100 (Continue) response before the |
| 5627 | | inbound server has sent its final reply. |
| 5628 | | </t> |
| 5629 | | <t> |
| 5630 | | The alternative (known as "write-back" or "copy-back" caching) is not |
| 5631 | | allowed in HTTP/1.1, due to the difficulty of providing consistent |
| 5632 | | updates and the problems arising from server, cache, or network |
| 5633 | | failure prior to write-back. |
| 5634 | | </t> |
| 5635 | | </section> |
| 5636 | | |
| 5637 | | <section title="Cache Replacement" anchor="cache.replacement"> |
| 5638 | | <t> |
| 5639 | | If a new cacheable (see sections <xref target="what.may.be.stored.by.caches" format="counter"/>, |
| 5640 | | <xref target="disambiguating.expiration.values" format="counter"/>, |
| 5641 | | <xref target="disambiguating.multiple.responses" format="counter"/> |
| 5642 | | and <xref target="errors.or.incomplete.response.cache.behavior" format="counter"/>) |
| 5643 | | response is received from a resource while any existing responses for |
| 5644 | | the same resource are cached, the cache &SHOULD; use the new response |
| 5645 | | to reply to the current request. It &MAY; insert it into cache storage |
| 5646 | | and &MAY;, if it meets all other requirements, use it to respond to any |
| 5647 | | future requests that would previously have caused the old response to |
| 5648 | | be returned. If it inserts the new response into cache storage the |
| 5649 | | rules in <xref target="combining.headers"/> apply. |
| 5650 | | <list><t> |
| 5651 | | <x:h>Note:</x:h> a new response that has an older Date header value than |
| 5652 | | existing cached responses is not cacheable. |
| 5653 | | </t></list> |
| 5654 | | </t> |
| 5655 | | </section> |
| 5656 | | |
| 5657 | | <section title="History Lists" anchor="history.lists"> |
| 5658 | | <t> |
| 5659 | | User agents often have history mechanisms, such as "Back" buttons and |
| 5660 | | history lists, which can be used to redisplay an entity retrieved |
| 5661 | | earlier in a session. |
| 5662 | | </t> |
| 5663 | | <t> |
| 5664 | | History mechanisms and caches are different. In particular history |
| 5665 | | mechanisms &SHOULD-NOT; try to show a semantically transparent view of |
| 5666 | | the current state of a resource. Rather, a history mechanism is meant |
| 5667 | | to show exactly what the user saw at the time when the resource was |
| 5668 | | retrieved. |
| 5669 | | </t> |
| 5670 | | <t> |
| 5671 | | By default, an expiration time does not apply to history mechanisms. |
| 5672 | | If the entity is still in storage, a history mechanism &SHOULD; display |
| 5673 | | it even if the entity has expired, unless the user has specifically |
| 5674 | | configured the agent to refresh expired history documents. |
| 5675 | | </t> |
| 5676 | | <t> |
| 5677 | | This is not to be construed to prohibit the history mechanism from |
| 5678 | | telling the user that a view might be stale. |
| 5679 | | <list><t> |
| 5680 | | <x:h>Note:</x:h> if history list mechanisms unnecessarily prevent users from |
| 5681 | | viewing stale resources, this will tend to force service authors |
| 5682 | | to avoid using HTTP expiration controls and cache controls when |
| 5683 | | they would otherwise like to. Service authors may consider it |
| 5684 | | important that users not be presented with error messages or |
| 5685 | | warning messages when they use navigation controls (such as BACK) |
| 5686 | | to view previously fetched resources. Even though sometimes such |
| 5687 | | resources ought not to cached, or ought to expire quickly, user |
| 5688 | | interface considerations may force service authors to resort to |
| 5689 | | other means of preventing caching (e.g. "once-only" URLs) in order |
| 5690 | | not to suffer the effects of improperly functioning history |
| 5691 | | mechanisms. |
| 5692 | | </t></list> |
| 5693 | | </t> |
| 5694 | | </section> |
| 5695 | | </section> |
| 5696 | | |
| 5697 | | |
| 5707 | | |
| 5708 | | <section title="Accept" anchor="header.accept"> |
| 5709 | | <iref primary="true" item="Accept header" x:for-anchor=""/> |
| 5710 | | <iref primary="true" item="Headers" subitem="Accept" x:for-anchor=""/> |
| 5711 | | <t> |
| 5712 | | The Accept request-header field can be used to specify certain media |
| 5713 | | types which are acceptable for the response. Accept headers can be |
| 5714 | | used to indicate that the request is specifically limited to a small |
| 5715 | | set of desired types, as in the case of a request for an in-line |
| 5716 | | image. |
| 5717 | | </t> |
| 5718 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept"/><iref primary="true" item="Grammar" subitem="media-range"/><iref primary="true" item="Grammar" subitem="accept-params"/><iref primary="true" item="Grammar" subitem="accept-extension"/> |
| 5719 | | Accept = "Accept" ":" |
| 5720 | | #( media-range [ accept-params ] ) |
| 5721 | | |
| 5722 | | media-range = ( "*/*" |
| 5723 | | | ( type "/" "*" ) |
| 5724 | | | ( type "/" subtype ) |
| 5725 | | ) *( ";" parameter ) |
| 5726 | | accept-params = ";" "q" "=" qvalue *( accept-extension ) |
| 5727 | | accept-extension = ";" token [ "=" ( token | quoted-string ) ] |
| 5728 | | </artwork></figure> |
| 5729 | | <t> |
| 5730 | | The asterisk "*" character is used to group media types into ranges, |
| 5731 | | with "*/*" indicating all media types and "type/*" indicating all |
| 5732 | | subtypes of that type. The media-range &MAY; include media type |
| 5733 | | parameters that are applicable to that range. |
| 5734 | | </t> |
| 5735 | | <t> |
| 5736 | | Each media-range &MAY; be followed by one or more accept-params, |
| 5737 | | beginning with the "q" parameter for indicating a relative quality |
| 5738 | | factor. The first "q" parameter (if any) separates the media-range |
| 5739 | | parameter(s) from the accept-params. Quality factors allow the user |
| 5740 | | or user agent to indicate the relative degree of preference for that |
| 5741 | | media-range, using the qvalue scale from 0 to 1 (<xref target="quality.values"/>). The |
| 5742 | | default value is q=1. |
| 5743 | | <list><t> |
| 5744 | | <x:h>Note:</x:h> Use of the "q" parameter name to separate media type |
| 5745 | | parameters from Accept extension parameters is due to historical |
| 5746 | | practice. Although this prevents any media type parameter named |
| 5747 | | "q" from being used with a media range, such an event is believed |
| 5748 | | to be unlikely given the lack of any "q" parameters in the IANA |
| 5749 | | media type registry and the rare usage of any media type |
| 5750 | | parameters in Accept. Future media types are discouraged from |
| 5751 | | registering any parameter named "q". |
| 5752 | | </t></list> |
| 5753 | | </t> |
| 5754 | | <t> |
| 5755 | | The example |
| 5756 | | </t> |
| 5757 | | <figure><artwork type="example"> |
| 5758 | | Accept: audio/*; q=0.2, audio/basic |
| 5759 | | </artwork></figure> |
| 5760 | | <t> |
| 5761 | | &SHOULD; be interpreted as "I prefer audio/basic, but send me any audio |
| 5762 | | type if it is the best available after an 80% mark-down in quality." |
| 5763 | | </t> |
| 5764 | | <t> |
| 5765 | | If no Accept header field is present, then it is assumed that the |
| 5766 | | client accepts all media types. If an Accept header field is present, |
| 5767 | | and if the server cannot send a response which is acceptable |
| 5768 | | according to the combined Accept field value, then the server &SHOULD; |
| 5769 | | send a 406 (not acceptable) response. |
| 5770 | | </t> |
| 5771 | | <t> |
| 5772 | | A more elaborate example is |
| 5773 | | </t> |
| 5774 | | <figure><artwork type="example"> |
| 5775 | | Accept: text/plain; q=0.5, text/html, |
| 5776 | | text/x-dvi; q=0.8, text/x-c |
| 5777 | | </artwork></figure> |
| 5778 | | <t> |
| 5779 | | Verbally, this would be interpreted as "text/html and text/x-c are |
| 5780 | | the preferred media types, but if they do not exist, then send the |
| 5781 | | text/x-dvi entity, and if that does not exist, send the text/plain |
| 5782 | | entity." |
| 5783 | | </t> |
| 5784 | | <t> |
| 5785 | | Media ranges can be overridden by more specific media ranges or |
| 5786 | | specific media types. If more than one media range applies to a given |
| 5787 | | type, the most specific reference has precedence. For example, |
| 5788 | | </t> |
| 5789 | | <figure><artwork type="example"> |
| 5790 | | Accept: text/*, text/html, text/html;level=1, */* |
| 5791 | | </artwork></figure> |
| 5792 | | <t> |
| 5793 | | have the following precedence: |
| 5794 | | </t> |
| 5795 | | <figure><artwork type="example"> |
| 5796 | | 1) text/html;level=1 |
| 5797 | | 2) text/html |
| 5798 | | 3) text/* |
| 5799 | | 4) */* |
| 5800 | | </artwork></figure> |
| 5801 | | <t> |
| 5802 | | The media type quality factor associated with a given type is |
| 5803 | | determined by finding the media range with the highest precedence |
| 5804 | | which matches that type. For example, |
| 5805 | | </t> |
| 5806 | | <figure><artwork type="example"> |
| 5807 | | Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, |
| 5808 | | text/html;level=2;q=0.4, */*;q=0.5 |
| 5809 | | </artwork></figure> |
| 5810 | | <t> |
| 5811 | | would cause the following values to be associated: |
| 5812 | | </t> |
| 5813 | | <figure><artwork type="example"> |
| 5814 | | text/html;level=1 = 1 |
| 5815 | | text/html = 0.7 |
| 5816 | | text/plain = 0.3 |
| 5817 | | image/jpeg = 0.5 |
| 5818 | | text/html;level=2 = 0.4 |
| 5819 | | text/html;level=3 = 0.7 |
| 5820 | | </artwork></figure> |
| 5821 | | <t> |
| 5822 | | <x:h>Note:</x:h> A user agent might be provided with a default set of quality |
| 5823 | | values for certain media ranges. However, unless the user agent is |
| 5824 | | a closed system which cannot interact with other rendering agents, |
| 5825 | | this default set ought to be configurable by the user. |
| 5826 | | </t> |
| 5827 | | </section> |
| 5828 | | |
| 5829 | | <section title="Accept-Charset" anchor="header.accept-charset"> |
| 5830 | | <iref primary="true" item="Accept-Charset header" x:for-anchor=""/> |
| 5831 | | <iref primary="true" item="Headers" subitem="Accept-Charset" x:for-anchor=""/> |
| 5832 | | <t> |
| 5833 | | The Accept-Charset request-header field can be used to indicate what |
| 5834 | | character sets are acceptable for the response. This field allows |
| 5835 | | clients capable of understanding more comprehensive or special-purpose |
| 5836 | | character sets to signal that capability to a server which is |
| 5837 | | capable of representing documents in those character sets. |
| 5838 | | </t> |
| 5839 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Charset"/> |
| 5840 | | Accept-Charset = "Accept-Charset" ":" |
| 5841 | | 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) |
| 5842 | | </artwork></figure> |
| 5843 | | <t> |
| 5844 | | Character set values are described in <xref target="character.sets"/>. Each charset &MAY; |
| 5845 | | be given an associated quality value which represents the user's |
| 5846 | | preference for that charset. The default value is q=1. An example is |
| 5847 | | </t> |
| 5848 | | <figure><artwork type="example"> |
| 5849 | | Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 |
| 5850 | | </artwork></figure> |
| 5851 | | <t> |
| 5852 | | The special value "*", if present in the Accept-Charset field, |
| 5853 | | matches every character set (including ISO-8859-1) which is not |
| 5854 | | mentioned elsewhere in the Accept-Charset field. If no "*" is present |
| 5855 | | in an Accept-Charset field, then all character sets not explicitly |
| 5856 | | mentioned get a quality value of 0, except for ISO-8859-1, which gets |
| 5857 | | a quality value of 1 if not explicitly mentioned. |
| 5858 | | </t> |
| 5859 | | <t> |
| 5860 | | If no Accept-Charset header is present, the default is that any |
| 5861 | | character set is acceptable. If an Accept-Charset header is present, |
| 5862 | | and if the server cannot send a response which is acceptable |
| 5863 | | according to the Accept-Charset header, then the server &SHOULD; send |
| 5864 | | an error response with the 406 (not acceptable) status code, though |
| 5865 | | the sending of an unacceptable response is also allowed. |
| 5866 | | </t> |
| 5867 | | </section> |
| 5868 | | |
| 5869 | | <section title="Accept-Encoding" anchor="header.accept-encoding"> |
| 5870 | | <iref primary="true" item="Accept-Encoding header" x:for-anchor=""/> |
| 5871 | | <iref primary="true" item="Headers" subitem="Accept-Encoding" x:for-anchor=""/> |
| 5872 | | <t> |
| 5873 | | The Accept-Encoding request-header field is similar to Accept, but |
| 5874 | | restricts the content-codings (<xref target="content.codings"/>) that are acceptable in |
| 5875 | | the response. |
| 5876 | | </t> |
| 5877 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Encoding"/><iref primary="true" item="Grammar" subitem="codings"/> |
| 5878 | | Accept-Encoding = "Accept-Encoding" ":" |
| 5879 | | 1#( codings [ ";" "q" "=" qvalue ] ) |
| 5880 | | codings = ( content-coding | "*" ) |
| 5881 | | </artwork></figure> |
| 5882 | | <t> |
| 5883 | | Examples of its use are: |
| 5884 | | </t> |
| 5885 | | <figure><artwork type="example"> |
| 5886 | | Accept-Encoding: compress, gzip |
| 5887 | | Accept-Encoding: |
| 5888 | | Accept-Encoding: * |
| 5889 | | Accept-Encoding: compress;q=0.5, gzip;q=1.0 |
| 5890 | | Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 |
| 5891 | | </artwork></figure> |
| 5892 | | <t> |
| 5893 | | A server tests whether a content-coding is acceptable, according to |
| 5894 | | an Accept-Encoding field, using these rules: |
| 5895 | | <list style="numbers"> |
| 5896 | | <t>If the content-coding is one of the content-codings listed in |
| 5897 | | the Accept-Encoding field, then it is acceptable, unless it is |
| 5898 | | accompanied by a qvalue of 0. (As defined in <xref target="quality.values"/>, a |
| 5899 | | qvalue of 0 means "not acceptable.")</t> |
| 5900 | | |
| 5901 | | <t>The special "*" symbol in an Accept-Encoding field matches any |
| 5902 | | available content-coding not explicitly listed in the header |
| 5903 | | field.</t> |
| 5904 | | |
| 5905 | | <t>If multiple content-codings are acceptable, then the acceptable |
| 5906 | | content-coding with the highest non-zero qvalue is preferred.</t> |
| 5907 | | |
| 5908 | | <t>The "identity" content-coding is always acceptable, unless |
| 5909 | | specifically refused because the Accept-Encoding field includes |
| 5910 | | "identity;q=0", or because the field includes "*;q=0" and does |
| 5911 | | not explicitly include the "identity" content-coding. If the |
| 5912 | | Accept-Encoding field-value is empty, then only the "identity" |
| 5913 | | encoding is acceptable.</t> |
| 5914 | | </list> |
| 5915 | | </t> |
| 5916 | | <t> |
| 5917 | | If an Accept-Encoding field is present in a request, and if the |
| 5918 | | server cannot send a response which is acceptable according to the |
| 5919 | | Accept-Encoding header, then the server &SHOULD; send an error response |
| 5920 | | with the 406 (Not Acceptable) status code. |
| 5921 | | </t> |
| 5922 | | <t> |
| 5923 | | If no Accept-Encoding field is present in a request, the server &MAY; |
| 5924 | | assume that the client will accept any content coding. In this case, |
| 5925 | | if "identity" is one of the available content-codings, then the |
| 5926 | | server &SHOULD; use the "identity" content-coding, unless it has |
| 5927 | | additional information that a different content-coding is meaningful |
| 5928 | | to the client. |
| 5929 | | <list><t> |
| 5930 | | <x:h>Note:</x:h> If the request does not include an Accept-Encoding field, |
| 5931 | | and if the "identity" content-coding is unavailable, then |
| 5932 | | content-codings commonly understood by HTTP/1.0 clients (i.e., |
| 5933 | | "gzip" and "compress") are preferred; some older clients |
| 5934 | | improperly display messages sent with other content-codings. The |
| 5935 | | server might also make this decision based on information about |
| 5936 | | the particular user-agent or client. |
| 5937 | | </t><t> |
| 5938 | | <x:h>Note:</x:h> Most HTTP/1.0 applications do not recognize or obey qvalues |
| 5939 | | associated with content-codings. This means that qvalues will not |
| 5940 | | work and are not permitted with x-gzip or x-compress. |
| 5941 | | </t></list> |
| 5942 | | </t> |
| 5943 | | </section> |
| 5944 | | |
| 5945 | | <section title="Accept-Language" anchor="header.accept-language"> |
| 5946 | | <iref primary="true" item="Accept-Language header" x:for-anchor=""/> |
| 5947 | | <iref primary="true" item="Headers" subitem="Accept-Language" x:for-anchor=""/> |
| 5948 | | <t> |
| 5949 | | The Accept-Language request-header field is similar to Accept, but |
| 5950 | | restricts the set of natural languages that are preferred as a |
| 5951 | | response to the request. Language tags are defined in <xref target="language.tags"/>. |
| 5952 | | </t> |
| 5953 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Language"/><iref primary="true" item="Grammar" subitem="language-range"/> |
| 5954 | | Accept-Language = "Accept-Language" ":" |
| 5955 | | 1#( language-range [ ";" "q" "=" qvalue ] ) |
| 5956 | | language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) |
| 5957 | | </artwork></figure> |
| 5958 | | <t> |
| 5959 | | Each language-range &MAY; be given an associated quality value which |
| 5960 | | represents an estimate of the user's preference for the languages |
| 5961 | | specified by that range. The quality value defaults to "q=1". For |
| 5962 | | example, |
| 5963 | | </t> |
| 5964 | | <figure><artwork type="example"> |
| 5965 | | Accept-Language: da, en-gb;q=0.8, en;q=0.7 |
| 5966 | | </artwork></figure> |
| 5967 | | <t> |
| 5968 | | would mean: "I prefer Danish, but will accept British English and |
| 5969 | | other types of English." A language-range matches a language-tag if |
| 5970 | | it exactly equals the tag, or if it exactly equals a prefix of the |
| 5971 | | tag such that the first tag character following the prefix is "-". |
| 5972 | | The special range "*", if present in the Accept-Language field, |
| 5973 | | matches every tag not matched by any other range present in the |
| 5974 | | Accept-Language field. |
| 5975 | | <list><t> |
| 5976 | | <x:h>Note:</x:h> This use of a prefix matching rule does not imply that |
| 5977 | | language tags are assigned to languages in such a way that it is |
| 5978 | | always true that if a user understands a language with a certain |
| 5979 | | tag, then this user will also understand all languages with tags |
| 5980 | | for which this tag is a prefix. The prefix rule simply allows the |
| 5981 | | use of prefix tags if this is the case. |
| 5982 | | </t></list> |
| 5983 | | </t> |
| 5984 | | <t> |
| 5985 | | The language quality factor assigned to a language-tag by the |
| 5986 | | Accept-Language field is the quality value of the longest language-range |
| 5987 | | in the field that matches the language-tag. If no language-range |
| 5988 | | in the field matches the tag, the language quality factor |
| 5989 | | assigned is 0. If no Accept-Language header is present in the |
| 5990 | | request, the server |
| 5991 | | &SHOULD; assume that all languages are equally acceptable. If an |
| 5992 | | Accept-Language header is present, then all languages which are |
| 5993 | | assigned a quality factor greater than 0 are acceptable. |
| 5994 | | </t> |
| 5995 | | <t> |
| 5996 | | It might be contrary to the privacy expectations of the user to send |
| 5997 | | an Accept-Language header with the complete linguistic preferences of |
| 5998 | | the user in every request. For a discussion of this issue, see |
| 5999 | | <xref target="privacy.issues.connected.to.accept.headers"/>. |
| 6000 | | </t> |
| 6001 | | <t> |
| 6002 | | As intelligibility is highly dependent on the individual user, it is |
| 6003 | | recommended that client applications make the choice of linguistic |
| 6004 | | preference available to the user. If the choice is not made |
| 6005 | | available, then the Accept-Language header field &MUST-NOT; be given in |
| 6006 | | the request. |
| 6007 | | <list><t> |
| 6008 | | <x:h>Note:</x:h> When making the choice of linguistic preference available to |
| 6009 | | the user, we remind implementors of the fact that users are not |
| 6010 | | familiar with the details of language matching as described above, |
| 6011 | | and should provide appropriate guidance. As an example, users |
| 6012 | | might assume that on selecting "en-gb", they will be served any |
| 6013 | | kind of English document if British English is not available. A |
| 6014 | | user agent might suggest in such a case to add "en" to get the |
| 6015 | | best matching behavior. |
| 6016 | | </t></list> |
| 6017 | | </t> |
| 6018 | | </section> |
| 6019 | | |
| 6020 | | <section title="Accept-Ranges" anchor="header.accept-ranges"> |
| 6021 | | <iref primary="true" item="Accept-Ranges header" x:for-anchor=""/> |
| 6022 | | <iref primary="true" item="Headers" subitem="Accept-Ranges" x:for-anchor=""/> |
| 6023 | | <t> |
| 6024 | | The Accept-Ranges response-header field allows the server to |
| 6025 | | indicate its acceptance of range requests for a resource: |
| 6026 | | </t> |
| 6027 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Ranges"/><iref primary="true" item="Grammar" subitem="acceptable-ranges"/> |
| 6028 | | Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges |
| 6029 | | acceptable-ranges = 1#range-unit | "none" |
| 6030 | | </artwork></figure> |
| 6031 | | <t> |
| 6032 | | Origin servers that accept byte-range requests &MAY; send |
| 6033 | | </t> |
| 6034 | | <figure><artwork type="example"> |
| 6035 | | Accept-Ranges: bytes |
| 6036 | | </artwork></figure> |
| 6037 | | <t> |
| 6038 | | but are not required to do so. Clients &MAY; generate byte-range |
| 6039 | | requests without having received this header for the resource |
| 6040 | | involved. Range units are defined in <xref target="range.units"/>. |
| 6041 | | </t> |
| 6042 | | <t> |
| 6043 | | Servers that do not accept any kind of range request for a |
| 6044 | | resource &MAY; send |
| 6045 | | </t> |
| 6046 | | <figure><artwork type="example"> |
| 6047 | | Accept-Ranges: none |
| 6048 | | </artwork></figure> |
| 6049 | | <t> |
| 6050 | | to advise the client not to attempt a range request. |
| 6051 | | </t> |
| 6052 | | </section> |
| 6053 | | |
| 6054 | | <section title="Age" anchor="header.age"> |
| 6055 | | <iref primary="true" item="Age header" x:for-anchor=""/> |
| 6056 | | <iref primary="true" item="Headers" subitem="Age" x:for-anchor=""/> |
| 6057 | | <t> |
| 6058 | | The Age response-header field conveys the sender's estimate of the |
| 6059 | | amount of time since the response (or its revalidation) was |
| 6060 | | generated at the origin server. A cached response is "fresh" if |
| 6061 | | its age does not exceed its freshness lifetime. Age values are |
| 6062 | | calculated as specified in <xref target="age.calculations"/>. |
| 6063 | | </t> |
| 6064 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Age"/><iref primary="true" item="Grammar" subitem="age-value"/> |
| 6065 | | Age = "Age" ":" age-value |
| 6066 | | age-value = delta-seconds |
| 6067 | | </artwork></figure> |
| 6068 | | <t> |
| 6069 | | Age values are non-negative decimal integers, representing time in |
| 6070 | | seconds. |
| 6071 | | </t> |
| 6072 | | <t> |
| 6073 | | If a cache receives a value larger than the largest positive |
| 6074 | | integer it can represent, or if any of its age calculations |
| 6075 | | overflows, it &MUST; transmit an Age header with a value of |
| 6076 | | 2147483648 (2^31). An HTTP/1.1 server that includes a cache &MUST; |
| 6077 | | include an Age header field in every response generated from its |
| 6078 | | own cache. Caches &SHOULD; use an arithmetic type of at least 31 |
| 6079 | | bits of range. |
| 6080 | | </t> |
| 6081 | | </section> |
| 6120 | | </section> |
| 6121 | | |
| 6122 | | <section title="Authorization" anchor="header.authorization"> |
| 6123 | | <iref primary="true" item="Authorization header" x:for-anchor=""/> |
| 6124 | | <iref primary="true" item="Headers" subitem="Authorization" x:for-anchor=""/> |
| 6125 | | <t> |
| 6126 | | A user agent that wishes to authenticate itself with a server-- |
| 6127 | | usually, but not necessarily, after receiving a 401 response--does |
| 6128 | | so by including an Authorization request-header field with the |
| 6129 | | request. The Authorization field value consists of credentials |
| 6130 | | containing the authentication information of the user agent for |
| 6131 | | the realm of the resource being requested. |
| 6132 | | </t> |
| 6133 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Authorization"/> |
| 6134 | | Authorization = "Authorization" ":" credentials |
| 6135 | | </artwork></figure> |
| 6136 | | <t> |
| 6137 | | HTTP access authentication is described in "HTTP Authentication: |
| 6138 | | Basic and Digest Access Authentication" <xref target="RFC2617"/>. If a request is |
| 6139 | | authenticated and a realm specified, the same credentials &SHOULD; |
| 6140 | | be valid for all other requests within this realm (assuming that |
| 6141 | | the authentication scheme itself does not require otherwise, such |
| 6142 | | as credentials that vary according to a challenge value or using |
| 6143 | | synchronized clocks). |
| 6144 | | </t> |
| 6145 | | <t> |
| 6146 | | When a shared cache (see <xref target="shared.and.non-shared.caches"/>) receives a request |
| 6147 | | containing an Authorization field, it &MUST-NOT; return the |
| 6148 | | corresponding response as a reply to any other request, unless one |
| 6149 | | of the following specific exceptions holds: |
| 6150 | | </t> |
| 6151 | | <t> |
| 6152 | | <list style="numbers"> |
| 6153 | | <t>If the response includes the "s-maxage" cache-control |
| 6154 | | directive, the cache &MAY; use that response in replying to a |
| 6155 | | subsequent request. But (if the specified maximum age has |
| 6156 | | passed) a proxy cache &MUST; first revalidate it with the origin |
| 6157 | | server, using the request-headers from the new request to allow |
| 6158 | | the origin server to authenticate the new request. (This is the |
| 6159 | | defined behavior for s-maxage.) If the response includes "s-maxage=0", |
| 6160 | | the proxy &MUST; always revalidate it before re-using |
| 6161 | | it.</t> |
| 6162 | | |
| 6163 | | <t>If the response includes the "must-revalidate" cache-control |
| 6164 | | directive, the cache &MAY; use that response in replying to a |
| 6165 | | subsequent request. But if the response is stale, all caches |
| 6166 | | &MUST; first revalidate it with the origin server, using the |
| 6167 | | request-headers from the new request to allow the origin server |
| 6168 | | to authenticate the new request.</t> |
| 6169 | | |
| 6170 | | <t>If the response includes the "public" cache-control directive, |
| 6171 | | it &MAY; be returned in reply to any subsequent request.</t> |
| 6172 | | </list> |
| 6173 | | </t> |
| 6174 | | </section> |
| 6175 | | |
| 6176 | | <section title="Cache-Control" anchor="header.cache-control"> |
| 6177 | | <iref primary="true" item="Cache-Control header" x:for-anchor=""/> |
| 6178 | | <iref primary="true" item="Headers" subitem="Cache-Control" x:for-anchor=""/> |
| 6179 | | <t> |
| 6180 | | The Cache-Control general-header field is used to specify directives |
| 6181 | | that &MUST; be obeyed by all caching mechanisms along the |
| 6182 | | request/response chain. The directives specify behavior intended to |
| 6183 | | prevent caches from adversely interfering with the request or |
| 6184 | | response. These directives typically override the default caching |
| 6185 | | algorithms. Cache directives are unidirectional in that the presence |
| 6186 | | of a directive in a request does not imply that the same directive is |
| 6187 | | to be given in the response. |
| 6188 | | <list><t> |
| 6189 | | Note that HTTP/1.0 caches might not implement Cache-Control and |
| 6190 | | might only implement Pragma: no-cache (see <xref target="header.pragma"/>). |
| 6191 | | </t></list> |
| 6192 | | </t> |
| 6193 | | <t> |
| 6194 | | Cache directives &MUST; be passed through by a proxy or gateway |
| 6195 | | application, regardless of their significance to that application, |
| 6196 | | since the directives might be applicable to all recipients along the |
| 6197 | | request/response chain. It is not possible to specify a cache-directive |
| 6198 | | for a specific cache. |
| 6199 | | </t> |
| 6200 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Cache-Control"/><iref primary="true" item="Grammar" subitem="cache-directive"/><iref primary="true" item="Grammar" subitem="cache-request-directive"/><iref primary="true" item="Grammar" subitem="cache-response-directive"/><iref primary="true" item="Grammar" subitem="cache-extension"/> |
| 6201 | | Cache-Control = "Cache-Control" ":" 1#cache-directive |
| 6202 | | |
| 6203 | | cache-directive = cache-request-directive |
| 6204 | | | cache-response-directive |
| 6205 | | |
| 6206 | | cache-request-directive = |
| 6207 | | "no-cache" ; <xref target="what.is.cacheable"/> |
| 6208 | | | "no-store" ; <xref target="what.may.be.stored.by.caches"/> |
| 6209 | | | "max-age" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/>, <xref format="counter" target="cache.revalidation.and.reload.controls"/> |
| 6210 | | | "max-stale" [ "=" delta-seconds ] ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6211 | | | "min-fresh" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6212 | | | "no-transform" ; <xref target="no-transform.directive"/> |
| 6213 | | | "only-if-cached" ; <xref target="cache.revalidation.and.reload.controls"/> |
| 6214 | | | cache-extension ; <xref target="cache.control.extensions"/> |
| 6215 | | |
| 6216 | | cache-response-directive = |
| 6217 | | "public" ; <xref target="what.is.cacheable"/> |
| 6218 | | | "private" [ "=" <"> 1#field-name <"> ] ; <xref target="what.is.cacheable"/> |
| 6219 | | | "no-cache" [ "=" <"> 1#field-name <"> ]; <xref target="what.is.cacheable"/> |
| 6220 | | | "no-store" ; <xref target="what.may.be.stored.by.caches"/> |
| 6221 | | | "no-transform" ; <xref target="no-transform.directive"/> |
| 6222 | | | "must-revalidate" ; <xref target="cache.revalidation.and.reload.controls"/> |
| 6223 | | | "proxy-revalidate" ; <xref target="cache.revalidation.and.reload.controls"/> |
| 6224 | | | "max-age" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6225 | | | "s-maxage" "=" delta-seconds ; <xref target="modifications.of.the.basic.expiration.mechanism"/> |
| 6226 | | | cache-extension ; <xref target="cache.control.extensions"/> |
| 6227 | | |
| 6228 | | cache-extension = token [ "=" ( token | quoted-string ) ] |
| 6229 | | </artwork></figure> |
| 6230 | | <t> |
| 6231 | | When a directive appears without any 1#field-name parameter, the |
| 6232 | | directive applies to the entire request or response. When such a |
| 6233 | | directive appears with a 1#field-name parameter, it applies only to |
| 6234 | | the named field or fields, and not to the rest of the request or |
| 6235 | | response. This mechanism supports extensibility; implementations of |
| 6236 | | future versions of the HTTP protocol might apply these directives to |
| 6237 | | header fields not defined in HTTP/1.1. |
| 6238 | | </t> |
| 6239 | | <t> |
| 6240 | | The cache-control directives can be broken down into these general |
| 6241 | | categories: |
| 6242 | | <list style="symbols"> |
| 6243 | | <t>Restrictions on what are cacheable; these may only be imposed by |
| 6244 | | the origin server.</t> |
| 6245 | | |
| 6246 | | <t>Restrictions on what may be stored by a cache; these may be |
| 6247 | | imposed by either the origin server or the user agent.</t> |
| 6248 | | |
| 6249 | | <t>Modifications of the basic expiration mechanism; these may be |
| 6250 | | imposed by either the origin server or the user agent.</t> |
| 6251 | | |
| 6252 | | <t>Controls over cache revalidation and reload; these may only be |
| 6253 | | imposed by a user agent.</t> |
| 6254 | | |
| 6255 | | <t>Control over transformation of entities.</t> |
| 6256 | | |
| 6257 | | <t>Extensions to the caching system.</t> |
| 6258 | | </list> |
| 6259 | | </t> |
| 6260 | | |
| 6261 | | <section title="What is Cacheable" anchor="what.is.cacheable"> |
| 6262 | | <t> |
| 6263 | | By default, a response is cacheable if the requirements of the |
| 6264 | | request method, request header fields, and the response status |
| 6265 | | indicate that it is cacheable. <xref target="response.cacheability"/> summarizes these defaults |
| 6266 | | for cacheability. The following Cache-Control response directives |
| 6267 | | allow an origin server to override the default cacheability of a |
| 6268 | | response: |
| 6269 | | </t> |
| 6270 | | <t> |
| 6271 | | <iref item="Cache Directives" subitem="public" primary="true"/> |
| 6272 | | <iref item="public" subitem="Cache Directive" primary="true"/> |
| 6273 | | public |
| 6274 | | <list><t> |
| 6275 | | Indicates that the response &MAY; be cached by any cache, even if it |
| 6276 | | would normally be non-cacheable or cacheable only within a non-shared |
| 6277 | | cache. (See also Authorization, <xref target="header.authorization"/>, for |
| 6278 | | additional details.) |
| 6279 | | </t></list> |
| 6280 | | </t> |
| 6281 | | <t> |
| 6282 | | <iref item="Cache Directives" subitem="private" primary="true"/> |
| 6283 | | <iref item="private" subitem="Cache Directive" primary="true"/> |
| 6284 | | private |
| 6285 | | <list><t> |
| 6286 | | Indicates that all or part of the response message is intended for |
| 6287 | | a single user and &MUST-NOT; be cached by a shared cache. This |
| 6288 | | allows an origin server to state that the specified parts of the |
| 6289 | | response are intended for only one user and are not a valid |
| 6290 | | response for requests by other users. A private (non-shared) cache |
| 6291 | | &MAY; cache the response. |
| 6292 | | </t><t> |
| 6293 | | <x:h>Note:</x:h> This usage of the word private only controls where the |
| 6294 | | response may be cached, and cannot ensure the privacy of the |
| 6295 | | message content. |
| 6296 | | </t></list> |
| 6297 | | </t> |
| 6298 | | <t> |
| 6299 | | <iref item="Cache Directives" subitem="no-cache" primary="true"/> |
| 6300 | | <iref item="no-cache" subitem="Cache Directive" primary="true"/> |
| 6301 | | no-cache |
| 6302 | | <list><t> |
| 6303 | | If the no-cache directive does not specify a field-name, then a |
| 6304 | | cache &MUST-NOT; use the response to satisfy a subsequent request |
| 6305 | | without successful revalidation with the origin server. This |
| 6306 | | allows an origin server to prevent caching even by caches that |
| 6307 | | have been configured to return stale responses to client requests. |
| 6308 | | </t><t> |
| 6309 | | If the no-cache directive does specify one or more field-names, |
| 6310 | | then a cache &MAY; use the response to satisfy a subsequent request, |
| 6311 | | subject to any other restrictions on caching. However, the |
| 6312 | | specified field-name(s) &MUST-NOT; be sent in the response to a |
| 6313 | | subsequent request without successful revalidation with the origin |
| 6314 | | server. This allows an origin server to prevent the re-use of |
| 6315 | | certain header fields in a response, while still allowing caching |
| 6316 | | of the rest of the response. |
| 6317 | | <list><t> |
| 6318 | | <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey this |
| 6319 | | directive. |
| 6320 | | </t></list> |
| 6321 | | </t></list> |
| 6322 | | </t> |
| 6323 | | </section> |
| 6324 | | |
| 6325 | | <section title="What May be Stored by Caches" anchor="what.may.be.stored.by.caches"> |
| 6326 | | <t> |
| 6327 | | <iref item="Cache Directives" subitem="no-store" primary="true"/> |
| 6328 | | <iref item="no-store" subitem="Cache Directive" primary="true"/> |
| 6329 | | no-store |
| 6330 | | <list><t> |
| 6331 | | The purpose of the no-store directive is to prevent the |
| 6332 | | inadvertent release or retention of sensitive information (for |
| 6333 | | example, on backup tapes). The no-store directive applies to the |
| 6334 | | entire message, and &MAY; be sent either in a response or in a |
| 6335 | | request. If sent in a request, a cache &MUST-NOT; store any part of |
| 6336 | | either this request or any response to it. If sent in a response, |
| 6337 | | a cache &MUST-NOT; store any part of either this response or the |
| 6338 | | request that elicited it. This directive applies to both non-shared |
| 6339 | | and shared caches. "&MUST-NOT; store" in this context means |
| 6340 | | that the cache &MUST-NOT; intentionally store the information in |
| 6341 | | non-volatile storage, and &MUST; make a best-effort attempt to |
| 6342 | | remove the information from volatile storage as promptly as |
| 6343 | | possible after forwarding it. |
| 6344 | | </t><t> |
| 6345 | | Even when this directive is associated with a response, users |
| 6346 | | might explicitly store such a response outside of the caching |
| 6347 | | system (e.g., with a "Save As" dialog). History buffers &MAY; store |
| 6348 | | such responses as part of their normal operation. |
| 6349 | | </t><t> |
| 6350 | | The purpose of this directive is to meet the stated requirements |
| 6351 | | of certain users and service authors who are concerned about |
| 6352 | | accidental releases of information via unanticipated accesses to |
| 6353 | | cache data structures. While the use of this directive might |
| 6354 | | improve privacy in some cases, we caution that it is NOT in any |
| 6355 | | way a reliable or sufficient mechanism for ensuring privacy. In |
| 6356 | | particular, malicious or compromised caches might not recognize or |
| 6357 | | obey this directive, and communications networks might be |
| 6358 | | vulnerable to eavesdropping. |
| 6359 | | </t></list> |
| 6360 | | </t> |
| 6361 | | </section> |
| 6362 | | |
| 6363 | | <section title="Modifications of the Basic Expiration Mechanism" anchor="modifications.of.the.basic.expiration.mechanism"> |
| 6364 | | <t> |
| 6365 | | The expiration time of an entity &MAY; be specified by the origin |
| 6366 | | server using the Expires header (see <xref target="header.expires"/>). Alternatively, |
| 6367 | | it &MAY; be specified using the max-age directive in a response. When |
| 6368 | | the max-age cache-control directive is present in a cached response, |
| 6369 | | the response is stale if its current age is greater than the age |
| 6370 | | value given (in seconds) at the time of a new request for that |
| 6371 | | resource. The max-age directive on a response implies that the |
| 6372 | | response is cacheable (i.e., "public") unless some other, more |
| 6373 | | restrictive cache directive is also present. |
| 6374 | | </t> |
| 6375 | | <t> |
| 6376 | | If a response includes both an Expires header and a max-age |
| 6377 | | directive, the max-age directive overrides the Expires header, even |
| 6378 | | if the Expires header is more restrictive. This rule allows an origin |
| 6379 | | server to provide, for a given response, a longer expiration time to |
| 6380 | | an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be |
| 6381 | | useful if certain HTTP/1.0 caches improperly calculate ages or |
| 6382 | | expiration times, perhaps due to desynchronized clocks. |
| 6383 | | </t> |
| 6384 | | <t> |
| 6385 | | Many HTTP/1.0 cache implementations will treat an Expires value that |
| 6386 | | is less than or equal to the response Date value as being equivalent |
| 6387 | | to the Cache-Control response directive "no-cache". If an HTTP/1.1 |
| 6388 | | cache receives such a response, and the response does not include a |
| 6389 | | Cache-Control header field, it &SHOULD; consider the response to be |
| 6390 | | non-cacheable in order to retain compatibility with HTTP/1.0 servers. |
| 6391 | | <list><t> |
| 6392 | | <x:h>Note:</x:h> An origin server might wish to use a relatively new HTTP |
| 6393 | | cache control feature, such as the "private" directive, on a |
| 6394 | | network including older caches that do not understand that |
| 6395 | | feature. The origin server will need to combine the new feature |
| 6396 | | with an Expires field whose value is less than or equal to the |
| 6397 | | Date value. This will prevent older caches from improperly |
| 6398 | | caching the response. |
| 6399 | | </t></list> |
| 6400 | | </t> |
| 6401 | | <t> |
| 6402 | | <iref item="Cache Directives" subitem="s-maxage" primary="true"/> |
| 6403 | | <iref item="s-maxage" subitem="Cache Directive" primary="true"/> |
| 6404 | | s-maxage |
| 6405 | | <list><t> |
| 6406 | | If a response includes an s-maxage directive, then for a shared |
| 6407 | | cache (but not for a private cache), the maximum age specified by |
| 6408 | | this directive overrides the maximum age specified by either the |
| 6409 | | max-age directive or the Expires header. The s-maxage directive |
| 6410 | | also implies the semantics of the proxy-revalidate directive (see |
| 6411 | | <xref target="cache.revalidation.and.reload.controls"/>), i.e., that the shared cache must not use the |
| 6412 | | entry after it becomes stale to respond to a subsequent request |
| 6413 | | without first revalidating it with the origin server. The s-maxage |
| 6414 | | directive is always ignored by a private cache. |
| 6415 | | </t></list> |
| 6416 | | </t> |
| 6417 | | <t> |
| 6418 | | Note that most older caches, not compliant with this specification, |
| 6419 | | do not implement any cache-control directives. An origin server |
| 6420 | | wishing to use a cache-control directive that restricts, but does not |
| 6421 | | prevent, caching by an HTTP/1.1-compliant cache &MAY; exploit the |
| 6422 | | requirement that the max-age directive overrides the Expires header, |
| 6423 | | and the fact that pre-HTTP/1.1-compliant caches do not observe the |
| 6424 | | max-age directive. |
| 6425 | | </t> |
| 6426 | | <t> |
| 6427 | | Other directives allow a user agent to modify the basic expiration |
| 6428 | | mechanism. These directives &MAY; be specified on a request: |
| 6429 | | </t> |
| 6430 | | <t> |
| 6431 | | <iref item="Cache Directives" subitem="max-age" primary="true"/> |
| 6432 | | <iref item="max-age" subitem="Cache Directive" primary="true"/> |
| 6433 | | max-age |
| 6434 | | <list><t> |
| 6435 | | Indicates that the client is willing to accept a response whose |
| 6436 | | age is no greater than the specified time in seconds. Unless max-stale |
| 6437 | | directive is also included, the client is not willing to |
| 6438 | | accept a stale response. |
| 6439 | | </t></list> |
| 6440 | | </t> |
| 6441 | | <t> |
| 6442 | | <iref item="Cache Directives" subitem="min-fresh" primary="true"/> |
| 6443 | | <iref item="min-fresh" subitem="Cache Directive" primary="true"/> |
| 6444 | | min-fresh |
| 6445 | | <list><t> |
| 6446 | | Indicates that the client is willing to accept a response whose |
| 6447 | | freshness lifetime is no less than its current age plus the |
| 6448 | | specified time in seconds. That is, the client wants a response |
| 6449 | | that will still be fresh for at least the specified number of |
| 6450 | | seconds. |
| 6451 | | </t></list> |
| 6452 | | </t> |
| 6453 | | <t> |
| 6454 | | <iref item="Cache Directives" subitem="max-stale" primary="true"/> |
| 6455 | | <iref item="max-stale" subitem="Cache Directive" primary="true"/> |
| 6456 | | max-stale |
| 6457 | | <list><t> |
| 6458 | | Indicates that the client is willing to accept a response that has |
| 6459 | | exceeded its expiration time. If max-stale is assigned a value, |
| 6460 | | then the client is willing to accept a response that has exceeded |
| 6461 | | its expiration time by no more than the specified number of |
| 6462 | | seconds. If no value is assigned to max-stale, then the client is |
| 6463 | | willing to accept a stale response of any age. |
| 6464 | | </t></list> |
| 6465 | | </t> |
| 6466 | | <t> |
| 6467 | | If a cache returns a stale response, either because of a max-stale |
| 6468 | | directive on a request, or because the cache is configured to |
| 6469 | | override the expiration time of a response, the cache &MUST; attach a |
| 6470 | | Warning header to the stale response, using Warning 110 (Response is |
| 6471 | | stale). |
| 6472 | | </t> |
| 6473 | | <t> |
| 6474 | | A cache &MAY; be configured to return stale responses without |
| 6475 | | validation, but only if this does not conflict with any "MUST"-level |
| 6476 | | requirements concerning cache validation (e.g., a "must-revalidate" |
| 6477 | | cache-control directive). |
| 6478 | | </t> |
| 6479 | | <t> |
| 6480 | | If both the new request and the cached entry include "max-age" |
| 6481 | | directives, then the lesser of the two values is used for determining |
| 6482 | | the freshness of the cached entry for that request. |
| 6483 | | </t> |
| 6484 | | </section> |
| 6485 | | |
| 6486 | | <section title="Cache Revalidation and Reload Controls" anchor="cache.revalidation.and.reload.controls"> |
| 6487 | | <t> |
| 6488 | | Sometimes a user agent might want or need to insist that a cache |
| 6489 | | revalidate its cache entry with the origin server (and not just with |
| 6490 | | the next cache along the path to the origin server), or to reload its |
| 6491 | | cache entry from the origin server. End-to-end revalidation might be |
| 6492 | | necessary if either the cache or the origin server has overestimated |
| 6493 | | the expiration time of the cached response. End-to-end reload may be |
| 6494 | | necessary if the cache entry has become corrupted for some reason. |
| 6495 | | </t> |
| 6496 | | <t> |
| 6497 | | End-to-end revalidation may be requested either when the client does |
| 6498 | | not have its own local cached copy, in which case we call it |
| 6499 | | "unspecified end-to-end revalidation", or when the client does have a |
| 6500 | | local cached copy, in which case we call it "specific end-to-end |
| 6501 | | revalidation." |
| 6502 | | </t> |
| 6503 | | <t> |
| 6504 | | The client can specify these three kinds of action using Cache-Control |
| 6505 | | request directives: |
| 6506 | | </t> |
| 6507 | | <t> |
| 6508 | | End-to-end reload |
| 6509 | | <list><t> |
| 6510 | | The request includes a "no-cache" cache-control directive or, for |
| 6511 | | compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field |
| 6512 | | names &MUST-NOT; be included with the no-cache directive in a |
| 6513 | | request. The server &MUST-NOT; use a cached copy when responding to |
| 6514 | | such a request. |
| 6515 | | </t></list> |
| 6516 | | </t> |
| 6517 | | <t> |
| 6518 | | Specific end-to-end revalidation |
| 6519 | | <list><t> |
| 6520 | | The request includes a "max-age=0" cache-control directive, which |
| 6521 | | forces each cache along the path to the origin server to |
| 6522 | | revalidate its own entry, if any, with the next cache or server. |
| 6523 | | The initial request includes a cache-validating conditional with |
| 6524 | | the client's current validator. |
| 6525 | | </t></list> |
| 6526 | | </t> |
| 6527 | | <t> |
| 6528 | | Unspecified end-to-end revalidation |
| 6529 | | <list><t> |
| 6530 | | The request includes "max-age=0" cache-control directive, which |
| 6531 | | forces each cache along the path to the origin server to |
| 6532 | | revalidate its own entry, if any, with the next cache or server. |
| 6533 | | The initial request does not include a cache-validating |
| 6534 | | conditional; the first cache along the path (if any) that holds a |
| 6535 | | cache entry for this resource includes a cache-validating |
| 6536 | | conditional with its current validator. |
| 6537 | | </t></list> |
| 6538 | | </t> |
| 6539 | | <t> |
| 6540 | | <iref item="Cache Directives" subitem="max-age" primary="true"/> |
| 6541 | | <iref item="max-age" subitem="Cache Directive" primary="true"/> |
| 6542 | | max-age |
| 6543 | | <list><t> |
| 6544 | | When an intermediate cache is forced, by means of a max-age=0 |
| 6545 | | directive, to revalidate its own cache entry, and the client has |
| 6546 | | supplied its own validator in the request, the supplied validator |
| 6547 | | might differ from the validator currently stored with the cache |
| 6548 | | entry. In this case, the cache &MAY; use either validator in making |
| 6549 | | its own request without affecting semantic transparency. |
| 6550 | | </t><t> |
| 6551 | | However, the choice of validator might affect performance. The |
| 6552 | | best approach is for the intermediate cache to use its own |
| 6553 | | validator when making its request. If the server replies with 304 |
| 6554 | | (Not Modified), then the cache can return its now validated copy |
| 6555 | | to the client with a 200 (OK) response. If the server replies with |
| 6556 | | a new entity and cache validator, however, the intermediate cache |
| 6557 | | can compare the returned validator with the one provided in the |
| 6558 | | client's request, using the strong comparison function. If the |
| 6559 | | client's validator is equal to the origin server's, then the |
| 6560 | | intermediate cache simply returns 304 (Not Modified). Otherwise, |
| 6561 | | it returns the new entity with a 200 (OK) response. |
| 6562 | | </t><t> |
| 6563 | | If a request includes the no-cache directive, it &SHOULD-NOT; |
| 6564 | | include min-fresh, max-stale, or max-age. |
| 6565 | | </t></list> |
| 6566 | | </t> |
| 6567 | | <t> |
| 6568 | | <iref item="Cache Directives" subitem="only-if-cached" primary="true"/> |
| 6569 | | <iref item="only-if-cached" subitem="Cache Directive" primary="true"/> |
| 6570 | | only-if-cached |
| 6571 | | <list><t> |
| 6572 | | In some cases, such as times of extremely poor network |
| 6573 | | connectivity, a client may want a cache to return only those |
| 6574 | | responses that it currently has stored, and not to reload or |
| 6575 | | revalidate with the origin server. To do this, the client may |
| 6576 | | include the only-if-cached directive in a request. If it receives |
| 6577 | | this directive, a cache &SHOULD; either respond using a cached entry |
| 6578 | | that is consistent with the other constraints of the request, or |
| 6579 | | respond with a 504 (Gateway Timeout) status. However, if a group |
| 6580 | | of caches is being operated as a unified system with good internal |
| 6581 | | connectivity, such a request &MAY; be forwarded within that group of |
| 6582 | | caches. |
| 6583 | | </t></list> |
| 6584 | | </t> |
| 6585 | | <t> |
| 6586 | | <iref item="Cache Directives" subitem="must-revalidate" primary="true"/> |
| 6587 | | <iref item="must-revalidate" subitem="Cache Directive" primary="true"/> |
| 6588 | | must-revalidate |
| 6589 | | <list><t> |
| 6590 | | Because a cache &MAY; be configured to ignore a server's specified |
| 6591 | | expiration time, and because a client request &MAY; include a max-stale |
| 6592 | | directive (which has a similar effect), the protocol also |
| 6593 | | includes a mechanism for the origin server to require revalidation |
| 6594 | | of a cache entry on any subsequent use. When the must-revalidate |
| 6595 | | directive is present in a response received by a cache, that cache |
| 6596 | | &MUST-NOT; use the entry after it becomes stale to respond to a |
| 6597 | | subsequent request without first revalidating it with the origin |
| 6598 | | server. (I.e., the cache &MUST; do an end-to-end revalidation every |
| 6599 | | time, if, based solely on the origin server's Expires or max-age |
| 6600 | | value, the cached response is stale.) |
| 6601 | | </t><t> |
| 6602 | | The must-revalidate directive is necessary to support reliable |
| 6603 | | operation for certain protocol features. In all circumstances an |
| 6604 | | HTTP/1.1 cache &MUST; obey the must-revalidate directive; in |
| 6605 | | particular, if the cache cannot reach the origin server for any |
| 6606 | | reason, it &MUST; generate a 504 (Gateway Timeout) response. |
| 6607 | | </t><t> |
| 6608 | | Servers &SHOULD; send the must-revalidate directive if and only if |
| 6609 | | failure to revalidate a request on the entity could result in |
| 6610 | | incorrect operation, such as a silently unexecuted financial |
| 6611 | | transaction. Recipients &MUST-NOT; take any automated action that |
| 6612 | | violates this directive, and &MUST-NOT; automatically provide an |
| 6613 | | unvalidated copy of the entity if revalidation fails. |
| 6614 | | </t><t> |
| 6615 | | Although this is not recommended, user agents operating under |
| 6616 | | severe connectivity constraints &MAY; violate this directive but, if |
| 6617 | | so, &MUST; explicitly warn the user that an unvalidated response has |
| 6618 | | been provided. The warning &MUST; be provided on each unvalidated |
| 6619 | | access, and &SHOULD; require explicit user confirmation. |
| 6620 | | </t></list> |
| 6621 | | </t> |
| 6622 | | <t> |
| 6623 | | <iref item="Cache Directives" subitem="proxy-revalidate" primary="true"/> |
| 6624 | | <iref item="proxy-revalidate" subitem="Cache Directive" primary="true"/> |
| 6625 | | proxy-revalidate |
| 6626 | | <list><t> |
| 6627 | | The proxy-revalidate directive has the same meaning as the must-revalidate |
| 6628 | | directive, except that it does not apply to non-shared |
| 6629 | | user agent caches. It can be used on a response to an |
| 6630 | | authenticated request to permit the user's cache to store and |
| 6631 | | later return the response without needing to revalidate it (since |
| 6632 | | it has already been authenticated once by that user), while still |
| 6633 | | requiring proxies that service many users to revalidate each time |
| 6634 | | (in order to make sure that each user has been authenticated). |
| 6635 | | Note that such authenticated responses also need the public cache |
| 6636 | | control directive in order to allow them to be cached at all. |
| 6637 | | </t></list> |
| 6638 | | </t> |
| 6639 | | </section> |
| 6640 | | |
| 6641 | | <section title="No-Transform Directive" anchor="no-transform.directive"> |
| 6642 | | <t> |
| 6643 | | <iref item="Cache Directives" subitem="no-transform" primary="true"/> |
| 6644 | | <iref item="no-transform" subitem="Cache Directive" primary="true"/> |
| 6645 | | no-transform |
| 6646 | | <list><t> |
| 6647 | | Implementors of intermediate caches (proxies) have found it useful |
| 6648 | | to convert the media type of certain entity bodies. A non-transparent |
| 6649 | | proxy might, for example, convert between image |
| 6650 | | formats in order to save cache space or to reduce the amount of |
| 6651 | | traffic on a slow link. |
| 6652 | | </t><t> |
| 6653 | | Serious operational problems occur, however, when these |
| 6654 | | transformations are applied to entity bodies intended for certain |
| 6655 | | kinds of applications. For example, applications for medical |
| 6656 | | imaging, scientific data analysis and those using end-to-end |
| 6657 | | authentication, all depend on receiving an entity body that is bit |
| 6658 | | for bit identical to the original entity-body. |
| 6659 | | </t><t> |
| 6660 | | Therefore, if a message includes the no-transform directive, an |
| 6661 | | intermediate cache or proxy &MUST-NOT; change those headers that are |
| 6662 | | listed in <xref target="non-modifiable.headers"/> as being subject to the no-transform |
| 6663 | | directive. This implies that the cache or proxy &MUST-NOT; change |
| 6664 | | any aspect of the entity-body that is specified by these headers, |
| 6665 | | including the value of the entity-body itself. |
| 6666 | | </t></list> |
| 6667 | | </t> |
| 6668 | | </section> |
| 6669 | | |
| 6670 | | <section title="Cache Control Extensions" anchor="cache.control.extensions"> |
| 6671 | | <t> |
| 6672 | | The Cache-Control header field can be extended through the use of one |
| 6673 | | or more cache-extension tokens, each with an optional assigned value. |
| 6674 | | Informational extensions (those which do not require a change in |
| 6675 | | cache behavior) &MAY; be added without changing the semantics of other |
| 6676 | | directives. Behavioral extensions are designed to work by acting as |
| 6677 | | modifiers to the existing base of cache directives. Both the new |
| 6678 | | directive and the standard directive are supplied, such that |
| 6679 | | applications which do not understand the new directive will default |
| 6680 | | to the behavior specified by the standard directive, and those that |
| 6681 | | understand the new directive will recognize it as modifying the |
| 6682 | | requirements associated with the standard directive. In this way, |
| 6683 | | extensions to the cache-control directives can be made without |
| 6684 | | requiring changes to the base protocol. |
| 6685 | | </t> |
| 6686 | | <t> |
| 6687 | | This extension mechanism depends on an HTTP cache obeying all of the |
| 6688 | | cache-control directives defined for its native HTTP-version, obeying |
| 6689 | | certain extensions, and ignoring all directives that it does not |
| 6690 | | understand. |
| 6691 | | </t> |
| 6692 | | <t> |
| 6693 | | For example, consider a hypothetical new response directive called |
| 6694 | | community which acts as a modifier to the private directive. We |
| 6695 | | define this new directive to mean that, in addition to any non-shared |
| 6696 | | cache, any cache which is shared only by members of the community |
| 6697 | | named within its value may cache the response. An origin server |
| 6698 | | wishing to allow the UCI community to use an otherwise private |
| 6699 | | response in their shared cache(s) could do so by including |
| 6700 | | </t> |
| 6701 | | <figure><artwork type="example"> |
| 6702 | | Cache-Control: private, community="UCI" |
| 6703 | | </artwork></figure> |
| 6704 | | <t> |
| 6705 | | A cache seeing this header field will act correctly even if the cache |
| 6706 | | does not understand the community cache-extension, since it will also |
| 6707 | | see and understand the private directive and thus default to the safe |
| 6708 | | behavior. |
| 6709 | | </t> |
| 6710 | | <t> |
| 6711 | | Unrecognized cache-directives &MUST; be ignored; it is assumed that any |
| 6712 | | cache-directive likely to be unrecognized by an HTTP/1.1 cache will |
| 6713 | | be combined with standard directives (or the response's default |
| 6714 | | cacheability) such that the cache behavior will remain minimally |
| 6715 | | correct even if the cache does not understand the extension(s). |
| 6716 | | </t> |
| 6717 | | </section> |
| 6718 | | </section> |
| 6719 | | |
| 6720 | | <section title="Connection" anchor="header.connection"> |
| 6721 | | <iref primary="true" item="Connection header" x:for-anchor=""/> |
| 6722 | | <iref primary="true" item="Headers" subitem="Connection" x:for-anchor=""/> |
| 6723 | | <t> |
| 6724 | | The Connection general-header field allows the sender to specify |
| 6725 | | options that are desired for that particular connection and &MUST-NOT; |
| 6726 | | be communicated by proxies over further connections. |
| 6727 | | </t> |
| 6728 | | <t> |
| 6729 | | The Connection header has the following grammar: |
| 6730 | | </t> |
| 6731 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Connection"/><iref primary="true" item="Grammar" subitem="connection-token"/> |
| 6732 | | Connection = "Connection" ":" 1#(connection-token) |
| 6733 | | connection-token = token |
| 6734 | | </artwork></figure> |
| 6735 | | <t> |
| 6736 | | HTTP/1.1 proxies &MUST; parse the Connection header field before a |
| 6737 | | message is forwarded and, for each connection-token in this field, |
| 6738 | | remove any header field(s) from the message with the same name as the |
| 6739 | | connection-token. Connection options are signaled by the presence of |
| 6740 | | a connection-token in the Connection header field, not by any |
| 6741 | | corresponding additional header field(s), since the additional header |
| 6742 | | field may not be sent if there are no parameters associated with that |
| 6743 | | connection option. |
| 6744 | | </t> |
| 6745 | | <t> |
| 6746 | | Message headers listed in the Connection header &MUST-NOT; include |
| 6747 | | end-to-end headers, such as Cache-Control. |
| 6748 | | </t> |
| 6749 | | <t> |
| 6750 | | HTTP/1.1 defines the "close" connection option for the sender to |
| 6751 | | signal that the connection will be closed after completion of the |
| 6752 | | response. For example, |
| 6753 | | </t> |
| 6754 | | <figure><artwork type="example"> |
| 6755 | | Connection: close |
| 6756 | | </artwork></figure> |
| 6757 | | <t> |
| 6758 | | in either the request or the response header fields indicates that |
| 6759 | | the connection &SHOULD-NOT; be considered `persistent' (<xref target="persistent.connections"/>) |
| 6760 | | after the current request/response is complete. |
| 6761 | | </t> |
| 6762 | | <t> |
| 6763 | | HTTP/1.1 applications that do not support persistent connections &MUST; |
| 6764 | | include the "close" connection option in every message. |
| 6765 | | </t> |
| 6766 | | <t> |
| 6767 | | A system receiving an HTTP/1.0 (or lower-version) message that |
| 6768 | | includes a Connection header MUST, for each connection-token in this |
| 6769 | | field, remove and ignore any header field(s) from the message with |
| 6770 | | the same name as the connection-token. This protects against mistaken |
| 6771 | | forwarding of such header fields by pre-HTTP/1.1 proxies. See <xref target="compatibility.with.http.1.0.persistent.connections"/>. |
| 6772 | | </t> |
| 6773 | | </section> |
| 6774 | | |
| 6775 | | <section title="Content-Encoding" anchor="header.content-encoding"> |
| 6776 | | <iref primary="true" item="Content-Encoding header" x:for-anchor=""/> |
| 6777 | | <iref primary="true" item="Headers" subitem="Content-Encoding" x:for-anchor=""/> |
| 6778 | | <t> |
| 6779 | | The Content-Encoding entity-header field is used as a modifier to the |
| 6780 | | media-type. When present, its value indicates what additional content |
| 6781 | | codings have been applied to the entity-body, and thus what decoding |
| 6782 | | mechanisms must be applied in order to obtain the media-type |
| 6783 | | referenced by the Content-Type header field. Content-Encoding is |
| 6784 | | primarily used to allow a document to be compressed without losing |
| 6785 | | the identity of its underlying media type. |
| 6786 | | </t> |
| 6787 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Encoding"/> |
| 6788 | | Content-Encoding = "Content-Encoding" ":" 1#content-coding |
| 6789 | | </artwork></figure> |
| 6790 | | <t> |
| 6791 | | Content codings are defined in <xref target="content.codings"/>. An example of its use is |
| 6792 | | </t> |
| 6793 | | <figure><artwork type="example"> |
| 6794 | | Content-Encoding: gzip |
| 6795 | | </artwork></figure> |
| 6796 | | <t> |
| 6797 | | The content-coding is a characteristic of the entity identified by |
| 6798 | | the Request-URI. Typically, the entity-body is stored with this |
| 6799 | | encoding and is only decoded before rendering or analogous usage. |
| 6800 | | However, a non-transparent proxy &MAY; modify the content-coding if the |
| 6801 | | new coding is known to be acceptable to the recipient, unless the |
| 6802 | | "no-transform" cache-control directive is present in the message. |
| 6803 | | </t> |
| 6804 | | <t> |
| 6805 | | If the content-coding of an entity is not "identity", then the |
| 6806 | | response &MUST; include a Content-Encoding entity-header (<xref target="header.content-encoding"/>) |
| 6807 | | that lists the non-identity content-coding(s) used. |
| 6808 | | </t> |
| 6809 | | <t> |
| 6810 | | If the content-coding of an entity in a request message is not |
| 6811 | | acceptable to the origin server, the server &SHOULD; respond with a |
| 6812 | | status code of 415 (Unsupported Media Type). |
| 6813 | | </t> |
| 6814 | | <t> |
| 6815 | | If multiple encodings have been applied to an entity, the content |
| 6816 | | codings &MUST; be listed in the order in which they were applied. |
| 6817 | | Additional information about the encoding parameters &MAY; be provided |
| 6818 | | by other entity-header fields not defined by this specification. |
| 6819 | | </t> |
| 6820 | | </section> |
| 6821 | | |
| 6822 | | <section title="Content-Language" anchor="header.content-language"> |
| 6823 | | <iref primary="true" item="Content-Language header" x:for-anchor=""/> |
| 6824 | | <iref primary="true" item="Headers" subitem="Content-Language" x:for-anchor=""/> |
| 6825 | | <t> |
| 6826 | | The Content-Language entity-header field describes the natural |
| 6827 | | language(s) of the intended audience for the enclosed entity. Note |
| 6828 | | that this might not be equivalent to all the languages used within |
| 6829 | | the entity-body. |
| 6830 | | </t> |
| 6831 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Language"/> |
| 6832 | | Content-Language = "Content-Language" ":" 1#language-tag |
| 6833 | | </artwork></figure> |
| 6834 | | <t> |
| 6835 | | Language tags are defined in <xref target="language.tags"/>. The primary purpose of |
| 6836 | | Content-Language is to allow a user to identify and differentiate |
| 6837 | | entities according to the user's own preferred language. Thus, if the |
| 6838 | | body content is intended only for a Danish-literate audience, the |
| 6839 | | appropriate field is |
| 6840 | | </t> |
| 6841 | | <figure><artwork type="example"> |
| 6842 | | Content-Language: da |
| 6843 | | </artwork></figure> |
| 6844 | | <t> |
| 6845 | | If no Content-Language is specified, the default is that the content |
| 6846 | | is intended for all language audiences. This might mean that the |
| 6847 | | sender does not consider it to be specific to any natural language, |
| 6848 | | or that the sender does not know for which language it is intended. |
| 6849 | | </t> |
| 6850 | | <t> |
| 6851 | | Multiple languages &MAY; be listed for content that is intended for |
| 6852 | | multiple audiences. For example, a rendition of the "Treaty of |
| 6853 | | Waitangi," presented simultaneously in the original Maori and English |
| 6854 | | versions, would call for |
| 6855 | | </t> |
| 6856 | | <figure><artwork type="example"> |
| 6857 | | Content-Language: mi, en |
| 6858 | | </artwork></figure> |
| 6859 | | <t> |
| 6860 | | However, just because multiple languages are present within an entity |
| 6861 | | does not mean that it is intended for multiple linguistic audiences. |
| 6862 | | An example would be a beginner's language primer, such as "A First |
| 6863 | | Lesson in Latin," which is clearly intended to be used by an |
| 6864 | | English-literate audience. In this case, the Content-Language would |
| 6865 | | properly only include "en". |
| 6866 | | </t> |
| 6867 | | <t> |
| 6868 | | Content-Language &MAY; be applied to any media type -- it is not |
| 6869 | | limited to textual documents. |
| 6870 | | </t> |
| 6871 | | </section> |
| 6872 | | |
| 6873 | | <section title="Content-Length" anchor="header.content-length"> |
| 6874 | | <iref primary="true" item="Content-Length header" x:for-anchor=""/> |
| 6875 | | <iref primary="true" item="Headers" subitem="Content-Length" x:for-anchor=""/> |
| 6876 | | <t> |
| 6877 | | The Content-Length entity-header field indicates the size of the |
| 6878 | | entity-body, in decimal number of OCTETs, sent to the recipient or, |
| 6879 | | in the case of the HEAD method, the size of the entity-body that |
| 6880 | | would have been sent had the request been a GET. |
| 6881 | | </t> |
| 6882 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Length"/> |
| 6883 | | Content-Length = "Content-Length" ":" 1*DIGIT |
| 6884 | | </artwork></figure> |
| 6885 | | <t> |
| 6886 | | An example is |
| 6887 | | </t> |
| 6888 | | <figure><artwork type="example"> |
| 6889 | | Content-Length: 3495 |
| 6890 | | </artwork></figure> |
| 6891 | | <t> |
| 6892 | | Applications &SHOULD; use this field to indicate the transfer-length of |
| 6893 | | the message-body, unless this is prohibited by the rules in <xref target="message.length"/>. |
| 6894 | | </t> |
| 6895 | | <t> |
| 6896 | | Any Content-Length greater than or equal to zero is a valid value. |
| 6897 | | <xref target="message.length"/> describes how to determine the length of a message-body |
| 6898 | | if a Content-Length is not given. |
| 6899 | | </t> |
| 6900 | | <t> |
| 6901 | | Note that the meaning of this field is significantly different from |
| 6902 | | the corresponding definition in MIME, where it is an optional field |
| 6903 | | used within the "message/external-body" content-type. In HTTP, it |
| 6904 | | &SHOULD; be sent whenever the message's length can be determined prior |
| 6905 | | to being transferred, unless this is prohibited by the rules in |
| 6906 | | <xref target="message.length"/>. |
| 6907 | | </t> |
| 6908 | | </section> |
| 6909 | | |
| 6910 | | <section title="Content-Location" anchor="header.content-location"> |
| 6911 | | <iref primary="true" item="Content-Location header" x:for-anchor=""/> |
| 6912 | | <iref primary="true" item="Headers" subitem="Content-Location" x:for-anchor=""/> |
| 6913 | | <t> |
| 6914 | | The Content-Location entity-header field &MAY; be used to supply the |
| 6915 | | resource location for the entity enclosed in the message when that |
| 6916 | | entity is accessible from a location separate from the requested |
| 6917 | | resource's URI. A server &SHOULD; provide a Content-Location for the |
| 6918 | | variant corresponding to the response entity; especially in the case |
| 6919 | | where a resource has multiple entities associated with it, and those |
| 6920 | | entities actually have separate locations by which they might be |
| 6921 | | individually accessed, the server &SHOULD; provide a Content-Location |
| 6922 | | for the particular variant which is returned. |
| 6923 | | </t> |
| 6924 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Location"/> |
| 6925 | | Content-Location = "Content-Location" ":" |
| 6926 | | ( absoluteURI | relativeURI ) |
| 6927 | | </artwork></figure> |
| 6928 | | <t> |
| 6929 | | The value of Content-Location also defines the base URI for the |
| 6930 | | entity. |
| 6931 | | </t> |
| 6932 | | <t> |
| 6933 | | The Content-Location value is not a replacement for the original |
| 6934 | | requested URI; it is only a statement of the location of the resource |
| 6935 | | corresponding to this particular entity at the time of the request. |
| 6936 | | Future requests &MAY; specify the Content-Location URI as the request-URI |
| 6937 | | if the desire is to identify the source of that particular |
| 6938 | | entity. |
| 6939 | | </t> |
| 6940 | | <t> |
| 6941 | | A cache cannot assume that an entity with a Content-Location |
| 6942 | | different from the URI used to retrieve it can be used to respond to |
| 6943 | | later requests on that Content-Location URI. However, the Content-Location |
| 6944 | | can be used to differentiate between multiple entities |
| 6945 | | retrieved from a single requested resource, as described in <xref target="caching.negotiated.responses"/>. |
| 6946 | | </t> |
| 6947 | | <t> |
| 6948 | | If the Content-Location is a relative URI, the relative URI is |
| 6949 | | interpreted relative to the Request-URI. |
| 6950 | | </t> |
| 6951 | | <t> |
| 6952 | | The meaning of the Content-Location header in PUT or POST requests is |
| 6953 | | undefined; servers are free to ignore it in those cases. |
| 6954 | | </t> |
| 6955 | | </section> |
| 6956 | | |
| 6957 | | <section title="Content-MD5" anchor="header.content-md5"> |
| 6958 | | <iref primary="true" item="Content-MD5 header" x:for-anchor=""/> |
| 6959 | | <iref primary="true" item="Headers" subitem="Content-MD5" x:for-anchor=""/> |
| 6960 | | <t> |
| 6961 | | The Content-MD5 entity-header field, as defined in RFC 1864 <xref target="RFC1864"/>, is |
| 6962 | | an MD5 digest of the entity-body for the purpose of providing an |
| 6963 | | end-to-end message integrity check (MIC) of the entity-body. (Note: a |
| 6964 | | MIC is good for detecting accidental modification of the entity-body |
| 6965 | | in transit, but is not proof against malicious attacks.) |
| 6966 | | </t> |
| 6967 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-MD5"/><iref primary="true" item="Grammar" subitem="md5-digest"/> |
| 6968 | | Content-MD5 = "Content-MD5" ":" md5-digest |
| 6969 | | md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864> |
| 6970 | | </artwork></figure> |
| 6971 | | <t> |
| 6972 | | The Content-MD5 header field &MAY; be generated by an origin server or |
| 6973 | | client to function as an integrity check of the entity-body. Only |
| 6974 | | origin servers or clients &MAY; generate the Content-MD5 header field; |
| 6975 | | proxies and gateways &MUST-NOT; generate it, as this would defeat its |
| 6976 | | value as an end-to-end integrity check. Any recipient of the entity-body, |
| 6977 | | including gateways and proxies, &MAY; check that the digest value |
| 6978 | | in this header field matches that of the entity-body as received. |
| 6979 | | </t> |
| 6980 | | <t> |
| 6981 | | The MD5 digest is computed based on the content of the entity-body, |
| 6982 | | including any content-coding that has been applied, but not including |
| 6983 | | any transfer-encoding applied to the message-body. If the message is |
| 6984 | | received with a transfer-encoding, that encoding &MUST; be removed |
| 6985 | | prior to checking the Content-MD5 value against the received entity. |
| 6986 | | </t> |
| 6987 | | <t> |
| 6988 | | This has the result that the digest is computed on the octets of the |
| 6989 | | entity-body exactly as, and in the order that, they would be sent if |
| 6990 | | no transfer-encoding were being applied. |
| 6991 | | </t> |
| 6992 | | <t> |
| 6993 | | HTTP extends RFC 1864 to permit the digest to be computed for MIME |
| 6994 | | composite media-types (e.g., multipart/* and message/rfc822), but |
| 6995 | | this does not change how the digest is computed as defined in the |
| 6996 | | preceding paragraph. |
| 6997 | | </t> |
| 6998 | | <t> |
| 6999 | | There are several consequences of this. The entity-body for composite |
| 7000 | | types &MAY; contain many body-parts, each with its own MIME and HTTP |
| 7001 | | headers (including Content-MD5, Content-Transfer-Encoding, and |
| 7002 | | Content-Encoding headers). If a body-part has a Content-Transfer-Encoding |
| 7003 | | or Content-Encoding header, it is assumed that the content |
| 7004 | | of the body-part has had the encoding applied, and the body-part is |
| 7005 | | included in the Content-MD5 digest as is -- i.e., after the |
| 7006 | | application. The Transfer-Encoding header field is not allowed within |
| 7007 | | body-parts. |
| 7008 | | </t> |
| 7009 | | <t> |
| 7010 | | Conversion of all line breaks to CRLF &MUST-NOT; be done before |
| 7011 | | computing or checking the digest: the line break convention used in |
| 7012 | | the text actually transmitted &MUST; be left unaltered when computing |
| 7013 | | the digest. |
| 7014 | | <list><t> |
| 7015 | | <x:h>Note:</x:h> while the definition of Content-MD5 is exactly the same for |
| 7016 | | HTTP as in RFC 1864 for MIME entity-bodies, there are several ways |
| 7017 | | in which the application of Content-MD5 to HTTP entity-bodies |
| 7018 | | differs from its application to MIME entity-bodies. One is that |
| 7019 | | HTTP, unlike MIME, does not use Content-Transfer-Encoding, and |
| 7020 | | does use Transfer-Encoding and Content-Encoding. Another is that |
| 7021 | | HTTP more frequently uses binary content types than MIME, so it is |
| 7022 | | worth noting that, in such cases, the byte order used to compute |
| 7023 | | the digest is the transmission byte order defined for the type. |
| 7024 | | Lastly, HTTP allows transmission of text types with any of several |
| 7025 | | line break conventions and not just the canonical form using CRLF. |
| 7026 | | </t></list> |
| 7027 | | </t> |
| 7028 | | </section> |
| 7029 | | |
| 7030 | | <section title="Content-Range" anchor="header.content-range"> |
| 7031 | | <iref primary="true" item="Content-Range header" x:for-anchor=""/> |
| 7032 | | <iref primary="true" item="Headers" subitem="Content-Range" x:for-anchor=""/> |
| 7033 | | <t> |
| 7034 | | The Content-Range entity-header is sent with a partial entity-body to |
| 7035 | | specify where in the full entity-body the partial body should be |
| 7036 | | applied. Range units are defined in <xref target="range.units"/>. |
| 7037 | | </t> |
| 7038 | | <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Range"/><iref primary="true" item="Grammar" subitem="content-range-spec"/><iref primary="true" item="Grammar" subitem="byte-content-range-spec"/><iref primary="true" item="Grammar" subitem="byte-range-resp-spec"/><iref primary="true" item="Grammar" subitem="instance-length"/> |
| 7039 | | Content-Range = "Content-Range" ":" content-range-spec |
| 7040 | | |
| 7041 | | content-range-spec = byte-content-range-spec |
| 7042 | | byte-content-range-spec = bytes-unit SP |
| 7043 | | byte-range-resp-spec "/" |
| 7044 | | ( instance-length | "*" ) |
| 7045 | | |
| 7046 | | byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) |
| 7047 | | | "*" |
| 7048 | | instance-length = 1*DIGIT |
| 7049 | | </artwork></figure> |
| 7050 | | <t> |
| 7051 | | The header &SHOULD; indicate the total length of the full entity-body, |
| 7052 | | unless this length is unknown or difficult to determine. The asterisk |
| 7053 | | "*" character means that the instance-length is unknown at the time |
| 7054 | | when the response was generated. |
| 7055 | | </t> |
| 7056 | | <t> |
| 7057 | | Unlike byte-ranges-specifier values (see <xref target="byte.ranges"/>), a byte-range-resp-spec |
| 7058 | | &MUST; only specify one range, and &MUST; contain |
| 7059 | | absolute byte positions for both the first and last byte of the |
| 7060 | | range. |
| 7061 | | </t> |
| 7062 | | <t> |
| 7063 | | A byte-content-range-spec with a byte-range-resp-spec whose last-byte-pos |
| 7064 | | value is less than its first-byte-pos value, or whose |
| 7065 | | instance-length value is less than or equal to its last-byte-pos |
| 7066 | | value, is invalid. The recipient of an invalid byte-content-range-spec |
| 7067 | | &MUST; ignore it and any content transferred along with it. |
| 7068 | | </t> |
| 7069 | | <t> |
| 7070 | | A server sending a response with status code 416 (Requested range not |
| 7071 | | satisfiable) &SHOULD; include a Content-Range field with a byte-range-resp-spec |
| 7072 | | of "*". The instance-length specifies the current length of |
| 7073 | | the selected resource. A response with status code 206 (Partial |
| 7074 | | Content) &MUST-NOT; include a Content-Range field with a byte-range-resp-spec of "*". |
| 7075 | | </t> |
| 7076 | | <t> |
| 7077 | | Examples of byte-content-range-spec values, assuming that the entity |
| 7078 | | contains a total of 1234 bytes: |
| 7079 | | <list style="symbols"> |
| 7080 | | <t> |
| 7081 | | The first 500 bytes: |
| 7082 | | <figure><artwork type="text/plain"> |
| 7083 | | bytes 0-499/1234 |
| 7084 | | </artwork></figure> |
| 7085 | | </t> |
| 7086 | | <t> |
| 7087 | | The second 500 bytes: |
| 7088 | | <figure><artwork type="text/plain"> |
| 7089 | | bytes 500-999/1234 |
| 7090 | | </artwork></figure> |
| 7091 | | </t> |
| 7092 | | <t> |
| 7093 | | All except for the first 500 bytes: |
| 7094 | | <figure><artwork type="text/plain"> |
| 7095 | | bytes 500-1233/1234 |
| 7096 | | </artwork></figure> |
| 7097 | | </t> |
| 7098 | | <t> |
| 7099 | | The last 500 bytes: |
| 7100 | | <figure><artwork type="text/plain"> |
| 7101 | | bytes 734-1233/1234 |
| 7102 | | </artwork></figure> |
| 7103 | | </t> |
| 7104 | | </list> |
| 7105 | | </t> |
| 7106 | | <t> |
| 7107 | | When an HTTP message includes the content of a single range (for |
| 7108 | | example, a response to a request for a single range, or to a request |
| 7109 | | for a set of ranges that overlap without any holes), this content is |
| 7110 | | transmitted with a Content-Range header, and a Content-Length header |
| 7111 | | showing the number of bytes actually transferred. For example, |
| 7112 | | </t> |
| 7113 | | <figure><artwork type="example"> |
| 7114 | | HTTP/1.1 206 Partial content |
| 7115 | | Date: Wed, 15 Nov 1995 06:25:24 GMT |
| 7116 | | Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT |
| 7117 | | Content-Range: bytes 21010-47021/47022 |
| 7118 | | Content-Length: 26012 |
| 7119 | | Content-Type: image/gif |
| 7120 | | </artwork></figure> |
| 7121 | | <t> |
| 7122 | | When an HTTP message includes the content of multiple ranges (for |
| 7123 | | example, a response to a request for multiple non-overlapping |
| 7124 | | ranges), these are transmitted as a multipart message. The multipart |
| 7125 | | media type used for this purpose is "multipart/byteranges" as defined |
| 7126 | | in <xref target="internet.media.type.multipart.byteranges"/>. See <xref target="changes.from.rfc.2068"/> for a compatibility issue. |
| 7127 | | </t> |
| 7128 | | <t> |
| 7129 | | A response to a request for a single range &MUST-NOT; be sent using the |
| 7130 | | multipart/byteranges media type. A response to a request for |
| 7131 | | multiple ranges, whose result is a single range, &MAY; be sent as a |
| 7132 | | multipart/byteranges media type with one part. A client that cannot |
| 7133 | | decode a multipart/byteranges message &MUST-NOT; ask for multiple |
| 7134 | | byte-ranges in a single request. |
| 7135 | | </t> |
| 7136 | | <t> |
| 7137 | | When a client requests multiple byte-ranges in one request, the |
| 7138 | | server &SHOULD; return them in the order that they appeared in the |
| 7139 | | request. |
| 7140 | | </t> |
| 7141 | | <t> |
| 7142 | | If the server ignores a byte-range-spec because it is syntactically |
| 7143 | | invalid, the server &SHOULD; treat the request as if the invalid Range |
| 7144 | | header field did not exist. (Normally, this means return a 200 |
| 7145 | | response containing the full entity). |
| 7146 | | </t> |
| 7147 | | <t> |
| 7148 | | If the server receives a request (other than one including an If-Range |
| 7149 | | request-header field) with an unsatisfiable Range request-header |
| 7150 | | field (that is, all of whose byte-range-spec values have a |
| 7151 | | first-byte-pos value greater than the current length of the selected |
| 7152 | | resource), it &SHOULD; return a response code of 416 (Requested range |
| 7153 | | not satisfiable) (<xref target="status.416"/>). |
| 7154 | | <list><t> |
| 7155 | | <x:h>Note:</x:h> clients cannot depend on servers to send a 416 (Requested |
| 7156 | | range not satisfiable) response instead of a 200 (OK) response for |
| 7157 | | an unsatisfiable Range request-header, since not all servers |
| 7158 | | implement this request-header. |
| 7159 | | </t></list> |
| 7160 | | </t> |
| 7161 | | </section> |
| 7162 | | |
| 7163 | | <section title="Content-Type" anchor="header.content-type"> |
| 7164 | | <iref primary="true" item="Content-Type header" x:for-anchor=""/> |
| 7165 | | <iref primary="true" item="Headers" subitem="Content-Type" x:for-anchor=""/> |
| 7166 | | <t> |
| 7167 | | The Content-Type entity-header field indicates the media type of the |
![(please configure the [header_logo] section in trac.ini)](https://www.ietf.org/images/ietflogotrans.gif)