diff --git a/docs/fetch-later-api.md b/docs/fetch-later-api.md index 9314160..264981d 100644 --- a/docs/fetch-later-api.md +++ b/docs/fetch-later-api.md @@ -25,7 +25,7 @@ Note that from the point of view of the API user, the exact send time is unknown ### Constraints * A deferred fetch request body, if exists, has to be a byte sequence. Streaming requests are not allowed. -* A new permissions policy `deferred-fetch` is defined to control the feature availability and to delegate request quota. See [Permissions Policy and Quota](#permissions-policy-and-quota). +* A new permissions policy `deferred-fetch` is defined to control the feature availability and to delegate request quota. See [Quota and permissions policy](#quota-and-permissions-policy). ## Key scenarios @@ -144,32 +144,27 @@ class PendingBeacon { } ``` -## Permissions Policy and Quota +## Quota and Permissions Policy -This section summarizes the discussion in [#87], and is still subject to change. +### Overview -[#87]: https://github.com/WICG/pending-beacon/issues/87#issuecomment-1985358609 - -### Permissions Policy: `deferred-fetch` - -* Define a new Permissions Policy `deferred-fetch`, default to `self`. -* Every top-level document has a quota of **640KB** for all fetchLater request bodies from its descendants and itself. -* Every reporting origin within a top-level document has a quota of **64KB** across all fetchLater request bodies the document can issue. -* A cross-origin child document is only allowed to make fetchLater requests if its origin is allowed by its top-level document’s `deferred-fetch` policy. - -Both quotas may subject to change if we have more developer feedback. +Deferred fetches are different from normal fetches, due to the fact that they are batched and sent once the tab is closed, and at that point the user has no way to abort them. +To avoid situations where documents abuse this bandwidth to send unlimited amounts of data over the network, the overall quota for a top level document is capped at 640KB (which should be enough for anyone). +Since this cap makes deferred fetch bandwidth a scarce resource which needs to be shared between multiple reporting origins (e.g. several RUM libraries) and also across subframes of multiple origins, the platform +provides a reasonable default division of this quota, and also provides knobs, in the form of permission policies, to allow dividing it in a different way when desired. ### Default Behavior -Without any configuration, a top-level document can make an unlimited number of fetchLater requests, -but the total of their body sizes of the pending fetchLater requests must <= 64KB for a single reporting origin, and <= 640KB across all reporting origins. +Without any configuration, a top-level document and its same-origin descendant subframes can invoke an unlimited number of `fetchLater` requests, but with the following limitations: +1. The total bandwidth taken by these requests (counting the URL, custom headers and POST body size) must not exceed 64KB for each reporting origin +2. The total bandwidth for all the reporting origins must not exceed 512KB. ```html