diff --git a/files/en-us/web/api/deferredrequestinit/index.md b/files/en-us/web/api/deferredrequestinit/index.md new file mode 100644 index 000000000000000..1ba560bbc7fef34 --- /dev/null +++ b/files/en-us/web/api/deferredrequestinit/index.md @@ -0,0 +1,63 @@ +--- +title: DeferredRequestInit +slug: Web/API/DeferredRequestInit +page-type: web-api-interface +status: + - experimental +browser-compat: api.Window.fetchLater +--- + +{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}} + +The **`DeferredRequestInit`** dictionary of the [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) represents the set of options that can be used to configure a deferred fetch request. + +The `DeferredRequestInit` object is passed directly into the {{domxref("window.fetchLater()")}} function call as the second argument. + +## Instance properties + +This dictionary extends the {{domxref("RequestInit")}} dictionary with the addition of the following properties: + +- `activateAfter` {{optional_inline}} + + - : A {{ domxref("DOMHighResTimeStamp") }} indicating a timeout in milliseconds after which the fetch request should be sent. The fetch can be sent earlier on navigating away. The _actual_ sending time is unknown, as the browser may wait for a longer or shorter time, for example, to optimize the batching of deferred fetches. If the `activateAfter` property is not provided, the deferred fetch waits until the end of the page visit (including entering the [bfcache](/en-US/docs/Glossary/bfcache)). + +### Exceptions + +- `RangeError` {{domxref("DOMException")}} + - : Raised when a negative `activateAfter` is provided. + +## Examples + +### Defer a `GET` request until the page is destroyed or enters the bfcache + +In this example, no `DeferredRequestInit` object is provided and no timeout is used: + +```js +fetchLater("/send_beacon"); +``` + +### Defer a `POST` request for around 1 minute + +In this example we create a {{domxref("Request")}}, and provide an `activateAfter` value to delay sending the request for 60,000 milliseconds (or one minute): + +```js +fetchLater({ + url: "/send_beacon" + method: "POST" + body: getBeaconData(), +}, {activateAfter: 60000 /* 1 minute */}); +``` + +> [!NOTE] +> The actual sending time is unknown, as the browser may wait for a longer or shorter period of time, for example to optimize batching of deferred fetches. + +## Specifications + +{{Specifications}} + +## See also + +- [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) +- [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) +- [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/fetch_api/index.md b/files/en-us/web/api/fetch_api/index.md index f4fd805c1be2de6..bfb555c00bfc853 100644 --- a/files/en-us/web/api/fetch_api/index.md +++ b/files/en-us/web/api/fetch_api/index.md @@ -23,7 +23,7 @@ You can create a request and response directly using the {{DOMxRef("Request.Requ Find out more about using the Fetch API features in [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch). -## Fetch Interfaces +## Interfaces - {{domxref("Window.fetch()")}} and {{domxref("WorkerGlobalScope.fetch()")}} - : The `fetch()` method used to fetch a resource. diff --git a/files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md b/files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md new file mode 100644 index 000000000000000..f382c5431d636f0 --- /dev/null +++ b/files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md @@ -0,0 +1,203 @@ +--- +title: fetchLater() quotas +slug: Web/API/fetchLater_API/fetchLater_quotas +page-type: guide +status: + - experimental +browser-compat: + - http.headers.Permissions-Policy.deferred-fetch + - http.headers.Permissions-Policy.deferred-fetch-minimal +--- + +{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}} + +Deferred [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) fetches are batched and sent once the tab is closed. At this point, there is no way for the user to abort them. To avoid situations where documents abuse this bandwidth to send unlimited amounts of data over the network the API sets quotas on how much data can be deferred to be sent later. + +These quotas can be managed through {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} and {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directives. + +## Overview + +The overall quota for `fetchLater()` is 640KiB per document. By default, this is divided into a 512KiB top-level quota and a 128KiB shared quota: + +- The 512KiB top-level quota by default is for any `fetchLater()` requests made from the top-level document and direct subframes using that origin. +- The 128KiB shared quota by default is for any `fetchLater()` requests made in cross-origin subframes (for exmaple, `