From 7d7b014191b4892e7a059493a90f0c511cfdf633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=BF=E3=81=91CAT?= Date: Mon, 18 Nov 2024 08:16:29 +0900 Subject: [PATCH 001/131] updateText: Remove false information (#36832) --- files/en-us/web/api/editcontext/updatetext/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/files/en-us/web/api/editcontext/updatetext/index.md b/files/en-us/web/api/editcontext/updatetext/index.md index 8b46c0ec980c325..da1d17e77239f3b 100644 --- a/files/en-us/web/api/editcontext/updatetext/index.md +++ b/files/en-us/web/api/editcontext/updatetext/index.md @@ -34,7 +34,6 @@ updateText(rangeStart, rangeEnd, text) ### Exceptions - If less than three arguments are provided, a `TypeError` {{domxref("DOMException")}} is thrown. -- if `rangeStart` is greater than `rangeEnd`, a {{domxref("DOMException")}} is thrown. ## Examples From ab5aa440278a135b9932a071f9208f4c58b86d21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=BF=E3=81=91CAT?= Date: Mon, 18 Nov 2024 09:16:24 +0900 Subject: [PATCH 002/131] updateSelection: make more intuitive (#36834) --- files/en-us/web/api/editcontext/updateselection/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/files/en-us/web/api/editcontext/updateselection/index.md b/files/en-us/web/api/editcontext/updateselection/index.md index 9edb2d3b15639a9..25eaf7c2ac7f739 100644 --- a/files/en-us/web/api/editcontext/updateselection/index.md +++ b/files/en-us/web/api/editcontext/updateselection/index.md @@ -30,8 +30,7 @@ If the `start` and `end` values are the same, the selection is equivalent to a c ### Exceptions - If only one argument is provided, a `TypeError` {{domxref("DOMException")}} is thrown. -- If either argument is not a positive number, a {{domxref("DOMException")}} is thrown. -- If `start` is greater than `end`, a {{domxref("DOMException")}} is thrown. +- If either argument is not a non-negative number, a {{domxref("DOMException")}} is thrown. ## Examples From fbc04f8ffb33fb5539a247aeb25746a1965a32a4 Mon Sep 17 00:00:00 2001 From: Jim <32126310+Eandalf@users.noreply.github.com> Date: Mon, 18 Nov 2024 12:30:25 +0800 Subject: [PATCH 003/131] docs: update Accept-Charset status (#36822) * docs: update Accept-Charset status * move deprecation information into warning. --------- Co-authored-by: Hamish Willee --- files/en-us/web/http/headers/accept-charset/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/files/en-us/web/http/headers/accept-charset/index.md b/files/en-us/web/http/headers/accept-charset/index.md index e766d00d835c113..8af30e14a607e28 100644 --- a/files/en-us/web/http/headers/accept-charset/index.md +++ b/files/en-us/web/http/headers/accept-charset/index.md @@ -8,6 +8,8 @@ page-type: http-header > [!WARNING] > Do not use this header. Browsers omit this header and servers should ignore it. +> +> The header was deprecated by [RFC 9110 section 12.5.2 Accept-Charset](https://datatracker.ietf.org/doc/html/rfc9110#section-12.5.2) (June 2022). The HTTP **`Accept-Charset`** {{Glossary("request header")}} was a header that advertised a client's supported {{glossary("character encoding", "character encodings")}}. It is no longer widely used. From 45913d055f02da51493b1b8a5d2c07a86e8d90b7 Mon Sep 17 00:00:00 2001 From: Onkar Khadangale <87750369+OnkarRuikar@users.noreply.github.com> Date: Mon, 18 Nov 2024 11:35:24 +0530 Subject: [PATCH 004/131] fix typos (#36837) * fix typos * One fix --------- Co-authored-by: Joshua Chen --- .vscode/dictionaries/code-entities.txt | 1 + .vscode/dictionaries/ignore-list.txt | 1 + .vscode/dictionaries/proper-names.txt | 5 +++++ files/en-us/web/api/htmlelement/beforetoggle_event/index.md | 2 +- files/en-us/web/css/css_fonts/variable_fonts_guide/index.md | 4 ++-- files/en-us/web/css/zoom/index.md | 2 +- 6 files changed, 11 insertions(+), 4 deletions(-) diff --git a/.vscode/dictionaries/code-entities.txt b/.vscode/dictionaries/code-entities.txt index f7f22d20253e4f2..4a8c5eae7b7fc50 100644 --- a/.vscode/dictionaries/code-entities.txt +++ b/.vscode/dictionaries/code-entities.txt @@ -31,6 +31,7 @@ -moz-visitedhyperlinktext -moz-win-communicationstext -moz-win-mediatext +3rdparty accentcolor accentcolortext Accept-EncodXng diff --git a/.vscode/dictionaries/ignore-list.txt b/.vscode/dictionaries/ignore-list.txt index e049fcda4ff0f19..1c8f1449d68890e 100644 --- a/.vscode/dictionaries/ignore-list.txt +++ b/.vscode/dictionaries/ignore-list.txt @@ -190,6 +190,7 @@ liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK Llanfair LLLLLLLLLLLLLLLLRRRRRRRRRRRRRRRR locallibrary +Loomings loopend LRLRLRLRLRLRLRLRLRLRLRLRLRLRLRLR LROR diff --git a/.vscode/dictionaries/proper-names.txt b/.vscode/dictionaries/proper-names.txt index f07902b73c299c9..33f75b176a79d3b 100644 --- a/.vscode/dictionaries/proper-names.txt +++ b/.vscode/dictionaries/proper-names.txt @@ -120,9 +120,11 @@ Darmok Datumizer davbrito Dedalium +Dedreux Deepti Degit DekiWiki +Delaville Denicola DeSandro Desaulniers @@ -222,6 +224,7 @@ Hobson hochan Hochberg Hoenigswald +Holborn Holdem Holzman Honigswald @@ -259,6 +262,7 @@ Johansson Joomla Jory Josiel +Jost Joyo jpmedley JSCAMP @@ -349,6 +353,7 @@ mcdetect McLellan McNally McVerry +Megalosaurus Meggin Mercure Merkle diff --git a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md index 9d310a3ab1a3952..058fbc5b0a5b257 100644 --- a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md +++ b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md @@ -39,7 +39,7 @@ A {{domxref("ToggleEvent")}}. Inherits from {{domxref("Event")}}. ## Examples The examples below demonstrates how the `beforetoggle` event might be used for a {{domxref("Popover_API", "popover", "", "nocode")}} or {{htmlelement("dialog")}} element. -The same examples would work similarily on the other element types. +The same examples would work similarly on the other element types. ### Basic example diff --git a/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md b/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md index 311f3b18351af87..68fb56937f18c25 100644 --- a/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md +++ b/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md @@ -719,7 +719,7 @@ The following example pages show two different ways to structure your CSS. The f ```html hidden live-sample___sample-page-example
-

Moby Dick

+

Moby-Dick

CHAPTER 1. Loomings.

Call me Ishmael. Some years ago—never mind how long precisely–having little @@ -737,7 +737,7 @@ The following example pages show two different ways to structure your CSS. The f

-

Moby Dick

+

Moby-Dick

CHAPTER 1. (hover here)

Call me Ishmael. Some years ago—never mind how long precisely–having little diff --git a/files/en-us/web/css/zoom/index.md b/files/en-us/web/css/zoom/index.md index 4762c6dd41afb62..0f073ce101f0808 100644 --- a/files/en-us/web/css/zoom/index.md +++ b/files/en-us/web/css/zoom/index.md @@ -262,4 +262,4 @@ zoomControl.addEventListener("change", updateZoom); - {{cssxref("transform")}} - {{cssxref("scale")}} - {{cssxref("unset")}} keyword -- [Legay `zoom` property](https://css-tricks.com/almanac/properties/z/zoom/) via CSS-Tricks (2013) +- [Legacy `zoom` property](https://css-tricks.com/almanac/properties/z/zoom/) via CSS-Tricks (2013) From f2511633b9bf9106956ad0b6ab0e4f701e87552a Mon Sep 17 00:00:00 2001 From: Andi Pieper Date: Mon, 18 Nov 2024 11:51:35 +0100 Subject: [PATCH 005/131] Remove all redirects to other locales (#36811) removes redirects that use localized slugs into translated content --- files/en-us/_redirects.txt | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index ae29fe73869d763..8f5b52018becef4 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -165,13 +165,6 @@ /en-US/docs/Bugzilla_(external) https://bugzilla.mozilla.org/enter_bug.cgi?format=guided /en-US/docs/Building_an_Extension /en-US/docs/Mozilla/Add-ons /en-US/docs/CER_temp /en-US/docs/Web/API/Document/ -/en-US/docs/CN_MDN /zh-CN/docs/Web -/en-US/docs/CN_MDN/JavaScript /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/create -/en-US/docs/CN_MDN/JavaScript/About_JavaScript /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/seal -/en-US/docs/CN_MDN/JavaScript/JavaScript_参考 /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/isSealed -/en-US/docs/CN_MDN/JavaScript/Reference /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/preventExtensions -/en-US/docs/CN_MDN/JavaScript/Reference/About_this_Reference /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze -/en-US/docs/CN_MDN/JavaScript/Reference/Global_Objects /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/isFrozen /en-US/docs/CORS_Enabled_Image /en-US/docs/Web/HTML/CORS_enabled_image /en-US/docs/CSS /en-US/docs/Web/CSS /en-US/docs/CSS-2_Quick_Reference /en-US/docs/Web/CSS @@ -6740,7 +6733,6 @@ /en-US/docs/SVG/polyline /en-US/docs/Web/SVG/Element/polyline /en-US/docs/SVG/rect /en-US/docs/Web/SVG/Element/rect /en-US/docs/SVG/use /en-US/docs/Web/SVG/Element/use -/en-US/docs/SVG/教程 /zh-TW/docs/Web/SVG/Tutorial /en-US/docs/SVG:Linking /en-US/docs/Web/SVG/Linking /en-US/docs/SVG:Namespaces_Crash_Course /en-US/docs/Web/SVG/Namespaces_Crash_Course /en-US/docs/SVG:Namespaces_Crash_Course:Example /en-US/docs/Web/SVG/Namespaces_Crash_Course/Example @@ -6770,7 +6762,6 @@ /en-US/docs/Same_origin_policy_for_JavaScript /en-US/docs/Web/Security/Same-origin_policy /en-US/docs/Sample_.htaccess_file /en-US/docs/Learn/Server-side/Apache_Configuration_htaccess /en-US/docs/Scripting_plugins /en-US/docs/Glossary/Plugin -/en-US/docs/Secciones_y_contornos_de_un_documento_HTML5 /es/docs/Sections_and_Outlines_of_an_HTML5_document /en-US/docs/Security/CSP /en-US/docs/Web/HTTP/CSP /en-US/docs/Security/CSP/CSP_policy_directives /en-US/docs/Web/HTTP/Headers/Content-Security-Policy /en-US/docs/Security/CSP/Default_CSP_restrictions /en-US/docs/Web/HTTP/Headers/Content-Security-Policy @@ -10071,9 +10062,7 @@ /en-US/docs/Web/API/WebGL_API/Creating_3D_objects_using_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Creating_3D_objects_using_WebGL /en-US/docs/Web/API/WebGL_API/Cross-Domain_Textures /en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL#Cross-domain_textures /en-US/docs/Web/API/WebGL_API/Getting_started_with_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL -/en-US/docs/Web/API/WebGL_API/Getting_started_with_WebGL/Commencer_avec_le_WebGL /fr/docs/Web/API/WebGL_API/Tutorial/Commencer_avec_WebGL /en-US/docs/Web/API/WebGL_API/Lighting_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Lighting_in_WebGL -/en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL/Commencer_avec_le_WebGL /fr/docs/Web/API/WebGL_API/Tutorial/Commencer_avec_WebGL /en-US/docs/Web/API/WebGL_API/Using_shaders_to_apply_color_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL /en-US/docs/Web/API/WebGL_API/Using_textures_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL /en-US/docs/Web/API/WebKitCSSMatrix /en-US/docs/Web/API/DOMMatrix @@ -13018,7 +13007,6 @@ /en-US/docs/Web/SVG/polyline /en-US/docs/Web/SVG/Element/polyline /en-US/docs/Web/SVG/rect /en-US/docs/Web/SVG/Element/rect /en-US/docs/Web/SVG/use /en-US/docs/Web/SVG/Element/use -/en-US/docs/Web/SVG/教程 /zh-TW/docs/Web/SVG/Tutorial /en-US/docs/Web/Security/CSP /en-US/docs/Web/HTTP/CSP /en-US/docs/Web/Security/CSP/CSP_policy_directives /en-US/docs/Web/HTTP/Headers/Content-Security-Policy /en-US/docs/Web/Security/CSP/Default_CSP_restrictions /en-US/docs/Web/HTTP/Headers/Content-Security-Policy @@ -13064,7 +13052,6 @@ /en-US/docs/Web/WebGL/Creating_3D_objects_using_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Creating_3D_objects_using_WebGL /en-US/docs/Web/WebGL/Cross-Domain_Textures /en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL#Cross-domain_textures /en-US/docs/Web/WebGL/Getting_started_with_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL -/en-US/docs/Web/WebGL/Getting_started_with_WebGL/Commencer_avec_le_WebGL /fr/docs/Web/API/WebGL_API/Tutorial/Commencer_avec_WebGL /en-US/docs/Web/WebGL/Lighting_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Lighting_in_WebGL /en-US/docs/Web/WebGL/Using_Extensions /en-US/docs/Web/API/WebGL_API/Using_Extensions /en-US/docs/Web/WebGL/Using_shaders_to_apply_color_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL @@ -13231,7 +13218,6 @@ /en-US/docs/WebGL/Creating_3D_objects_using_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Creating_3D_objects_using_WebGL /en-US/docs/WebGL/Cross-Domain_Textures /en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL#Cross-domain_textures /en-US/docs/WebGL/Getting_started_with_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL -/en-US/docs/WebGL/Getting_started_with_WebGL/Commencer_avec_le_WebGL /fr/docs/Web/API/WebGL_API/Tutorial/Commencer_avec_WebGL /en-US/docs/WebGL/Lighting_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Lighting_in_WebGL /en-US/docs/WebGL/Using_Extensions /en-US/docs/Web/API/WebGL_API/Using_Extensions /en-US/docs/WebGL/Using_shaders_to_apply_color_in_WebGL /en-US/docs/Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL @@ -13747,7 +13733,6 @@ /en-US/docs/transform /en-US/docs/Web/CSS/transform /en-US/docs/typeof /en-US/docs/Web/JavaScript/Reference/Operators/typeof /en-US/docs/var /en-US/docs/Web/CSS/var -/en-US/docs/video /es/docs/Web/HTML/Elemento/video /en-US/docs/web/accessibility/aria/aria_techniques/using_the_alertdialog_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role /en-US/docs/web/accessibility/aria/aria_techniques/using_the_article_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/article_role /en-US/docs/web/accessibility/aria/aria_techniques/using_the_group_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/group_role @@ -13816,5 +13801,3 @@ /en-US/docs/window.window /en-US/docs/Web/API/Window/window /en-US/docs/www_vs_non-www_URLs /en-US/docs/Web/URI/Authority/Choosing_between_www_and_non-www_URLs /en-US/docs/xml:base /en-US/docs/Web/API/Node/baseURI -/en-US/docs/zh-n/JavaScript/Reference/Global_Objects/String/quote /zh-CN/docs/Web/JavaScript/Reference/Global_Objects/String/quote -/en-US/docs/zh_cn /zh-CN/docs/Web From 1759afe30edd337bbf8954e368c9c9889f6e865e Mon Sep 17 00:00:00 2001 From: jolka-ef <94794622+jolka-ef@users.noreply.github.com> Date: Mon, 18 Nov 2024 12:55:07 +0100 Subject: [PATCH 006/131] fix : wrong method name (#36843) --- files/en-us/web/api/medialist/deletemedium/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/medialist/deletemedium/index.md b/files/en-us/web/api/medialist/deletemedium/index.md index 0335162d9660168..ace4670ddeca3ca 100644 --- a/files/en-us/web/api/medialist/deletemedium/index.md +++ b/files/en-us/web/api/medialist/deletemedium/index.md @@ -37,7 +37,7 @@ The following removes the media query `print` from the ```js const stylesheet = document.styleSheets[0]; -stylesheet.media.removeMedium("print"); +stylesheet.media.deleteMedium("print"); ``` ## Specifications From 6232eb05e39097a7ad2fb4b93a3715b07f38f9d3 Mon Sep 17 00:00:00 2001 From: Vipul Agarwal Date: Mon, 18 Nov 2024 22:02:41 +0530 Subject: [PATCH 007/131] Updated index.md (#36845) * Update index.md fixed the sentence structure from "not learning a new tool" to "learning a new tool" which sound correct. * Update files/en-us/mdn/community/contributing/getting_started/index.md * Update files/en-us/mdn/community/contributing/getting_started/index.md Co-authored-by: Brian Thomas Smith --------- Co-authored-by: Brian Thomas Smith --- .../mdn/community/contributing/getting_started/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/files/en-us/mdn/community/contributing/getting_started/index.md b/files/en-us/mdn/community/contributing/getting_started/index.md index 8250d314c1562cd..a28b604d520cb55 100644 --- a/files/en-us/mdn/community/contributing/getting_started/index.md +++ b/files/en-us/mdn/community/contributing/getting_started/index.md @@ -23,9 +23,10 @@ We have created a [contributors task board](https://github.com/orgs/mdn/projects ### Getting ready to contribute -To contribute, you will need a GitHub account. If you do not already have one, go ahead and [sign up](https://github.com/signup) for an account before continuing. If you are new to GitHub, we encourage you to take the following free, self-paced courses and reading material offered by GitHub. With this knowledge, you can focus on your contributions and not learn a new tool at the same time. +To contribute, you will need a GitHub account. If you do not already have one, go ahead and [sign up](https://github.com/signup) for an account before continuing. If you are new to GitHub, we encourage you to take the following free, self-paced courses and reading material offered by GitHub. With this knowledge, you can focus on your contributions without the burden of learning a new tool at the same time. -> NOTE: Do not feel overwhelmed or like you have to read through and complete _all_ of the course work. With the knowledge gained from the "Introduction to GitHub" course, you will be well on your way. +> [!NOTE] +> Do not feel overwhelmed or like you have to read through and complete _all_ of the course work. With the knowledge gained from the "Introduction to GitHub" course, you will be well on your way. - [Introduction to GitHub](https://github.com/skills/introduction-to-github) - [Setting up Git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) From 6c32e8b21a39b1b8d3db7a194d2350e0f8218b64 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 18 Nov 2024 23:31:45 +0100 Subject: [PATCH 008/131] chore(http): Refresh headers r-s (#36590) * chore(http): Refresh headers r-s * Apply suggestions from code review Co-authored-by: Hamish Willee * chore(http): Changes following reviewer feedback --------- Co-authored-by: Hamish Willee --- .../web/http/headers/repr-digest/index.md | 91 +++++++++++++------ .../web/http/headers/retry-after/index.md | 32 +++---- files/en-us/web/http/headers/rtt/index.md | 34 ++++--- .../en-us/web/http/headers/save-data/index.md | 52 +++++------ .../http/headers/sec-browsing-topics/index.md | 4 +- .../sec-ch-prefers-color-scheme/index.md | 14 +-- .../sec-ch-prefers-reduced-motion/index.md | 13 +-- .../index.md | 11 ++- .../web/http/headers/sec-ch-ua-arch/index.md | 10 +- .../http/headers/sec-ch-ua-bitness/index.md | 12 ++- .../sec-ch-ua-full-version-list/index.md | 40 ++++---- .../headers/sec-ch-ua-full-version/index.md | 10 +- .../http/headers/sec-ch-ua-mobile/index.md | 11 ++- .../web/http/headers/sec-ch-ua-model/index.md | 12 ++- .../sec-ch-ua-platform-version/index.md | 15 ++- .../http/headers/sec-ch-ua-platform/index.md | 11 ++- .../en-us/web/http/headers/sec-ch-ua/index.md | 52 ++++++----- .../web/http/headers/sec-fetch-dest/index.md | 16 ++-- .../web/http/headers/sec-fetch-mode/index.md | 18 ++-- .../web/http/headers/sec-fetch-site/index.md | 15 +-- .../web/http/headers/sec-fetch-user/index.md | 15 ++- files/en-us/web/http/headers/sec-gpc/index.md | 13 ++- .../web/http/headers/sec-purpose/index.md | 7 +- .../headers/sec-websocket-accept/index.md | 14 +-- .../headers/sec-websocket-extensions/index.md | 6 +- .../http/headers/sec-websocket-key/index.md | 12 ++- .../headers/sec-websocket-protocol/index.md | 6 +- .../headers/sec-websocket-version/index.md | 8 +- 28 files changed, 295 insertions(+), 259 deletions(-) diff --git a/files/en-us/web/http/headers/repr-digest/index.md b/files/en-us/web/http/headers/repr-digest/index.md index 49004a64d723539..e71299d244c113c 100644 --- a/files/en-us/web/http/headers/repr-digest/index.md +++ b/files/en-us/web/http/headers/repr-digest/index.md @@ -7,7 +7,13 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc9530 {{HTTPSidebar}} -The **`Repr-Digest`** response or request header provides a {{Glossary("digest")}} of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource. It is invariant under e.g., {{HTTPHeader("Content-Encoding")}} or {{HTTPHeader("Content-Range")}}, which do affect the {{HTTPHeader("Content-Digest")}}. Furthermore, [Content Negotiation](/en-US/docs/Web/HTTP/Content_negotiation) can result in different selected representations with different representation digests. +The HTTP **`Repr-Digest`** {{Glossary("Request header", "request")}} and {{Glossary("Response header", "response header")}} provides a {{Glossary("digest")}} of the selected representation of the target resource. + +The _selected representation_ is the specific format of a resource chosen through [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation). +Details about this representation can be determined from the response's {{Glossary("Representation header", "representation headers")}}, such as {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Type")}}, and {{HTTPHeader("Content-Encoding")}}. + +The representation digest applies to the whole resource rather than the encoding or chunking of the messages that are used to send it. +This differs from {{HTTPHeader("Content-Digest")}} which applies to the content of a particular message, and is therefore is affected by the {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}} of each message. @@ -17,104 +23,129 @@ The **`Repr-Digest`** response or request header provides a {{Glossary("digest") - +
{{Glossary("Forbidden header name")}}noNo
## Syntax -`Repr-Digest` describes an [RFC8941 dictionary](https://www.rfc-editor.org/rfc/rfc8941#section-3.2) with its keys being names of digest algorithms and its values being the digest in bytes (or an integer digest for legacy digest algorithms). +```http +Repr-Digest: = -> [!NOTE] -> In contrast to earlier drafts of the specification, the standard-base64-encoded digest bytes are wrapped in colons (`:`, ASCII 0x3A) as part of the [dictionary syntax](https://www.rfc-editor.org/rfc/rfc8941#name-byte-sequences). +// Multiple digest algorithms +Repr-Digest: =,= +``` ## Directives -### Digest algorithms +- `` + - : The algorithm used to create a digest of the representation. + Only two registered digest algorithms are considered secure: `sha-512` and `sha-256`. + The insecure (legacy) registered digest algorithms are: `md5`, `sha` (SHA-1), `unixsum`, `unixcksum`, `adler` (ADLER32) and `crc32c`. +- `` + - : The digest in bytes of the representation using the ``. + The choice of digest algorithm also determines the encoding to use: `sha-512` and `sha-256` use {{Glossary("base64")}} encoding, while some legacy digest algorithms such as `unixsum` use a decimal integer. + In contrast to earlier drafts of the specification, the standard-base64-encoded digest bytes are wrapped in colons (`:`, ASCII 0x3A) as part of the [dictionary syntax](https://www.rfc-editor.org/rfc/rfc8941#name-byte-sequences). -Only two digest algorithms are currently registered and not considered insecure: `sha-512` and `sha-256`. - -The registered insecure digest algorithms are: `md5`, `sha` (SHA-1), `unixsum`, `unixcksum`, `adler` (ADLER32) and `crc32c`. - -Usage of digest algorithms which are considered insecure is discouraged as collisions can realistically be forced, rendering the digest's usefulness weak. Unless when working with legacy systems (which is unlikely since most will expect the legacy {{HTTPHeader("Digest")}} header and not understand this specification), consider not emitting a `Repr-Digest` instead of emitting one using an insecure digest algorithm. +Usage of insecure digest algorithms is discouraged as collisions can realistically be forced, rendering the digest's usefulness weak. +Unless working with legacy systems (which is unlikely since most will expect the legacy {{HTTPHeader("Digest")}} header and not understand this specification), consider omitting a `Repr-Digest` instead of including one with an insecure digest algorithm. ## Examples ### HTTP response where `Repr-Digest` and `Content-Digest` coincide -An HTTP server may send content octets equivalent to the selected representation's octets: +An HTTP server may send the whole representation unencoded in a single message. +In this case, `Repr-Digest` and `Content-Digest` have equal values for the same digest algorithms: ```http -... +… Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=: Content-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=: -... +… Content-Type: text/yaml -Content-Encoding: identity +Content-Encoding: br Content-Length: 38054 Content-Range: 0-38053/38054 -... +… + +[message body] ``` ### HTTP responses where `Repr-Digest` and `Content-Digest` diverge -A static file server may however choose to compress an HTML page, resulting in differing {{HTTPHeader("Content-Digest")}} and `Repr-Digest` header values: +A server may compress the content for sending. +In this case {{HTTPHeader("Content-Digest")}} will depend on the {{HTTPHeader("Content-Encoding")}}, and will therefore have a different value to the `Repr-Digest` header in a response: ```http -... +… Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U59TCCaZPA9Qio3CzHJVAgDnIAut53t5Sgkj2Gv4BvDd0b+OX9QpIdgWkzdXLmBsmvBrf3t5PBt+UrVK6k5dkw==: Content-Digest: sha-256=:293wcr5IoFAsDCzdoDXR1Qppgf2yxOPO1bvQ3nZQtuI=:, unixsum=54809 -... +… Content-Type: text/html; charset=utf-8 Content-Encoding: br -... +… -... +[message body] ``` +In another response, the server uses a different compression method, resulting in a new `Content-Digest`, but the same `Repr-Digest` digests: + ```http -... +… Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U59TCCaZPA9Qio3CzHJVAgDnIAut53t5Sgkj2Gv4BvDd0b+OX9QpIdgWkzdXLmBsmvBrf3t5PBt+UrVK6k5dkw==: Content-Digest: sha-256=:rv9Jivc4TmcacLUshzN3OdX7Hz+ORnQRaiTaIKZQ0zk=: -... +… Content-Type: text/html; charset=utf-8 -Content-Encoding: deflate, deflate, deflate -... +Content-Encoding: zstd +… -... +[message body] ``` ### Successful HTTP request-response employing `Want-Repr-Digest`, `Repr-Digest`, and `Content-Digest` +The following {{HTTPMethod("PUT")}} request includes a `Want-Repr-Digest` header, indicating that the server should include a `Repr-Digest` header with a `sha-256` digest if the operation is successful: + ```http PUT /api/transact HTTP/1.1 Want-Repr-Digest: sha-256=8 Content-Type: text/json -... +… + +[message body] ``` +The server responds with a successful {{HTTPStatus("201", "201 Created")}} response, including `Repr-Digest` and `Content-Digest` headers with sha-256 digests of the representation and content, respectively: + ```http HTTP/1.1 201 Created Repr-Digest: sha-256=:W8oN3H3CmE/CBpV6ZPNozV2AIDzzQpWL7CCOXyDyDzI=: Content-Encoding: br Content-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=: -... +… + +[message body] ``` ### Unsuccessful HTTP request-response employing `Repr-Digest` +In the following message, a client requests a resource with a specific sha-256 digest: + ```http GET /api/last-transaction HTTP/1.1 Accept: text/json Repr-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=: -... +… ``` +A {{HTTPStatus("406", "406 Not Acceptable")}} is returned by the server to indicate the operation failed given a specific digest for the resource. +A `Repr-Digest` header is included with the SHA-256 digest value that would result in a successful response if the client repeated the request with that value: + ```http HTTP/1.1 406 Not Acceptable Repr-Digest: sha-256=:W8oN3H3CmE/CBpV6ZPNozV2AIDzzQpWL7CCOXyDyDzI=: -... +… ``` ## Specifications diff --git a/files/en-us/web/http/headers/retry-after/index.md b/files/en-us/web/http/headers/retry-after/index.md index b937e26897011c9..8d6c544dcaa83af 100644 --- a/files/en-us/web/http/headers/retry-after/index.md +++ b/files/en-us/web/http/headers/retry-after/index.md @@ -7,17 +7,12 @@ browser-compat: http.headers.Retry-After {{HTTPSidebar}} -The **`Retry-After`** response HTTP header indicates how long -the user agent should wait before making a follow-up request. There are three main cases -this header is used: - -- When sent with a {{HTTPStatus(503)}} (Service Unavailable) response, this indicates - how long the service is expected to be unavailable. -- When sent with a {{HTTPStatus(429)}} (Too Many Requests) response, this indicates - how long to wait before making a new request. -- When sent with a redirect response, such as {{HTTPStatus(301)}} (Moved Permanently), - this indicates the minimum time that the user agent is asked to wait before issuing - the redirected request. +The HTTP **`Retry-After`** {{Glossary("response header")}} indicates how long the user agent should wait before making a follow-up request. +There are three main cases this header is used: + +- In a {{HTTPStatus("503", "503 Service Unavailable")}} response, this indicates how long the service is expected to be unavailable. +- In a {{HTTPStatus("429", "429 Too Many Requests")}} response, this indicates how long to wait before making a new request. +- In a redirect response, such as {{HTTPStatus("301", "301 Moved Permanently")}}, this indicates the minimum time that the user agent is asked to wait before issuing the redirected request. @@ -27,7 +22,7 @@ this header is used: - +
{{Glossary("Forbidden header name")}}noNo
@@ -41,10 +36,10 @@ Retry-After: ## Directives -- \ +- `` - : A date after which to retry. See the {{HTTPHeader("Date")}} header for more details on the HTTP date format. -- \ +- `` - : A non-negative decimal integer indicating the seconds to delay after the response is received. @@ -54,8 +49,7 @@ Retry-After: Support for the `Retry-After` header on both clients and servers is still inconsistent. However, some crawlers and spiders, like the Googlebot, honor the -`Retry-After` header. It is useful to send it along with a -{{HTTPStatus(503)}} (Service Unavailable) response, so that search engines will keep +`Retry-After` header. It is useful to send it along with a `503` response, so that search engines will keep indexing your site when the downtime is over. ```http @@ -73,6 +67,6 @@ Retry-After: 120 ## See also -- [Google Webmaster blog: How to deal with planned site downtime](https://webmasters.googleblog.com/2011/01/how-to-deal-with-planned-site-downtime.html) -- {{HTTPStatus(503)}} (Service Unavailable) -- {{HTTPStatus(301)}} (Moved Permanently) +- {{HTTPStatus("503", "503 Service Unavailable")}} +- {{HTTPStatus("301", "301 Moved Permanently")}} +- [How to deal with planned site downtime](https://developers.google.com/search/blog/2011/01/how-to-deal-with-planned-site-downtime) on developers.google.com (2011) diff --git a/files/en-us/web/http/headers/rtt/index.md b/files/en-us/web/http/headers/rtt/index.md index b82db67d0b5e1ed..d2b01daf4f3f953 100644 --- a/files/en-us/web/http/headers/rtt/index.md +++ b/files/en-us/web/http/headers/rtt/index.md @@ -9,7 +9,15 @@ browser-compat: http.headers.RTT {{HTTPSidebar}} {{SeeCompatTable}} -The **`RTT`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header field provides the approximate round trip time on the application layer, in milliseconds. The RTT hint, unlike transport layer RTT, includes server processing time. +The HTTP **`RTT`** {{Glossary("request header")}} is a [network client hint](/en-US/docs/Web/HTTP/Client_hints#network_client_hints) which provides the approximate round trip time on the application layer, in milliseconds. +The RTT hint includes server processing time, unlike transport layer RTT. + +The RTT value is rounded to the nearest 25 milliseconds to prevent [fingerprinting](/en-US/docs/Glossary/Fingerprinting), although there are many other mechanisms an attacker might use to obtain similar round-trip information. + +The hint allows a server to choose what information is sent based on the network responsiveness/latency. For example, it might choose to send fewer resources. + +> [!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 `RTT` 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 +30,11 @@ The **`RTT`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header fi - +
{{Glossary("Forbidden header name")}}noNo
-The RTT value is rounded to the nearest 25 milliseconds to prevent [fingerprinting](/en-US/docs/Glossary/Fingerprinting). There are many other mechanisms an attacker might use to obtain similar round-trip information. - -The hint allows a server to choose what information is sent based on the network responsiveness/latency. For example, it might choose to send fewer resources. - -> [!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 `RTT` 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,11 +43,13 @@ RTT: ## Directives -- \ +- `` - : The approximate round trip time in milliseconds, rounded to the nearest 25 milliseconds. ## Examples +### Using RTT client hints + A server first needs to opt in to receive the `RTT` header by sending the {{HTTPHeader("Accept-CH")}} response header containing `RTT`. ```http @@ -69,13 +72,8 @@ RTT: 125 ## 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) -- Network client hints - - - {{HTTPHeader("Downlink")}} - - {{HTTPHeader("ECT")}} - - {{HTTPHeader("Save-Data")}} - +- {{HTTPHeader("Downlink")}}, {{HTTPHeader("ECT")}}, {{HTTPHeader("Save-Data")}} network client hints - {{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")}} +- [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/save-data/index.md b/files/en-us/web/http/headers/save-data/index.md index 0872427e43a2b41..76f8757dde360f3 100644 --- a/files/en-us/web/http/headers/save-data/index.md +++ b/files/en-us/web/http/headers/save-data/index.md @@ -9,12 +9,19 @@ browser-compat: http.headers.Save-Data {{HTTPSidebar}}{{SeeCompatTable}} -The **`Save-Data`** [network client hint](/en-US/docs/Web/HTTP/Client_hints#network_client_hints) request header field is a boolean which indicates the client's preference for reduced data usage. +The HTTP **`Save-Data`** {{Glossary("request header")}} is a [network client hint](/en-US/docs/Web/HTTP/Client_hints#network_client_hints) which indicates the client's preference for reduced data usage. This could be for reasons such as high transfer costs, slow connection speeds, etc. -**`Save-Data`** is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints), and hence may be sent by the client even if not requested by the server using an {{HTTPHeader("Accept-CH")}} response header. +`Save-Data` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints), and hence may be sent by the client even if not requested by the server using an {{HTTPHeader("Accept-CH")}} response header. Further, it should be used to reduce data sent to the client irrespective of the values of other client hints that indicate network capability, like {{HTTPHeader("Downlink")}} and {{HTTPHeader("RTT")}}. +A value of `On` indicates explicit user opt-in into a reduced data usage mode on the client. +When communicated to origins, this allows them to deliver alternative content to reduce the data downloaded such as smaller image and video resources, different markup and styling, disabled polling and automatic updates, and so on. + +> [!NOTE] +> Disabling HTTP/2 Server Push ({{RFC("7540", "Server Push", "8.2")}}) may reduce data downloads. +> Note that this feature is no longer supported by default in most major browser engines. + @@ -26,26 +33,17 @@ Further, it should be used to reduce data sent to the client irrespective of the - + - +
{{Glossary("Forbidden header name")}}noNo
{{Glossary("CORS-safelisted response header")}} noNo
-A value of `On` indicates explicit user opt-in into a reduced data usage -mode on the client, and when communicated to origins allows them to deliver alternative -content to reduce the data downloaded such as smaller image and video resources, -different markup and styling, disabled polling and automatic updates, and so on. - -> [!NOTE] -> Disabling HTTP/2 Server Push ({{RFC("7540", "Server Push", "8.2")}}) may reduce data downloads. -> Note that this feature is no longer supported by default in most major browser engines. - ## Syntax ```http @@ -60,13 +58,9 @@ Save-Data: ## Examples -The {{HTTPHeader("Vary")}} header ensures that the content is cached properly (for -instance ensuring that the user is not served a lower-quality image from the cache when -`Save-Data` header is no longer present \[_e.g._ after having switched from cellular to Wi-Fi]). +### Using `Save-Data: on` -### With `Save-Data: on` - -Request: +The following message requests a resource with `Save-Data` header indicating the client is opting in to reduced data mode: ```http GET /image.jpg HTTP/1.1 @@ -74,7 +68,7 @@ Host: example.com Save-Data: on ``` -Response: +The server responds with a `200` response, and the {{HTTPHeader("Vary")}} header indicates that `Save-Data` may have been used to create the response, and caches should be aware of this header to differentiate responses: ```http HTTP/1.1 200 OK @@ -86,16 +80,18 @@ Content-Type: image/jpeg […] ``` -### Without `Save-Data` +### Omitting `Save-Data` -Request: +In this case, the client requests the same resource without the `Save-Data` header: ```http GET /image.jpg HTTP/1.1 Host: example.com ``` -Response: +The server's response provides the full version of the content. +The {{HTTPHeader("Vary")}} header ensures that responses should be separately cached based on the value of the `Save-Data` header. +This can ensure that the user is not served a lower-quality image from the cache when the `Save-Data` header is no longer present (e.g., after having switched from cellular to Wi-Fi). ```http HTTP/1.1 200 OK @@ -117,9 +113,9 @@ Content-Type: image/jpeg ## See also -- [Help Your Users `Save-Data` - CSS Tricks](https://css-tricks.com/help-users-save-data/) -- [Delivering Fast and Light Applications with Save-Data - web.dev](https://web.dev/articles/optimizing-content-efficiency-save-data) -- {{HTTPHeader("Vary")}} header which indicates that the content served varies depending on the value of `Save-Data` (see [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary)) -- CSS @media feature [`prefers-reduced-data`](/en-US/docs/Web/CSS/@media/prefers-reduced-data) {{experimental_inline}} -- [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) +- CSS `@media` feature [`prefers-reduced-data`](/en-US/docs/Web/CSS/@media/prefers-reduced-data) {{experimental_inline}} +- {{HTTPHeader("Vary")}} header which indicates that the content served varies depending on the value of `Save-Data` (see [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary)) - {{domxref("NetworkInformation.saveData")}} +- [Help Your Users `Save-Data`](https://css-tricks.com/help-users-save-data/) on css-tricks.com +- [Delivering Fast and Light Applications with Save-Data - web.dev](https://web.dev/articles/optimizing-content-efficiency-save-data) on web.dev +- [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/sec-browsing-topics/index.md b/files/en-us/web/http/headers/sec-browsing-topics/index.md index 68a2bc025e06f6c..1e1696e83488654 100644 --- a/files/en-us/web/http/headers/sec-browsing-topics/index.md +++ b/files/en-us/web/http/headers/sec-browsing-topics/index.md @@ -16,7 +16,7 @@ browser-compat: http.headers.Sec-Browsing-Topics > [!NOTE] > An [Enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment) is required to use this feature in your applications. -The **`Sec-Browsing-Topics`** request header sends the selected topics for the current user along with the associated request, which are used by an ad tech platform to choose a personalized ad to display. +The HTTP **`Sec-Browsing-Topics`** {{Glossary("request header")}} sends the selected topics for the current user along with the associated request, which are used by an ad tech platform to choose a personalized ad to display. If the calling site does not have the Topics API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment), attempting to create or modify `Sec-Browsing-Topics` fails silently, and any existing `Sec-Browsing-Topics` header is deleted. @@ -30,7 +30,7 @@ See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more detail {{Glossary("Forbidden header name")}} - yes (prefix Sec-) + Yes (Sec- prefix) diff --git a/files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md b/files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md index efa9126c2d270fd..7e845492ce26890 100644 --- a/files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md +++ b/files/en-us/web/http/headers/sec-ch-prefers-color-scheme/index.md @@ -9,7 +9,8 @@ browser-compat: http.headers.Sec-CH-Prefers-Color-Scheme {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-Prefers-Color-Scheme`** [user preference media feature client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) request header provides the user's preference for light or dark color themes. A user indicates their preference through an operating system setting (for example, light or dark mode) or a user agent setting. +The HTTP **`Sec-CH-Prefers-Color-Scheme`** {{Glossary("request header")}} is a [media feature client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) which provides the user's preference for light or dark color themes. +A user indicates their preference through an operating system setting (for example, light or dark mode) or a user agent setting. If a server signals to a client via the {{httpheader("Accept-CH")}} header that it accepts `Sec-CH-Prefers-Color-Scheme`, the client can then respond with this header to indicate the user's preference for a specific color scheme. The server can send the client appropriately adapted content including images or CSS to display a light or dark mode for subsequent rendered content. @@ -26,7 +27,7 @@ This header is modeled on the {{cssxref("@media/prefers-color-scheme", "prefers- {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -48,12 +49,13 @@ Sec-CH-Prefers-Color-Scheme: ### Directives - `` - - : A string indicating the user agent's preference for dark or light content: `"light"` or `"dark"`. The value may originate from a corresponding setting in the underlying operating system. ## Examples +### Using Sec-CH-Prefers-Color-Scheme + The client makes an initial request to the server: ```http @@ -96,8 +98,8 @@ The client will include the header in subsequent requests in the current session ## See also - [Client hints](/en-US/docs/Web/HTTP/Client_hints) -- [`prefers-color-scheme` CSS Media Query](/en-US/docs/Web/CSS/@media/prefers-color-scheme) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{HTTPHeader("Accept-CH")}} -- [HTTP Caching varying responses](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} +- [HTTP Caching varying responses](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} header +- [`prefers-color-scheme` CSS Media Query](/en-US/docs/Web/CSS/@media/prefers-color-scheme) +- [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/sec-ch-prefers-reduced-motion/index.md b/files/en-us/web/http/headers/sec-ch-prefers-reduced-motion/index.md index 5b93fe34d4f3ef8..76ba7862929f956 100644 --- a/files/en-us/web/http/headers/sec-ch-prefers-reduced-motion/index.md +++ b/files/en-us/web/http/headers/sec-ch-prefers-reduced-motion/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-Prefers-Reduced-Motion {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-Prefers-Reduced-Motion`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) request header indicates the user agent's preference for animations to be displayed with reduced motion. +The HTTP **`Sec-CH-Prefers-Reduced-Motion`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) which indicates the user agent's preference for animations to be displayed with reduced motion. If a server signals to a client via the {{httpheader("Accept-CH")}} header that it accepts `Sec-CH-Prefers-Reduced-Motion`, the client can then respond with this header to indicate the user's preference for reduced motion. The server can send the client appropriately adapted content, for example, JavaScript or CSS, to reduce the motion of any animations presented on subsequent rendered content. This could include reducing the speed or amplitude of movement to reduce discomfort for those with vestibular motion disorders. @@ -26,7 +26,7 @@ This header is modeled on the {{cssxref("@media/prefers-reduced-motion", "prefer {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -40,11 +40,12 @@ Sec-CH-Prefers-Reduced-Motion: ### Directives - `` - - : The user agent's preference for reduced-motion animations. This is often taken from the underlying operating system's setting. The value of this directive can be either `no-preference` or `reduce`. ## Examples +### Using Sec-CH-Prefers-Reduced-Motion + The client makes an initial request to the server: ```http @@ -86,8 +87,8 @@ The client will include the header in subsequent requests in the current session ## See also - [Client hints](/en-US/docs/Web/HTTP/Client_hints) -- [`prefers-reduced-motion` CSS Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{HTTPHeader("Accept-CH")}} -- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} +- [`prefers-reduced-motion` CSS Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) +- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}} header +- [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/sec-ch-prefers-reduced-transparency/index.md b/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md index a552b840b0dc024..485065b1e5fe1e9 100644 --- a/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md +++ b/files/en-us/web/http/headers/sec-ch-prefers-reduced-transparency/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-Prefers-Reduced-Transparency {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-Prefers-Reduced-Transparency`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) request header indicates the user agent's preference for reduced transparency. +The HTTP **`Sec-CH-Prefers-Reduced-Transparency`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user_preference_media_features_client_hints) that indicates the user agent's preference for reduced transparency. If a server signals to a client via the {{httpheader("Accept-CH")}} header that it accepts `Sec-CH-Prefers-Reduced-Transparency`, the client can then respond with this header to indicate the user's preference for reduced transparency. The server can send the client appropriately adapted content — for example, CSS or images — to reduce the transparency of the content. @@ -26,7 +26,7 @@ This header is modeled on the {{cssxref("@media/prefers-reduced-transparency", " {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -40,11 +40,12 @@ Sec-CH-Prefers-Reduced-Transparency: ### Directives - `` - - : The user agent's preference for reduced transparency. This is often taken from the underlying operating system's setting. The value of this directive can be either `no-preference` or `reduce`. ## Examples +### Using Sec-CH-Prefers-Reduced-Transparency + The client makes an initial request to the server: ```http @@ -87,6 +88,6 @@ The client will include the header in subsequent requests in the current session - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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 the {{HTTPHeader("Vary")}} header +- [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/sec-ch-ua-arch/index.md b/files/en-us/web/http/headers/sec-ch-ua-arch/index.md index 86a7d741c8adefd..af073d849a28811 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-arch/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-arch/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-UA-Arch {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Arch`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the user-agent's underlying CPU architecture, such as ARM or x86. +The HTTP **`Sec-CH-UA-Arch`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which contains the user-agent's underlying CPU architecture, such as ARM or x86. This might be used by a server, for example, to select and offer the correct binary format of an executable for a user to download. @@ -24,7 +24,7 @@ This might be used by a server, for example, to select and offer the correct bin {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -42,6 +42,8 @@ Sec-CH-UA-Arch: ## Examples +### Using Sec-CH-UA-Arch + A server requests the `Sec-CH-UA-Arch` header by including the {{HTTPHeader("Accept-CH")}} in a response to some request from the client, using the name of the desired header as a token: ```http @@ -76,6 +78,6 @@ Note above that the [low entropy headers](/en-US/docs/Web/HTTP/Client_hints#low_ - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-bitness/index.md b/files/en-us/web/http/headers/sec-ch-ua-bitness/index.md index 777c86fbcfc6f2e..81023cc2c052c6f 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-bitness/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-bitness/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-UA-Bitness {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Bitness`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the "bitness" of the user-agent's underlying CPU architecture. +The HTTP **`Sec-CH-UA-Bitness`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which provides the "bitness" of the user-agent's underlying CPU architecture. This is the size in bits of an integer or memory address—typically 64 or 32 bits. This might be used by a server, for example, to select and offer the correct binary format of an executable for a user to download. @@ -25,7 +25,7 @@ This might be used by a server, for example, to select and offer the correct bin {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -43,7 +43,9 @@ Sec-CH-UA-Bitness: ## Examples -A server requests the `Sec-CH-UA-Bitness` header by including the {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: +### Using Sec-CH-UA-Bitness + +A server requests the `Sec-CH-UA-Bitness` header by including {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: ```http HTTP/1.1 200 OK @@ -75,6 +77,6 @@ Sec-CH-UA-Bitness: "64" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-full-version-list/index.md b/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md index cde4ae2f204e5e4..7980e1a2598c134 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-full-version-list/index.md @@ -9,7 +9,15 @@ browser-compat: http.headers.Sec-CH-UA-Full-Version-List {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Full-Version-List`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the user-agent's branding and full version information. +The HTTP **`Sec-CH-UA-Full-Version-List`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which provides the user-agent's branding and full version information. + +The **`Sec-CH-UA-Full-Version-List`** header provides the brand and full version information for each brand associated with the browser, in a comma-separated list. + +The header may include "fake" brands in any position and with any name. +This is a feature designed to prevent servers from rejecting unknown user agents outright, forcing user agents to lie about their brand identity. + +> [!NOTE] +> This is similar to {{HTTPHeader("Sec-CH-UA")}}, but includes the full version number instead of the significant version number for each brand. @@ -22,25 +30,11 @@ The **`Sec-CH-UA-Full-Version-List`** [user agent client hint](/en-US/docs/Web/H - +
{{Glossary("Forbidden header name")}}yesYes (Sec- prefix)
-The **`Sec-CH-UA-Full-Version-List`** header provides the brand and full version information for each brand associated with the browser, in a comma-separated list. - -A brand is a commercial name for the user agent like: Chromium, Opera, Google Chrome, Microsoft Edge, Firefox, and Safari. -A user agent might have several associated brands. -For example, Opera, Chrome, and Edge are all based on Chromium, and will provide both brands in the **`Sec-CH-UA-Full-Version-List`** header. - -The header therefore allows the server to customize its response based on both shared brands and on particular customizations in their specific respective builds. - -The header may include "fake" brands in any position and with any name. -This is a feature designed to prevent servers from rejecting unknown user agents outright, forcing user agents to lie about their brand identity. - -> [!NOTE] -> This is similar to {{HTTPHeader("Sec-CH-UA")}}, but includes the full version number instead of the significant version number for each brand. - ## Syntax A comma separated list of brands in the user agent brand list, and their associated full version number. @@ -58,8 +52,18 @@ Sec-CH-UA-Full-Version-List: "";v="", ... - `` - : A full version number, such as 98.0.4750.0. +## Description + +A brand is a commercial name for the user agent like: Chromium, Opera, Google Chrome, Microsoft Edge, Firefox, and Safari. +A user agent might have several associated brands. +For example, Opera, Chrome, and Edge are all based on Chromium, and will provide both brands in the `Sec-CH-UA-Full-Version-List` header. + +The header allows the server to customize its response based on both shared brands and on particular customizations in their specific respective builds. + ## Examples +### Using Sec-CH-UA-Full-Version-List + A server requests the `Sec-CH-UA-Full-Version-List` header by including the {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: ```http @@ -91,6 +95,6 @@ Sec-CH-UA-Platform: "Linux" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-full-version/index.md b/files/en-us/web/http/headers/sec-ch-ua-full-version/index.md index afb9c86a921b857..85106f96cfc6db2 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-full-version/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-full-version/index.md @@ -12,7 +12,7 @@ browser-compat: http.headers.Sec-CH-UA-Full-Version > [!NOTE] > This is being replaced by the {{HTTPHeader("Sec-CH-UA-Full-Version-List")}}. -The **`Sec-CH-UA-Full-Version`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the user-agent's full version string. +The HTTP **`Sec-CH-UA-Full-Version`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which provides the user-agent's full version string. @@ -25,7 +25,7 @@ The **`Sec-CH-UA-Full-Version`** [user agent client hint](/en-US/docs/Web/HTTP/C - +
{{Glossary("Forbidden header name")}}yesYes (Sec- prefix)
@@ -43,6 +43,8 @@ Sec-CH-UA-Full-Version: ## Examples +### Using Sec-CH-UA-Full-Version + A server requests the `Sec-CH-UA-Full-Version` header by including the {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: ```http @@ -75,6 +77,6 @@ Sec-CH-UA-Platform: "Windows" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-mobile/index.md b/files/en-us/web/http/headers/sec-ch-ua-mobile/index.md index cd878964ef3097b..ffd70cb24d5e887 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-mobile/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-mobile/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-UA-Mobile {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Mobile`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header indicates whether the browser is on a mobile device. +The HTTP **`Sec-CH-UA-Mobile`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which indicates whether the browser is on a mobile device. It can also be used by a desktop browser to indicate a preference for a "mobile" user experience. `Sec-CH-UA-Mobile` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints). @@ -26,7 +26,7 @@ Unless blocked by a user agent permission policy, it is sent by default, without {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -45,8 +45,9 @@ Sec-CH-UA-Mobile: ## Examples -As `Sec-CH-UA-Mobile` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints) it is typically sent in all requests. +### Using Sec-CH-UA-Mobile +As `Sec-CH-UA-Mobile` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints) it is typically sent in all requests. A desktop browser would usually send requests with the following header: ```http @@ -71,6 +72,6 @@ Sec-CH-UA-Mobile: ?1 - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-model/index.md b/files/en-us/web/http/headers/sec-ch-ua-model/index.md index 01c810fb49bc7b6..b04595f4a3df0cf 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-model/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-model/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-UA-Model {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Model`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header indicates the device model on which the browser is running. +The HTTP **`Sec-CH-UA-Model`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which indicates the device model on which the browser is running. @@ -22,7 +22,7 @@ The **`Sec-CH-UA-Model`** [user agent client hint](/en-US/docs/Web/HTTP/Client_h - +
{{Glossary("Forbidden header name")}}yesYes (Sec- prefix)
@@ -40,7 +40,9 @@ Sec-CH-UA-Model: ## Examples -A server requests the `Sec-CH-UA-Model` header by including the {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: +### Using Sec-CH-UA-Model + +A server requests the `Sec-CH-UA-Model` header by including {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: ```http HTTP/1.1 200 OK @@ -73,6 +75,6 @@ Sec-CH-UA-Model: "Pixel 3 XL" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-platform-version/index.md b/files/en-us/web/http/headers/sec-ch-ua-platform-version/index.md index 8fa04f9f3516d06..3dccafdab58f050 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-platform-version/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-platform-version/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-UA-Platform-Version {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Platform-Version`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the version of the operating system on which the user agent is running. +The HTTP **`Sec-CH-UA-Platform-Version`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which provides the version of the operating system on which the user agent is running. @@ -22,7 +22,7 @@ The **`Sec-CH-UA-Platform-Version`** [user agent client hint](/en-US/docs/Web/HT - +
{{Glossary("Forbidden header name")}}yesYes (Sec- prefix)
@@ -36,14 +36,13 @@ Sec-CH-UA-Platform-Version: ### Directives - `` - - - : The version string typically contains the operating system version in a string, consisting of dot-separated major, minor and patch version numbers. - For example, `"11.0.0"` - + - : The version string typically contains the operating system version in a string, consisting of dot-separated major, minor and patch version numbers, for example `"11.0.0"`. The version string on Linux is always empty. ## Examples +### Using Sec-CH-UA-Platform-Version + A server requests the `Sec-CH-UA-Platform-Version` header by including the {{HTTPHeader("Accept-CH")}} in a _response_ to any request from the client, using the name of the desired header as a token: ```http @@ -76,6 +75,6 @@ Sec-CH-UA-Platform-Version: "10.0.0" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua-platform/index.md b/files/en-us/web/http/headers/sec-ch-ua-platform/index.md index db34d091b0ac2d5..ec8b0fd18f3527b 100644 --- a/files/en-us/web/http/headers/sec-ch-ua-platform/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua-platform/index.md @@ -9,7 +9,7 @@ browser-compat: http.headers.Sec-CH-UA-Platform {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA-Platform`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the platform or operating system on which the user agent is running. +The HTTP **`Sec-CH-UA-Platform`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which provides the platform or operating system on which the user agent is running. For example: "Windows" or "Android". `Sec-CH-UA-Platform` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints). @@ -26,7 +26,7 @@ Unless blocked by a user agent permission policy, it is sent by default (without {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -44,8 +44,9 @@ Sec-CH-UA-Platform: ## Examples -As `Sec-CH-UA-Platform` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints) it is typically sent in all requests. +### Using Sec-CH-UA-Platform +As `Sec-CH-UA-Platform` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints) it is typically sent in all requests. A browser running on a macOS computer might add the following header to all requests. ```http @@ -64,6 +65,6 @@ Sec-CH-UA-Platform: "macOS" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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")}} header +- [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/sec-ch-ua/index.md b/files/en-us/web/http/headers/sec-ch-ua/index.md index 032a9b8030cda0d..024647e687f5c8a 100644 --- a/files/en-us/web/http/headers/sec-ch-ua/index.md +++ b/files/en-us/web/http/headers/sec-ch-ua/index.md @@ -9,7 +9,19 @@ browser-compat: http.headers.Sec-CH-UA {{HTTPSidebar}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`Sec-CH-UA`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) request header provides the user-agent's branding and significant version information. +The HTTP **`Sec-CH-UA`** {{Glossary("request header")}} is a [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) which provides the user-agent's branding and significant version information. + +The `Sec-CH-UA` header provides the brand and significant version for each brand associated with the browser in a comma-separated list. +The header therefore allows the server to customize its response based on both shared brands and on particular customizations in their respective versions. + +`Sec-CH-UA` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints). +Unless blocked by a user agent permission policy, it is sent by default, without the server opting in by sending {{HTTPHeader("Accept-CH")}}. + +The header may include "fake" brands in any position and with any name. +This is a feature designed to prevent servers from rejecting unknown user agents outright, forcing user agents to lie about their brand identity. + +> [!NOTE] +> The {{HTTPHeader("Sec-CH-UA-Full-Version-List")}} header is the same as `Sec-CH-UA`, but includes the full version number rather than the significant version number for each brand. @@ -22,37 +34,18 @@ The **`Sec-CH-UA`** [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#u - +
{{Glossary("Forbidden header name")}}yesYes (Sec- prefix)
-The **`Sec-CH-UA`** header provides the brand and significant version for each brand associated with the browser in a comma-separated list. - -A brand is a commercial name for the user agent like: Chromium, Opera, Google Chrome, Microsoft Edge, Firefox, and Safari. -A user agent might have several associated brands. -For example, Opera, Chrome, and Edge are all based on Chromium, and will provide both brands in the **`Sec-CH-UA`** header. - -The _significant version_ is the "marketing" version identifier that is used to distinguish between major releases of the brand. -For example a Chromium build with _full version number_ "96.0.4664.45" has a significant version number of "96". - -The header therefore allows the server to customize its response based on both shared brands and on particular customizations in their respective versions. - -`Sec-CH-UA` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints). -Unless blocked by a user agent permission policy, it is sent by default, without the server opting in by sending {{HTTPHeader("Accept-CH")}}. - -The header may include "fake" brands in any position and with any name. -This is a feature designed to prevent servers from rejecting unknown user agents outright, forcing user agents to lie about their brand identity. - -> **Note:** {{HTTPHeader("Sec-CH-UA-Full-Version-List")}} is the same as **`Sec-CH-UA`**, but includes the full version number rather than the significant version number for each brand. - ## Syntax A comma separated list of brands in the user agent brand list, and their associated significant version number. The syntax for a single entry has the following format: ```http -Sec-CH-UA: "";v="", ... +Sec-CH-UA: "";v="", … ``` ### Directives @@ -62,8 +55,19 @@ Sec-CH-UA: "";v="", ... - `` - : The "marketing" version number associated with distinguishable web-exposed features. +## Description + +A brand is a commercial name for the user agent like: Chromium, Opera, Google Chrome, Microsoft Edge, Firefox, and Safari. +A user agent might have several associated brands. +For example, Opera, Chrome, and Edge are all based on Chromium, and will provide both brands in the `Sec-CH-UA` header. + +The _significant version_ is the "marketing" version identifier that is used to distinguish between major releases of the brand. +For example a Chromium build with _full version number_ "96.0.4664.45" has a significant version number of "96". + ## Examples +### Different Sec-CH-UA brands + `Sec-CH-UA` is a [low entropy hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints). Unless explicitly blocked by a user agent policy, it will be sent in all requests (without the server having to opt in by sending {{HTTPHeader("Accept-CH")}}). @@ -99,6 +103,6 @@ Sec-CH-UA: "Opera";v="81", " Not;A Brand";v="99", "Chromium";v="95" - [Client hints](/en-US/docs/Web/HTTP/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) -- [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) - {{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/sec-fetch-dest/index.md b/files/en-us/web/http/headers/sec-fetch-dest/index.md index 44e089eff457597..c280f6f0ccb960f 100644 --- a/files/en-us/web/http/headers/sec-fetch-dest/index.md +++ b/files/en-us/web/http/headers/sec-fetch-dest/index.md @@ -7,7 +7,8 @@ browser-compat: http.headers.Sec-Fetch-Dest {{HTTPSidebar}} -The **`Sec-Fetch-Dest`** {{Glossary("Fetch metadata request header", "fetch metadata request header")}} indicates the request's _destination_. That is the initiator of the original fetch request, which is where (and how) the fetched data will be used. +The HTTP **`Sec-Fetch-Dest`** {{Glossary("fetch metadata request header")}} indicates the request's _destination_. +That is the initiator of the original fetch request, which is where (and how) the fetched data will be used. This allows servers to determine whether to service a request based on whether it is appropriate for how it is _expected_ to be used. For example, a request with an `audio` destination should request audio data, not some other type of resource (for example, a document that includes sensitive user information). @@ -19,13 +20,13 @@ This allows servers to determine whether to service a request based on whether i {{Glossary("Forbidden header name")}} - yes (prefix Sec-) + Yes (Sec- prefix) {{Glossary("CORS-safelisted request header")}} - no + No @@ -114,6 +115,8 @@ Servers should ignore this header if it contains any other value. ## Examples +### Using Sec-Fetch-Dest + A cross-site request generated by an {{HTMLElement("img")}} element would result in a request with the following HTTP request headers (note that the destination is `image`): ```http @@ -132,11 +135,6 @@ Sec-Fetch-Site: cross-site ## See also -- Related headers - - - {{HTTPHeader("Sec-Fetch-Mode")}} - - {{HTTPHeader("Sec-Fetch-Site")}} - - {{HTTPHeader("Sec-Fetch-User")}} - +- {{HTTPHeader("Sec-Fetch-Mode")}}, {{HTTPHeader("Sec-Fetch-Site")}}, {{HTTPHeader("Sec-Fetch-User")}} fetch metadata request headers - [Protect your resources from web attacks with Fetch Metadata](https://web.dev/articles/fetch-metadata) (web.dev) - [Fetch Metadata Request Headers playground](https://secmetadata.appspot.com/) (secmetadata.appspot.com) diff --git a/files/en-us/web/http/headers/sec-fetch-mode/index.md b/files/en-us/web/http/headers/sec-fetch-mode/index.md index d000e32350533a7..911b1566998f9cd 100644 --- a/files/en-us/web/http/headers/sec-fetch-mode/index.md +++ b/files/en-us/web/http/headers/sec-fetch-mode/index.md @@ -7,9 +7,10 @@ browser-compat: http.headers.Sec-Fetch-Mode {{HTTPSidebar}} -The **`Sec-Fetch-Mode`** {{Glossary("Fetch metadata request header", "fetch metadata request header")}} indicates the [mode](/en-US/docs/Web/API/Request/mode) of the request. +The HTTP **`Sec-Fetch-Mode`** {{Glossary("fetch metadata request header")}} indicates the [mode](/en-US/docs/Web/API/Request/mode) of the request. -Broadly speaking, this allows a server to distinguish between: requests originating from a user navigating between HTML pages, and requests to load images and other resources. For example, this header would contain `navigate` for top level navigation requests, while `no-cors` is used for loading an image. +Broadly speaking, this allows a server to distinguish between requests originating from a user navigating between HTML pages, and requests to load images and other resources. +For example, this header would contain `navigate` for top level navigation requests, while `no-cors` is used for loading an image. @@ -19,13 +20,13 @@ Broadly speaking, this allows a server to distinguish between: requests originat - + - +
{{Glossary("Forbidden header name")}}yes (prefix Sec-)Yes (Sec- prefix)
{{Glossary("CORS-safelisted request header")}} noNo
@@ -60,6 +61,8 @@ Servers should ignore this header if it contains any other value. ## Examples +### Using Sec-Fetch-Mode + If a user clicks on a page link to another page on the same origin, the resulting request would have the following headers (note that the mode is `navigate`): ```http @@ -87,11 +90,6 @@ Sec-Fetch-Site: cross-site ## See also -- Related headers - - - {{HTTPHeader("Sec-Fetch-Dest")}} - - {{HTTPHeader("Sec-Fetch-Site")}} - - {{HTTPHeader("Sec-Fetch-User")}} - +- {{HTTPHeader("Sec-Fetch-Dest")}}, {{HTTPHeader("Sec-Fetch-Site")}}, {{HTTPHeader("Sec-Fetch-User")}} fetch metadata request headers - [Protect your resources from web attacks with Fetch Metadata](https://web.dev/articles/fetch-metadata) (web.dev) - [Fetch Metadata Request Headers playground](https://secmetadata.appspot.com/) (secmetadata.appspot.com) diff --git a/files/en-us/web/http/headers/sec-fetch-site/index.md b/files/en-us/web/http/headers/sec-fetch-site/index.md index 1f12ad5c3a72623..b588a5e634a95eb 100644 --- a/files/en-us/web/http/headers/sec-fetch-site/index.md +++ b/files/en-us/web/http/headers/sec-fetch-site/index.md @@ -7,11 +7,11 @@ browser-compat: http.headers.Sec-Fetch-Site {{HTTPSidebar}} -The **`Sec-Fetch-Site`** {{Glossary("Fetch metadata request header", "fetch metadata request header")}} indicates the relationship between a request initiator's origin and the origin of the requested resource. +The HTTP **`Sec-Fetch-Site`** {{Glossary("fetch metadata request header")}} indicates the relationship between a request initiator's origin and the origin of the requested resource. In other words, this header tells a server whether a request for a resource is coming from the same origin, the same site, a different site, or is a "user initiated" request. The server can then use this information to decide if the request should be allowed. -Same-origin requests would usually be allowed by default, but what happens for requests from other origins may further depend on what resource is being requested, or information in other {{Glossary("Fetch metadata request header","Fetch metadata request headers")}}. By default, requests that are not accepted should be rejected with a {{HTTPStatus("403")}} response code. +Same-origin requests would usually be allowed by default, but what happens for requests from other origins may further depend on what resource is being requested, or information in another {{Glossary("fetch metadata request header")}}. By default, requests that are not accepted should be rejected with a {{HTTPStatus("403")}} response code. @@ -21,13 +21,13 @@ Same-origin requests would usually be allowed by default, but what happens for r - + - +
{{Glossary("Forbidden header name")}}yes (prefix Sec-)Yes (Sec- prefix)
{{Glossary("CORS-safelisted request header")}} noNo
@@ -83,11 +83,6 @@ Sec-Fetch-Site: cross-site ## See also -- Related headers - - - {{HTTPHeader("Sec-Fetch-Mode")}} - - {{HTTPHeader("Sec-Fetch-User")}} - - {{HTTPHeader("Sec-Fetch-Dest")}} - +- {{HTTPHeader("Sec-Fetch-Mode")}}, {{HTTPHeader("Sec-Fetch-User")}}, {{HTTPHeader("Sec-Fetch-Dest")}} fetch metadata request headers - [Protect your resources from web attacks with Fetch Metadata](https://web.dev/articles/fetch-metadata) (web.dev) - [Fetch Metadata Request Headers playground](https://secmetadata.appspot.com/) (secmetadata.appspot.com) diff --git a/files/en-us/web/http/headers/sec-fetch-user/index.md b/files/en-us/web/http/headers/sec-fetch-user/index.md index d130e502e7f6108..4e294e55e1dd702 100644 --- a/files/en-us/web/http/headers/sec-fetch-user/index.md +++ b/files/en-us/web/http/headers/sec-fetch-user/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Sec-Fetch-User {{HTTPSidebar}} -The **`Sec-Fetch-User`** {{Glossary("Fetch metadata request header", "fetch metadata request header")}} is only sent for requests initiated by user activation, and its value will always be `?1`. +The HTTP **`Sec-Fetch-User`** {{Glossary("fetch metadata request header")}} is sent for requests initiated by user activation, and its value is always `?1`. A server can use this header to identify whether a navigation request from a document, iframe, etc., was originated by the user. @@ -19,13 +19,13 @@ A server can use this header to identify whether a navigation request from a doc {{Glossary("Forbidden header name")}} - yes (prefix Sec-) + Yes (Sec- prefix) {{Glossary("CORS-safelisted request header")}} - no + No @@ -42,6 +42,8 @@ The value will always be `?1`. When a request is triggered by something other th ## Examples +### Using Sec-Fetch-User + If a user clicks on a page link to another page on the same origin, the resulting request would have the following headers: ```http @@ -61,11 +63,6 @@ Sec-Fetch-User: ?1 ## See also -- Related headers - - - {{HTTPHeader("Sec-Fetch-Dest")}} - - {{HTTPHeader("Sec-Fetch-Mode")}} - - {{HTTPHeader("Sec-Fetch-Site")}} - +- {{HTTPHeader("Sec-Fetch-Dest")}}, {{HTTPHeader("Sec-Fetch-Mode")}}, {{HTTPHeader("Sec-Fetch-Site")}} fetch metadata request headers - [Protect your resources from web attacks with Fetch Metadata](https://web.dev/articles/fetch-metadata) (web.dev) - [Fetch Metadata Request Headers playground](https://secmetadata.appspot.com/) (secmetadata.appspot.com) diff --git a/files/en-us/web/http/headers/sec-gpc/index.md b/files/en-us/web/http/headers/sec-gpc/index.md index 1c933d9ca20d098..285d1e131f5b160 100644 --- a/files/en-us/web/http/headers/sec-gpc/index.md +++ b/files/en-us/web/http/headers/sec-gpc/index.md @@ -11,10 +11,9 @@ spec-urls: https://privacycg.github.io/gpc-spec/ {{HTTPSidebar}}{{SeeCompatTable}}{{non-standard_header}} -The **`Sec-GPC`** ([**G**lobal **P**rivacy **C**ontrol](https://globalprivacycontrol.org/)) request header indicates whether the user consents to a website or service selling or sharing their personal information with third parties. +The HTTP **`Sec-GPC`** {{Glossary("request header")}} is part of the [Global Privacy Control](https://globalprivacycontrol.org/) (GPC) mechanism to indicate whether the user consents to a website or service selling or sharing their personal information with third parties. The specification does not define how the user can withdraw or grant consent for website. -Where possible the mechanism will be indicated in the [browser compatibility](#browser_compatibility) section below. @@ -24,7 +23,7 @@ Where possible the mechanism will be indicated in the [browser compatibility](#b - +
{{Glossary("Forbidden header name")}}yesYes (Sec- prefix)
@@ -32,14 +31,14 @@ Where possible the mechanism will be indicated in the [browser compatibility](#b ## Syntax ```http -Sec-GPC: 1 +Sec-GPC: ``` ## Directives -The `Sec-GPC` is header is sent with a value of `1` if the user has indicated that they prefer their information not be shared with, or sold to, third parties. - -Otherwise, the header is not sent, which indicates that either the user has not made a decision or the user is okay with their information being shared with or sold to third parties. +- `` + - : A value of `1` means the user has indicated that they prefer their information not be shared with, or sold to, third parties. + Otherwise, the header is not sent, which indicates that either the user has not made a decision or the user is okay with their information being shared with or sold to third parties. ## Examples diff --git a/files/en-us/web/http/headers/sec-purpose/index.md b/files/en-us/web/http/headers/sec-purpose/index.md index f7ba76d25d36374..88dfeddc7964b37 100644 --- a/files/en-us/web/http/headers/sec-purpose/index.md +++ b/files/en-us/web/http/headers/sec-purpose/index.md @@ -7,7 +7,7 @@ browser-compat: http.headers.Sec-Purpose {{HTTPSidebar}} -The **`Sec-Purpose`** {{Glossary("Fetch metadata request header", "fetch metadata request header")}} indicates the purpose for which the requested resource will be used, when that purpose is something other than immediate use by the user-agent. +The HTTP **`Sec-Purpose`** {{Glossary("fetch metadata request header")}} indicates the purpose for which the requested resource will be used, when that purpose is something other than immediate use by the user-agent. The only purpose that is currently defined is `prefetch`, which indicates that the resource is being requested in anticipation that it will be needed by a page that is likely to be navigated to in the near future, such as a page linked in search results or a link that a user has hovered over. The server can use this knowledge to: adjust the caching expiry for the request, disallow the request, or perhaps to treat it differently when counting page visits. @@ -23,13 +23,13 @@ Note that if this header is set then a {{HTTPHeader("Sec-Fetch-Dest")}} header i {{Glossary("Forbidden header name")}} - yes (prefix Sec-) + Yes (Sec- prefix) {{Glossary("CORS-safelisted request header")}} - no + No @@ -87,5 +87,6 @@ Cache-Control: no-cache ## See also +- {{HTTPHeader("Sec-Fetch-Dest")}}, {{HTTPHeader("Sec-Fetch-Mode")}}, {{HTTPHeader("Sec-Fetch-Site")}}, {{HTTPHeader("Sec-Fetch-User")}} fetch metadata request headers - {{Glossary("Prefetch")}} (Glossary) - [``](/en-US/docs/Web/HTML/Element/link) element with attribute [`rel="prefetch"`](/en-US/docs/Web/HTML/Attributes/rel/prefetch) diff --git a/files/en-us/web/http/headers/sec-websocket-accept/index.md b/files/en-us/web/http/headers/sec-websocket-accept/index.md index 53f4e86bb5ec2ba..843f4db9290adac 100644 --- a/files/en-us/web/http/headers/sec-websocket-accept/index.md +++ b/files/en-us/web/http/headers/sec-websocket-accept/index.md @@ -8,7 +8,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.3 {{HTTPSidebar}} -The **Sec-WebSocket-Accept** HTTP {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to indicate that the server is willing to upgrade to a WebSocket connection. +The HTTP **Sec-WebSocket-Accept** {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to indicate that the server is willing to upgrade to a WebSocket connection. This header must appear no more than once in the response, and has a directive value that is calculated from the {{HTTPHeader("Sec-WebSocket-Key")}} request header sent in the corresponding request. @@ -20,7 +20,7 @@ This header must appear no more than once in the response, and has a directive v {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -33,15 +33,17 @@ Sec-WebSocket-Accept: ## Directives -- \ +- `` - : If a {{HTTPHeader("Sec-WebSocket-Key")}} header was provided, the value of this header is computed by taking the value of the key, concatenating the string `258EAFA5-E914-47DA-95CA-C5AB0DC85B11`, and taking the [SHA-1](https://en.wikipedia.org/wiki/SHA-1) hash of that concatenated string — resulting in a 20-byte value. That value is then [base64](/en-US/docs/Glossary/Base64) encoded to obtain the value of this property. ## Examples +### WebSocket opening handshake + The client will initiate a WebSocket handshake with a request like the following. -Note that this starts as an HTTP `GET` request (HTTP/1.1 or later) and includes the {{httpheader("Upgrade")}} header indicating the intent to upgrade to a web socket. -It also includes `Sec-WebSocket-Key`, which is used in the calculation of `Sec-WebSocket-Accept` to confirm the intent to upgrade the connection to a web socket. +Note that this starts as an HTTP `GET` request (HTTP/1.1 or later) and includes the {{httpheader("Upgrade")}} header indicating the intent to upgrade to a WebSocket connection. +It also includes `Sec-WebSocket-Key`, which is used in the calculation of `Sec-WebSocket-Accept` to confirm the intent to upgrade the connection to a WebSocket connection. ```http GET /chat HTTP/1.1 @@ -52,7 +54,7 @@ Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13 ``` -The response from the server should include the `Sec-WebSocket-Accept` header with a value that is calculated from the `Sec-WebSocket-Key` header in the request, and confirms the intent to upgrade the connection to a web socket: +The response from the server should include the `Sec-WebSocket-Accept` header with a value that is calculated from the `Sec-WebSocket-Key` header in the request, and confirms the intent to upgrade the connection to a WebSocket connection: ```http HTTP/1.1 101 Switching Protocols diff --git a/files/en-us/web/http/headers/sec-websocket-extensions/index.md b/files/en-us/web/http/headers/sec-websocket-extensions/index.md index 6274ae57bc10fea..e5465b951441675 100644 --- a/files/en-us/web/http/headers/sec-websocket-extensions/index.md +++ b/files/en-us/web/http/headers/sec-websocket-extensions/index.md @@ -8,7 +8,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.2 {{HTTPSidebar}} -The **Sec-WebSocket-Extensions** HTTP {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to negotiate a protocol extension used by the client and server. +The HTTP **Sec-WebSocket-Extensions** {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to negotiate a protocol extension used by the client and server. In a request the header specifies one or more extensions that the web application would like to use, in order of preference. These can be added as in multiple headers, or as comma separate values added to a single header. @@ -26,7 +26,7 @@ The request header is automatically added by the browser based on its own capabi {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -54,6 +54,8 @@ Sec-WebSocket-Extensions: ## Examples +### WebSocket opening handshake + The HTTP request below shows the opening handshake where a client supports the `permessage-deflate` and `client_max_window_bits` extensions. ```http diff --git a/files/en-us/web/http/headers/sec-websocket-key/index.md b/files/en-us/web/http/headers/sec-websocket-key/index.md index 1c617c14c6cd3f6..99b6201c96a2935 100644 --- a/files/en-us/web/http/headers/sec-websocket-key/index.md +++ b/files/en-us/web/http/headers/sec-websocket-key/index.md @@ -8,7 +8,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.1 {{HTTPSidebar}} -The **Sec-WebSocket-Key** HTTP {{glossary("request header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to allow a client (user agent) to confirm that it "really wants" to request that an HTTP client is upgraded to become a WebSocket. +The HTTP **Sec-WebSocket-Key** {{glossary("request header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to allow a client (user agent) to confirm that it "really wants" to request that an HTTP client is upgraded to become a WebSocket. The value of the key is computed using an algorithm defined in the WebSocket specification, so this _does not provide security_. Instead, it helps to prevent non-WebSocket clients from inadvertently, or through misuse, requesting a WebSocket connection. @@ -26,7 +26,7 @@ The user agent can then validate this before this before confirming the connecti {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -39,15 +39,17 @@ Sec-WebSocket-Key: ## Directives -- \ +- `` - : The key for this request to upgrade. This is a randomly selected 16-byte nonce that has been base64-encoded and isomorphic encoded. The user agent adds this when initiating the WebSocket connection. ## Examples +### WebSocket opening handshake + The client will initiate a WebSocket handshake with a request like the following. -Note that this starts as an HTTP `GET` request (HTTP/1.1 or later), in addition to `Sec-WebSocket-Key`, the request includes the {{httpheader("Upgrade")}} header, indicating the intent to upgrade from HTTP to a web socket. +Note that this starts as an HTTP `GET` request (HTTP/1.1 or later), in addition to `Sec-WebSocket-Key`, the request includes the {{httpheader("Upgrade")}} header, indicating the intent to upgrade from HTTP to a WebSocket connection. ```http GET /chat HTTP/1.1 @@ -58,7 +60,7 @@ Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13 ``` -The response from the server should include the `Sec-WebSocket-Accept` header with a value that is calculated from the `Sec-WebSocket-Key` header in the request, and confirms the intent to upgrade the connection to a web socket: +The response from the server should include the `Sec-WebSocket-Accept` header with a value that is calculated from the `Sec-WebSocket-Key` header in the request, and confirms the intent to upgrade the connection to a WebSocket connection: ```http HTTP/1.1 101 Switching Protocols diff --git a/files/en-us/web/http/headers/sec-websocket-protocol/index.md b/files/en-us/web/http/headers/sec-websocket-protocol/index.md index 59ab9e025cd6007..7a09df47afdffb9 100644 --- a/files/en-us/web/http/headers/sec-websocket-protocol/index.md +++ b/files/en-us/web/http/headers/sec-websocket-protocol/index.md @@ -8,7 +8,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.4 {{HTTPSidebar}} -The **`Sec-WebSocket-Protocol`** HTTP {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to negotiate a [sub-protocol](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) to use in the communication. +The HTTP **`Sec-WebSocket-Protocol`** {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to negotiate a [sub-protocol](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) to use in the communication. This can be a well understood protocol, such as SOAP or WAMP, or a custom protocol understood by the client and server. In a request the header specifies one or more WebSocket sub-protocols that the web application would like to use, in order of preference. @@ -28,7 +28,7 @@ The sub-protocol selected by the server is made available to the web application {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -55,6 +55,8 @@ Sec-WebSocket-Protocol: ## Examples +### WebSocket opening handshake + The sub-protocol is specified in the original WebSocket [handshake request](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake). The request below shows that the client prefers `soap`, but also supports `wamp`. diff --git a/files/en-us/web/http/headers/sec-websocket-version/index.md b/files/en-us/web/http/headers/sec-websocket-version/index.md index af38edf4da19869..cf78bccdea7ca73 100644 --- a/files/en-us/web/http/headers/sec-websocket-version/index.md +++ b/files/en-us/web/http/headers/sec-websocket-version/index.md @@ -8,7 +8,7 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.5 {{HTTPSidebar}} -The **Sec-WebSocket-Version** HTTP {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to indicate the WebSocket protocol supported by the client, and the protocol versions supported by the server if it does _not_ support the version specified in the request. +The HTTP **Sec-WebSocket-Version** {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to indicate the WebSocket protocol supported by the client, and the protocol versions supported by the server if it does _not_ support the version specified in the request. The header can only appear once in a request, and specifies the WebSocket version that web application is using. The current version of the protocol at time of writing is 13. @@ -29,7 +29,7 @@ The header should not be sent in responses if the server understands the version {{Glossary("Forbidden header name")}} - yes + Yes (Sec- prefix) @@ -51,17 +51,17 @@ Sec-WebSocket-Version: ## Directives - `` - - : The WebSocket protocol version the client wishes to use when communicating with the server. This number should be the most recent version possible listed in the [IANA WebSocket Version Number Registry](https://www.iana.org/assignments/websocket/websocket.xml#version-number). The most recent final version of the WebSocket protocol is version 13. - - `` - : On error, a comma-delineated list of the WebSocket protocol versions supported by the server. The header is not sent in responses if `` is supported. ## Examples +### WebSocket opening handshake + The version supported by the client is specified in the original `WebSocket` [handshake request](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake). For the current protocol, the version is "13", as shown below. From edefa50f18613599b92e2eb3e9556fbde220b360 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 19 Nov 2024 00:02:43 +0100 Subject: [PATCH 009/131] chore(http): Refresh headers docs (d-k) (#36075) * chore(http): Refresh headers docs d-k * chore(http): Refresh headers docs d-k * chore(http): Add glossary links to request and response header terms * etag - more layout fixes * expect-ct - add response header * expect - minor layout changes * if-unmodified-since layout * Apply suggestions from code review Co-authored-by: Hamish Willee * 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> * Update files/en-us/web/http/headers/date/index.md Co-authored-by: Hamish Willee * chore(http): Use code style for date format DLs * chore(http): Use nested DLs under directives * chore(http): Details about forbidden header names * chore(http): Changes following reviewer feedback * Update files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md --------- Co-authored-by: Hamish Willee Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../glossary/forbidden_header_name/index.md | 18 +++-- .../http_header_page_template/index.md | 23 ++++-- .../web/http/headers/accept-encoding/index.md | 2 +- files/en-us/web/http/headers/date/index.md | 72 ++++++++++--------- .../web/http/headers/device-memory/index.md | 24 +++---- files/en-us/web/http/headers/digest/index.md | 12 ++-- 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 | 31 ++++++-- files/en-us/web/http/headers/ect/index.md | 23 +++--- files/en-us/web/http/headers/etag/index.md | 61 ++++++---------- .../en-us/web/http/headers/expect-ct/index.md | 13 ++-- files/en-us/web/http/headers/expect/index.md | 41 +++++------ 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 | 19 +++-- .../en-us/web/http/headers/if-match/index.md | 20 +++--- .../http/headers/if-modified-since/index.md | 57 +++++++-------- .../web/http/headers/if-none-match/index.md | 29 ++++---- .../en-us/web/http/headers/if-range/index.md | 60 +++++++--------- .../http/headers/if-unmodified-since/index.md | 14 ++-- .../web/http/headers/keep-alive/index.md | 38 +++++----- 24 files changed, 349 insertions(+), 333 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/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..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 @@ -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 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 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 e7d1d56cbf5510b..56ba3b807a7a96d 100644 --- a/files/en-us/web/http/headers/date/index.md +++ b/files/en-us/web/http/headers/date/index.md @@ -7,20 +7,7 @@ browser-compat: http.headers.Date {{HTTPSidebar}} -The **`Date`** general HTTP 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: -> -> ```js -> fetch("https://httpbin.org/get", { -> headers: { -> Date: new Date().toUTCString(), -> }, -> }); -> ``` +The HTTP **`Date`** {{Glossary("request header", "request")}} and {{Glossary("response header")}} contains the date and time at which the message originated. @@ -33,7 +20,7 @@ at which the message originated. - +
{{Glossary("Forbidden header name")}}yesYes
@@ -46,29 +33,48 @@ 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). -- \ - - : 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". +- `` + - : 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. + - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time. ## 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 + + @@ -20,17 +25,11 @@ The **`Device-Memory`** [device client hint](/en-US/docs/Web/HTTP/Client_hints#d {{Glossary("Forbidden header name")}} - no + No -> [!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..783dbd9e9ffd0cb 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`** {{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. -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_ 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. @@ -30,11 +31,11 @@ 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")}} - 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..f366494bb2deef5 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) {{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")}}. @@ -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..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,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`** {{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. + +> [!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..a860ad2e3e0cfb4 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")}}. +> [!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")}}. + +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. @@ -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..a6d42d62973fdb4 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,12 @@ 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`** {{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). +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). @@ -24,7 +24,7 @@ request (i.e., a browser). - +
{{Glossary("Forbidden header name")}}noNo
@@ -37,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 ``` @@ -50,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/ect/index.md b/files/en-us/web/http/headers/ect/index.md index 5822e43691974c3..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,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`** {{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. + +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..a58d0c775680369 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) {{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)). -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,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. -- "\" - - : 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. + - : `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. For example, a wiki engine can use a hexadecimal hash of the documentation article content. ## Examples @@ -63,11 +57,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" @@ -86,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")}} `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 @@ -112,8 +97,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-ct/index.md b/files/en-us/web/http/headers/expect-ct/index.md index 460b793dc4a4dc9..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. @@ -36,7 +41,7 @@ CT requirements can be satisfied via any one of the following mechanisms: - +
{{Glossary("Forbidden header name")}}yesYes
diff --git a/files/en-us/web/http/headers/expect/index.md b/files/en-us/web/http/headers/expect/index.md index 69984b081fd0736..13bfbb99b2c9570 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`** {{Glossary("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. +None of the more common 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
@@ -49,16 +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")}} (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 @@ -68,8 +56,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..6d3f995b14119cc 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`** {{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. +> 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..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 **`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`** {{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. @@ -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..afc7dcdd0284b74 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`** {{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 (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..92a84b6bf0080ba 100644 --- a/files/en-us/web/http/headers/host/index.md +++ b/files/en-us/web/http/headers/host/index.md @@ -7,15 +7,12 @@ 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`** {{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")}} (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 +22,7 @@ message that lacks or contains more than one `Host` header field. - +
{{Glossary("Forbidden header name")}}yesYes
@@ -38,9 +35,9 @@ Host: : ## Directives -- \ - - : the domain name of the server (for virtual hosting). -- \ {{optional_inline}} +- `` + - : The domain name of the server (for virtual hosting). +- `` {{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..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,12 +7,11 @@ browser-compat: http.headers.If-Match {{HTTPSidebar}} -The **`If-Match`** HTTP request header makes a request conditional. +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. -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..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 @@ -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`** {{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 the 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). -- \ - - : 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` +- `` + - : 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 @@ -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..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 @@ -7,18 +7,22 @@ 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`** {{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. -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 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 {{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 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). @@ -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..876f8e6cfdc9412 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,13 @@ 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`** {{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, 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 +23,7 @@ has not been modified since the last fragment has been received. - +
{{Glossary("Forbidden header name")}}noNo
@@ -41,31 +37,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). -- \ - - : 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` +- `` + - : 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 ```http If-Range: Wed, 21 Oct 2015 07:28:00 GMT + +If-Range: "67ab43" ``` ## Specifications @@ -78,11 +75,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 008c9cabe2976cc..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 @@ -7,7 +7,7 @@ browser-compat: http.headers.If-Unmodified-Since {{HTTPSidebar}} -The HTTP **`If-Unmodified-Since`** {{glossary("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. @@ -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. 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..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,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`** {{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] -> 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,21 @@ 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 +65,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 6368e2b112a343fa00ae1a8cf51ceb0b0b845834 Mon Sep 17 00:00:00 2001 From: wbamberg Date: Mon, 18 Nov 2024 20:36:44 -0800 Subject: [PATCH 010/131] Update CSP source expression reference (#36792) * Add reference for source expressions * Document applicable source expression values for 'simple' fetch directives * Update source expression values for default-src, script* and style* * Update fenced-frame-src directive * Document secure upgrade behavior with 'self' * Delete old source values doc; update links * move glossary entry into body of text * Trusted types now how MDN link - fix * Rename fetch directive syntax section * Better names for hash and source expression sections * Document fallbacks in directive list --------- Co-authored-by: Hamish Willee --- files/en-us/_redirects.txt | 1 + .../content_security_policy/index.md | 2 +- .../content-security-policy/base-uri/index.md | 10 +- .../child-src/index.md | 6 +- .../connect-src/index.md | 6 +- .../default-src/index.md | 4 +- .../fenced-frame-src/index.md | 11 +- .../content-security-policy/font-src/index.md | 6 +- .../form-action/index.md | 10 +- .../frame-src/index.md | 6 +- .../content-security-policy/img-src/index.md | 6 +- .../headers/content-security-policy/index.md | 261 ++++++++++++++---- .../manifest-src/index.md | 6 +- .../media-src/index.md | 6 +- .../object-src/index.md | 6 +- .../prefetch-src/index.md | 6 +- .../script-src-attr/index.md | 6 +- .../script-src-elem/index.md | 4 +- .../script-src/index.md | 4 +- .../content-security-policy/sources/index.md | 102 ------- .../style-src-attr/index.md | 6 +- .../style-src-elem/index.md | 4 +- .../style-src/index.md | 13 +- .../worker-src/index.md | 6 +- 24 files changed, 276 insertions(+), 222 deletions(-) delete mode 100644 files/en-us/web/http/headers/content-security-policy/sources/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 8f5b52018becef4..e3e8cce2f4efcb9 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -12286,6 +12286,7 @@ /en-US/docs/Web/HTTP/Gecko_user_agent_string_reference /en-US/docs/Web/HTTP/Headers/User-Agent/Firefox /en-US/docs/Web/HTTP/HTTP_response_codes /en-US/docs/Web/HTTP/Status /en-US/docs/Web/HTTP/Headers/Cache-Disposition /en-US/docs/Web/HTTP/Headers/Content-Disposition +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources /en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directive_syntax /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/navigate-to /en-US/docs/Web/HTTP/Headers/Content-Security-Policy /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/referrer /en-US/docs/Web/HTTP/Headers/Referrer-Policy /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-sri-for /en-US/docs/Web/HTTP/Headers/Content-Security-Policy diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md index ea17687c2c766f3..a1b046a60c6dbf9 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md @@ -65,7 +65,7 @@ In Manifest V2, a source for a script directive is considered secure if it meets - Remote sources must not use wildcards for any domains in the [public suffix list](https://publicsuffix.org/list/) (so `*.co.uk` and `*.blogspot.com` are not allowed, although `*.foo.blogspot.com` is permitted). - All sources must specify a host. - The only permitted schemes for sources are `blob:`, `filesystem:`, `moz-extension:`, `https:`, and `wss:`. -- The only permitted [keywords](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources) are: `'none'`, `'self'`, `'unsafe-eval'`, and `'wasm-unsafe-eval'`. +- The only permitted [keywords](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directive_syntax) are: `'none'`, `'self'`, `'unsafe-eval'`, and `'wasm-unsafe-eval'`. ## object-src directive diff --git a/files/en-us/web/http/headers/content-security-policy/base-uri/index.md b/files/en-us/web/http/headers/content-security-policy/base-uri/index.md index 4ed60863edfd126..cc1f0010ad57906 100644 --- a/files/en-us/web/http/headers/content-security-policy/base-uri/index.md +++ b/files/en-us/web/http/headers/content-security-policy/base-uri/index.md @@ -39,13 +39,11 @@ This directive may have one of the following values: - : No base URI may be set using a `` element. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. A `` element may set a base URI if its value matches any of the given source expressions. + - : A space-separated list of _source expression_ values. A `` element may set a base URI if its value matches any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). However, only the following subset of those values apply to `base-uri`: - - - `` - - `` - - the keyword value `'self'`. + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/child-src/index.md b/files/en-us/web/http/headers/content-security-policy/child-src/index.md index 447a5c6640071cc..afdc5db088b6470 100644 --- a/files/en-us/web/http/headers/content-security-policy/child-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/child-src/index.md @@ -46,9 +46,11 @@ This directive may have one of the following values: - : No resources of this type may be loaded. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. + - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/connect-src/index.md b/files/en-us/web/http/headers/content-security-policy/connect-src/index.md index fee392fdafeb62f..f241f9980b50d95 100644 --- a/files/en-us/web/http/headers/content-security-policy/connect-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/connect-src/index.md @@ -54,9 +54,11 @@ This directive may have one of the following values: - : No resources of this type may be loaded. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. + - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/default-src/index.md b/files/en-us/web/http/headers/content-security-policy/default-src/index.md index 611d782fa9cf09d..f8b287a23276838 100644 --- a/files/en-us/web/http/headers/content-security-policy/default-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/default-src/index.md @@ -52,9 +52,7 @@ This directive may have one of the following values: - : No resources may be loaded. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Resources may be loaded if they match any of the given source expressions. - - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). + - : A space-separated list of _source expression_ values. Resources may be loaded if they match any of the given source expressions. For this directive, any of the source expression values listed in [Fetch directive syntax](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directive_syntax) are applicable. ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/fenced-frame-src/index.md b/files/en-us/web/http/headers/content-security-policy/fenced-frame-src/index.md index 11e8eea87b41e8c..606e07c35e1fd87 100644 --- a/files/en-us/web/http/headers/content-security-policy/fenced-frame-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/fenced-frame-src/index.md @@ -42,17 +42,12 @@ Content-Security-Policy: fenced-frame-src ; Content-Security-Policy: fenced-frame-src ; ``` -### Sources +A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. For this directive, the following source expression values are applicable: -``s for `fenced-frame-src` are more limited than for {{CSP("frame-src")}}. Only the following source expressions can be used: - -- The scheme-source `"https:"` -- The host-source `"https://*:*"` +- The [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) value `"https:"` +- The [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) value `"https:"` - The string `"*"` -> [!NOTE] -> See the full list of [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources). - ## Examples ### Violation cases diff --git a/files/en-us/web/http/headers/content-security-policy/font-src/index.md b/files/en-us/web/http/headers/content-security-policy/font-src/index.md index 9cd7ea7d0e3e208..447155713a63218 100644 --- a/files/en-us/web/http/headers/content-security-policy/font-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/font-src/index.md @@ -44,9 +44,11 @@ This directive may have one of the following values: - : No resources of this type may be loaded. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. + - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/form-action/index.md b/files/en-us/web/http/headers/content-security-policy/form-action/index.md index 053c4024e0398ef..31e4f7f8fa4481b 100644 --- a/files/en-us/web/http/headers/content-security-policy/form-action/index.md +++ b/files/en-us/web/http/headers/content-security-policy/form-action/index.md @@ -42,13 +42,11 @@ This directive may have one of the following values: - : No form submissions may be made. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Form submissions may be made to URLs that match any of the given source expressions. + - : A space-separated list of _source expression_ values. Form submissions may be made to URLs that match any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). However, only the following subset of those values apply to `form-action`: - - - `` - - `` - - the keyword value `'self'`. + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/frame-src/index.md b/files/en-us/web/http/headers/content-security-policy/frame-src/index.md index 1e8fa9b6a800751..0a9ffc7f4adbe8e 100644 --- a/files/en-us/web/http/headers/content-security-policy/frame-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/frame-src/index.md @@ -49,9 +49,11 @@ This directive may have one of the following values: - : No resources of this type may be loaded. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. + - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/img-src/index.md b/files/en-us/web/http/headers/content-security-policy/img-src/index.md index 42e6437d95ec196..bebb5d6c482fc04 100644 --- a/files/en-us/web/http/headers/content-security-policy/img-src/index.md +++ b/files/en-us/web/http/headers/content-security-policy/img-src/index.md @@ -42,9 +42,11 @@ This directive may have one of the following values: - : No resources of this type may be loaded. The single quotes are mandatory. - `` - - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. + - : A space-separated list of _source expression_ values. Resources of this type may be loaded if they match any of the given source expressions. For this directive, the following source expression values are applicable: - Source expressions are specified as keyword values or URL patterns: the syntax for each source expression is given in [CSP Source Values](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources). + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) + - [``](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#scheme-source) + - [`'self'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#self) ## Examples diff --git a/files/en-us/web/http/headers/content-security-policy/index.md b/files/en-us/web/http/headers/content-security-policy/index.md index 3c3e8babdbc7424..2bfdd877f718cd9 100644 --- a/files/en-us/web/http/headers/content-security-policy/index.md +++ b/files/en-us/web/http/headers/content-security-policy/index.md @@ -7,11 +7,8 @@ browser-compat: http.headers.Content-Security-Policy {{HTTPSidebar}} -The HTTP **`Content-Security-Policy`** response header allows -website administrators to control resources the user agent is allowed to load for a -given page. With a few exceptions, policies mostly involve specifying server origins and -script endpoints. This helps guard against cross-site scripting attacks -({{Glossary("Cross-site_scripting")}}). +The HTTP **`Content-Security-Policy`** response header allows website administrators to control resources the user agent is allowed to load for a given page. With a few exceptions, policies mostly involve specifying server origins and script endpoints. +This helps guard against {{Glossary("cross-site scripting")}} attacks. For more information, see the introductory article on [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP). @@ -41,22 +38,23 @@ where `` consists of: ### Fetch directives -{{Glossary("Fetch directive","Fetch directives")}} control the locations from which certain resource types may be loaded. +Fetch directives control the locations from which certain resource types may be loaded. - {{CSP("child-src")}} - : Defines the valid sources for [web workers](/en-US/docs/Web/API/Web_Workers_API) and nested browsing contexts loaded using elements such as {{HTMLElement("frame")}} and {{HTMLElement("iframe")}}. - > [!WARNING] - > Instead of **`child-src`**, - > if you want to regulate nested browsing contexts and workers, - > you should use the {{CSP("frame-src")}} and {{CSP("worker-src")}} directives, respectively. + [Fallback](#fallbacks) for `frame-src` and `worker-src`. - {{CSP("connect-src")}} - : Restricts the URLs which can be loaded using script interfaces. - {{CSP("default-src")}} + - : Serves as a fallback for the other {{Glossary("Fetch directive", "fetch directives")}}. + + [Fallback](#fallbacks) for all other fetch directives. + - {{CSP("fenced-frame-src")}} {{experimental_inline}} - : Specifies valid sources for nested browsing contexts loaded into {{HTMLElement("fencedframe")}} elements. - {{CSP("font-src")}} @@ -72,27 +70,25 @@ where `` consists of: - : Specifies valid sources for loading media using the {{HTMLElement("audio")}}, {{HTMLElement("video")}} and {{HTMLElement("track")}} elements. - {{CSP("object-src")}} - - : Specifies valid sources for the {{HTMLElement("object")}} and {{HTMLElement("embed")}} elements. - - > [!NOTE] - > Elements controlled by `object-src` are perhaps - > coincidentally considered legacy HTML elements and are not receiving new standardized - > features (such as the security attributes `sandbox` or `allow` - > for `