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 |