From 7845cf01145e634e655ccf2d38e06bf650754039 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 27 Sep 2024 11:13:35 +0200 Subject: [PATCH 01/15] chore(http): Refresh headers docs d-k --- files/en-us/web/http/headers/date/index.md | 32 +++++------ .../web/http/headers/device-memory/index.md | 24 ++++---- files/en-us/web/http/headers/digest/index.md | 10 ++-- files/en-us/web/http/headers/dnt/index.md | 13 ++--- .../en-us/web/http/headers/downlink/index.md | 25 ++++----- files/en-us/web/http/headers/dpr/index.md | 37 ++++++------ .../web/http/headers/early-data/index.md | 9 +-- files/en-us/web/http/headers/ect/index.md | 23 ++++---- files/en-us/web/http/headers/etag/index.md | 39 ++++++------- files/en-us/web/http/headers/expect/index.md | 37 ++++++------ files/en-us/web/http/headers/expires/index.md | 35 ++++++++---- .../en-us/web/http/headers/forwarded/index.md | 4 +- files/en-us/web/http/headers/from/index.md | 11 ++-- files/en-us/web/http/headers/host/index.md | 14 ++--- .../en-us/web/http/headers/if-match/index.md | 20 +++---- .../http/headers/if-modified-since/index.md | 47 +++++++--------- .../web/http/headers/if-none-match/index.md | 27 ++++----- .../en-us/web/http/headers/if-range/index.md | 47 +++++++--------- .../http/headers/if-unmodified-since/index.md | 56 +++++++++---------- .../web/http/headers/keep-alive/index.md | 36 ++++++------ 20 files changed, 257 insertions(+), 289 deletions(-) diff --git a/files/en-us/web/http/headers/date/index.md b/files/en-us/web/http/headers/date/index.md index e7d1d56cbf5510b..f0cf9f33451373b 100644 --- a/files/en-us/web/http/headers/date/index.md +++ b/files/en-us/web/http/headers/date/index.md @@ -7,12 +7,10 @@ browser-compat: http.headers.Date {{HTTPSidebar}} -The **`Date`** general HTTP header contains the date and time -at which the message originated. +The HTTP **`Date`** header contains the date and time at which the message originated. -> **Warning:** `Date` is listed -> in the [forbidden header names](https://fetch.spec.whatwg.org/#forbidden-header-name) -> in the fetch spec, so this code will not send the `Date` header: +> [!WARNING] +> The `Date` header is a {{Glossary("Forbidden header name")}}, so this code cannot set the message `Date`, for example: > > ```js > fetch("https://httpbin.org/get", { @@ -33,7 +31,7 @@ at which the message originated. {{Glossary("Forbidden header name")}} - yes + Yes @@ -46,24 +44,22 @@ Date: , :: GMT ## Directives -- \ +- `` - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). -- \ - - : 2 digit day number, e.g. "04" or "23". -- \ - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", - "Nov", "Dec" (case sensitive). -- \ +- `` + - : 2 digit day number, e.g., "04" or "23". +- `` + - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). +- `` - : 4 digit year number, e.g. "1990" or "2016". -- \ +- `` - : 2 digit hour number, e.g. "09" or "23". -- \ +- `` - : 2 digit minute number, e.g. "04" or "59". -- \ +- `` - : 2 digit second number, e.g. "04" or "59". - GMT - - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local - time. + - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. ## Examples diff --git a/files/en-us/web/http/headers/device-memory/index.md b/files/en-us/web/http/headers/device-memory/index.md index f05cf6d91fd390a..cc842fffd461468 100644 --- a/files/en-us/web/http/headers/device-memory/index.md +++ b/files/en-us/web/http/headers/device-memory/index.md @@ -7,7 +7,12 @@ browser-compat: http.headers.Device-Memory {{HTTPSidebar}}{{securecontext_header}} -The **`Device-Memory`** [device client hint](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) request header field indicates the approximate amount of available RAM on the client device. The header is part of the {{DOMxRef("Device Memory API", "Device Memory API", "", "nocode")}}. +The HTTP **`Device-Memory`** request header is used in [device client hints](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) to indicate the approximate amount of available RAM on the client device. +The header is part of the {{DOMxRef("Device Memory API", "Device Memory API", "", "nocode")}}. + +Client hints are accessible only on secure origins. +A server has to opt in to receive the `Device-Memory` header from the client, by first sending the {{HTTPHeader("Accept-CH")}} response header. +Servers that opt in to the `Device-Memory` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header to inform caches that the server may send different responses based on the header value in a request. @@ -20,17 +25,11 @@ The **`Device-Memory`** [device client hint](/en-US/docs/Web/HTTP/Client_hints#d - +
{{Glossary("Forbidden header name")}}noNo
-> [!NOTE] -> -> - Client Hints are accessible only on secure origins (via TLS). -> - A server has to opt in to receive the `Device-Memory` header from the client, by sending the {{HTTPHeader("Accept-CH")}} response header. -> - Servers that opt in to the `Device-Memory` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header. This informs caches that the server may send different responses based on the header value in a request. - ## Syntax ```http @@ -41,12 +40,11 @@ Device-Memory: - `` - : The approximate amount of device RAM. Possible values are: `0.25`, `0.5`, `1`, `2`, `4`, `8`. - -The amount of device RAM can be used as a {{glossary("fingerprinting")}} variable, so values for the header are intentionally coarse to reduce the potential for its misuse. + The amount of device RAM can be used as a {{glossary("fingerprinting")}} variable, so values for the header are intentionally coarse to reduce the potential for its misuse. ## Examples -The server first needs to opt in to receive `Device-Memory` header by sending the response headers {{HTTPHeader("Accept-CH")}} containing `Device-Memory`. +The server first needs to opt in to receive `Device-Memory` header by sending the {{HTTPHeader("Accept-CH")}} response header containing `Device-Memory`: ```http Accept-CH: Device-Memory @@ -73,11 +71,9 @@ Device-Memory: 1 - {{DOMxRef("Navigator.deviceMemory")}} - {{DOMxRef("WorkerNavigator.deviceMemory")}} - Device client hints - - {{HTTPHeader("Content-DPR")}} - {{HTTPHeader("DPR")}} - {{HTTPHeader("Viewport-Width")}} - {{HTTPHeader("Width")}} - - {{HTTPHeader("Accept-CH")}} -- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} +- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} diff --git a/files/en-us/web/http/headers/digest/index.md b/files/en-us/web/http/headers/digest/index.md index 36a32ed009eca51..8ce06e7e75c06b5 100644 --- a/files/en-us/web/http/headers/digest/index.md +++ b/files/en-us/web/http/headers/digest/index.md @@ -15,10 +15,11 @@ browser-compat: http.headers.Digest > Use {{HTTPHeader("Content-Digest")}} instead. > For `id-*` digest algorithms, use {{HTTPHeader("Repr-Digest")}}. -The **`Digest`** response or request HTTP header provides the other side with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. It can be requested by using the {{HTTPHeader("Want-Digest")}} header. +The HTTP **`Digest`** header provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. +It can be requested by using the {{HTTPHeader("Want-Digest")}} header. Representations are different forms of a particular resource that might be returned from a request: for example, the same resource might be formatted in a particular media type such as XML or JSON, localized to a particular written language or geographical region, and/or compressed or otherwise encoded for transmission. -The _selected representation_ is the actual format of a resource that is returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}. +The _selected representation_ a resource returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}. The digest applies to the whole representation of a resource, not to a particular message. It can be used to verify that the representation data has not been modified during transmission. @@ -34,7 +35,7 @@ It can be used to verify that the representation data has not been modified duri {{Glossary("Forbidden header name")}} - no + No @@ -76,6 +77,5 @@ Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,id-sha-256=0KJL0PvN ## See also - {{HTTPHeader("Want-Digest")}} - - [HTTP range requests](/en-US/docs/Web/HTTP/Range_requests) -- [`206 Partial Content`](/en-US/docs/Web/HTTP/Status/206) +- {{HTTPStatus("206", "206 Partial Content")}} diff --git a/files/en-us/web/http/headers/dnt/index.md b/files/en-us/web/http/headers/dnt/index.md index 47bb43428fa6a29..511cf68b5e44642 100644 --- a/files/en-us/web/http/headers/dnt/index.md +++ b/files/en-us/web/http/headers/dnt/index.md @@ -13,9 +13,8 @@ browser-compat: http.headers.DNT > [!NOTE] > The DNT (Do Not Track) specification has been discontinued. See {{domxref("Navigator.doNotTrack")}} for more information. -The **`DNT`** (**D**o **N**ot -**T**rack) request header indicates the user's tracking preference. It lets -users indicate whether they would prefer privacy rather than personalized content. +The HTTP **`DNT`** (Do Not Track) request header indicates the user's tracking preference. +It lets users indicate whether they would prefer privacy rather than personalized content. DNT is deprecated in favor of [Global Privacy Control](https://globalprivacycontrol.org/), which is communicated to servers using the {{HTTPHeader("Sec-GPC")}} header, and accessible to clients from {{domxref("navigator.globalPrivacyControl")}}. @@ -27,7 +26,7 @@ DNT is deprecated in favor of [Global Privacy Control](https://globalprivacycont {{Glossary("Forbidden header name")}} - yes + Yes @@ -42,11 +41,11 @@ DNT: null ## Directives -- 0 +- `0` - : The user prefers to allow tracking on the target site. -- 1 +- `1` - : The user prefers not to be tracked on the target site. -- null +- `null` - : The user has not specified a preference about tracking. ## Examples diff --git a/files/en-us/web/http/headers/downlink/index.md b/files/en-us/web/http/headers/downlink/index.md index b8099fe8464587b..fa46e413877c2b8 100644 --- a/files/en-us/web/http/headers/downlink/index.md +++ b/files/en-us/web/http/headers/downlink/index.md @@ -9,7 +9,14 @@ browser-compat: http.headers.Downlink {{HTTPSidebar}} {{SeeCompatTable}} -The **`Downlink`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header field provides the approximate bandwidth of the client's connection to the server, in Mbps. +The HTTP **`Downlink`** request header is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to provide the approximate bandwidth in Mbps of the client's connection to the server. + +The hint allows a server to choose what information is sent based on the network bandwidth. +For example, a server might choose to send smaller versions of images and other resources on low bandwidth networks. + +> [!NOTE] +> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see [HTTP Caching Vary](/en-US/docs/Web/HTTP/Caching#vary)). +> Even if `Downlink` is used to configure what resources are sent, consider omitting it in the {{HTTPHeader("Vary")}} header — it is likely to change often, which effectively makes the resource uncacheable. @@ -22,18 +29,11 @@ The **`Downlink`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request head - +
{{Glossary("Forbidden header name")}}noNo
-The `Downlink` value is given in Mbps and rounded to the nearest 25 kilobits per second to prevent [fingerprinting](/en-US/docs/Glossary/Fingerprinting). There are many other mechanisms an attacker might use to obtain similar information. - -The hint allows a server to choose what information is sent based on the network bandwidth. For example, a server might choose to send smaller versions of images and other resources on low bandwidth networks. - -> [!NOTE] -> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see [HTTP Caching Vary](/en-US/docs/Web/HTTP/Caching#vary)). Even if `Downlink` is used to configure what resources are sent, consider omitting it in the {{HTTPHeader("Vary")}} header — it is likely to change often, which effectively makes the resource uncacheable. - ## Syntax ```http @@ -42,8 +42,9 @@ Downlink: ## Directives -- \ +- `` - : The downlink rate in Mbps, rounded to the nearest 25 kilobits. + The downlink rate may be used as a {{glossary("fingerprinting")}} variable, so values for the header are intentionally coarse to reduce the potential for its misuse. ## Examples @@ -71,11 +72,9 @@ Downlink: 1.7 - [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com) - Network client hints - - {{HTTPHeader("RTT")}} - {{HTTPHeader("ECT")}} - {{HTTPHeader("Save-Data")}} - - {{HTTPHeader("Accept-CH")}} -- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} +- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} - {{domxref("NetworkInformation.effectiveType")}} diff --git a/files/en-us/web/http/headers/dpr/index.md b/files/en-us/web/http/headers/dpr/index.md index a5541fe79b379a7..0dc0fbfe7493faf 100644 --- a/files/en-us/web/http/headers/dpr/index.md +++ b/files/en-us/web/http/headers/dpr/index.md @@ -10,7 +10,21 @@ browser-compat: http.headers.DPR {{HTTPSidebar}}{{Deprecated_Header}}{{SecureContext_Header}}{{Non-standard_Header}} -The **`DPR`** [device client hint](/en-US/docs/Web/HTTP/Client_hints) request header provides the client device pixel ratio. This ratio is the number of physical device pixels corresponding to every {{Glossary("CSS pixel")}}. +The HTTP **`DPR`** request header provides [device client hints](/en-US/docs/Web/HTTP/Client_hints) about the client device pixel ratio (DPR). +This ratio is the number of physical device pixels corresponding to every {{Glossary("CSS pixel")}}. + +The hint is useful when selecting image sources that best correspond to a screen's pixel density. +This is similar to the role played by `x` descriptors in the `` [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute to allow user agents to select a preferred image. + +If a server uses the `DPR` hint to choose which resource is sent in a response, the response must include the {{HTTPHeader("Content-DPR")}} header. +The client must use the value in `Content-DPR` for layout if it differs from the value in the request's `DPR` header. +If the `DPR` header appears more than once in a message the last occurrence is used. + +Servers that opt in to the `DPR` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header to inform caches that the server may send different responses based on the header value in a request. + +> [!WARNING] +> The `DPR` header was removed from the client hints specification in [draft-ietf-httpbis-client-hints-07](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07). +> The proposed replacement is [`Sec-CH-DPR`](https://wicg.github.io/responsive-image-client-hints/#sec-ch-dpr) (Responsive Image Client Hints). @@ -23,24 +37,11 @@ The **`DPR`** [device client hint](/en-US/docs/Web/HTTP/Client_hints) request he - +
{{Glossary("Forbidden header name")}}noNo
-The hint is useful when selecting image sources that best correspond to a screen's pixel density. This is similar to the role played by `x` descriptors in the `` [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute to allow user agents to select a preferred image. - -If a server uses the `DPR` hint to choose which resource is sent in a response, the response must include the {{HTTPHeader("Content-DPR")}} header. The client must use the value in `Content-DPR` for layout if it differs from the value in the request's `DPR` header. - -If the `DPR` header appears more than once in a message the last occurrence is used. - -> [!NOTE] -> -> - Client Hints are accessible only on secure origins (via TLS). -> - A server has to opt in to receive the `DPR` header from the client, by sending the {{HTTPHeader("Accept-CH")}} response header. -> - Servers that opt in to the `DPR` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header. This informs caches that the server may send different responses based on the header value in a request. -> - `DPR` was removed from the client hints specification in [draft-ietf-httpbis-client-hints-07](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07). The proposed replacement is [`Sec-CH-DPR`](https://wicg.github.io/responsive-image-client-hints/#sec-ch-dpr) (Responsive Image Client Hints). - ## Syntax ```http @@ -78,13 +79,11 @@ Content-DPR: 2.0 ## See also -- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com) - Device client hints - - {{HTTPHeader("Content-DPR")}} - {{HTTPHeader("Device-Memory")}} - {{HTTPHeader("Viewport-Width")}} - {{HTTPHeader("Width")}} - - {{HTTPHeader("Accept-CH")}} -- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} +- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} +- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com) diff --git a/files/en-us/web/http/headers/early-data/index.md b/files/en-us/web/http/headers/early-data/index.md index d741aa8663fc279..999fefa0fae7a4a 100644 --- a/files/en-us/web/http/headers/early-data/index.md +++ b/files/en-us/web/http/headers/early-data/index.md @@ -9,12 +9,9 @@ browser-compat: http.headers.Early-Data {{SeeCompatTable}}{{HTTPSidebar}} -The **`Early-Data`** header is set by -an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3), -and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code. +The HTTP **`Early-Data`** header is set by an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3), and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code. -The `Early-Data` header is **not** set by the originator of the -request (i.e., a browser). +The `Early-Data` header is **not** set by the originator of the request (i.e., a browser). @@ -24,7 +21,7 @@ request (i.e., a browser). - +
{{Glossary("Forbidden header name")}}noNo
diff --git a/files/en-us/web/http/headers/ect/index.md b/files/en-us/web/http/headers/ect/index.md index 5822e43691974c3..db12beabbab93aa 100644 --- a/files/en-us/web/http/headers/ect/index.md +++ b/files/en-us/web/http/headers/ect/index.md @@ -9,7 +9,15 @@ browser-compat: http.headers.ECT {{HTTPSidebar}} {{SeeCompatTable}} -The **`ECT`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header field indicates the {{Glossary("effective connection type")}}: `slow-2g`, `2g`, `3g`, `4g`. +The HTTP **`ECT`** request header is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to indicate the {{Glossary("effective connection type")}}: `slow-2g`, `2g`, `3g`, or `4g`. + +The value represents the "network profile" that best matches the connection's latency and bandwidth, rather than the actual mechanisms used for transferring the data. +For example, `2g` might be used to represent a slow Wi-Fi connection with high latency and low bandwidth, while `4g` might represent a fast fibre-based broadband network. + +The hint allows a server to choose what information is sent based on the broad characteristics of the network. For example, a server might choose to send smaller versions of images and other resources on less capable connections. The value might also be used as a starting point for determining what information is sent, which is further refined using information in {{HTTPHeader("RTT")}} and {{HTTPHeader("Downlink")}} hints. + +> [!NOTE] +> A server that specifies `ECT` in {{HTTPHeader("Accept-CH")}} may also specify it in {{HTTPHeader("Vary")}} to indicate that responses should be cached for different ECT values. @@ -22,18 +30,11 @@ The **`ECT`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header fi - +
{{Glossary("Forbidden header name")}}noNo
-The value represents the "network profile" that best matches the connection's latency and bandwidth, rather than the actual mechanisms used for transferring the data. For example, `2g` might be used to represent a slow Wi-Fi connection with high latency and low bandwidth, while `4g` might be used to represent a fast fibre-based broadband network. - -The hint allows a server to choose what information is sent based on the broad characteristics of the network. For example, a server might choose to send smaller versions of images and other resources on less capable connections. The value might also be used as a starting point for determining what information is sent, which is further refined using information in {{HTTPHeader("RTT")}} and {{HTTPHeader("Downlink")}} hints. - -> [!NOTE] -> A server that specifies `ECT` in {{HTTPHeader("Accept-CH")}} may also specify it in {{HTTPHeader("Vary")}} to indicate that responses should be cached for different ECT values. - ## Syntax ```http @@ -42,8 +43,8 @@ ECT: ## Directives -- \ - - : A value indicating {{Glossary("effective connection type")}}. This is one of: `slow-2g`, `2g`, `3g`, or `4g`. +- `` + - : A value indicating {{Glossary("effective connection type")}}. Can be one of: `slow-2g`, `2g`, `3g`, or `4g`. ## Examples diff --git a/files/en-us/web/http/headers/etag/index.md b/files/en-us/web/http/headers/etag/index.md index fef9ac76e11b446..dbc99b67adeef27 100644 --- a/files/en-us/web/http/headers/etag/index.md +++ b/files/en-us/web/http/headers/etag/index.md @@ -7,15 +7,12 @@ browser-compat: http.headers.ETag {{HTTPSidebar}} -The **`ETag`** (or **entity tag**) HTTP response header is an identifier for a -specific version of a resource. It lets caches be more efficient and save bandwidth, as -a web server does not need to resend a full response if the content was not changed. -Additionally, etags help to prevent simultaneous updates of a resource from overwriting -each other (["mid-air collisions"](#avoiding_mid-air_collisions)). +The HTTP **`ETag`** (entity tag) response header is an identifier for a specific version of a resource. +It lets [caches](/en-US/docs/Web/HTTP/Caching) be more efficient and save bandwidth, as a web server does not need to resend a full response if the content has not changed. +Additionally, ETags help to prevent simultaneous updates of a resource from overwriting each other (["mid-air collisions"](#avoiding_mid-air_collisions)). -If the resource at a given URL changes, a new `Etag` value _must_ be -generated. A comparison of them can determine whether two representations of a resource -are the same. +If the resource at a given URL changes, a new `Etag` value _must_ be generated. +A comparison of them can determine whether two representations of a resource are the same. @@ -25,7 +22,7 @@ are the same. - +
{{Glossary("Forbidden header name")}}noNo
@@ -40,14 +37,14 @@ ETag: "" ## Directives - `W/` {{optional_inline}} - - : `'W/'` (case-sensitive) indicates that a [weak validator](/en-US/docs/Web/HTTP/Conditional_requests#weak_validation) - is used. Weak etags are easy to generate, but are far less useful for comparisons. + - : `W/` (case-sensitive) indicates that a [weak validator](/en-US/docs/Web/HTTP/Conditional_requests#weak_validation) + is used. Weak ETags are easy to generate, but are far less useful for comparisons. Strong validators are ideal for comparisons but can be very difficult to generate efficiently. Weak `ETag` values of two representations of the same resources might be semantically equivalent, but not byte-for-byte identical. This - means weak etags prevent caching when [byte range requests](/en-US/docs/Web/HTTP/Headers/Accept-Ranges) are used, - but strong etags mean range requests can still be cached. -- "\" + means weak ETags prevent caching when [byte range requests](/en-US/docs/Web/HTTP/Headers/Accept-Ranges) are used, + but strong ETags mean range requests can still be cached. +- `` - : Entity tag that uniquely represents the requested resource. It is a string of {{Glossary("ASCII")}} characters placed between double quotes, like `"675af34563dc-tr34"`. The method by which `ETag` values are generated is not specified. Typically, the ETag value @@ -63,11 +60,9 @@ ETag: W/"0815" ### Avoiding mid-air collisions -With the help of the `ETag` and the {{HTTPHeader("If-Match")}} headers, you -can detect mid-air edit collisions. +With the help of the `ETag` and the {{HTTPHeader("If-Match")}} headers, you can detect mid-air edit collisions (conflicts). -For example, when editing a wiki, the current wiki content may be hashed -and put into an `Etag` header in the response: +For example, when editing a wiki, the current wiki content may be hashed and put into an `Etag` header in the response: ```http ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4" @@ -98,7 +93,7 @@ If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4" The server compares the client's `ETag` (sent with `If-None-Match`) with the `ETag` for its current version of the resource, and if both values match (that is, the resource has not changed), the server -sends back a {{HTTPStatus("304")}} `Not Modified` status, without a body, +sends back a {{HTTPStatus("304", "304 Not Modified")}} status, without a body, which tells the client that the cached version of the response is still good to use (_fresh_). @@ -112,8 +107,6 @@ which tells the client that the cached version of the response is still good to ## See also -- {{HTTPHeader("If-Match")}} -- {{HTTPHeader("If-None-Match")}} -- {{HTTPStatus("304", "304 Not Modified")}} -- {{HTTPStatus("412", "412 Precondition Failed")}} +- {{HTTPHeader("If-Match")}}, {{HTTPHeader("If-None-Match")}} headers +- {{HTTPStatus("304", "304 Not Modified")}}, {{HTTPStatus("412", "412 Precondition Failed")}} response status codes - [W3C Note: Editing the Web – Detecting the Lost Update Problem Using Unreserved Checkout](https://www.w3.org/1999/04/Editing/) diff --git a/files/en-us/web/http/headers/expect/index.md b/files/en-us/web/http/headers/expect/index.md index 69984b081fd0736..efeb50fb8d88592 100644 --- a/files/en-us/web/http/headers/expect/index.md +++ b/files/en-us/web/http/headers/expect/index.md @@ -7,23 +7,14 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#field.expect {{HTTPSidebar}} -The **`Expect`** HTTP request header indicates expectations -that need to be met by the server to handle the request successfully. +The HTTP **`Expect`** request header indicates that there are expectations that need to be met by the server in order to handle the complete request successfully. -Upon `Expect: 100-continue`, the server responds with: +When a request has an `Expect: 100-continue` header, a server sends a {{HTTPStatus("100", "100 Continue")}} response to indicate that the server is ready or capable of receiving the rest of the request content. +Waiting for a `100` response can be helpful if a client anticipates that an error is likely, for example, when sending state-changing operations without previously verified authentication credentials. -- {{HTTPStatus("100")}} (Continue) if the information from the request header is insufficient to - resolve the response and the client should proceed with sending the body. -- {{HTTPStatus("417")}} (Expectation Failed) if the server cannot meet the expectation +A {{HTTPStatus("417", "417 Expectation Failed")}} response is returned if the server cannot meet the expectation, or any other status otherwise (e.g., a [4XX](/en-US/docs/Web/HTTP/Status#client_error_responses) status for a client error, or a [2XX](/en-US/docs/Web/HTTP/Status#successful_responses) status if the request can be resolved successfully without further processing). -or any other status otherwise (e.g. a 4xx status for a client error, or a 2xx status if the -request can be resolved successfully without further processing). - -For example, the server may reject a request if its {{HTTPHeader("Content-Length")}} is -too large. - -No common browsers send the `Expect` header, but some other clients such as -cURL do so by default. +No browsers send the `Expect` header, but some clients (command-line tools) do so by default. @@ -33,7 +24,7 @@ cURL do so by default. - +
{{Glossary("Forbidden header name")}}yesYes
@@ -50,8 +41,7 @@ There is only one defined expectation: - `100-continue` - : Informs recipients that the client is about to send a (presumably large) message - body in this request and wishes to receive a {{HTTPStatus("100")}} (Continue) interim - response. + body in this request and wishes to receive a {{HTTPStatus("100", "100 Continue")}} interim response. ## Examples @@ -68,8 +58,17 @@ Content-Length: 1234567890987 Expect: 100-continue ``` -The server checks the headers and generates the response. -The server sends {{HTTPStatus("100")}} (Continue), which instructs the client to send the message body. +The server checks the headers and generates the response, where a {{HTTPStatus("100", "100 Continue")}} instructs the client to send the message body: + +```http +HTTP/1.1 100 Continue +``` + +The client completes the request by sending the actual data: + +```http +[Video data as content for PUT request] +``` ## Specifications diff --git a/files/en-us/web/http/headers/expires/index.md b/files/en-us/web/http/headers/expires/index.md index 409d69be7b7dd0d..716a411115fcc5a 100644 --- a/files/en-us/web/http/headers/expires/index.md +++ b/files/en-us/web/http/headers/expires/index.md @@ -7,16 +7,12 @@ browser-compat: http.headers.Expires {{HTTPSidebar}} -The **`Expires`** HTTP header contains the date/time after which the -response is considered expired. +The HTTP **`Expires`** header contains the date/time after which the response is considered expired in the context of [HTTP caching](/en-US/docs/Web/HTTP/Caching). -Invalid expiration dates with value 0 represent a date in the past and mean that the -resource is already expired. +Invalid expiration dates with value `0` represent a date in the past and mean that the resource is already expired. > [!NOTE] -> If there is a {{HTTPHeader("Cache-Control")}} header -> with the `max-age` or `s-maxage` directive in the response, -> the `Expires` header is ignored. +> If there is a {{HTTPHeader("Cache-Control")}} header with the `max-age` or `s-maxage` directive in the response, the `Expires` header is ignored. @@ -26,13 +22,13 @@ resource is already expired. - + - +
{{Glossary("Forbidden header name")}}noNo
{{Glossary("CORS-safelisted response header")}} yesYes
@@ -40,13 +36,27 @@ resource is already expired. ## Syntax ```http -Expires: +Expires: , :: GMT ``` ## Directives -- \ - - : An HTTP-date timestamp. +- `` + - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). +- `` + - : 2 digit day number, e.g., "04" or "23". +- `` + - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). +- `` + - : 4 digit year number, e.g. "1990" or "2016". +- `` + - : 2 digit hour number, e.g. "09" or "23". +- `` + - : 2 digit minute number, e.g. "04" or "59". +- `` + - : 2 digit second number, e.g. "04" or "59". +- GMT + - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. ## Examples @@ -64,5 +74,6 @@ Expires: Wed, 21 Oct 2015 07:28:00 GMT ## See also +- [HTTP caching](/en-US/docs/Web/HTTP/Caching) guide - {{HTTPHeader("Cache-Control")}} - {{HTTPHeader("Age")}} diff --git a/files/en-us/web/http/headers/forwarded/index.md b/files/en-us/web/http/headers/forwarded/index.md index f679205b2358e1e..47db91b58a7fe6d 100644 --- a/files/en-us/web/http/headers/forwarded/index.md +++ b/files/en-us/web/http/headers/forwarded/index.md @@ -7,7 +7,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc7239 {{HTTPSidebar}} -The **`Forwarded`** request header contains information that may be added by [reverse proxy servers](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling) (load balancers, CDNs, and so on) that would otherwise be altered or lost when proxy servers are involved in the path of the request. +The HTTP **`Forwarded`** request header contains information that may be added by [reverse proxy servers](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling) (load balancers, CDNs, etc.) that would otherwise be altered or lost when proxy servers are involved in the path of the request. For example, if a client is connecting to a web server through an HTTP proxy (or load balancer), server logs will only contain the IP address, host address, and protocol of the proxy; this header can be used to identify the IP address, host, and protocol, of the original request. The header is optional and may be added to, modified, or removed, by any of the proxy servers on the path to the server. @@ -26,7 +26,7 @@ The alternative and de-facto standard versions of this header are the {{HTTPHead {{Glossary("Forbidden header name")}} - no + No diff --git a/files/en-us/web/http/headers/from/index.md b/files/en-us/web/http/headers/from/index.md index 0ed007cf5e8431d..b6f649be2203d15 100644 --- a/files/en-us/web/http/headers/from/index.md +++ b/files/en-us/web/http/headers/from/index.md @@ -7,12 +7,9 @@ browser-compat: http.headers.From {{HTTPSidebar}} -The **`From`** request header contains an Internet email -address for a human user who controls the requesting user agent. +The HTTP **`From`** request header contains an Internet email address for an administrator who controls an automated user agent. -If you are running a robotic user agent (e.g. a crawler), the `From` header -must be sent, so you can be contacted if problems occur on servers, such as if the -robot is sending excessive, unwanted, or invalid requests. +If you are running a robotic user agent (a web crawler, for example), the `From` header must be sent in requests so you can be contacted if problems occur, such as a bot sending excessive, unwanted, or invalid requests. > [!WARNING] > You must not use the `From` header for access control or authentication. @@ -25,7 +22,7 @@ robot is sending excessive, unwanted, or invalid requests. {{Glossary("Forbidden header name")}} - no + No @@ -38,7 +35,7 @@ From: ## Directives -- \ +- `` - : A machine-usable email address. ## Examples diff --git a/files/en-us/web/http/headers/host/index.md b/files/en-us/web/http/headers/host/index.md index 5103533a214249c..b4f0f42e31b0eff 100644 --- a/files/en-us/web/http/headers/host/index.md +++ b/files/en-us/web/http/headers/host/index.md @@ -7,15 +7,13 @@ browser-compat: http.headers.Host {{HTTPSidebar}} -The **`Host`** request header specifies the host and port -number of the server to which the request is being sent. +The HTTP **`Host`** request header specifies the host and port number of the server to which the request is being sent. If no port is included, the default port for the service requested is implied (e.g., `443` for an HTTPS URL, and `80` for an HTTP URL). -A `Host` header field must be sent in all HTTP/1.1 request messages. A -{{HTTPStatus("400")}} (Bad Request) status code may be sent to any HTTP/1.1 request -message that lacks or contains more than one `Host` header field. +A `Host` header field must be sent in all HTTP/1.1 request messages. +A {{HTTPStatus("400", "400 Bad Request")}} status code may be sent to any HTTP/1.1 request message that lacks or contains more than one `Host` header field. @@ -25,7 +23,7 @@ message that lacks or contains more than one `Host` header field. - +
{{Glossary("Forbidden header name")}}yesYes
@@ -38,9 +36,9 @@ Host: : ## Directives -- \ +- `` - : the domain name of the server (for virtual hosting). -- \ {{optional_inline}} +- `` {{optional_inline}} - : TCP port number on which the server is listening. ## Examples diff --git a/files/en-us/web/http/headers/if-match/index.md b/files/en-us/web/http/headers/if-match/index.md index d9f442b93732883..137b131f1ac94d2 100644 --- a/files/en-us/web/http/headers/if-match/index.md +++ b/files/en-us/web/http/headers/if-match/index.md @@ -7,12 +7,11 @@ browser-compat: http.headers.If-Match {{HTTPSidebar}} -The **`If-Match`** HTTP request header makes a request conditional. +The HTTP **`If-Match`** request header makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +A server will return resources for {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, or upload resource for {{HTTPMethod("PUT")}} and other non-safe methods, only if the resource matches one of the {{HTTPHeader("ETag")}} values in the `If-Match` request header. +If the conditional does not match, the {{HTTPStatus("412", "412 Precondition Failed")}} response is returned instead. -A server will only return requested resources for {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, or upload resource for {{HTTPMethod("PUT")}} and other non-safe methods, if the resource matches one of the listed {{HTTPHeader("ETag")}} values. -If the conditional does not match then the {{HTTPStatus("412")}} (Precondition Failed) response is returned. - -The comparison with the stored {{HTTPHeader("ETag")}} uses the _strong comparison algorithm_, meaning two files are considered identical byte by byte only. +The comparison with the stored {{HTTPHeader("ETag")}} uses the _strong comparison algorithm_, meaning two files are considered identical byte-by-byte. If a listed `ETag` has the `W/` prefix indicating a weak entity tag, this comparison algorithm will never match it. There are two common use cases: @@ -30,7 +29,7 @@ There are two common use cases: {{Glossary("Forbidden header name")}} - no + No @@ -47,8 +46,8 @@ If-Match: , , … - `` - : Entity tags uniquely representing the requested resources. They are a string of {{Glossary("ASCII")}} characters placed between double quotes (like `"675af34563dc-tr34"`). - They may be prefixed by `W/` to indicate that they are "weak", i.e. that they represent the resource semantically but not byte-by-byte. - However, in an **`If-Match`** header, weak entity tags will never match. + They may be prefixed by `W/` to indicate that they are 'weak', i.e. that they represent the resource semantically but not byte-by-byte. + However, in an `If-Match` header, weak entity tags will never match. - `*` - : The asterisk is a special value representing any resource. Note that this must match as `false` if the origin server does not have a current representation for the target resource. @@ -74,8 +73,5 @@ If-Match: * ## See also - {{HTTPHeader("ETag")}} -- {{HTTPHeader("If-Unmodified-Since")}} -- {{HTTPHeader("If-Modified-Since")}} -- {{HTTPHeader("If-None-Match")}} +- {{HTTPHeader("If-None-Match")}}, {{HTTPHeader("If-Modified-Since")}}, {{HTTPHeader("If-Unmodified-Since")}} conditional request headers - {{HTTPStatus("412", "412 Precondition Failed")}} -- {{HTTPStatus("416", "416 Range Not Satisfiable")}} diff --git a/files/en-us/web/http/headers/if-modified-since/index.md b/files/en-us/web/http/headers/if-modified-since/index.md index 62473c8a8c67f90..8b79d9af8c9bfd6 100644 --- a/files/en-us/web/http/headers/if-modified-since/index.md +++ b/files/en-us/web/http/headers/if-modified-since/index.md @@ -7,20 +7,14 @@ browser-compat: http.headers.If-Modified-Since {{HTTPSidebar}} -The **`If-Modified-Since`** request HTTP header makes the -request conditional: the server sends back the requested resource, with a -{{HTTPStatus("200")}} status, only if it has been last modified after the given date. If -the resource has not been modified since, the response is a {{HTTPStatus("304")}} -without any body; the {{HTTPHeader("Last-Modified")}} response header of a previous -request contains the date of last modification. Unlike -{{HTTPHeader("If-Unmodified-Since")}}, `If-Modified-Since` can only be used -with a {{HTTPMethod("GET")}} or {{HTTPMethod("HEAD")}}. +The HTTP **`If-Modified-Since`** request header makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The server sends back the requested resource, with a {{HTTPStatus("200")}} status, only if it has been modified after the date in the `If-Modified-Since` header. +If the resource has not been modified since, the response is a {{HTTPStatus("304")}} without any body and the {{HTTPHeader("Last-Modified")}} response header of a previous request contains the date of the last modification. -When used in combination with {{HTTPHeader("If-None-Match")}}, it is ignored, unless -the server doesn't support `If-None-Match`. +Unlike {{HTTPHeader("If-Unmodified-Since")}}, `If-Modified-Since` can only be used with a {{HTTPMethod("GET")}} or {{HTTPMethod("HEAD")}}. +When used in combination with {{HTTPHeader("If-None-Match")}}, it is ignored, unless the server doesn't support `If-None-Match`. -The most common use case is to update a cached entity that has no associated -{{HTTPHeader("ETag")}}. +The most common use case is to update a cached entity that has no associated {{HTTPHeader("ETag")}}. @@ -30,7 +24,7 @@ The most common use case is to update a cached entity that has no associated - +
{{Glossary("Forbidden header name")}}noNo
@@ -43,22 +37,21 @@ If-Modified-Since: , :: GMT ## Directives -- \ +- `` - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). -- \ - - : 2 digit day number, e.g. "04" or "23". -- \ - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", - "Dec" (case sensitive). -- \ +- `` + - : 2 digit day number, e.g., "04" or "23". +- `` + - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). +- `` - : 4 digit year number, e.g. "1990" or "2016". -- \ +- `` - : 2 digit hour number, e.g. "09" or "23". -- \ +- `` - : 2 digit minute number, e.g. "04" or "59". -- \ +- `` - : 2 digit second number, e.g. "04" or "59". -- `GMT` +- GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. ## Examples @@ -78,7 +71,5 @@ If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT ## See also - {{HTTPHeader("ETag")}} -- {{HTTPHeader("If-Unmodified-since")}} -- {{HTTPHeader("If-Match")}} -- {{HTTPHeader("If-None-Match")}} -- {{HTTPStatus("304", "304 Not Modified")}} +- {{HTTPHeader("If-Match")}}, {{HTTPHeader("If-None-Match")}}, {{HTTPHeader("If-Unmodified-Since")}} conditional request headers +- {{HTTPStatus("304", "304 Not Modified")}}, {{HTTPStatus("412", "412 Precondition Failed")}} response status codes diff --git a/files/en-us/web/http/headers/if-none-match/index.md b/files/en-us/web/http/headers/if-none-match/index.md index 45bb59f1a760fb6..39c69732e4468a4 100644 --- a/files/en-us/web/http/headers/if-none-match/index.md +++ b/files/en-us/web/http/headers/if-none-match/index.md @@ -7,17 +7,21 @@ browser-compat: http.headers.If-None-Match {{HTTPSidebar}} -The **`If-None-Match`** HTTP request header makes the request conditional. For {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, the server will return the requested resource, with a {{HTTPStatus("200")}} status, only if it doesn't have an {{HTTPHeader("ETag")}} matching the given ones. For other methods, the request will be processed only if the eventually existing resource's {{HTTPHeader("ETag")}} doesn't match any of the values listed. +The HTTP **`If-None-Match`** request header makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The server returns the requested resource in {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods with a {{HTTPStatus("200")}} status, only if it doesn't have an {{HTTPHeader("ETag")}} matching the ones in the `If-None-Match` header. +For other methods, the request will be processed only if the eventually existing resource's {{HTTPHeader("ETag")}} doesn't match any of the values listed. -When the condition fails for {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, then the server must return HTTP status code 304 (Not Modified). For methods that apply server-side changes, the status code 412 (Precondition Failed) is used. Note that the server generating a 304 response MUST generate any of the following header fields that would have been sent in a 200 (OK) response to the same request: Cache-Control, Content-Location, Date, ETag, Expires, and Vary. +When the condition fails for {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, the server must return a {{HTTPStatus("304", "304 Not Modified")}} and any of the following header fields that would have been sent in a 200 response to the same request: `Cache-Control`, `Content-Location`, `Date`, `ETag`, `Expires`, and `Vary`. +For methods that apply server-side changes, the {{HTTPStatus("412", "412 Precondition Failed")}} is used when the condition fails. -The comparison with the stored {{HTTPHeader("ETag")}} uses the _weak comparison algorithm_, meaning two files are considered identical if the content is equivalent — they don't have to be identical byte by byte. For example, two pages that differ by their creation date in the footer would still be considered identical. +The comparison with the stored ETag uses the _weak comparison algorithm_, meaning two files are considered identical if the content is equivalent — they don't have to be identical byte-by-byte. +For example, two pages that differ by their creation date in the footer would still be considered identical. -When used in combination with {{HTTPHeader("If-Modified-Since")}}, **`If-None-Match`** has precedence (if the server supports it). +When used in combination with {{HTTPHeader("If-Modified-Since")}}, `If-None-Match` has precedence if the server supports it. -There are two common use cases: +There are two common cases for using `If-None-Match` in requests: -- For {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, to update a cached entity that has an associated {{HTTPHeader("ETag")}}. +- For {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, to update a cached entity that has an associated ETag. - For other methods, and in particular for {{HTTPMethod("PUT")}}, `If-None-Match` used with the `*` value can be used to save a file not known to exist, guaranteeing that another upload didn't happen before, losing the data of the previous put; this problem is a variation of the [lost update problem](https://www.w3.org/1999/04/Editing/#3.1). @@ -28,7 +32,7 @@ There are two common use cases: - +
{{Glossary("Forbidden header name")}}noNo
@@ -43,7 +47,7 @@ If-None-Match: * ## Directives -- \ +- `` - : Entity tags uniquely representing the requested resources. They are a string of {{Glossary("ASCII")}} characters placed between double quotes (Like `"675af34563dc-tr34"`) and may be prefixed by `W/` to indicate that the weak comparison algorithm should be used (this is useless with `If-None-Match` as it only uses that algorithm). - `*` - : The asterisk is a special value representing any resource. They are only useful when uploading a resource, usually with {{HTTPMethod("PUT")}}, to check if another resource with the identity has already been uploaded before. @@ -69,8 +73,5 @@ If-None-Match: * ## See also - {{HTTPHeader("ETag")}} -- {{HTTPHeader("If-Unmodified-Since")}} -- {{HTTPHeader("If-Modified-Since")}} -- {{HTTPHeader("If-Match")}} -- {{HTTPStatus("304", "304 Not Modified")}} -- {{HTTPStatus("412", "412 Precondition Failed")}} +- {{HTTPHeader("If-Match")}}, {{HTTPHeader("If-Modified-Since")}}, {{HTTPHeader("If-Unmodified-Since")}} conditional request headers +- {{HTTPStatus("304", "304 Not Modified")}}, {{HTTPStatus("412", "412 Precondition Failed")}} response status codes diff --git a/files/en-us/web/http/headers/if-range/index.md b/files/en-us/web/http/headers/if-range/index.md index 6332c57a782f763..cb0f8251c302687 100644 --- a/files/en-us/web/http/headers/if-range/index.md +++ b/files/en-us/web/http/headers/if-range/index.md @@ -7,17 +7,14 @@ browser-compat: http.headers.If-Range {{HTTPSidebar}} -The **`If-Range`** HTTP request header makes a range request -conditional: if the condition is fulfilled, the range request is issued, and the -server sends back a {{HTTPStatus("206")}} `Partial Content` answer with the -appropriate body. If the condition is not fulfilled, the full resource is sent back -with a {{HTTPStatus("200")}} `OK` status. +The HTTP **`If-Range`** request header is used to make a range request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +If the condition is fulfilled, a [range request](/en-US/docs/Web/HTTP/Range_requests) is issued, and the server sends back a {{HTTPStatus("206", "206 Partial Content")}} response with part (or parts) of the resource in the body. +If the condition is not fulfilled, the full resource is sent back with a {{HTTPStatus("200", "200 OK")}} status. This header can be used either with the {{HTTPHeader("Last-Modified")}} validator or with {{HTTPHeader("ETag")}}, but not with both. -The most common use case is to resume a download, to guarantee that the stored resource -has not been modified since the last fragment has been received. +The most common use case is to resume a download with guarantees that the resource on the server has not been modified since the last part has been received by the client. @@ -27,7 +24,7 @@ has not been modified since the last fragment has been received. - +
{{Glossary("Forbidden header name")}}noNo
@@ -41,31 +38,32 @@ If-Range: ## Directives -- \ +- `` - : An entity tag uniquely representing the requested resource. It is a string of ASCII characters placed between double quotes (Like `"675af34563dc-tr34"`). A weak entity tag (one prefixed by `W/`) must not be used in this header. -- \ +- `` - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). -- \ - - : 2 digit day number, e.g. "04" or "23". -- \ - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", - "Dec" (case-sensitive). -- \ +- `` + - : 2 digit day number, e.g., "04" or "23". +- `` + - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). +- `` - : 4 digit year number, e.g. "1990" or "2016". -- \ +- `` - : 2 digit hour number, e.g. "09" or "23". -- \ +- `` - : 2 digit minute number, e.g. "04" or "59". -- \ +- `` - : 2 digit second number, e.g. "04" or "59". -- `GMT` +- GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. ## Examples ```http If-Range: Wed, 21 Oct 2015 07:28:00 GMT + +If-Range: "67ab43" ``` ## Specifications @@ -78,11 +76,8 @@ If-Range: Wed, 21 Oct 2015 07:28:00 GMT ## See also +- [HTTP Conditional Requests](/en-US/docs/Web/HTTP/Conditional_requests) guide - {{HTTPHeader("ETag")}} - {{HTTPHeader("Last-Modified")}} -- {{HTTPHeader("If-Modified-Since")}} -- {{HTTPHeader("If-Unmodified-Since")}} -- {{HTTPHeader("If-Match")}} -- {{HTTPHeader("If-None-Match")}} -- {{HTTPStatus("206", "206 Partial Content")}} -- [HTTP Conditional Requests](/en-US/docs/Web/HTTP/Conditional_requests) +- {{HTTPHeader("If-Match")}}, {{HTTPHeader("If-Modified-Since")}}, {{HTTPHeader("If-Unmodified-Since")}}, {{HTTPHeader("If-None-Match")}} conditional request headers +- {{HTTPStatus("206", "206 Partial Content")}}, {{HTTPStatus("412", "412 Precondition Failed")}}, {{HTTPStatus("416", "416 Range Not Satisfiable")}} response status codes diff --git a/files/en-us/web/http/headers/if-unmodified-since/index.md b/files/en-us/web/http/headers/if-unmodified-since/index.md index f42172c21698930..893149fceae0296 100644 --- a/files/en-us/web/http/headers/if-unmodified-since/index.md +++ b/files/en-us/web/http/headers/if-unmodified-since/index.md @@ -7,16 +7,15 @@ browser-compat: http.headers.If-Unmodified-Since {{HTTPSidebar}} -The HyperText Transfer Protocol (HTTP) **`If-Unmodified-Since`** request header makes the -request for the resource conditional: the server will send the requested resource or accept it in -the case of a {{HTTPMethod("POST")}} or another non-{{Glossary("Safe/HTTP", "safe")}} method only if the resource has not been modified after the date specified by this HTTP header. If the resource has been modified -after the specified date, the response will be a {{HTTPStatus("412", "412 Precondition Failed")}} error. +The HTTP **`If-Unmodified-Since`** request header makes the request for the resource [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The server will send the requested resource (or accept it in the case of a {{HTTPMethod("POST")}} or another non-{{Glossary("Safe/HTTP", "safe")}} method) only if the resource on the server has not been modified after the date in the request header. +If the resource has been modified after the specified date, the response will be a {{HTTPStatus("412", "412 Precondition Failed")}} error. -The **`If-Unmodified-Since`** HTTP header is commonly used in the following situations: +The `If-Unmodified-Since` header is commonly used in the following situations: -- In conjunction with non-{{Glossary("Safe/HTTP", "safe")}} methods, like {{HTTPMethod("POST")}}, - this header can be used to implement an [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control), as is done by some wikis: editions are rejected if the - stored document has been modified since the original was retrieved. +- In conjunction with non-{{Glossary("Safe/HTTP", "safe")}} methods like {{HTTPMethod("POST")}}, + this header can be used to implement an [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control), as is done by some wikis: revision are rejected if the + stored document has been modified since the original was retrieved, avoiding conflicts. - In conjunction with a range request using the {{HTTPHeader("Range")}} header, this header can be used to ensure that the new fragment requested comes from an unmodified document. @@ -28,7 +27,7 @@ The **`If-Unmodified-Since`** HTTP header is commonly used in the following situ {{Glossary("Forbidden header name")}} - no + No @@ -41,21 +40,21 @@ If-Unmodified-Since: , :: G ## Directives -- \ - - : A 3-letter description of the day of the week. One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). -- \ - - : A 2-digit day number of the month. Examples: "04", "23". -- \ - - : A 3-letter description of the month. One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case-sensitive). -- \ - - : A 4-digit year number. Examples: "1990", "2016". -- \ - - : A 2-digit hour number based on a 24-hour system. Examples: "09", "23". -- \ - - : A 2-digit minute number. Examples: "04", "59". -- \ - - : A 2-digit second number. Examples: "04", "59". -- `GMT` +- `` + - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). +- `` + - : 2 digit day number, e.g., "04" or "23". +- `` + - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). +- `` + - : 4 digit year number, e.g. "1990" or "2016". +- `` + - : 2 digit hour number, e.g. "09" or "23". +- `` + - : 2 digit minute number, e.g. "04" or "59". +- `` + - : 2 digit second number, e.g. "04" or "59". +- GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. ## Examples @@ -74,9 +73,8 @@ If-Unmodified-Since: Wed, 21 Oct 2015 07:28:00 GMT ## See also +- [HTTP Conditional Requests](/en-US/docs/Web/HTTP/Conditional_requests) guide - {{HTTPHeader("Last-Modified")}} -- {{HTTPHeader("If-Modified-Since")}} -- {{HTTPHeader("If-Match")}} -- {{HTTPHeader("If-None-Match")}} -- {{HTTPHeader("Range")}} -- {{HTTPStatus("412", "412 Precondition Failed")}} +- {{HTTPHeader("If-Range")}}, {{HTTPHeader("Range")}} range request headers +- {{HTTPHeader("If-Match")}}, {{HTTPHeader("If-Modified-Since")}}, {{HTTPHeader("If-None-Match")}} conditional request headers +- {{HTTPStatus("304", "304 Not Modified")}}, {{HTTPStatus("412", "412 Precondition Failed")}} response status codes diff --git a/files/en-us/web/http/headers/keep-alive/index.md b/files/en-us/web/http/headers/keep-alive/index.md index 4d2e84d6a9a55b6..208249fe4ec7cee 100644 --- a/files/en-us/web/http/headers/keep-alive/index.md +++ b/files/en-us/web/http/headers/keep-alive/index.md @@ -7,18 +7,18 @@ browser-compat: http.headers.Keep-Alive {{HTTPSidebar}} -The **`Keep-Alive`** general header allows the sender to hint about how the connection may be used to set a timeout and a maximum amount of requests. +The HTTP **`Keep-Alive`** header allows the sender to hint how a connection may be used in terms of a timeout and a maximum amount of requests. > [!NOTE] -> Set the {{HTTPHeader("Connection")}} header to "keep-alive" for this header to have any effect. +> For `Keep-Alive` to have any effect, the message must also include a {{HTTPHeader("Connection", "Connection: keep-alive")}} header. + +HTTP/1.0 closes the connection after each request/response interaction by default, so persistent connections in HTTP/1.0 must be explicitly negotiated. +Some clients and servers might wish to be compatible with previous approaches to persistent connections, and can do this with a `Connection: keep-alive` request header. +Additional parameters for the connection can be requested with the `Keep-Alive` header. > [!WARNING] -> Connection-specific header fields such as -> {{HTTPHeader("Connection")}} and `Keep-Alive` are prohibited -> in [HTTP/2](https://httpwg.org/specs/rfc9113.html#ConnectionSpecific) and -> [HTTP/3](https://httpwg.org/specs/rfc9114.html#header-formatting). Chrome and -> Firefox ignore them in HTTP/2 responses, but Safari conforms to the HTTP/2 -> specification requirements and does not load any response that contains them. +> Connection-specific header fields such as {{HTTPHeader("Connection")}} and `Keep-Alive` are prohibited in [HTTP/2](https://httpwg.org/specs/rfc9113.html#ConnectionSpecific) and [HTTP/3](https://httpwg.org/specs/rfc9114.html#header-formatting). +> Chrome and Firefox ignore them in HTTP/2 responses, but Safari conforms to the HTTP/2 specification requirements and does not load any response that contains them. @@ -31,7 +31,7 @@ The **`Keep-Alive`** general header allows the sender to hint about how the conn - +
{{Glossary("Forbidden header name")}}yesYes
@@ -39,17 +39,19 @@ The **`Keep-Alive`** general header allows the sender to hint about how the conn ## Syntax ```http -Keep-Alive: parameters +Keep-Alive: ``` ## Directives -- `parameters` - - - : A comma-separated list of parameters, each consisting of an identifier and a value separated by the equal sign (`'='`). The following identifiers are possible: - - - `timeout`: An integer that is the time in seconds that the host will allow an idle connection to remain open before it is closed. A connection is idle if no data is sent or received by a host. A host may keep an idle connection open for longer than `timeout` seconds, but the host should attempt to retain a connection for at least `timeout` seconds. - - `max`: An integer that is the maximum number of requests that can be sent on this connection before closing it. Unless `0`, this value is ignored for non-pipelined connections as another request will be sent in the next response. An HTTP pipeline can use it to limit the pipelining. +- `` + - : A comma-separated list of parameters, each consisting of an identifier and a value separated by the equal sign (`=`). + The following identifiers are possible: + - `timeout`: An integer that is the time in seconds that the host will allow an idle connection to remain open before it is closed. + A connection is idle if no data is sent or received by a host. A host may keep an idle connection open for longer than `timeout` seconds, but the host should attempt to retain a connection for at least `timeout` seconds. + - `max`: An integer that is the maximum number of requests that can be sent on this connection before closing it. + Unless `0`, this value is ignored for non-pipelined connections as another request will be sent in the next response. + An HTTP pipeline can use it to limit the pipelining. ## Examples @@ -61,7 +63,7 @@ Connection: Keep-Alive Content-Encoding: gzip Content-Type: text/html; charset=utf-8 Date: Thu, 11 Aug 2016 15:23:13 GMT -Keep-Alive: timeout=5, max=1000 +Keep-Alive: timeout=5, max=200 Last-Modified: Mon, 25 Jul 2016 04:32:39 GMT Server: Apache From 36cf3aa13bff6a670066046749c6e82e80a19b73 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 27 Sep 2024 11:15:03 +0200 Subject: [PATCH 02/15] chore(http): Refresh headers docs d-k --- files/en-us/web/http/headers/expect-ct/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/http/headers/expect-ct/index.md b/files/en-us/web/http/headers/expect-ct/index.md index 460b793dc4a4dc9..948c4493aa359df 100644 --- a/files/en-us/web/http/headers/expect-ct/index.md +++ b/files/en-us/web/http/headers/expect-ct/index.md @@ -36,7 +36,7 @@ CT requirements can be satisfied via any one of the following mechanisms: {{Glossary("Forbidden header name")}} - yes + Yes From 4075e11b7af191b241ccbd1ea78eb8a5c065db5b Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Wed, 23 Oct 2024 13:08:46 +0200 Subject: [PATCH 03/15] chore(http): Add glossary links to request and response header terms --- files/en-us/web/http/headers/device-memory/index.md | 2 +- files/en-us/web/http/headers/digest/index.md | 4 ++-- files/en-us/web/http/headers/dnt/index.md | 2 +- files/en-us/web/http/headers/downlink/index.md | 2 +- files/en-us/web/http/headers/dpr/index.md | 2 +- files/en-us/web/http/headers/early-data/index.md | 2 +- files/en-us/web/http/headers/ect/index.md | 2 +- files/en-us/web/http/headers/etag/index.md | 2 +- files/en-us/web/http/headers/expect/index.md | 2 +- files/en-us/web/http/headers/expires/index.md | 2 +- files/en-us/web/http/headers/forwarded/index.md | 2 +- files/en-us/web/http/headers/from/index.md | 2 +- files/en-us/web/http/headers/host/index.md | 5 ++--- files/en-us/web/http/headers/if-match/index.md | 2 +- files/en-us/web/http/headers/if-modified-since/index.md | 2 +- files/en-us/web/http/headers/if-none-match/index.md | 2 +- files/en-us/web/http/headers/if-range/index.md | 5 ++--- files/en-us/web/http/headers/if-unmodified-since/index.md | 2 +- 18 files changed, 21 insertions(+), 23 deletions(-) diff --git a/files/en-us/web/http/headers/device-memory/index.md b/files/en-us/web/http/headers/device-memory/index.md index cc842fffd461468..10b5cd588cd7f1c 100644 --- a/files/en-us/web/http/headers/device-memory/index.md +++ b/files/en-us/web/http/headers/device-memory/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Device-Memory {{HTTPSidebar}}{{securecontext_header}} -The HTTP **`Device-Memory`** request header is used in [device client hints](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) to indicate the approximate amount of available RAM on the client device. +The HTTP **`Device-Memory`** {{Glossary("request header")}} is used in [device client hints](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) to indicate the approximate amount of available RAM on the client device. The header is part of the {{DOMxRef("Device Memory API", "Device Memory API", "", "nocode")}}. Client hints are accessible only on secure origins. diff --git a/files/en-us/web/http/headers/digest/index.md b/files/en-us/web/http/headers/digest/index.md index 8ce06e7e75c06b5..79ae38d9611f1e9 100644 --- a/files/en-us/web/http/headers/digest/index.md +++ b/files/en-us/web/http/headers/digest/index.md @@ -19,7 +19,7 @@ The HTTP **`Digest`** header provides the recipient with a {{Glossary("digest")} It can be requested by using the {{HTTPHeader("Want-Digest")}} header. Representations are different forms of a particular resource that might be returned from a request: for example, the same resource might be formatted in a particular media type such as XML or JSON, localized to a particular written language or geographical region, and/or compressed or otherwise encoded for transmission. -The _selected representation_ a resource returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}. +The _selected representation_ is a resource returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}. The digest applies to the whole representation of a resource, not to a particular message. It can be used to verify that the representation data has not been modified during transmission. @@ -31,7 +31,7 @@ It can be used to verify that the representation data has not been modified duri Header type - {{Glossary("Response header")}} + {{Glossary("Response header")}}, {{Glossary("Request header")}} {{Glossary("Forbidden header name")}} diff --git a/files/en-us/web/http/headers/dnt/index.md b/files/en-us/web/http/headers/dnt/index.md index 511cf68b5e44642..f366494bb2deef5 100644 --- a/files/en-us/web/http/headers/dnt/index.md +++ b/files/en-us/web/http/headers/dnt/index.md @@ -13,7 +13,7 @@ browser-compat: http.headers.DNT > [!NOTE] > The DNT (Do Not Track) specification has been discontinued. See {{domxref("Navigator.doNotTrack")}} for more information. -The HTTP **`DNT`** (Do Not Track) request header indicates the user's tracking preference. +The HTTP **`DNT`** (Do Not Track) {{Glossary("request header")}} indicates the user's tracking preference. It lets users indicate whether they would prefer privacy rather than personalized content. DNT is deprecated in favor of [Global Privacy Control](https://globalprivacycontrol.org/), which is communicated to servers using the {{HTTPHeader("Sec-GPC")}} header, and accessible to clients from {{domxref("navigator.globalPrivacyControl")}}. diff --git a/files/en-us/web/http/headers/downlink/index.md b/files/en-us/web/http/headers/downlink/index.md index fa46e413877c2b8..5b1170655a49fb6 100644 --- a/files/en-us/web/http/headers/downlink/index.md +++ b/files/en-us/web/http/headers/downlink/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Downlink {{HTTPSidebar}} {{SeeCompatTable}} -The HTTP **`Downlink`** request header is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to provide the approximate bandwidth in Mbps of the client's connection to the server. +The HTTP **`Downlink`** {{Glossary("request header")}} is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to provide the approximate bandwidth in Mbps of the client's connection to the server. The hint allows a server to choose what information is sent based on the network bandwidth. For example, a server might choose to send smaller versions of images and other resources on low bandwidth networks. diff --git a/files/en-us/web/http/headers/dpr/index.md b/files/en-us/web/http/headers/dpr/index.md index 0dc0fbfe7493faf..153e80cae355fec 100644 --- a/files/en-us/web/http/headers/dpr/index.md +++ b/files/en-us/web/http/headers/dpr/index.md @@ -10,7 +10,7 @@ browser-compat: http.headers.DPR {{HTTPSidebar}}{{Deprecated_Header}}{{SecureContext_Header}}{{Non-standard_Header}} -The HTTP **`DPR`** request header provides [device client hints](/en-US/docs/Web/HTTP/Client_hints) about the client device pixel ratio (DPR). +The HTTP **`DPR`** {{Glossary("request header")}} provides [device client hints](/en-US/docs/Web/HTTP/Client_hints) about the client device pixel ratio (DPR). This ratio is the number of physical device pixels corresponding to every {{Glossary("CSS pixel")}}. The hint is useful when selecting image sources that best correspond to a screen's pixel density. diff --git a/files/en-us/web/http/headers/early-data/index.md b/files/en-us/web/http/headers/early-data/index.md index 999fefa0fae7a4a..3ba4d6d2059398f 100644 --- a/files/en-us/web/http/headers/early-data/index.md +++ b/files/en-us/web/http/headers/early-data/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Early-Data {{SeeCompatTable}}{{HTTPSidebar}} -The HTTP **`Early-Data`** header is set by an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3), and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code. +The HTTP **`Early-Data`** {{Glossary("request header")}} is set by an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3), and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code. The `Early-Data` header is **not** set by the originator of the request (i.e., a browser). diff --git a/files/en-us/web/http/headers/ect/index.md b/files/en-us/web/http/headers/ect/index.md index db12beabbab93aa..1034ec91be954ea 100644 --- a/files/en-us/web/http/headers/ect/index.md +++ b/files/en-us/web/http/headers/ect/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.ECT {{HTTPSidebar}} {{SeeCompatTable}} -The HTTP **`ECT`** request header is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to indicate the {{Glossary("effective connection type")}}: `slow-2g`, `2g`, `3g`, or `4g`. +The HTTP **`ECT`** {{Glossary("request header")}} is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to indicate the {{Glossary("effective connection type")}}: `slow-2g`, `2g`, `3g`, or `4g`. The value represents the "network profile" that best matches the connection's latency and bandwidth, rather than the actual mechanisms used for transferring the data. For example, `2g` might be used to represent a slow Wi-Fi connection with high latency and low bandwidth, while `4g` might represent a fast fibre-based broadband network. diff --git a/files/en-us/web/http/headers/etag/index.md b/files/en-us/web/http/headers/etag/index.md index dbc99b67adeef27..eb17ce4f3454ac4 100644 --- a/files/en-us/web/http/headers/etag/index.md +++ b/files/en-us/web/http/headers/etag/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.ETag {{HTTPSidebar}} -The HTTP **`ETag`** (entity tag) response header is an identifier for a specific version of a resource. +The HTTP **`ETag`** (entity tag) {{Glossary("response header")}} is an identifier for a specific version of a resource. It lets [caches](/en-US/docs/Web/HTTP/Caching) be more efficient and save bandwidth, as a web server does not need to resend a full response if the content has not changed. Additionally, ETags help to prevent simultaneous updates of a resource from overwriting each other (["mid-air collisions"](#avoiding_mid-air_collisions)). diff --git a/files/en-us/web/http/headers/expect/index.md b/files/en-us/web/http/headers/expect/index.md index efeb50fb8d88592..0dd38130a17dafe 100644 --- a/files/en-us/web/http/headers/expect/index.md +++ b/files/en-us/web/http/headers/expect/index.md @@ -7,7 +7,7 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#field.expect {{HTTPSidebar}} -The HTTP **`Expect`** request header indicates that there are expectations that need to be met by the server in order to handle the complete request successfully. +The HTTP **`Expect`** {{Glossary("request header")}} indicates that there are expectations that need to be met by the server in order to handle the complete request successfully. When a request has an `Expect: 100-continue` header, a server sends a {{HTTPStatus("100", "100 Continue")}} response to indicate that the server is ready or capable of receiving the rest of the request content. Waiting for a `100` response can be helpful if a client anticipates that an error is likely, for example, when sending state-changing operations without previously verified authentication credentials. diff --git a/files/en-us/web/http/headers/expires/index.md b/files/en-us/web/http/headers/expires/index.md index 716a411115fcc5a..ac442cc079a100c 100644 --- a/files/en-us/web/http/headers/expires/index.md +++ b/files/en-us/web/http/headers/expires/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Expires {{HTTPSidebar}} -The HTTP **`Expires`** header contains the date/time after which the response is considered expired in the context of [HTTP caching](/en-US/docs/Web/HTTP/Caching). +The HTTP **`Expires`** {{Glossary("response header")}} contains the date/time after which the response is considered expired in the context of [HTTP caching](/en-US/docs/Web/HTTP/Caching). Invalid expiration dates with value `0` represent a date in the past and mean that the resource is already expired. diff --git a/files/en-us/web/http/headers/forwarded/index.md b/files/en-us/web/http/headers/forwarded/index.md index 47db91b58a7fe6d..c3b77f6a946f8d9 100644 --- a/files/en-us/web/http/headers/forwarded/index.md +++ b/files/en-us/web/http/headers/forwarded/index.md @@ -7,7 +7,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc7239 {{HTTPSidebar}} -The HTTP **`Forwarded`** request header contains information that may be added by [reverse proxy servers](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling) (load balancers, CDNs, etc.) that would otherwise be altered or lost when proxy servers are involved in the path of the request. +The HTTP **`Forwarded`** {{Glossary("request header")}} contains information that may be added by [reverse proxy servers](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling) (load balancers, CDNs, etc.) that would otherwise be altered or lost when proxy servers are involved in the path of the request. For example, if a client is connecting to a web server through an HTTP proxy (or load balancer), server logs will only contain the IP address, host address, and protocol of the proxy; this header can be used to identify the IP address, host, and protocol, of the original request. The header is optional and may be added to, modified, or removed, by any of the proxy servers on the path to the server. diff --git a/files/en-us/web/http/headers/from/index.md b/files/en-us/web/http/headers/from/index.md index b6f649be2203d15..afc7dcdd0284b74 100644 --- a/files/en-us/web/http/headers/from/index.md +++ b/files/en-us/web/http/headers/from/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.From {{HTTPSidebar}} -The HTTP **`From`** request header contains an Internet email address for an administrator who controls an automated user agent. +The HTTP **`From`** {{Glossary("request header")}} contains an Internet email address for an administrator who controls an automated user agent. If you are running a robotic user agent (a web crawler, for example), the `From` header must be sent in requests so you can be contacted if problems occur, such as a bot sending excessive, unwanted, or invalid requests. diff --git a/files/en-us/web/http/headers/host/index.md b/files/en-us/web/http/headers/host/index.md index b4f0f42e31b0eff..09b58076747011d 100644 --- a/files/en-us/web/http/headers/host/index.md +++ b/files/en-us/web/http/headers/host/index.md @@ -7,10 +7,9 @@ browser-compat: http.headers.Host {{HTTPSidebar}} -The HTTP **`Host`** request header specifies the host and port number of the server to which the request is being sent. +The HTTP **`Host`** {{Glossary("request header")}} specifies the host and port number of the server to which the request is being sent. -If no port is included, the default port for the service requested is implied (e.g., -`443` for an HTTPS URL, and `80` for an HTTP URL). +If no port is included, the default port for the service requested is implied (e.g., `443` for an HTTPS URL, and `80` for an HTTP URL). A `Host` header field must be sent in all HTTP/1.1 request messages. A {{HTTPStatus("400", "400 Bad Request")}} status code may be sent to any HTTP/1.1 request message that lacks or contains more than one `Host` header field. diff --git a/files/en-us/web/http/headers/if-match/index.md b/files/en-us/web/http/headers/if-match/index.md index 137b131f1ac94d2..41d3a40e3ac9e69 100644 --- a/files/en-us/web/http/headers/if-match/index.md +++ b/files/en-us/web/http/headers/if-match/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.If-Match {{HTTPSidebar}} -The HTTP **`If-Match`** request header makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The HTTP **`If-Match`** {{Glossary("request header")}} makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). A server will return resources for {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, or upload resource for {{HTTPMethod("PUT")}} and other non-safe methods, only if the resource matches one of the {{HTTPHeader("ETag")}} values in the `If-Match` request header. If the conditional does not match, the {{HTTPStatus("412", "412 Precondition Failed")}} response is returned instead. diff --git a/files/en-us/web/http/headers/if-modified-since/index.md b/files/en-us/web/http/headers/if-modified-since/index.md index 8b79d9af8c9bfd6..75e26f596e1167c 100644 --- a/files/en-us/web/http/headers/if-modified-since/index.md +++ b/files/en-us/web/http/headers/if-modified-since/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.If-Modified-Since {{HTTPSidebar}} -The HTTP **`If-Modified-Since`** request header makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The HTTP **`If-Modified-Since`** {{Glossary("request header")}} makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). The server sends back the requested resource, with a {{HTTPStatus("200")}} status, only if it has been modified after the date in the `If-Modified-Since` header. If the resource has not been modified since, the response is a {{HTTPStatus("304")}} without any body and the {{HTTPHeader("Last-Modified")}} response header of a previous request contains the date of the last modification. diff --git a/files/en-us/web/http/headers/if-none-match/index.md b/files/en-us/web/http/headers/if-none-match/index.md index 39c69732e4468a4..40006ec70e9c397 100644 --- a/files/en-us/web/http/headers/if-none-match/index.md +++ b/files/en-us/web/http/headers/if-none-match/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.If-None-Match {{HTTPSidebar}} -The HTTP **`If-None-Match`** request header makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The HTTP **`If-None-Match`** {{Glossary("request header")}} makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). The server returns the requested resource in {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods with a {{HTTPStatus("200")}} status, only if it doesn't have an {{HTTPHeader("ETag")}} matching the ones in the `If-None-Match` header. For other methods, the request will be processed only if the eventually existing resource's {{HTTPHeader("ETag")}} doesn't match any of the values listed. diff --git a/files/en-us/web/http/headers/if-range/index.md b/files/en-us/web/http/headers/if-range/index.md index cb0f8251c302687..e5939a17325a8b3 100644 --- a/files/en-us/web/http/headers/if-range/index.md +++ b/files/en-us/web/http/headers/if-range/index.md @@ -7,12 +7,11 @@ browser-compat: http.headers.If-Range {{HTTPSidebar}} -The HTTP **`If-Range`** request header is used to make a range request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The HTTP **`If-Range`** {{Glossary("request header")}} makes a range request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). If the condition is fulfilled, a [range request](/en-US/docs/Web/HTTP/Range_requests) is issued, and the server sends back a {{HTTPStatus("206", "206 Partial Content")}} response with part (or parts) of the resource in the body. If the condition is not fulfilled, the full resource is sent back with a {{HTTPStatus("200", "200 OK")}} status. -This header can be used either with the {{HTTPHeader("Last-Modified")}} validator or -with {{HTTPHeader("ETag")}}, but not with both. +This header can be used either with the {{HTTPHeader("Last-Modified")}} validator or with {{HTTPHeader("ETag")}}, but not with both. The most common use case is to resume a download with guarantees that the resource on the server has not been modified since the last part has been received by the client. diff --git a/files/en-us/web/http/headers/if-unmodified-since/index.md b/files/en-us/web/http/headers/if-unmodified-since/index.md index 893149fceae0296..03fc699cfa8d121 100644 --- a/files/en-us/web/http/headers/if-unmodified-since/index.md +++ b/files/en-us/web/http/headers/if-unmodified-since/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.If-Unmodified-Since {{HTTPSidebar}} -The HTTP **`If-Unmodified-Since`** request header makes the request for the resource [conditional](/en-US/docs/Web/HTTP/Conditional_requests). +The HTTP **`If-Unmodified-Since`** {{Glossary("request header")}} makes the request for the resource [conditional](/en-US/docs/Web/HTTP/Conditional_requests). The server will send the requested resource (or accept it in the case of a {{HTTPMethod("POST")}} or another non-{{Glossary("Safe/HTTP", "safe")}} method) only if the resource on the server has not been modified after the date in the request header. If the resource has been modified after the specified date, the response will be a {{HTTPStatus("412", "412 Precondition Failed")}} error. From a5b96726cc83e3e5790e5f26bd74df7dddc84c2d Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 25 Oct 2024 09:57:23 +1100 Subject: [PATCH 04/15] etag - more layout fixes --- files/en-us/web/http/headers/etag/index.md | 32 ++++++++-------------- 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/files/en-us/web/http/headers/etag/index.md b/files/en-us/web/http/headers/etag/index.md index eb17ce4f3454ac4..a58d0c775680369 100644 --- a/files/en-us/web/http/headers/etag/index.md +++ b/files/en-us/web/http/headers/etag/index.md @@ -37,18 +37,15 @@ ETag: "" ## Directives - `W/` {{optional_inline}} - - : `W/` (case-sensitive) indicates that a [weak validator](/en-US/docs/Web/HTTP/Conditional_requests#weak_validation) - is used. Weak ETags are easy to generate, but are far less useful for comparisons. - Strong validators are ideal for comparisons but can be very difficult to generate - efficiently. Weak `ETag` values of two representations of the same - resources might be semantically equivalent, but not byte-for-byte identical. This - means weak ETags prevent caching when [byte range requests](/en-US/docs/Web/HTTP/Headers/Accept-Ranges) are used, - but strong ETags mean range requests can still be cached. + - : `W/` (case-sensitive) indicates that a [weak validator](/en-US/docs/Web/HTTP/Conditional_requests#weak_validation) is used. + Weak ETags are easy to generate, but are far less useful for comparisons. + Strong validators are ideal for comparisons but can be very difficult to generate efficiently. + Weak `ETag` values of two representations of the same resources might be semantically equivalent, but not byte-for-byte identical. + This means weak ETags prevent caching when [byte range requests](/en-US/docs/Web/HTTP/Headers/Accept-Ranges) are used, but strong ETags mean range requests can still be cached. - `` - - : Entity tag that uniquely represents the requested resource. It is a string of {{Glossary("ASCII")}} - characters placed between double quotes, like `"675af34563dc-tr34"`. The - method by which `ETag` values are generated is not specified. Typically, the ETag value - is a hash of the content, a hash of the last modification timestamp, or just a revision number. + - : Entity tag that uniquely represents the requested resource. It is a string of {{Glossary("ASCII")}} characters placed between double quotes, like `"675af34563dc-tr34"`. + The method by which `ETag` values are generated is not specified. + Typically, the ETag value is a hash of the content, a hash of the last modification timestamp, or just a revision number. For example, a wiki engine can use a hexadecimal hash of the documentation article content. ## Examples @@ -81,21 +78,14 @@ If the hashes don't match, it means that the document has been edited in-between ### Caching of unchanged resources -Another typical use of the `ETag` header is to cache resources that are -unchanged. If a user visits a given URL again (that has an `ETag` set), and -it is _stale_ (too old to be considered usable), the client will send the value -of its `ETag` along in an {{HTTPHeader("If-None-Match")}} header field: +Another typical use of the `ETag` header is to cache resources that are unchanged. +If a user visits a given URL again (that has an `ETag` set), and it is _stale_ (too old to be considered usable), the client will send the value of its `ETag` along in an {{HTTPHeader("If-None-Match")}} header field: ```http If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4" ``` -The server compares the client's `ETag` (sent with -`If-None-Match`) with the `ETag` for its current version of the -resource, and if both values match (that is, the resource has not changed), the server -sends back a {{HTTPStatus("304", "304 Not Modified")}} status, without a body, -which tells the client that the cached version of the response is still good to use -(_fresh_). +The server compares the client's `ETag` (sent with `If-None-Match`) with the `ETag` for its current version of the resource, and if both values match (that is, the resource has not changed), the server sends back a {{HTTPStatus("304", "304 Not Modified")}} status, without a body, which tells the client that the cached version of the response is still good to use (_fresh_). ## Specifications From 3f1225b13a99716d2fc1b39400aaa676c65d3cf7 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 25 Oct 2024 09:59:25 +1100 Subject: [PATCH 05/15] expect-ct - add response header --- files/en-us/web/http/headers/expect-ct/index.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/files/en-us/web/http/headers/expect-ct/index.md b/files/en-us/web/http/headers/expect-ct/index.md index 948c4493aa359df..dbd2eacbbe1daa0 100644 --- a/files/en-us/web/http/headers/expect-ct/index.md +++ b/files/en-us/web/http/headers/expect-ct/index.md @@ -9,9 +9,11 @@ browser-compat: http.headers.Expect-CT {{HTTPSidebar}}{{Deprecated_Header}} -The `Expect-CT` header lets sites opt in to reporting and/or enforcement of [Certificate Transparency](/en-US/docs/Web/Security/Certificate_Transparency) requirements. Certificate Transparency (CT) aims to prevent the use of misissued certificates for that site from going unnoticed. +The `Expect-CT` {{Glossary("response header")}} lets sites opt in to reporting and/or enforcement of [Certificate Transparency](/en-US/docs/Web/Security/Certificate_Transparency) requirements. +Certificate Transparency (CT) aims to prevent the use of misissued certificates for that site from going unnoticed. -Only Google Chrome and other Chromium-based browsers implemented `Expect-CT`, and Chromium has deprecated the header from version 107, because Chromium now enforces CT by default. See the [Chrome Platform Status](https://chromestatus.com/feature/6244547273687040) update. +Only Google Chrome and other Chromium-based browsers implemented `Expect-CT`, and Chromium has deprecated the header from version 107, because Chromium now enforces CT by default. +See the [Chrome Platform Status](https://chromestatus.com/feature/6244547273687040) update. CT requirements can be satisfied via any one of the following mechanisms: @@ -26,7 +28,10 @@ CT requirements can be satisfied via any one of the following mechanisms: > Browsers **ignore** the `Expect-CT` header over HTTP; the header only has effect on HTTPS connections. > [!NOTE] -> The `Expect-CT` is mostly obsolete since June 2021. Since May 2018, all new TLS certificates are expected to support SCTs by default. Certificates issued before March 2018 were allowed to have a lifetime of 39 months, so they had expired in June 2021. Chromium plans to deprecate `Expect-CT` header and to eventually remove it. +> The `Expect-CT` is mostly obsolete since June 2021. +> Since May 2018, all new TLS certificates are expected to support SCTs by default. +> Certificates issued before March 2018 were allowed to have a lifetime of 39 months, so they had expired in June 2021. +> Chromium plans to deprecate `Expect-CT` header and to eventually remove it. From 4abd5f0bda8c9cd125d25ae17708547e12b81727 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 25 Oct 2024 10:01:38 +1100 Subject: [PATCH 06/15] expect - minor layout changes --- files/en-us/web/http/headers/expect/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/http/headers/expect/index.md b/files/en-us/web/http/headers/expect/index.md index 0dd38130a17dafe..65669b30b8410e3 100644 --- a/files/en-us/web/http/headers/expect/index.md +++ b/files/en-us/web/http/headers/expect/index.md @@ -40,15 +40,13 @@ Expect: 100-continue There is only one defined expectation: - `100-continue` - - : Informs recipients that the client is about to send a (presumably large) message - body in this request and wishes to receive a {{HTTPStatus("100", "100 Continue")}} interim response. + - : Informs recipients that the client is about to send a (presumably large) message body in this request and wishes to receive a {{HTTPStatus("100", "100 Continue")}} interim response. ## Examples ### Large message body -A client sends a request with `Expect` header and waits for the server to respond -before sending the message body. +A client sends a request with `Expect` header and waits for the server to respond before sending the message body. ```http PUT /somewhere/fun HTTP/1.1 From 0de771ffc68339ab57b01d7215b8072875f29111 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 25 Oct 2024 10:26:15 +1100 Subject: [PATCH 07/15] if-unmodified-since layout --- files/en-us/web/http/headers/if-unmodified-since/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/http/headers/if-unmodified-since/index.md b/files/en-us/web/http/headers/if-unmodified-since/index.md index 03fc699cfa8d121..f3257531748fc8b 100644 --- a/files/en-us/web/http/headers/if-unmodified-since/index.md +++ b/files/en-us/web/http/headers/if-unmodified-since/index.md @@ -13,11 +13,9 @@ If the resource has been modified after the specified date, the response will be The `If-Unmodified-Since` header is commonly used in the following situations: -- In conjunction with non-{{Glossary("Safe/HTTP", "safe")}} methods like {{HTTPMethod("POST")}}, - this header can be used to implement an [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control), as is done by some wikis: revision are rejected if the +- In conjunction with non-{{Glossary("Safe/HTTP", "safe")}} methods like {{HTTPMethod("POST")}}, this header can be used to implement an [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control), as is done by some wikis: revision are rejected if the stored document has been modified since the original was retrieved, avoiding conflicts. -- In conjunction with a range request using the {{HTTPHeader("Range")}} header, this header can - be used to ensure that the new fragment requested comes from an unmodified document. +- In conjunction with a range request using the {{HTTPHeader("Range")}} header, this header can be used to ensure that the new fragment requested comes from an unmodified document.
From c81218fe31ef2bf9845b028be979b4569b616e40 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 29 Oct 2024 17:04:02 +0100 Subject: [PATCH 08/15] Apply suggestions from code review Co-authored-by: Hamish Willee --- files/en-us/web/http/headers/device-memory/index.md | 2 +- files/en-us/web/http/headers/expect/index.md | 2 +- files/en-us/web/http/headers/expires/index.md | 2 +- files/en-us/web/http/headers/host/index.md | 2 +- files/en-us/web/http/headers/if-modified-since/index.md | 2 +- files/en-us/web/http/headers/if-none-match/index.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/files/en-us/web/http/headers/device-memory/index.md b/files/en-us/web/http/headers/device-memory/index.md index 10b5cd588cd7f1c..27a3ebea47b26ad 100644 --- a/files/en-us/web/http/headers/device-memory/index.md +++ b/files/en-us/web/http/headers/device-memory/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Device-Memory {{HTTPSidebar}}{{securecontext_header}} -The HTTP **`Device-Memory`** {{Glossary("request header")}} is used in [device client hints](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) to indicate the approximate amount of available RAM on the client device. +The HTTP **`Device-Memory`** {{Glossary("request header")}} is used in [device client hints](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) to indicate the approximate amount of available RAM on the client device, in gigabytes. The header is part of the {{DOMxRef("Device Memory API", "Device Memory API", "", "nocode")}}. Client hints are accessible only on secure origins. diff --git a/files/en-us/web/http/headers/expect/index.md b/files/en-us/web/http/headers/expect/index.md index 65669b30b8410e3..13bfbb99b2c9570 100644 --- a/files/en-us/web/http/headers/expect/index.md +++ b/files/en-us/web/http/headers/expect/index.md @@ -14,7 +14,7 @@ Waiting for a `100` response can be helpful if a client anticipates that an erro A {{HTTPStatus("417", "417 Expectation Failed")}} response is returned if the server cannot meet the expectation, or any other status otherwise (e.g., a [4XX](/en-US/docs/Web/HTTP/Status#client_error_responses) status for a client error, or a [2XX](/en-US/docs/Web/HTTP/Status#successful_responses) status if the request can be resolved successfully without further processing). -No browsers send the `Expect` header, but some clients (command-line tools) do so by default. +None of the more common browsers send the `Expect` header, but some clients (command-line tools) do so by default.
diff --git a/files/en-us/web/http/headers/expires/index.md b/files/en-us/web/http/headers/expires/index.md index ac442cc079a100c..583da30a3272faf 100644 --- a/files/en-us/web/http/headers/expires/index.md +++ b/files/en-us/web/http/headers/expires/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Expires The HTTP **`Expires`** {{Glossary("response header")}} contains the date/time after which the response is considered expired in the context of [HTTP caching](/en-US/docs/Web/HTTP/Caching). -Invalid expiration dates with value `0` represent a date in the past and mean that the resource is already expired. +The value `0` is used to represent a date in the past, indicating the resource has already expired. > [!NOTE] > If there is a {{HTTPHeader("Cache-Control")}} header with the `max-age` or `s-maxage` directive in the response, the `Expires` header is ignored. diff --git a/files/en-us/web/http/headers/host/index.md b/files/en-us/web/http/headers/host/index.md index 09b58076747011d..92a84b6bf0080ba 100644 --- a/files/en-us/web/http/headers/host/index.md +++ b/files/en-us/web/http/headers/host/index.md @@ -36,7 +36,7 @@ Host: : ## Directives - `` - - : the domain name of the server (for virtual hosting). + - : The domain name of the server (for virtual hosting). - `` {{optional_inline}} - : TCP port number on which the server is listening. diff --git a/files/en-us/web/http/headers/if-modified-since/index.md b/files/en-us/web/http/headers/if-modified-since/index.md index 75e26f596e1167c..df20224073c11dd 100644 --- a/files/en-us/web/http/headers/if-modified-since/index.md +++ b/files/en-us/web/http/headers/if-modified-since/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.If-Modified-Since The HTTP **`If-Modified-Since`** {{Glossary("request header")}} makes a request [conditional](/en-US/docs/Web/HTTP/Conditional_requests). The server sends back the requested resource, with a {{HTTPStatus("200")}} status, only if it has been modified after the date in the `If-Modified-Since` header. -If the resource has not been modified since, the response is a {{HTTPStatus("304")}} without any body and the {{HTTPHeader("Last-Modified")}} response header of a previous request contains the date of the last modification. +If the resource has not been modified since, the response is a {{HTTPStatus("304")}} without any body, and the {{HTTPHeader("Last-Modified")}} response header of the previous request contains the date of the last modification. Unlike {{HTTPHeader("If-Unmodified-Since")}}, `If-Modified-Since` can only be used with a {{HTTPMethod("GET")}} or {{HTTPMethod("HEAD")}}. When used in combination with {{HTTPHeader("If-None-Match")}}, it is ignored, unless the server doesn't support `If-None-Match`. diff --git a/files/en-us/web/http/headers/if-none-match/index.md b/files/en-us/web/http/headers/if-none-match/index.md index 40006ec70e9c397..058ab90a9f9e99a 100644 --- a/files/en-us/web/http/headers/if-none-match/index.md +++ b/files/en-us/web/http/headers/if-none-match/index.md @@ -22,7 +22,7 @@ When used in combination with {{HTTPHeader("If-Modified-Since")}}, `If-None-Matc There are two common cases for using `If-None-Match` in requests: - For {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}} methods, to update a cached entity that has an associated ETag. -- For other methods, and in particular for {{HTTPMethod("PUT")}}, `If-None-Match` used with the `*` value can be used to save a file not known to exist, guaranteeing that another upload didn't happen before, losing the data of the previous put; this problem is a variation of the [lost update problem](https://www.w3.org/1999/04/Editing/#3.1). +- For other methods, and in particular for {{HTTPMethod("PUT")}}, `If-None-Match` used with the `*` value can be used to save a file only if it does not already exist, guaranteeing that the upload won't accidentally overwrite another upload and lose the data of the previous `PUT`; this problem is a variation of the [lost update problem](https://www.w3.org/1999/04/Editing/#3.1).
From 0070d387697f47de66f8a8239c320f86c385de43 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 29 Oct 2024 17:09:28 +0100 Subject: [PATCH 09/15] Update files/en-us/web/http/headers/if-unmodified-since/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/http/headers/if-unmodified-since/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/files/en-us/web/http/headers/if-unmodified-since/index.md b/files/en-us/web/http/headers/if-unmodified-since/index.md index 3cfee265f215642..d3177297df5618c 100644 --- a/files/en-us/web/http/headers/if-unmodified-since/index.md +++ b/files/en-us/web/http/headers/if-unmodified-since/index.md @@ -13,7 +13,6 @@ If the resource has been modified after the specified date, the response will be The `If-Unmodified-Since` header is commonly used in the following situations: - - In conjunction with non-{{Glossary("Safe/HTTP", "safe")}} methods like {{HTTPMethod("POST")}}, this header can be used to implement an [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control), as is done by some wikis: revision are rejected if the stored document has been modified since the original was retrieved, avoiding conflicts. - In conjunction with a range request using the {{HTTPHeader("Range")}} header, this header can be used to ensure that the new fragment requested comes from an unmodified document. From c4dd4d540615b45e3c9d154eacedb86af25cd8f9 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 29 Oct 2024 17:29:02 +0100 Subject: [PATCH 10/15] Update files/en-us/web/http/headers/date/index.md Co-authored-by: Hamish Willee --- files/en-us/web/http/headers/date/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/http/headers/date/index.md b/files/en-us/web/http/headers/date/index.md index f0cf9f33451373b..075ead0e960e555 100644 --- a/files/en-us/web/http/headers/date/index.md +++ b/files/en-us/web/http/headers/date/index.md @@ -45,7 +45,7 @@ Date: , :: GMT ## Directives - `` - - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). + - : One of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, or `Sun` (case-sensitive). - `` - : 2 digit day number, e.g., "04" or "23". - `` From cbbafade262a59b230140907bae499dc3dac0f66 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 29 Oct 2024 17:33:11 +0100 Subject: [PATCH 11/15] chore(http): Use code style for date format DLs --- files/en-us/web/http/headers/date/index.md | 10 +++++----- files/en-us/web/http/headers/expires/index.md | 12 ++++++------ .../web/http/headers/if-modified-since/index.md | 12 ++++++------ files/en-us/web/http/headers/if-range/index.md | 12 ++++++------ .../web/http/headers/if-unmodified-since/index.md | 12 ++++++------ 5 files changed, 29 insertions(+), 29 deletions(-) diff --git a/files/en-us/web/http/headers/date/index.md b/files/en-us/web/http/headers/date/index.md index 075ead0e960e555..5fecf514da6043b 100644 --- a/files/en-us/web/http/headers/date/index.md +++ b/files/en-us/web/http/headers/date/index.md @@ -49,15 +49,15 @@ Date: , :: GMT - `` - : 2 digit day number, e.g., "04" or "23". - `` - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). + - : One of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec` (case sensitive). - `` - - : 4 digit year number, e.g. "1990" or "2016". + - : 4 digit year number, e.g., "1990" or "2016". - `` - - : 2 digit hour number, e.g. "09" or "23". + - : 2 digit hour number, e.g., "09" or "23". - `` - - : 2 digit minute number, e.g. "04" or "59". + - : 2 digit minute number, e.g., "04" or "59". - `` - - : 2 digit second number, e.g. "04" or "59". + - : 2 digit second number, e.g., "04" or "59". - GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. diff --git a/files/en-us/web/http/headers/expires/index.md b/files/en-us/web/http/headers/expires/index.md index 583da30a3272faf..6d3f995b14119cc 100644 --- a/files/en-us/web/http/headers/expires/index.md +++ b/files/en-us/web/http/headers/expires/index.md @@ -42,19 +42,19 @@ Expires: , :: GMT ## Directives - `` - - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). + - : One of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, or `Sun` (case-sensitive). - `` - : 2 digit day number, e.g., "04" or "23". - `` - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). + - : One of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec` (case sensitive). - `` - - : 4 digit year number, e.g. "1990" or "2016". + - : 4 digit year number, e.g., "1990" or "2016". - `` - - : 2 digit hour number, e.g. "09" or "23". + - : 2 digit hour number, e.g., "09" or "23". - `` - - : 2 digit minute number, e.g. "04" or "59". + - : 2 digit minute number, e.g., "04" or "59". - `` - - : 2 digit second number, e.g. "04" or "59". + - : 2 digit second number, e.g., "04" or "59". - GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. diff --git a/files/en-us/web/http/headers/if-modified-since/index.md b/files/en-us/web/http/headers/if-modified-since/index.md index df20224073c11dd..25fe771316f08d2 100644 --- a/files/en-us/web/http/headers/if-modified-since/index.md +++ b/files/en-us/web/http/headers/if-modified-since/index.md @@ -38,19 +38,19 @@ If-Modified-Since: , :: GMT ## Directives - `` - - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). + - : One of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, or `Sun` (case-sensitive). - `` - : 2 digit day number, e.g., "04" or "23". - `` - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). + - : One of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec` (case sensitive). - `` - - : 4 digit year number, e.g. "1990" or "2016". + - : 4 digit year number, e.g., "1990" or "2016". - `` - - : 2 digit hour number, e.g. "09" or "23". + - : 2 digit hour number, e.g., "09" or "23". - `` - - : 2 digit minute number, e.g. "04" or "59". + - : 2 digit minute number, e.g., "04" or "59". - `` - - : 2 digit second number, e.g. "04" or "59". + - : 2 digit second number, e.g., "04" or "59". - GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. diff --git a/files/en-us/web/http/headers/if-range/index.md b/files/en-us/web/http/headers/if-range/index.md index e5939a17325a8b3..876f8e6cfdc9412 100644 --- a/files/en-us/web/http/headers/if-range/index.md +++ b/files/en-us/web/http/headers/if-range/index.md @@ -41,19 +41,19 @@ If-Range: - : An entity tag uniquely representing the requested resource. It is a string of ASCII characters placed between double quotes (Like `"675af34563dc-tr34"`). A weak entity tag (one prefixed by `W/`) must not be used in this header. - `` - - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). + - : One of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, or `Sun` (case-sensitive). - `` - : 2 digit day number, e.g., "04" or "23". - `` - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). + - : One of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec` (case sensitive). - `` - - : 4 digit year number, e.g. "1990" or "2016". + - : 4 digit year number, e.g., "1990" or "2016". - `` - - : 2 digit hour number, e.g. "09" or "23". + - : 2 digit hour number, e.g., "09" or "23". - `` - - : 2 digit minute number, e.g. "04" or "59". + - : 2 digit minute number, e.g., "04" or "59". - `` - - : 2 digit second number, e.g. "04" or "59". + - : 2 digit second number, e.g., "04" or "59". - GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. diff --git a/files/en-us/web/http/headers/if-unmodified-since/index.md b/files/en-us/web/http/headers/if-unmodified-since/index.md index d3177297df5618c..5ac6a3661f4dd5b 100644 --- a/files/en-us/web/http/headers/if-unmodified-since/index.md +++ b/files/en-us/web/http/headers/if-unmodified-since/index.md @@ -38,19 +38,19 @@ If-Unmodified-Since: , :: G ## Directives - `` - - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive). + - : One of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, or `Sun` (case-sensitive). - `` - : 2 digit day number, e.g., "04" or "23". - `` - - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" (case sensitive). + - : One of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec` (case sensitive). - `` - - : 4 digit year number, e.g. "1990" or "2016". + - : 4 digit year number, e.g., "1990" or "2016". - `` - - : 2 digit hour number, e.g. "09" or "23". + - : 2 digit hour number, e.g., "09" or "23". - `` - - : 2 digit minute number, e.g. "04" or "59". + - : 2 digit minute number, e.g., "04" or "59". - `` - - : 2 digit second number, e.g. "04" or "59". + - : 2 digit second number, e.g., "04" or "59". - GMT - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. From 3df89d171d5c71b261280eb4157f0ffaff83257a Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 29 Oct 2024 17:37:01 +0100 Subject: [PATCH 12/15] chore(http): Use nested DLs under directives --- files/en-us/web/http/headers/keep-alive/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/http/headers/keep-alive/index.md b/files/en-us/web/http/headers/keep-alive/index.md index 208249fe4ec7cee..c2fdd0d0bc2027c 100644 --- a/files/en-us/web/http/headers/keep-alive/index.md +++ b/files/en-us/web/http/headers/keep-alive/index.md @@ -47,11 +47,13 @@ Keep-Alive: - `` - : A comma-separated list of parameters, each consisting of an identifier and a value separated by the equal sign (`=`). The following identifiers are possible: - - `timeout`: An integer that is the time in seconds that the host will allow an idle connection to remain open before it is closed. - A connection is idle if no data is sent or received by a host. A host may keep an idle connection open for longer than `timeout` seconds, but the host should attempt to retain a connection for at least `timeout` seconds. - - `max`: An integer that is the maximum number of requests that can be sent on this connection before closing it. - Unless `0`, this value is ignored for non-pipelined connections as another request will be sent in the next response. - An HTTP pipeline can use it to limit the pipelining. + - `timeout` + - : An integer that is the time in seconds that the host will allow an idle connection to remain open before it is closed. + A connection is idle if no data is sent or received by a host. A host may keep an idle connection open for longer than `timeout` seconds, but the host should attempt to retain a connection for at least `timeout` seconds. + - `max` + - : An integer that is the maximum number of requests that can be sent on this connection before closing it. + Unless `0`, this value is ignored for non-pipelined connections as another request will be sent in the next response. + An HTTP pipeline can use it to limit the pipelining. ## Examples From 9325624deacea879380cdf56622ded5967d62153 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 29 Oct 2024 18:04:13 +0100 Subject: [PATCH 13/15] chore(http): Details about forbidden header names --- .../glossary/forbidden_header_name/index.md | 18 +++++++--- files/en-us/web/http/headers/date/index.md | 34 ++++++++++++------- files/en-us/web/http/headers/dpr/index.md | 8 ++--- 3 files changed, 40 insertions(+), 20 deletions(-) diff --git a/files/en-us/glossary/forbidden_header_name/index.md b/files/en-us/glossary/forbidden_header_name/index.md index 526fe1b42b5ca57..c7dbf7f985b6363 100644 --- a/files/en-us/glossary/forbidden_header_name/index.md +++ b/files/en-us/glossary/forbidden_header_name/index.md @@ -8,8 +8,18 @@ page-type: glossary-definition A **forbidden header name** is the name of any [HTTP header](/en-US/docs/Web/HTTP/Headers) that cannot be modified programmatically; specifically, an HTTP **request** header name (in contrast with a {{Glossary("Forbidden response header name")}}). -Modifying such headers is forbidden because the user agent retains full control over them. Names starting with `Sec-` are reserved for creating new headers safe from {{glossary("API","APIs")}} that grant developers control over headers, such as {{domxref("Window/fetch", "fetch()")}}. - +Modifying such headers is forbidden because the user agent retains full control over them. +For example, the {{HTTPHeader("Date")}} header is a forbidden header name, so this code cannot set the message `Date` field: + +```js example-bad +fetch("https://httpbin.org/get", { + headers: { + Date: new Date().toUTCString(), + }, +}); +``` + +Names starting with `Sec-` are reserved for creating new headers safe from {{glossary("API","APIs")}} that grant developers control over headers, such as {{domxref("Window/fetch", "fetch()")}}. Forbidden header names start with `Proxy-` or `Sec-`, or are one of the following names: - {{HTTPHeader("Accept-Charset")}} @@ -26,8 +36,8 @@ Forbidden header names start with `Proxy-` or `Sec-`, or are one of the followin - {{HTTPHeader("Keep-Alive")}} - {{HTTPHeader("Origin")}} - {{HTTPHeader("Permissions-Policy")}} -- `Proxy-` -- `Sec-` +- `Proxy-` headers +- `Sec-` headers - {{HTTPHeader("Referer")}} - {{HTTPHeader("TE")}} - {{HTTPHeader("Trailer")}} diff --git a/files/en-us/web/http/headers/date/index.md b/files/en-us/web/http/headers/date/index.md index 5fecf514da6043b..f709981db075399 100644 --- a/files/en-us/web/http/headers/date/index.md +++ b/files/en-us/web/http/headers/date/index.md @@ -9,17 +9,6 @@ browser-compat: http.headers.Date The HTTP **`Date`** header contains the date and time at which the message originated. -> [!WARNING] -> The `Date` header is a {{Glossary("Forbidden header name")}}, so this code cannot set the message `Date`, for example: -> -> ```js -> fetch("https://httpbin.org/get", { -> headers: { -> Date: new Date().toUTCString(), -> }, -> }); -> ``` -
@@ -63,8 +52,29 @@ Date: , :: GMT ## Examples +### Response with a Date header + +The following HTTP message is a successful `200` status, with a `Date` header showing the time the message originated. +Other headers are omitted for brevity: + ```http -Date: Wed, 21 Oct 2015 07:28:00 GMT +HTTP/1.1 200 +Content-Type: text/html +Date: Tue, 29 Oct 2024 16:56:32 GMT + + [!WARNING] +> The `DPR` header was removed from the client hints specification in [draft-ietf-httpbis-client-hints-07](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07). +> The proposed replacement is [`Sec-CH-DPR`](https://wicg.github.io/responsive-image-client-hints/#sec-ch-dpr) (Responsive Image Client Hints). + The HTTP **`DPR`** {{Glossary("request header")}} provides [device client hints](/en-US/docs/Web/HTTP/Client_hints) about the client device pixel ratio (DPR). This ratio is the number of physical device pixels corresponding to every {{Glossary("CSS pixel")}}. @@ -22,10 +26,6 @@ If the `DPR` header appears more than once in a message the last occurrence is u Servers that opt in to the `DPR` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header to inform caches that the server may send different responses based on the header value in a request. -> [!WARNING] -> The `DPR` header was removed from the client hints specification in [draft-ietf-httpbis-client-hints-07](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-client-hints-07). -> The proposed replacement is [`Sec-CH-DPR`](https://wicg.github.io/responsive-image-client-hints/#sec-ch-dpr) (Responsive Image Client Hints). -
From 3e6ccdd9faee44c7e85ceef8e5fb4a83a776976b Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 18 Nov 2024 10:51:49 +0100 Subject: [PATCH 14/15] chore(http): Changes following reviewer feedback --- .../http_header_page_template/index.md | 23 +++++++++++++++---- .../web/http/headers/accept-encoding/index.md | 2 +- files/en-us/web/http/headers/date/index.md | 2 +- files/en-us/web/http/headers/digest/index.md | 2 +- .../web/http/headers/early-data/index.md | 22 +++++++++++++++++- .../web/http/headers/keep-alive/index.md | 2 +- 6 files changed, 43 insertions(+), 10 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md index 862af1c8684ec41..b6136288d74d787 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md @@ -72,8 +72,15 @@ page-type: mdn-writing-guide {{httpsidebar}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} -The summary paragraph — start by naming the http header and saying what it does. -This should ideally be one or two short sentences. +The first sentence of the page must follow this format: + +> The HTTP **`header-name`** (header type) is used for X in Y circumstances. + +The 'header type' should say if it's a {{Glossary("request header")}}, a {{Glossary("response header")}}, or if it may be either. +The summary paragraph should ideally be one or two short sentences. + +You can mention notable gotchas or common pitfalls in this section, linking to examples or more detailed documentation (guides, etc.) in this section. +Two or three paragraphs in this section is appropriate, and if there are substantial usage notes to include, use a "Description" section after "Directives" below.
@@ -88,13 +95,13 @@ This should ideally be one or two short sentences. - + - +
{{Glossary("Forbidden header name")}}yes or no"Yes" or "No"
{{Glossary("CORS-safelisted response header")}} yes or no"Yes" or "No"
@@ -123,13 +130,17 @@ Multiple directives are comma-separated (delete information as appropriate). If the header has a lot of available directives, feel free to include multiple definition lists, subsections, and explanations as appropriate. +## Description + +If there is too much context or notes to include in the opening paragraphs, provide as much detail as necessary here, such as background information, hints for usage, and links to documentation. + ## Examples Note that we use the plural "Examples" even if the page only contains one example. ### A descriptive heading -Each example must have an H3 heading (`###`) naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading. +Each example **must** have an H3 heading (`###`) naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading. See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples) for more information. @@ -183,6 +194,8 @@ Developers can set and get HTTP headers using `fetch()` in order to provide appl ## See also Include links to reference pages and guides related to the current HTTP header. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_. +You can link to relevant response statuses like `\{{HTTPStatus("123", "123 Response Status")}}` and headers like `\{{HTTPHeader("Header-Name")}}`. +You may group related statuses and headers in a single list item for brevity. - link1 - link2 diff --git a/files/en-us/web/http/headers/accept-encoding/index.md b/files/en-us/web/http/headers/accept-encoding/index.md index 7851ac43adcdb68..78863294a7460a7 100644 --- a/files/en-us/web/http/headers/accept-encoding/index.md +++ b/files/en-us/web/http/headers/accept-encoding/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Accept-Encoding {{HTTPSidebar}} -The HTTP **`Accept-Encoding`** {{glossary("request header", "request")}} and {{glossary("response header")}} indicates the content encoding (usually a compression algorithm) that the recipient can understand. +The HTTP **`Accept-Encoding`** {{glossary("request header", "request")}} and {{glossary("response header")}} indicates the content encoding (usually a compression algorithm) that the sender can understand. In requests, the server uses [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation) to select one of the encoding proposals from the client and informs the client of that choice with the {{HTTPHeader("Content-Encoding")}} response header. In responses, it provides information about which content encodings the server can understand in messages to the requested resource, so that the encoding can be used in subsequent requests to the resource. For example, this might be sent in the response to a `PUT` request to a resource that used an unsupported encoding. diff --git a/files/en-us/web/http/headers/date/index.md b/files/en-us/web/http/headers/date/index.md index f709981db075399..56ba3b807a7a96d 100644 --- a/files/en-us/web/http/headers/date/index.md +++ b/files/en-us/web/http/headers/date/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Date {{HTTPSidebar}} -The HTTP **`Date`** header contains the date and time at which the message originated. +The HTTP **`Date`** {{Glossary("request header", "request")}} and {{Glossary("response header")}} contains the date and time at which the message originated. diff --git a/files/en-us/web/http/headers/digest/index.md b/files/en-us/web/http/headers/digest/index.md index 79ae38d9611f1e9..783dbd9e9ffd0cb 100644 --- a/files/en-us/web/http/headers/digest/index.md +++ b/files/en-us/web/http/headers/digest/index.md @@ -15,7 +15,7 @@ browser-compat: http.headers.Digest > Use {{HTTPHeader("Content-Digest")}} instead. > For `id-*` digest algorithms, use {{HTTPHeader("Repr-Digest")}}. -The HTTP **`Digest`** header provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. +The HTTP **`Digest`** {{Glossary("request header")}} and {{Glossary("response header")}} provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. It can be requested by using the {{HTTPHeader("Want-Digest")}} header. Representations are different forms of a particular resource that might be returned from a request: for example, the same resource might be formatted in a particular media type such as XML or JSON, localized to a particular written language or geographical region, and/or compressed or otherwise encoded for transmission. diff --git a/files/en-us/web/http/headers/early-data/index.md b/files/en-us/web/http/headers/early-data/index.md index 3ba4d6d2059398f..a6d42d62973fdb4 100644 --- a/files/en-us/web/http/headers/early-data/index.md +++ b/files/en-us/web/http/headers/early-data/index.md @@ -11,6 +11,9 @@ browser-compat: http.headers.Early-Data The HTTP **`Early-Data`** {{Glossary("request header")}} is set by an intermediary to indicate that the request has been conveyed in [TLS early data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3), and also indicates that the intermediary understands the {{HTTPStatus("425", "425 Too Early")}} status code. +If a client has interacted with a server recently, early data (also known as zero round-trip time [(0-RTT) data](/en-US/docs/Web/Security/Transport_Layer_Security#tls_1.3)) allows the client to send data to a server in the first round trip of a connection, without waiting for the TLS [handshake](/en-US/docs/Glossary/TCP_handshake) to complete. +This reduces latency for repeat connections between a client and server, but has security implications, as early data is susceptible to replay attacks. + The `Early-Data` header is **not** set by the originator of the request (i.e., a browser).
@@ -34,8 +37,20 @@ Early-Data: 1 ## Examples +### A GET request with an Early-Data header + +A client that wants to use early data can send HTTP requests immediately after sending the TLS `ClientHello`. +Sending a request in early data implies that the client is willing to retry a request in response to a {{HTTPStatus("425", "425 Too Early")}} status code, so the `Early-Data` header is not included: + +```http +GET /resource HTTP/1.1 +Host: example.com +``` + +An intermediary that forwards a request prior to the completion of the TLS handshake with its client sends it with the `Early-Data` header set to `1`: + ```http -GET /resource HTTP/1.0 +GET /resource HTTP/1.1 Host: example.com Early-Data: 1 ``` @@ -47,3 +62,8 @@ Early-Data: 1 ## Browser compatibility {{Compat}} + +## See also + +- {{HTTPStatus("425", "425 Too Early")}} +- [Replay Attacks on 0-RTT](https://www.rfc-editor.org/rfc/rfc8446#appendix-E.5) diff --git a/files/en-us/web/http/headers/keep-alive/index.md b/files/en-us/web/http/headers/keep-alive/index.md index c2fdd0d0bc2027c..7447bcc43aa88a1 100644 --- a/files/en-us/web/http/headers/keep-alive/index.md +++ b/files/en-us/web/http/headers/keep-alive/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Keep-Alive {{HTTPSidebar}} -The HTTP **`Keep-Alive`** header allows the sender to hint how a connection may be used in terms of a timeout and a maximum amount of requests. +The HTTP **`Keep-Alive`** {{Glossary("request header", "request")}} and {{Glossary("response header")}} allows the sender to hint how a connection may be used in terms of a timeout and a maximum amount of requests. > [!NOTE] > For `Keep-Alive` to have any effect, the message must also include a {{HTTPHeader("Connection", "Connection: keep-alive")}} header. From 8cd1f0a52a78ae23eeed0c2a2fd7d5614f9fd213 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Tue, 19 Nov 2024 10:00:58 +1100 Subject: [PATCH 15/15] Update files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md --- .../page_types/http_header_page_template/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md index b6136288d74d787..02457e4a72b7708 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md @@ -132,7 +132,7 @@ feel free to include multiple definition lists, subsections, and explanations as ## Description -If there is too much context or notes to include in the opening paragraphs, provide as much detail as necessary here, such as background information, hints for usage, and links to documentation. +If there is too much content to include in the opening paragraphs, provide as much detail as necessary here, such as background information, hints for usage, and links to documentation. ## Examples