Web Periodic Background Synchronization

1. Introduction

This section is non-normative.

Web Applications often run in environments with unreliable networks (e.g., mobile phones) and unknown lifetimes (the browser might be killed or the user might navigate away). This makes it difficult for web apps to keep their content and state in sync with servers.

This API is intended to reduce the time between content creation and content synchronization between the servers and the web app. It does so by letting the web app register an intent to periodically synchronize state and data, with a minimum interval it wishes to do so at. Through a service worker event, the user agent then periodically lets the web app download network resources and update state.

As this API relies on service workers, functionality provided by this API is only available in a secure context.

1.1. Example

async function registerPeriodicNewsCheck() {
  const registration = await navigator.serviceWorker.ready;
  try {
    await registration.periodicSync.register('fetch-news', {
      minInterval: 24 * 60 * 60 * 1000,
    });
  } catch {
    console.log('Periodic Sync could not be registered!');
  }
}

Reacting to a periodicsync event within a service worker:

self.addEventListener('periodicsync', event => {
  event.waitUntil(fetchAndCacheLatestNews());
});

In the above example fetchAndCacheLatestNews is a developer-defined function is a developer-defined function that fetches the latest news articles from a server and stores them locally, for example using the Cache API, for offline consumption.

2. Concepts

When a periodicsync event is fired for a periodic sync registration registration, it is considered to run in the background if no service worker clients whose frame type is "top-level", "auxiliary" or "nested" exist for the origin of the service worker registration associated with registration.

3. Extensions to service worker registration

• Active periodic sync registrations (a map), where each key is a DOMString, and each item is a periodic sync registration.

• Periodic sync processing queue, initially the result of starting a new parallel queue.

4. Constructs

4.1. Periodic sync registration

4.2. Periodic Sync Scheduler

The effective minimum sync interval for origin origin (an origin), is the minimum periodic sync interval for any origin + some user agent defined amount for the origin (which may be Infinity). The user agent defined amount MUST be used to mitigate the concerns raised in § 5 Privacy Considerations, § 6 Security Considerations and § 7 Resource Usage.

Note: The user agent defined amount can be based on the amount of engagement the user has with the origin. This value can be different each time effective minimum sync interval for origin is called. No periodicsync events will fire for a particular origin if the last value returned by effective minimum sync interval for origin is Infinity.

The scheduler processes periodic sync registrations.

Note: Browsers may suspend this processing loop when there are no active periodic sync registrations to conserve resources.

4.3. Constants

• minimum periodic sync interval for any origin, an unsigned long long, that represents the minimum gap between periodicsync events for any given origin in milliseconds, and,

• minimum periodic sync interval across origins, an unsigned long long, that represents the minimum gap between periodicsync events across all origins in milliseconds.

These constants are used to mitigate the concerns raised in § 5 Privacy Considerations, § 6 Security Considerations and § 7 Resource Usage.

minimum periodic sync interval across origins MUST be greater than or equal to minimum periodic sync interval for any origin. minimum periodic sync interval across origins SHOULD be greater than or equal to 43200000, which is twelve hours in milliseconds.

Note: A minimum value of 43200000 (which is twelve hours in milliseconds) for minimum periodic sync interval across origins is suggested to mitigate the concerns described in § 5 Privacy Considerations and § 6 Security Considerations.

Note: Two caps on frequency are needed because conforming to the cap enforced by minimum periodic sync interval for any origin for each origin can still cause the browser to fire periodicsync events very frequently. This can happen, for instance, when there are many periodic sync registrations for different origins. minimum periodic sync interval across origins ensures there’s a global cap on how often these events are fired.

The user agent MAY define a maximum number of retries, a number, allowed for each periodicsync event. In choosing this, the user agent SHOULD ensure that the time needed to attempt the maximum number of retries is an order of magnitude smaller than the minimum periodic sync interval for any origin. If undefined, this number is zero.

5. Privacy Considerations

