Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[fetch-later] Add P&S considerations into explainer #86

Merged
merged 3 commits into from
Nov 13, 2023
Merged

[fetch-later] Add P&S considerations into explainer #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
56ec024
[fetch-later] Add P&S considerations into explainer
mingyc Nov 13, 2023
47d7bf8
Fixed broken link
mingyc Nov 13, 2023
c27111a
Address MD linter
mingyc Nov 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions docs/fetch-later-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,22 @@

*This document is an explainer for fetchLater() API. It is evolved from a series of [discussions and concerns](https://github.com/WICG/pending-beacon/issues/70) around the experimental PendingBeacon API and the draft PendingRequest API.*

[Draft Specification](https://whatpr.org/fetch/1647/9ca4bda...37a66c9.html)
* [Specification PR](https://github.com/whatwg/fetch/pull/1647)
* [Draft Specification](https://whatpr.org/fetch/1647/9ca4bda...37a66c9.html)

## Motivation

See [Motivation - Pending Beacon API](../README.md#motivation).

## Overview

`fetchLater()` is a JavaScript API to request a deferred fetch. Once requested, the deffered request is queued by the browser, and will be invoked in one of the following scenarios:

* The document is destroyed.
* After a user-specified time, even if the document is in bfcache.
* Browser decides its time to send it.

The API returns a `FetchLaterResult` that contains a boolean field `activated` that may be updated to tell whether the deferred request has been sent out or not.
The API returns a `FetchLaterResult` that contains a read-only boolean field `activated` that may be updated by Browser to tell whether the deferred request has been sent out or not.
On successful sending, the whole response will be ignored, including body and headers. Nothing at all should be processed or updated, as the page is already gone.

Note that from the point of view of the API user, the exact send time is unknown.
Expand Down Expand Up @@ -138,6 +144,31 @@ class PendingBeacon {
}
```

## Security and Privacy

For a high-level overview, see [Self-Review Questionnaire: Security and Privacy](security-privacy-questionnaire.md).

This design has no impact on the existing fetch API.
However, the following security & privacy requirements have been discussed on GitHub and are important to follow:

### Security Considerations

* Deferred requests must be sent over HTTPS. See [security review feedback #27][#27].

[#27]: https://github.com/WICG/pending-beacon/issues/27

### Privacy Considerations

* Deferred requests can only be sent after the page becomes inactive, i.e. bfcached, if BackgroundSync permission is enabled for the Origin of the page. See [privacy review feedback #30][#30].

### Implementation-Specific Considerations

Implementation-specific considerations are not listed in this explainer.
Please refer to each browser implementation design for more details:

* [Chromium](https://docs.google.com/document/d/1U8XSnICPY3j-fjzG35UVm6zjwL6LvX6ETU3T8WrzLyQ/edit#heading=h.kztg1uvdyoki)


## Alternatives Considered

### 1. BackgroundSync API
Expand Down
17 changes: 8 additions & 9 deletions docs/security-privacy-questionnaire.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# [Self-Review Questionnaire: Security and Privacy][self-review]

This questionnaire covers the Pending Beacon API [explainer], based on the [W3C TAG Self-Review Questionnaire: Security and Privacy][self-review].
This questionnaire covers the `FetchLater API` [explainer], based on the [W3C TAG Self-Review Questionnaire: Security and Privacy][self-review].

1. What information does this feature expose, and for what purposes?
> The API intends to provide a reliable way for a document to send data to the target URL on document discard, or sometimes later after the document entering bfcache (becoming non-"fully active"), by making the user agent process the "send" requests queued by calling the API.
>
> The user agent should not expose the queued requests to new network providers after users navigating away from the document where the requests were queued.
> The user agent should not expose the queued requests to new network providers after users navigating away from the document where the requests were queued without user permission.
>
> Users can disallow the "sending on document discard" behavior by disabling BackgroundSync for an origin.
> Users can disallow the "sending after navigating away" behavior by disabling BackgroundSync for an origin.
>
> The API only sends requests in CORS mode with Same-Origin credentials mode.

Expand Down Expand Up @@ -43,7 +43,7 @@ This questionnaire covers the Pending Beacon API [explainer], based on the [W3C
> 2. Queued requests persist across browsing session if ["Crash Recovery"][crash-recovery] is supported.
> We are still unsure how to address privacy concern for this, so it's not specified yet.
>
> Note: The API provides a way to queue HTTP requests on a document which will be send by the user agent sometimes later, but before the document is discarded/browsing session ends if without "Crash Recovery".
> Note: The API provides a way to queue HTTPS requests on a document which will be send by the user agent sometimes later, but before the document is discarded/browsing session ends if without "Crash Recovery".

6. Do the features in your specification expose information about the underlying platform to origins?

Expand Down Expand Up @@ -76,7 +76,6 @@ This questionnaire covers the Pending Beacon API [explainer], based on the [W3C
13. How does this specification distinguish between behavior in first-party and third-party contexts?

> Both 1st party and 3rd party can use the API.
> But the API only sends requests in CORS mode with Same-Origin credentials mode.

14. How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode?

Expand All @@ -93,11 +92,11 @@ This questionnaire covers the Pending Beacon API [explainer], based on the [W3C

17. How does your feature handle non-"fully active" documents?

> The API provides some mechanism for users to specify when to send the queued requests after the document becomes non-"fully active".
> The API provides some mechanism for users to specify when to send the queued requests after custom time, even if the document is non-"fully active" at the specified time.
>
> The data of the queued requests should only come from the API calls when the document is still active. If the document transits from non-"fully active" to fully active again, the API can continue to accumulate more data from the API calls in the document.
> The data of the queued requests should only come from the API calls when the document is still active. If the document transits from non-"fully active" to fully active again, the API can continue to be pending, and potentially be aborted by uers from the API calls in the document.
>
> If the network provider changes after the document becomes non-"fully active", the user agent should not expose the queued requests to the new network provider.
> If BackgroundSync permission is not enabled for the Origin of the document, the user agent should not allow the queued requests after the document becomes non-"fully active", i.e. they should all be sent out on navigating away.
>
> The user agent sends out all queued requests if a non-"fully active" document gets unloaded (discard).

Expand All @@ -106,5 +105,5 @@ This questionnaire covers the Pending Beacon API [explainer], based on the [W3C
> How long can a request be queued on a document by this feature?

[self-review]: https://w3ctag.github.io/security-questionnaire/
[explainer]: https://github.com/WICG/pending-beacon/blob/main/README.md
[explainer]: https://github.com/WICG/pending-beacon/blob/main/docs/fetch-later-api.md
[crash-recovery]: https://github.com/WICG/pending-beacon/issues/34