From 1787b3c5ba0301e77410370edef1f04e7ecf3d72 Mon Sep 17 00:00:00 2001 From: wbamberg Date: Fri, 1 Dec 2023 17:31:14 -0800 Subject: [PATCH] Add page for Origin-Agent-Cluster --- .../headers/origin-agent-cluster/index.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 files/en-us/web/http/headers/origin-agent-cluster/index.md diff --git a/files/en-us/web/http/headers/origin-agent-cluster/index.md b/files/en-us/web/http/headers/origin-agent-cluster/index.md new file mode 100644 index 000000000000000..1c86f6f7c44f94a --- /dev/null +++ b/files/en-us/web/http/headers/origin-agent-cluster/index.md @@ -0,0 +1,88 @@ +--- +title: Origin-Agent-Cluster +slug: Web/HTTP/Headers/Origin-Agent-Cluster +page-type: http-header +status: + - experimental +browser-compat: http.headers.Origin-Agent-Cluster +--- + +{{HTTPSidebar}}{{SeeCompatTable}} + +The **`Origin-Agent-Cluster`** HTTP response header is used to request that the associated {{domxref("Document")}} should be placed in an _origin-keyed agent cluster_. This means that operating system resources (for example, the operating system process) used to evaluate the document should be shared only with other documents from the same {{glossary("origin")}}. + +The effect of this is that a resource-intensive document will be less likely to degrade the performance of documents from other origins. + +Modern web browsers have a multiprocess architecture in which pages from different origins can run in different operating system processes. This is important for performance, because it means that a resource-intensive page will not have as much of an impact on other pages that the user has open. + +However, browsers can't as a general rule run {{glossary("site", "same-site")}}, {{glossary("origin", "cross-origin")}} pages in different processes, because of certain DOM APIs that depend on same-site, cross-origin communication. For example, by default, pages from the following two origins will share the same operating system resources: + +```plain +https://apples.example.org +https://oranges.example.org +``` + +By setting the `Origin-Agent-Cluster` header, a page can request that the browser allocate dedicated resources to this origin that are not shared with any other origins. + +The browser is not required to honor the request. If it does, the {{domxref("Window.originAgentCluster")}} property returns `true`, and the window is not able to do the following things, which all depend on same-site, cross-origin communication: + +- Use {{domxref("Document.domain")}}. +- Send [`WebAssembly.Module`](/en-US/docs/WebAssembly/JavaScript_interface/Module) objects to other same-site cross-origin pages using {{domxref("Window.postMessage()", "postMessage()")}}. +- Send {{jsxref("SharedArrayBuffer")}} or [`WebAssembly.Memory`](/en-US/docs/WebAssembly/JavaScript_interface/Memory) objects to other same-site cross-origin pages. + +Origin-keyed agent clusters should not be viewed as a security feature: browsers may ignore the request for various reasons, or choose to implement it in a way that does not provide memory protection (for example, using separate threads instead of separate processes). Instead, this feature is a hint that the user experience would be improved if this origin were allocated dedicated resources. + +For example, suppose your site includes a page from one origin that embeds a same-site, cross-origin iframe which runs a resource-intensive game. By setting `Origin-Agent-Cluster` on the document in the iframe, you can prevent the game from affecting the performance of the main page. + +The browser will ensure that all pages from a given origin are either origin-keyed or they are not. This means that: + +- If the first page from an origin does not set the header, then no other pages from that origin will be origin-keyed, even if those other pages do set the header. +- If the first page from an origin sets the header and is made origin-keyed, then all other pages from that origin will be origin-keyed whether they ask for it or not. + +To avoid this kind if unpredictable situation, you should be sure to set this header for all pages from a given origin, or none of them. + + + + + + + + + + + + +
Header type{{Glossary("Response header")}}
{{Glossary("Forbidden header name")}}no
+ +## Syntax + +```http +Origin-Agent-Cluster: +``` + +### Directives + +- `` + + - : `?1` indicates that the user-agent prefers a mobile experience (true). + + `?0` indicates that user-agent does not prefer a mobile experience (false). + +## Examples + +```http +Origin-Agent-Cluster: ?1 +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("Window.originAgentCluster")}} +- [Requesting performance isolation with the Origin-Agent-Cluster header](https://web.dev/articles/origin-agent-cluster) on web.dev