5.1. Permission

5.2. Location Tracking

5.3. History Leaking

6. Security Considerations

In addition, if the origin synchronizes more often than the user visits the site, the origin may be getting more power than the user is aware of or intends. This is because the origin is able to execute code more frequently than the user intends, from within the periodicsync event while in the background. Some of the attacks this opens up are:

• Cryptocurrency mining: If the web app is able to execute code in the background at a high frequency, a malicious origin may use this CPU power for cryptocurrency mining.

• Distributed Denial of Service: This is possible if a malicious origin uses periodicsync events on multiple devices to target a specific origin by repeatedly fetching resources from it.

• A malicious origin can use periodicsync events to abuse the digital advertising ecosystem by fake-clicking on online ads, from a multitude of user devices.

To mitigate the above, the user agent MUST:

• Gate the capability on "periodic-background-sync" permission, as described in § 5.1 Permission. This allows the user to stop firing [periodicsync event|periodicsync events=] for any origin they’ve identified as malicious.

• Impose a time limit on the lifetime extension and execution time of a PeriodicSyncEvent which is stricter than the time limit imposed for ExtendableEvents in general. In particular, any retries of the PeriodicSyncEvent MAY have a significantly shortened time limit. Note: This time-limited execution of the periodicsync event makes sure this capability cannot be used for crypto mining on behalf of a malicious origin.

• Block registration from contexts where permission UI cannot be shown to the user. (See register(tag, options)).

The user agent MUST also impement at least one of the following:

• Auto-deny the capability to an origin for which the user has not expressed a level of trust.

  Note: This trust may be expressed by installing the website as a web app.

• Cap the interval at which periodicsync events are fired, as described in § 4.3 Constants.

• Show an audit-style UI to explain to the user how frequently an origin synchronizes content through this API, with appropriate resource attribution.

In addition, the user agent SHOULD:

• Set effective minimum sync interval for origin in accordance with the user’s engagement level with the origin, as defined in § 4.2 Periodic Sync Scheduler. In particular, this means the implementation stops firing periodicsync events for periodic sync registrations whose associated origin the user has stopped engaging with.

7. Resource Usage

This section is non-normative.

A website will most likely download resources from the network when processing a periodicsync event. The underlying operating system may launch the user agent to dispatch these events, and may keep it awake for a pre-defined duration to allow processing of the events. Both cause battery drain. The user agent should cap the duration and frequency of these events to limit resource usage by websites when the user has navigated away.

Large resources should be downloaded by registering a background fetch via the BackgroundFetchManager interface.

In addition, the user agent should consider other factors such as user engagement with the origin, and any user indications to temporarily reduce data consumption, such as a Data Saving Mode, to adjust the frequency of periodicsync events.

8. Algorithms

9. API Description

9.1. Extensions to the ServiceWorkerGlobalScope interface

partial interface ServiceWorkerGlobalScope {
    attribute EventHandler onperiodicsync;
};

9.2. Extensions to the ServiceWorkerRegistration interface

[Exposed=(Window,Worker)]
partial interface ServiceWorkerRegistration {
  readonly attribute PeriodicSyncManager periodicSync;
};

9.3. PeriodicSyncManager interface

[Exposed=(Window,Worker)]
interface PeriodicSyncManager {
    Promise<void> register(DOMString tag, optional BackgroundSyncOptions options);
    Promise<sequence<DOMString>> getTags();
    Promise<void> unregister(DOMString tag);
};

dictionary BackgroundSyncOptions {
    [EnforceRange] unsigned long long minInterval = 0;
};

9.4. The periodicsync event

dictionary PeriodicSyncEventInit : ExtendableEventInit {
  required DOMString tag;
};

[Exposed=ServiceWorker]
interface PeriodicSyncEvent : ExtendableEvent {
  constructor(DOMString type, PeriodicSyncEventInit init);
  readonly attribute DOMString tag;
};

9.4.1. Fire a periodicsync event