|
| 1 | +--- |
| 2 | +title: fetchLater() quotas |
| 3 | +slug: Web/API/fetchLater_API/fetchLater_quotas |
| 4 | +page-type: guide |
| 5 | +status: |
| 6 | + - experimental |
| 7 | +browser-compat: |
| 8 | + - http.headers.Permissions-Policy.deferred-fetch |
| 9 | + - http.headers.Permissions-Policy.deferred-fetch-minimal |
| 10 | +--- |
| 11 | + |
| 12 | +{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}} |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +## Overview |
| 19 | + |
| 20 | +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: |
| 21 | + |
| 22 | +- The 512KiB top-level quota by default is for any `fetchLater()` requests made from the top-level document and direct subframes using that origin. |
| 23 | +- The 128KiB shared quota by default is for any `fetchLater()` requests made in cross-origin subframes (for exmaple, `<iframe>`s, `<object>`s, `<embed>`s, and`<frame>`s). |
| 24 | + |
| 25 | +`fetchLater()` requests can be made to any URL and are not restricted to the same origin as the document or the subframe, so it's important to differentiate between requests made in the top-level document content (whether to first-party or third-party origins) and those made in subframes. |
| 26 | + |
| 27 | +For example, if a top-level `a.com` document includes a `<script>` that makes a `fetchLater()` request to `analytics.example.com`, this request would be bound by the top-level 512KiB limit. Alternatively, if the top-level document embeds an `<iframe>` with a source of `analytics.example.com` that makes a `fetchLater()` request, that request would be bound by the 128KiB limit. |
| 28 | + |
| 29 | +## Quota limits by reporting origin and subframe |
| 30 | + |
| 31 | +Only 64KiB of the top-level 512KiB quota can be used concurrently for the same reporting origin (the request URL's origin). This prevents third-party libraries from reserving quota opportunistically before they have data to send. |
| 32 | + |
| 33 | +Each cross-origin subframe gets an 8KiB quota out of the shared 128KiB quota by default, allocated when the subframe is added to the DOM (whether `fetchLater()` will be used in that subframe or not). This means that, in general, only the first 16 cross-origin subframes added to a page can use `fetchLater()` as they will use up the 128KiB quota. |
| 34 | + |
| 35 | +## Increasing subframe quotas by sharing the top-level quota |
| 36 | + |
| 37 | +The top-level origin can give selected cross-origin subframes an increased quota of 64KiB, taking it out of the larger top-level 512KiB limit. It does this by listing those origins in the {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} Permissions Policy directive. This is allocated when the subframe is added to the DOM, leaving less quota for the top-level document and direct same-origin subframes. Multiple same-origin subdomains can each get a 64KiB quota. |
| 38 | + |
| 39 | +## Restricting the shared quota |
| 40 | + |
| 41 | +The top-level origin can also restrict the 128KiB shared quota to named cross-origin subframes by listing those origins in the {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} Permissions Policy. It can also revoke the entire 128KiB default subframe quota and instead keep the full 640KiB quota for itself and any named `deferred-fetch` cross-origins by setting the {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} Permissions Policy to `()`. |
| 42 | + |
| 43 | +## Delegating quotes to subframes of subframes |
| 44 | + |
| 45 | +By default, subframes of subframes are not allocated a quota and so cannot use `fetchLater()`. Subframes allocated the increased 64KiB quota can delegate the full 64KiB quota to further subframes and allow them to use `fetchLater()` by setting their own `deferred-fetch` Permissions Policy. They can only delegate their full quota to further subframes, not parts of it, and cannot specify new quotas. Subframes using the minimal 8KiB quota cannot delegate quotas to subframes. To be delegated quota, sub-subframes must be included in both the top-level and the subframe `deferred-fetch` {{httpheader('Permissions-Policy')}} directives. |
| 46 | + |
| 47 | +## When quotas are exceeded |
| 48 | + |
| 49 | +When quotas are exceeded, a `QuotaExceededError` is thrown when the {{domxref('Window.fetchLater()','fetchLater()')}} method is called to initiate the deferred request. |
| 50 | + |
| 51 | +Permissions Policy checks are not discernable from quota checks. Calling `fetchLater()` will throw a `QuotaExceededError` both if the quota is actually exceeded and if the quota was restricted for that origin via a Permissions Policy. |
| 52 | + |
| 53 | +Callers of `fetchLater()` should be defensive and catch `QuotaExceededError` errors in almost all cases, especially if they embed third-party JavaScript. |
| 54 | + |
| 55 | +## Examples |
| 56 | + |
| 57 | +### Using up the minimal quota |
| 58 | + |
| 59 | +```http |
| 60 | +Permissions-Policy: deferred-fetch=(self "https://b.com") |
| 61 | +``` |
| 62 | + |
| 63 | +1. A `<iframe src="https://b.com/page">` receives 64KiB upon being added to the top-level document, from the top-level's 512KiB limit. |
| 64 | +2. A `<iframe src="https://c.com/page">` is not listed and so receives 8KiB upon being added to the top-level document from the 128KiB shared limit. |
| 65 | +3. 15 more cross-origin iframes would each receive 8KiB upon being added to the top-level document (similar to `c.com`). |
| 66 | +4. The next cross-origin iframe would not be granted any quota. |
| 67 | +5. If one of the cross-origin iframes is removed, its deferred fetches will be sent. |
| 68 | +6. The next cross-origin iframe _would_ receive an 8KiB quota, as there is quota available again. |
| 69 | + |
| 70 | +### RevokiRestricting the minimal quota to named origins |
| 71 | + |
| 72 | +```http |
| 73 | +Permissions-Policy: deferred-fetch-minimal=("https://b.com") |
| 74 | +``` |
| 75 | + |
| 76 | +1. `<iframe src="https://b.com/page">` receives 8KiB upon being added to the top-level document. |
| 77 | +2. `<iframe src="https://c.com/page">` receives no quota upon being added to the top-level document. |
| 78 | +3. The top-level document and its same-origin descendants can use up to 512KiB. |
| 79 | + |
| 80 | +### Revoking the minimal quota altogether with top-level exceptions |
| 81 | + |
| 82 | +```http |
| 83 | +Permissions-Policy: deferred-fetch=(self "https://b.com") |
| 84 | +Permissions-Policy: deferred-fetch-minimal=() |
| 85 | +``` |
| 86 | + |
| 87 | +1. `<iframe src="https://b.com/page">` receives 64KiB upon being added to the top-level document. |
| 88 | +2. `<iframe src="https://c.com/page">` receives no quota upon being added to the top-level document. |
| 89 | +3. The top-level document and its same-origin descendants can use up to the full 640KiB but that is reduced to 574KiB if a `b.com` subframe is created (or even less if multiple `b.com` subframes are created, each of which will be allocated a 64KiB quota). |
| 90 | + |
| 91 | +### Revoking the minimal quota altogether with no exceptions |
| 92 | + |
| 93 | +```http |
| 94 | +Permissions-Policy: deferred-fetch-minimal=() |
| 95 | +``` |
| 96 | + |
| 97 | +1. The top-level document and its same-origin descendants can use up the full 640KiB. |
| 98 | +2. Subframes are not allocated any quota and cannot use `fetchLater()`. |
| 99 | + |
| 100 | +### Same-origin subframes share quota with the top-level and can delegate to subframes |
| 101 | + |
| 102 | +Assuming a top-level document on `a.com`, which embeds a subframe of `a.com`, which embeds a subframe of `b.com`, and no explicit Permission Policies. |
| 103 | + |
| 104 | +1. The top-level document of `a.com` has the default 512KiB quota. |
| 105 | +2. `<iframe src="https://a.com/embed">` shares the 512KiB quota upon being added to the top-level document. |
| 106 | +3. `<iframe src="https://b.com/embed">` receives an 8KiB quotaupon being added to the top-level document. |
| 107 | + |
| 108 | +### Same-origin subframes canot share quota with the top-level when separated by a cross-origin subframe |
| 109 | + |
| 110 | +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which embeds a subframe of `<iframe src="https://a.com/embed">`, and no explicit Permission Policies. |
| 111 | + |
| 112 | +1. The top-level document of `a.com` has the default 512KiB quota. |
| 113 | +2. `<iframe src="https://b.com/">` shares the 8KiB quota. |
| 114 | +3. `<iframe src="https://a.com/embed">` receives no quota; even though this is same-origin with the top origin, it is separated by a cross-origin. |
| 115 | + |
| 116 | +### Secondary subframes of subframes do not get quota by default |
| 117 | + |
| 118 | +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which embeds a `<iframe src="https://c.com/">`, and no explicit Permission Policies. |
| 119 | + |
| 120 | +1. The top-level frame of `a.com` has the default 512KiB quota. |
| 121 | +2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota. |
| 122 | +3. `<iframe src="https://c.com/">` receives no quota. |
| 123 | + |
| 124 | +### Granting the full quota to a further subframe |
| 125 | + |
| 126 | +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which embeds a `<iframe src="https://c.com/">`. |
| 127 | + |
| 128 | +Assuming that `a.com` has the following Permissions Policy: |
| 129 | + |
| 130 | +```http |
| 131 | +Permissions-Policy: deferred-fetch=("https://c.com" "https://c.com") |
| 132 | +``` |
| 133 | + |
| 134 | +And, assuming that `b.com` has the following Permissions Policy: |
| 135 | + |
| 136 | +```http |
| 137 | +Permissions-Policy: deferred-fetch=("https://c.com") |
| 138 | +``` |
| 139 | + |
| 140 | +1. The top-level frame of `a.com` has the default 512KiB quota. |
| 141 | +2. `<iframe src="https://b.com/">` receives 64KiB of the default quota. |
| 142 | +3. `<iframe src="https://b.com/">` delegates its full quota of 8KiB to `c.com`. `b.com` cannot use `fetchLater()`. |
| 143 | +4. `<iframe src="https://c.com/">` receives 8KiB of quota. |
| 144 | + |
| 145 | +### Redirects do not transfer quota |
| 146 | + |
| 147 | +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which redirects to `c.com`, and no explicit top-level Permission Policies. |
| 148 | + |
| 149 | +1. The top-level frame of `a.com` has the default 512KiB quota. |
| 150 | +2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota. |
| 151 | +3. The 8KiB is not transferred to `c.com` when `<iframe src="https://b.com/">` redirects to there, but the 8KiB is not released. |
| 152 | + |
| 153 | +### Redirects of subframes back to the top-level origin allow use of the top-level quota |
| 154 | + |
| 155 | +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which redirects to `a.com`, and no explicit top-level Permission Policies. |
| 156 | + |
| 157 | +1. The top-level frame of `a.com` has the default 512KiB quota. |
| 158 | +2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota. |
| 159 | +3. The 8KiB is not transferred to `a.com` when `<iframe src="https://b.com/">` redirects to there, but it is able to share the full top-level quota again, and the 8KiB is released. |
| 160 | + |
| 161 | +### Examples which throw a `QuotaExceededError` |
| 162 | + |
| 163 | +```js |
| 164 | +// Maximum of 64KiB per origin |
| 165 | +fetchLater(a_72_kb_url); |
| 166 | + |
| 167 | +// Maximum of 64KiB per origin including headers |
| 168 | +fetchLater("https://origin.example.com", { headers: headers_exceeding_64kb }); |
| 169 | + |
| 170 | +// Maximum of 64KiB per origin including body and headers |
| 171 | +fetchLater(a_32_kib_url, { headers: headers_exceeding_32kib }); |
| 172 | + |
| 173 | +// Maximum of 64KiB per origin including body |
| 174 | +fetchLater("https://origin.example.com", { |
| 175 | + method: "POST", |
| 176 | + body: body_exceeding_64_kib, |
| 177 | +}); |
| 178 | + |
| 179 | +// Maximum of 64KiB per origin including body and automatically added headers |
| 180 | +fetchLater(a_62_kib_url /* with a 3kb referrer */); |
| 181 | +``` |
| 182 | + |
| 183 | +### Examples which eventually throw a `QuotaExceededError` |
| 184 | + |
| 185 | +In the following sequence, contained in the top-level document, the first two requests would succeed, but the third would throw. That's because, even though the overall 640KiB quota was not exceeded, the third request exceeds the reporting-origin quota for `https://a.example.com` and would throw. |
| 186 | + |
| 187 | +```js |
| 188 | +fetchLater("https://a.example.com", { method: "POST", body: a_40kb_body }); |
| 189 | +fetchLater("https://b.example.com", { method: "POST", body: a_40kb_body }); |
| 190 | +fetchLater("https://a.example.com", { method: "POST", body: a_40kb_body }); |
| 191 | +``` |
| 192 | + |
| 193 | +## Specifications |
| 194 | + |
| 195 | +{{Specifications}} |
| 196 | + |
| 197 | +## Browser compatibility |
| 198 | + |
| 199 | +{{Compat}} |
| 200 | + |
| 201 | +## See also |
| 202 | + |
| 203 | +- [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments