From 3cb5848a799d161733af0e196123d20f760a5cbb Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 26 Nov 2024 19:38:28 +0100 Subject: [PATCH] chore(http): Updates to headers pages --- .../web/http/headers/server-timing/index.md | 87 ++++++++++++++----- files/en-us/web/http/headers/server/index.md | 4 +- .../index.md | 6 +- .../web/http/headers/set-cookie/index.md | 8 +- .../en-us/web/http/headers/set-login/index.md | 4 +- .../en-us/web/http/headers/sourcemap/index.md | 13 ++- .../strict-transport-security/index.md | 17 ++-- files/en-us/web/http/headers/te/index.md | 33 +++---- .../http/headers/timing-allow-origin/index.md | 3 +- files/en-us/web/http/headers/trailer/index.md | 32 +++---- .../http/headers/transfer-encoding/index.md | 12 +-- files/en-us/web/http/headers/upgrade/index.md | 35 ++++---- files/en-us/web/http/headers/via/index.md | 2 +- .../http/headers/want-content-digest/index.md | 2 +- .../http/headers/want-repr-digest/index.md | 2 +- 15 files changed, 157 insertions(+), 103 deletions(-) diff --git a/files/en-us/web/http/headers/server-timing/index.md b/files/en-us/web/http/headers/server-timing/index.md index 362aa578218fcdd..b11e547729641ce 100644 --- a/files/en-us/web/http/headers/server-timing/index.md +++ b/files/en-us/web/http/headers/server-timing/index.md @@ -7,7 +7,8 @@ browser-compat: http.headers.Server-Timing {{HTTPSidebar}} -The **`Server-Timing`** header communicates one or more metrics and descriptions for a given request-response cycle. It is used to surface any backend server timing metrics (e.g. database read/write, CPU time, file system access, etc.) in the developer tools in the user's browser or in the {{domxref("PerformanceServerTiming")}} interface. +The HTTP **`Server-Timing`** {{Glossary("response header")}} communicates one or more performance metrics about the request-response cycle to the user agent. +It is used to surface backend server timing metrics (for example, database read/write, CPU time, file system access, etc.) in the developer tools in the user's browser or in the {{domxref("PerformanceServerTiming")}} interface. @@ -17,55 +18,98 @@ The **`Server-Timing`** header communicates one or more metrics and descriptions - +
{{Glossary("Forbidden header name")}}noNo
## Syntax -The syntax of the `Server-Timing` header allows you to communicate metrics in different ways: server metric name only, metric with value, metric with value and description, and metric with description. - -This header can contain one or more metrics, separated by commas. Each metric has a name, an optional duration, and an optional description. These components are separated by semi-colons. +```http +// A single metric +Server-Timing: -The duration component consists of the string `"dur"`, followed by `"="`, followed by the value, like `"dur=23.2"`. -The description component consists of the string `"desc"`, followed by `"="`, followed by the value, like `"desc=DB lookup"`. +// Multiple metrics as a comma-separated list +Server-Timing: , +``` -The specification advises that names and descriptions should be kept as short as possible (use abbreviations and omit optional values where possible) to minimize the HTTP overhead. +A `` has a name, and may include an optional duration and an optional description. +For example: ```http -// Single metric without value +// A metric with a name only Server-Timing: missedCache -// Single metric with value +// A metric with a duration Server-Timing: cpu;dur=2.4 -// Single metric with description and value +// A metric with a description and duration Server-Timing: cache;desc="Cache Read";dur=23.2 -// Two metrics with value +// Two metrics with duration values Server-Timing: db;dur=53, app;dur=47.2 - -// Server-Timing as trailer -Trailer: Server-Timing ---- response body --- -Server-Timing: total;dur=123.4 ``` -## Privacy and security +## Directives -The `Server-Timing` header may expose potentially sensitive application and infrastructure information. Consider to control which metrics are returned when and to whom on the server side. For example, you could only show metrics to authenticated users and nothing to the public. +- `` + - : A comma-separated list of one or more metrics with the following components separated by semi-colons: + - `` + - : A name component as a token (cannot contain spaces or special characters). + - `` {{optional_inline}} + - : A duration component consisting of the string `dur`, followed by `=`, followed by a value, like `dur=23.2`. + - `` {{optional_inline}} + - : A description component consisting of the string `desc`, followed by `=`, followed by a value as a token or a quoted string, like `desc=prod` or `desc="DB lookup"`. -## PerformanceServerTiming interface +The specification advises that names and descriptions should be kept as short as possible (use abbreviations and omit optional values where possible) to minimize the HTTP overhead. + +## Description + +### Privacy and security + +The `Server-Timing` header may expose potentially sensitive application and infrastructure information. +Consider to control which metrics are returned when and to whom on the server side. +For example, you could only show metrics to authenticated users and nothing to the public. + +### PerformanceServerTiming interface In addition to having `Server-Timing` header metrics appear in the developer tools of the browser, the {{domxref("PerformanceServerTiming")}} interface enables tools to automatically collect and process metrics from JavaScript. This interface is restricted to the same origin, but you can use the {{HTTPHeader("Timing-Allow-Origin")}} header to specify the domains that are allowed to access the server metrics. The interface is only available in secure contexts (HTTPS) in some browsers. -The components of the `Server-Timing` header map to the {{domxref("PerformanceServerTiming")}} properties like this: +The components of the `Server-Timing` header map to the {{domxref("PerformanceServerTiming")}} properties as follows: - `"name"` -> {{domxref("PerformanceServerTiming.name")}} - `"dur"` -> {{domxref("PerformanceServerTiming.duration")}} - `"desc"` -> {{domxref("PerformanceServerTiming.description")}} +## Examples + +### Sending a metric using the Server-Timing header + +The following response includes a metric `custom-metric` with a duration of `123.45` milliseconds, and a description of "My custom metric": + +```http +Server-Timing: custom-metric;dur=123.45;desc="My custom metric" +``` + +### Server-Timing as HTTP trailer + +In the following response, the {{HTTPHeader("Trailer")}} header is used to indicate that a `Server-Timing` header will follow the response body. +A metric `custom-metric` with a duration of `123.4` milliseconds is sent. + +```http +HTTP/1.1 200 OK +Transfer-Encoding: chunked +Trailer: Server-Timing + +--- response body --- +Server-Timing: custom-metric;dur=123.4 +``` + +> [!WARNING] +> Only the browser's DevTools can use the Server-Timing header as a HTTP trailer to display information in the Network -> Timings tab. +> The Fetch API cannot access HTTP trailers. +> See [Browser compatibility](#browser_compatibility) for more information. + ## Specifications {{Specifications}} @@ -77,3 +121,4 @@ The components of the `Server-Timing` header map to the {{domxref("PerformanceSe ## See also - {{domxref("PerformanceServerTiming")}} +- {{HTTPHeader("Trailer")}} header diff --git a/files/en-us/web/http/headers/server/index.md b/files/en-us/web/http/headers/server/index.md index 39c448e2c78c356..b1b1e2240a8849e 100644 --- a/files/en-us/web/http/headers/server/index.md +++ b/files/en-us/web/http/headers/server/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Server {{HTTPSidebar}} -The **`Server`** header describes the software used by the origin server that handled the request and generated a response. +The HTTP **`Server`** {{Glossary("response header")}} describes the software used by the origin server that handled the request and generated a response. The benefits of advertising the server type and version via this header are that it helps with analytics and identifying how widespread specific interoperability issues are. Historically, clients have used the server version information to avoid known limitations, such as inconsistent support for [range requests](/en-US/docs/Web/HTTP/Range_requests) in specific software versions. @@ -27,7 +27,7 @@ In general, a more robust approach to server security is to ensure software is r {{Glossary("Forbidden header name")}} - no + No diff --git a/files/en-us/web/http/headers/service-worker-navigation-preload/index.md b/files/en-us/web/http/headers/service-worker-navigation-preload/index.md index 77fa8f71034bcef..729fa7fb77b3a7c 100644 --- a/files/en-us/web/http/headers/service-worker-navigation-preload/index.md +++ b/files/en-us/web/http/headers/service-worker-navigation-preload/index.md @@ -10,7 +10,7 @@ browser-compat: http.headers.Service-Worker-Navigation-Preload The HTTP **`Service-Worker-Navigation-Preload`** {{Glossary("request header")}} indicates that the request was the result of a {{domxref("Window/fetch", "fetch()")}} operation made during service worker navigation preloading. It allows a server to respond with a different resource than for a normal `fetch()`. -If a different response may result from setting this header, the server must set {{HTTPHeader("Vary", "Vary: Service-Worker-Navigation-Preload")}} to ensure that different responses are cached. +If a different response may result from setting this header, the server must include a {{HTTPHeader("Vary", "Vary: Service-Worker-Navigation-Preload")}} header in responses to ensure that different responses are cached. For more information see {{domxref("NavigationPreloadManager.setHeaderValue()")}} (and {{domxref("NavigationPreloadManager")}}). @@ -42,9 +42,9 @@ Service-Worker-Navigation-Preload: ## Examples -### Using Service-Worker-Navigation-Preload +### Service worker navigation preloading headers -The header below is sent by default in requests: +The following request header is sent by default in navigation preload requests: ```http Service-Worker-Navigation-Preload: true diff --git a/files/en-us/web/http/headers/set-cookie/index.md b/files/en-us/web/http/headers/set-cookie/index.md index fc55e0bd4ddbdd4..91bc4446b4da8f8 100644 --- a/files/en-us/web/http/headers/set-cookie/index.md +++ b/files/en-us/web/http/headers/set-cookie/index.md @@ -145,6 +145,10 @@ Set-Cookie: =; Domain=; Secure; HttpOnl - : Means that the cookie is not sent on cross-site requests, such as on requests to load images or frames, but is sent when a user is navigating to the origin site from an external site (for example, when following a link). This is the default behavior if the `SameSite` attribute is not specified. + > [!WARNING] + > Browser implementations vary when `SameSite` is omitted. + > See [Browser compatibility](#browser_compatibility) for details. + - `None` - : Means that the browser sends the cookie with both cross-site and same-site requests. @@ -176,7 +180,7 @@ Set-Cookie: =; Domain=; Secure; HttpOnl ### Session cookie -**Session cookies** are removed when the client shuts down. Cookies are session cookies if they do not specify the `Expires` or `Max-Age` attribute. +Session cookies are removed when the client shuts down. Cookies are session cookies if they do not specify the `Expires` or `Max-Age` attribute. ```http Set-Cookie: sessionId=38afes7a8 @@ -184,7 +188,7 @@ Set-Cookie: sessionId=38afes7a8 ### Permanent cookie -**Permanent cookies** are removed at a specific date (`Expires`) or after a specific length of time (`Max-Age`) and not when the client is closed. +Permanent cookies are removed at a specific date (`Expires`) or after a specific length of time (`Max-Age`) and not when the client is closed. ```http Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT diff --git a/files/en-us/web/http/headers/set-login/index.md b/files/en-us/web/http/headers/set-login/index.md index 14e3ce3f452a377..3f3385a398e0780 100644 --- a/files/en-us/web/http/headers/set-login/index.md +++ b/files/en-us/web/http/headers/set-login/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Set-Login {{HTTPSidebar}}{{SeeCompatTable}} -The HTTP **`Set-Login`** {{Glossary("response header")}} is sent by a federated identity provider (IdP) to set its login status, and indicates "whether any users are logged into the IdP on the current browser or not". +The HTTP **`Set-Login`** {{Glossary("response header")}} is sent by a federated identity provider (IdP) to set its login status, and indicates whether any users are logged into the IdP on the current browser or not. This is stored by the browser and used by the [FedCM API](/en-US/docs/Web/API/FedCM_API) to reduce the number of requests it makes to the IdP as the browser doesn't need to request accounts when there are no users logged in to the IdP. It also mitigates [potential timing attacks](https://github.com/w3c-fedid/FedCM/issues/447). @@ -47,7 +47,7 @@ Set-Login: - `logged-out`: All IdP user accounts are currently signed out. > [!NOTE] - > Browsers should ignore this header if it contains any other value. + > Browsers ignore this header if it contains any other value. ## Examples diff --git a/files/en-us/web/http/headers/sourcemap/index.md b/files/en-us/web/http/headers/sourcemap/index.md index be75d815ab0cc54..0fcc0edf5619ad4 100644 --- a/files/en-us/web/http/headers/sourcemap/index.md +++ b/files/en-us/web/http/headers/sourcemap/index.md @@ -9,6 +9,8 @@ browser-compat: http.headers.SourceMap The HTTP **`SourceMap`** {{Glossary("response header")}} links generated code to a {{Glossary("source map")}}, enabling the browser to reconstruct the original source and present the reconstructed original in the debugger. +The HTTP `SourceMap` header has precedence over a source annotation (`sourceMappingURL=path-to-map.js.map`), and if both are present, the header URL is used to resolve the source map file. + @@ -36,14 +38,20 @@ X-SourceMap: (deprecated) ## Examples -### Linking to a source map using `SourceMap` +### Linking to a source map using the `SourceMap` header -The following response contains an absolute +The following response contains an absolute path in the `SourceMap` header. ```http +HTTP/1.1 200 OK +Content-Type: application/javascript SourceMap: /path/to/file.js.map + + ``` +Developer tools use the mappings between optimized code and the original source to improve readability, which can make debugging easier. + ## Specifications {{Specifications}} @@ -56,3 +64,4 @@ SourceMap: /path/to/file.js.map - {{Glossary("Source map")}} - [Firefox Developer Tools: using a source map](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html) +- [What are source maps?](https://web.dev/articles/source-maps) on web.dev (2023) diff --git a/files/en-us/web/http/headers/strict-transport-security/index.md b/files/en-us/web/http/headers/strict-transport-security/index.md index 962bddd07c5e37b..be7767bfbaa2b3b 100644 --- a/files/en-us/web/http/headers/strict-transport-security/index.md +++ b/files/en-us/web/http/headers/strict-transport-security/index.md @@ -56,24 +56,23 @@ The `Strict-Transport-Security` header informs the browser that it should never > Once your site is accessed over HTTPS with no certificate errors, the browser knows your site is HTTPS-capable and will honor the `Strict-Transport-Security` header. > Browsers do this as attackers may intercept HTTP connections to the site and inject or remove the header. -### An example scenario +### Strict Transport Security example scenario -You log into a free Wi-Fi access point at an airport and start surfing the web, visiting your online banking service to check your balance and pay a couple of bills. +Assume you have logged into a free Wi-Fi access point at an airport and start surfing the web, visiting your online banking service to check your balance and pay a couple of bills. Unfortunately, the access point you're using is actually a hacker's laptop, and they're intercepting your original HTTP request and redirecting you to a clone of your bank's site instead of the real thing. Now your private data is exposed to the hacker. -Strict Transport Security resolves this problem; as long as you've accessed your bank's website once using HTTPS, and the bank's website uses Strict Transport Security, your -browser will know to automatically use only HTTPS, which prevents hackers from performing this sort of man-in-the-middle attack. +Strict Transport Security resolves this problem; as long as you've accessed your bank's website once using HTTPS, and the bank's website uses Strict Transport Security, your browser will know to automatically use only HTTPS, which prevents hackers from performing this sort of man-in-the-middle attack. -### How the browser handles it +### How the browser handles Strict Transport Security -The first time your site is accessed using HTTPS and it returns the `Strict-Transport-Security` header, the browser records this information, so that future attempts to load the site using HTTP will automatically use HTTPS instead. +The first time a site is accessed using HTTPS and it returns the `Strict-Transport-Security` header, the browser records this information, so that future attempts to load the site using HTTP will automatically use HTTPS instead. When the expiration time specified by the `Strict-Transport-Security` header elapses, the next attempt to load the site via HTTP will proceed as normal instead of automatically using HTTPS. -Whenever the Strict-Transport-Security header is delivered to the browser, it will update the expiration time for that site, so sites can refresh this information and prevent the timeout from expiring. -Should it be necessary to disable Strict Transport Security, setting the `max-age` to 0 (over an https connection) will immediately expire the `Strict-Transport-Security` header, allowing access via http. +Whenever the `Strict-Transport-Security` header is delivered to the browser, it will update the expiration time for that site, so sites can refresh this information and prevent the timeout from expiring. +Should it be necessary to disable Strict Transport Security, setting the `max-age` to `0` (over an HTTPS connection) will immediately expire the `Strict-Transport-Security` header, allowing access via HTTP. -## Preloading Strict Transport Security +### Preloading Strict Transport Security Google maintains [an HSTS preload service](https://hstspreload.org/). By following the guidelines and successfully submitting your domain, you can ensure that browsers will connect to your domain only via secure connections. diff --git a/files/en-us/web/http/headers/te/index.md b/files/en-us/web/http/headers/te/index.md index 80475965fc14b19..67950dc44a2619e 100644 --- a/files/en-us/web/http/headers/te/index.md +++ b/files/en-us/web/http/headers/te/index.md @@ -11,15 +11,13 @@ The HTTP **`TE`** {{Glossary("request header")}} specifies the transfer encoding Some people informally consider "`Accept-Transfer-Encoding`" to be a more intuitive name for this header. -> [!NOTE] -> In -> [HTTP/2](https://httpwg.org/specs/rfc9113.html#ConnectionSpecific) and -> [HTTP/3](https://httpwg.org/specs/rfc9114.html#header-formatting), the `TE` -> header field is only accepted if the `trailers` value is set. +Note that `chunked` is always acceptable for HTTP/1.1 recipients and you don't have to specify `chunked` using the `TE` header. +However, it is useful if the client is accepting trailer fields in a chunked transfer coding using the `trailers` value. See the {{HTTPHeader("Transfer-Encoding")}} response header for more details on transfer encodings. -Note that `chunked` is always acceptable for HTTP/1.1 recipients and you don't have to specify `chunked` using the `TE` header. -However, it is useful for setting if the client is accepting trailer fields in a chunked transfer coding using the `trailers` value. + +> [!NOTE] +> In [HTTP/2](https://httpwg.org/specs/rfc9113.html#ConnectionSpecific) and [HTTP/3](https://httpwg.org/specs/rfc9114.html#header-formatting), the `TE` header field is only accepted if the `trailers` value is set.
@@ -41,29 +39,26 @@ TE: compress TE: deflate TE: gzip TE: trailers +``` -// Multiple directives, weighted with the {{glossary("quality values", "quality value")}} syntax: +Multiple directives with {{glossary("quality values")}} as weights: + +```http TE: trailers, deflate;q=0.5 ``` ## Directives - `compress` - - : A format using the [Lempel-Ziv-Welch](https://en.wikipedia.org/wiki/LZW) (LZW) algorithm is - accepted as a transfer coding name. + - : A format using the [Lempel-Ziv-Welch](https://en.wikipedia.org/wiki/LZW) (LZW) algorithm is accepted as a transfer coding name. - `deflate` - - : Using the [zlib](https://en.wikipedia.org/wiki/Zlib) - structure is accepted as a transfer coding name. + - : Using the [zlib](https://en.wikipedia.org/wiki/Zlib) structure is accepted as a transfer coding name. - `gzip` - - : A format using the [Lempel-Ziv coding](https://en.wikipedia.org/wiki/LZ77_and_LZ78#LZ77) - (LZ77), with a 32-bit CRC is accepted as a transfer coding name. + - : A format using the [Lempel-Ziv coding](https://en.wikipedia.org/wiki/LZ77_and_LZ78#LZ77) (LZ77), with a 32-bit CRC is accepted as a transfer coding name. - `trailers` - - : Indicates that the client is willing to accept trailer fields in a chunked transfer - coding. + - : Indicates that the client is willing to accept trailer fields in a chunked transfer coding. - `q` - - : When multiple transfer codings are acceptable, the `q` parameter of the - [quality value](/en-US/docs/Glossary/Quality_values) syntax can rank - codings by preference. + - : When multiple transfer codings are acceptable, the `q` parameter ({{glossary("quality values")}}) syntax can order codings by preference. ## Specifications diff --git a/files/en-us/web/http/headers/timing-allow-origin/index.md b/files/en-us/web/http/headers/timing-allow-origin/index.md index 5a2178d00f52fc8..fe3df2a910b218a 100644 --- a/files/en-us/web/http/headers/timing-allow-origin/index.md +++ b/files/en-us/web/http/headers/timing-allow-origin/index.md @@ -63,4 +63,5 @@ Timing-Allow-Origin: https://developer.mozilla.org ## See also - [Resource Timing API](/en-US/docs/Web/API/Performance_API/Resource_timing) -- {{HTTPHeader("Vary")}} +- {{HTTPHeader("Server-Timing")}} header +- {{HTTPHeader("Vary")}} header diff --git a/files/en-us/web/http/headers/trailer/index.md b/files/en-us/web/http/headers/trailer/index.md index 6c4a094ab4fb695..d82d3bd9f33fc22 100644 --- a/files/en-us/web/http/headers/trailer/index.md +++ b/files/en-us/web/http/headers/trailer/index.md @@ -7,13 +7,16 @@ browser-compat: http.headers.Trailer {{HTTPSidebar}} -The HTTP **Trailer** {{glossary("request header", "request")}} and {{glossary("response header")}} allows the sender to include additional -fields at the end of chunked messages in order to supply metadata that might be -dynamically generated while the message body is sent, such as a message integrity check, -digital signature, or post-processing status. +The HTTP **Trailer** {{glossary("request header", "request")}} and {{glossary("response header")}} allows the sender to include additional fields at the end of chunked messages in order to supply metadata that might be dynamically generated while the message body is sent. +The content of a trailer field may be a message integrity check, digital signature, or post-processing status. > [!NOTE] -> The {{HTTPHeader("TE")}} request header needs to be set to "trailers" to allow trailer fields. +> The {{HTTPHeader("TE")}} request header needs to be set to `trailers` to allow trailer fields. + +> [!WARNING] +> Developers cannot access HTTP trailers via the Fetch API or XHR. +> Additionally, browsers ignore HTTP trailers, with the exception of {{HTTPHeader("Server-Timing")}}. +> See [Browser compatibility](#browser_compatibility) for more information.
@@ -43,21 +46,19 @@ Trailer: header-names - `header-names` - : HTTP header fields which will be present in the trailer part of chunked messages. - These header fields are **disallowed**: + The following header names are **disallowed**: - - message framing headers (e.g., {{HTTPHeader("Transfer-Encoding")}} and {{HTTPHeader("Content-Length")}}), - - routing headers (e.g., {{HTTPHeader("Host")}}), - - request modifiers (e.g., controls and conditionals, like - {{HTTPHeader("Cache-Control")}}, {{HTTPHeader("Max-Forwards")}}, or {{HTTPHeader("TE")}}), - - authentication headers (e.g., {{HTTPHeader("Authorization")}} or {{HTTPHeader("Set-Cookie")}}), - - or {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Content-Range")}}, and `Trailer` itself. + - {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Content-Range")}}, and `Trailer` + - Authentication headers (e.g., {{HTTPHeader("Authorization")}} or {{HTTPHeader("Set-Cookie")}}) + - Message framing headers (e.g., {{HTTPHeader("Transfer-Encoding")}} and {{HTTPHeader("Content-Length")}}) + - Routing headers (e.g., {{HTTPHeader("Host")}}) + - Request modifiers (e.g., controls and conditionals, like {{HTTPHeader("Cache-Control")}}, {{HTTPHeader("Max-Forwards")}}, or {{HTTPHeader("TE")}}) ## Examples -### Chunked transfer encoding using a trailing header +### Chunked response using a trailing header -In this example, the {{HTTPHeader("Expires")}} header is used at the end of the chunked -message and serves as a trailing header. +In this example response, the {{HTTPHeader("Expires")}} header is used at the end of the chunked message and serves as a trailing header: ```http HTTP/1.1 200 OK @@ -88,4 +89,5 @@ Expires: Wed, 21 Oct 2015 07:28:00 GMT\r\n - {{HTTPHeader("Transfer-Encoding")}} - {{HTTPHeader("TE")}} +- {{HTTPHeader("Server-Timing")}} - [Chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) diff --git a/files/en-us/web/http/headers/transfer-encoding/index.md b/files/en-us/web/http/headers/transfer-encoding/index.md index 784ba8ff05f7dd6..af5d9635c1c3fd3 100644 --- a/files/en-us/web/http/headers/transfer-encoding/index.md +++ b/files/en-us/web/http/headers/transfer-encoding/index.md @@ -9,17 +9,17 @@ browser-compat: http.headers.Transfer-Encoding The HTTP **`Transfer-Encoding`** {{glossary("request header", "request")}} and {{glossary("response header")}} specifies the form of encoding used to transfer messages between nodes on the network. -> [!WARNING] -> HTTP/2 disallows all uses of the Transfer-Encoding header other than the HTTP/2 specific: `"trailers"`. -> HTTP/2 and later provides its own more efficient mechanisms for data streaming than chunked transfer and forbids the use of the header. -> Usage of the header in HTTP/2 may likely result in a specific `protocol error` as HTTP/2 Protocol prohibits the use. - `Transfer-Encoding` is a [hop-by-hop header](/en-US/docs/Web/HTTP/Headers#hop-by-hop_headers), that is applied to a message between two nodes, not to a resource itself. Each segment of a multi-node connection can use different `Transfer-Encoding` values. If you want to compress data over the whole connection, use the end-to-end {{HTTPHeader("Content-Encoding")}} header instead. When present on a response to a {{HTTPMethod("HEAD")}} request that has no body, it indicates the value that would have applied to the corresponding {{HTTPMethod("GET")}} message. +> [!WARNING] +> HTTP/2 disallows all uses of the `Transfer-Encoding` header other than the HTTP/2 specific value `"trailers"`. +> HTTP/2 and later provides other, more efficient, mechanisms for data streaming than chunked transfer. +> Usage of the header in HTTP/2 may likely result in a specific `protocol error`. +
@@ -66,7 +66,7 @@ Transfer-Encoding: gzip, chunked ## Examples -### Chunked encoding +### Response with chunked encoding Chunked encoding is useful when larger amounts of data are sent to the client and the total size of the response may not be known until the request has been fully processed. For example, when generating a large HTML table resulting from a database query or when transmitting large images. diff --git a/files/en-us/web/http/headers/upgrade/index.md b/files/en-us/web/http/headers/upgrade/index.md index 8935a86370cbd48..a30aca5aca518f1 100644 --- a/files/en-us/web/http/headers/upgrade/index.md +++ b/files/en-us/web/http/headers/upgrade/index.md @@ -7,11 +7,11 @@ browser-compat: http.headers.Upgrade {{HTTPSidebar}} -The HTTP `Upgrade` {{glossary("request header", "request")}} and {{glossary("response header")}} header can be used to upgrade an already-established client/server connection to a different protocol (over the same transport protocol). +The HTTP `Upgrade` {{glossary("request header", "request")}} and {{glossary("response header")}} can be used to upgrade an already-established client/server connection to a different protocol (over the same transport protocol). For example, it can be used by a client to upgrade a connection from HTTP/1.1 to HTTP/2, or an HTTP(S) connection to a WebSocket connection. > [!WARNING] -> HTTP/2 explicitly disallows the use of this mechanism/header; it is specific to HTTP/1.1. +> HTTP/2 explicitly disallows the use of this mechanism and header; it is specific to HTTP/1.1.
@@ -29,10 +29,23 @@ For example, it can be used by a client to upgrade a connection from HTTP/1.1 to
-## Usage notes +## Syntax + +```http +Upgrade: [/] +``` + +## Directives + +- `` + - : Protocols are listed, comma-separated, in order of descending preference. + - `` {{optional_inline}} + - : An optional protocol version may be provided prefixed with a `/` forward slash. + +## Description The `Upgrade` header field may be used by clients to invite a server to switch to one (or more) of the listed protocols, in descending preference order. -For example, the client might send a `GET` request as shown, listing the preferred protocols to switch to (in this case "example/1" and "foo/2"): +For example, the client might send a `GET` request as shown, listing the preferred protocols to switch to (in this case `example/1` and `foo/2`): ```http GET /index.html HTTP/1.1 @@ -45,7 +58,6 @@ Upgrade: example/1, foo/2 > The {{HTTPHeader("Connection")}} header with type `upgrade` must _always_ be sent with the `Upgrade` header. The server can ignore the request, for any reason, in which case it should respond as though the `Upgrade` header had not been sent (for example, with a {{HTTPStatus(200, "200 OK")}}). - If the server will upgrade the connection, it must: 1. Send back a {{HTTPStatus(101, "101 Switching Protocols")}} response status with an `Upgrade` header that specifies the protocol(s) being switched to. For example: @@ -62,19 +74,6 @@ A server may also send the header as part of a {{HTTPStatus("426")}} `Upgrade Re More detail and examples are provided in the topic [Protocol upgrade mechanism](/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism). -## Syntax - -```http -Upgrade: [/] -``` - -## Directives - -- `` - - : Protocols are listed, comma-separated, in order of descending preference. - - `` {{optional_inline}} - - : An optional protocol version may be provided prefixed with a `/` forward slash. - ## Examples ### Upgrade header with multiple protocols diff --git a/files/en-us/web/http/headers/via/index.md b/files/en-us/web/http/headers/via/index.md index 2200faca2b1b0eb..548d407db295eb2 100644 --- a/files/en-us/web/http/headers/via/index.md +++ b/files/en-us/web/http/headers/via/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Via {{HTTPSidebar}} -The **`Via`** {{glossary("request header", "request")}} and {{glossary("response header")}} header is added by {{Glossary("proxies")}}, both forward and reverse. +The **`Via`** {{glossary("request header", "request")}} and {{glossary("response header")}} is added by {{Glossary("Proxy_server", "proxies")}}, both forward and reverse. It is used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain. diff --git a/files/en-us/web/http/headers/want-content-digest/index.md b/files/en-us/web/http/headers/want-content-digest/index.md index 569ca678dfe4fec..04bb314198fe5dc 100644 --- a/files/en-us/web/http/headers/want-content-digest/index.md +++ b/files/en-us/web/http/headers/want-content-digest/index.md @@ -7,7 +7,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc9530 {{HTTPSidebar}} -The HTTP **`Want-Content-Digest`** {{glossary("request header", "request")}} and {{glossary("response header")}} header indicates that the recipient should send a {{HTTPHeader("Content-Digest")}} header. +The HTTP **`Want-Content-Digest`** {{glossary("request header", "request")}} and {{glossary("response header")}} indicates that the recipient should send a {{HTTPHeader("Content-Digest")}} header. It is the `Content-` analogue of {{HTTPHeader("Want-Repr-Digest")}}.
diff --git a/files/en-us/web/http/headers/want-repr-digest/index.md b/files/en-us/web/http/headers/want-repr-digest/index.md index 0a465965f6f99b0..e0dfdc66d49c6b6 100644 --- a/files/en-us/web/http/headers/want-repr-digest/index.md +++ b/files/en-us/web/http/headers/want-repr-digest/index.md @@ -7,7 +7,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc9530 {{HTTPSidebar}} -The HTTP **`Want-Repr-Digest`** {{glossary("request header", "request")}} and {{glossary("response header")}} header indicates that the recipient should send a {{HTTPHeader("Repr-Digest")}} header. +The HTTP **`Want-Repr-Digest`** {{glossary("request header", "request")}} and {{glossary("response header")}} indicates that the recipient should send a {{HTTPHeader("Repr-Digest")}} header.