402 lines
16 KiB
JavaScript
402 lines
16 KiB
JavaScript
/*
|
|
Copyright 2018 Google LLC
|
|
|
|
Use of this source code is governed by an MIT-style
|
|
license that can be found in the LICENSE file or at
|
|
https://opensource.org/licenses/MIT.
|
|
*/
|
|
import { WorkboxError } from 'workbox-core/_private/WorkboxError.js';
|
|
import { logger } from 'workbox-core/_private/logger.js';
|
|
import { assert } from 'workbox-core/_private/assert.js';
|
|
import { getFriendlyURL } from 'workbox-core/_private/getFriendlyURL.js';
|
|
import { QueueStore } from './lib/QueueStore.js';
|
|
import { StorableRequest } from './lib/StorableRequest.js';
|
|
import './_version.js';
|
|
const TAG_PREFIX = 'workbox-background-sync';
|
|
const MAX_RETENTION_TIME = 60 * 24 * 7; // 7 days in minutes
|
|
const queueNames = new Set();
|
|
/**
|
|
* Converts a QueueStore entry into the format exposed by Queue. This entails
|
|
* converting the request data into a real request and omitting the `id` and
|
|
* `queueName` properties.
|
|
*
|
|
* @param {UnidentifiedQueueStoreEntry} queueStoreEntry
|
|
* @return {Queue}
|
|
* @private
|
|
*/
|
|
const convertEntry = (queueStoreEntry) => {
|
|
const queueEntry = {
|
|
request: new StorableRequest(queueStoreEntry.requestData).toRequest(),
|
|
timestamp: queueStoreEntry.timestamp,
|
|
};
|
|
if (queueStoreEntry.metadata) {
|
|
queueEntry.metadata = queueStoreEntry.metadata;
|
|
}
|
|
return queueEntry;
|
|
};
|
|
/**
|
|
* A class to manage storing failed requests in IndexedDB and retrying them
|
|
* later. All parts of the storing and replaying process are observable via
|
|
* callbacks.
|
|
*
|
|
* @memberof workbox-background-sync
|
|
*/
|
|
class Queue {
|
|
/**
|
|
* Creates an instance of Queue with the given options
|
|
*
|
|
* @param {string} name The unique name for this queue. This name must be
|
|
* unique as it's used to register sync events and store requests
|
|
* in IndexedDB specific to this instance. An error will be thrown if
|
|
* a duplicate name is detected.
|
|
* @param {Object} [options]
|
|
* @param {Function} [options.onSync] A function that gets invoked whenever
|
|
* the 'sync' event fires. The function is invoked with an object
|
|
* containing the `queue` property (referencing this instance), and you
|
|
* can use the callback to customize the replay behavior of the queue.
|
|
* When not set the `replayRequests()` method is called.
|
|
* Note: if the replay fails after a sync event, make sure you throw an
|
|
* error, so the browser knows to retry the sync event later.
|
|
* @param {number} [options.maxRetentionTime=7 days] The amount of time (in
|
|
* minutes) a request may be retried. After this amount of time has
|
|
* passed, the request will be deleted from the queue.
|
|
* @param {boolean} [options.forceSyncFallback=false] If `true`, instead
|
|
* of attempting to use background sync events, always attempt to replay
|
|
* queued request at service worker startup. Most folks will not need
|
|
* this, unless you explicitly target a runtime like Electron that
|
|
* exposes the interfaces for background sync, but does not have a working
|
|
* implementation.
|
|
*/
|
|
constructor(name, { forceSyncFallback, onSync, maxRetentionTime } = {}) {
|
|
this._syncInProgress = false;
|
|
this._requestsAddedDuringSync = false;
|
|
// Ensure the store name is not already being used
|
|
if (queueNames.has(name)) {
|
|
throw new WorkboxError('duplicate-queue-name', { name });
|
|
}
|
|
else {
|
|
queueNames.add(name);
|
|
}
|
|
this._name = name;
|
|
this._onSync = onSync || this.replayRequests;
|
|
this._maxRetentionTime = maxRetentionTime || MAX_RETENTION_TIME;
|
|
this._forceSyncFallback = Boolean(forceSyncFallback);
|
|
this._queueStore = new QueueStore(this._name);
|
|
this._addSyncListener();
|
|
}
|
|
/**
|
|
* @return {string}
|
|
*/
|
|
get name() {
|
|
return this._name;
|
|
}
|
|
/**
|
|
* Stores the passed request in IndexedDB (with its timestamp and any
|
|
* metadata) at the end of the queue.
|
|
*
|
|
* @param {QueueEntry} entry
|
|
* @param {Request} entry.request The request to store in the queue.
|
|
* @param {Object} [entry.metadata] Any metadata you want associated with the
|
|
* stored request. When requests are replayed you'll have access to this
|
|
* metadata object in case you need to modify the request beforehand.
|
|
* @param {number} [entry.timestamp] The timestamp (Epoch time in
|
|
* milliseconds) when the request was first added to the queue. This is
|
|
* used along with `maxRetentionTime` to remove outdated requests. In
|
|
* general you don't need to set this value, as it's automatically set
|
|
* for you (defaulting to `Date.now()`), but you can update it if you
|
|
* don't want particular requests to expire.
|
|
*/
|
|
async pushRequest(entry) {
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
assert.isType(entry, 'object', {
|
|
moduleName: 'workbox-background-sync',
|
|
className: 'Queue',
|
|
funcName: 'pushRequest',
|
|
paramName: 'entry',
|
|
});
|
|
assert.isInstance(entry.request, Request, {
|
|
moduleName: 'workbox-background-sync',
|
|
className: 'Queue',
|
|
funcName: 'pushRequest',
|
|
paramName: 'entry.request',
|
|
});
|
|
}
|
|
await this._addRequest(entry, 'push');
|
|
}
|
|
/**
|
|
* Stores the passed request in IndexedDB (with its timestamp and any
|
|
* metadata) at the beginning of the queue.
|
|
*
|
|
* @param {QueueEntry} entry
|
|
* @param {Request} entry.request The request to store in the queue.
|
|
* @param {Object} [entry.metadata] Any metadata you want associated with the
|
|
* stored request. When requests are replayed you'll have access to this
|
|
* metadata object in case you need to modify the request beforehand.
|
|
* @param {number} [entry.timestamp] The timestamp (Epoch time in
|
|
* milliseconds) when the request was first added to the queue. This is
|
|
* used along with `maxRetentionTime` to remove outdated requests. In
|
|
* general you don't need to set this value, as it's automatically set
|
|
* for you (defaulting to `Date.now()`), but you can update it if you
|
|
* don't want particular requests to expire.
|
|
*/
|
|
async unshiftRequest(entry) {
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
assert.isType(entry, 'object', {
|
|
moduleName: 'workbox-background-sync',
|
|
className: 'Queue',
|
|
funcName: 'unshiftRequest',
|
|
paramName: 'entry',
|
|
});
|
|
assert.isInstance(entry.request, Request, {
|
|
moduleName: 'workbox-background-sync',
|
|
className: 'Queue',
|
|
funcName: 'unshiftRequest',
|
|
paramName: 'entry.request',
|
|
});
|
|
}
|
|
await this._addRequest(entry, 'unshift');
|
|
}
|
|
/**
|
|
* Removes and returns the last request in the queue (along with its
|
|
* timestamp and any metadata). The returned object takes the form:
|
|
* `{request, timestamp, metadata}`.
|
|
*
|
|
* @return {Promise<QueueEntry | undefined>}
|
|
*/
|
|
async popRequest() {
|
|
return this._removeRequest('pop');
|
|
}
|
|
/**
|
|
* Removes and returns the first request in the queue (along with its
|
|
* timestamp and any metadata). The returned object takes the form:
|
|
* `{request, timestamp, metadata}`.
|
|
*
|
|
* @return {Promise<QueueEntry | undefined>}
|
|
*/
|
|
async shiftRequest() {
|
|
return this._removeRequest('shift');
|
|
}
|
|
/**
|
|
* Returns all the entries that have not expired (per `maxRetentionTime`).
|
|
* Any expired entries are removed from the queue.
|
|
*
|
|
* @return {Promise<Array<QueueEntry>>}
|
|
*/
|
|
async getAll() {
|
|
const allEntries = await this._queueStore.getAll();
|
|
const now = Date.now();
|
|
const unexpiredEntries = [];
|
|
for (const entry of allEntries) {
|
|
// Ignore requests older than maxRetentionTime. Call this function
|
|
// recursively until an unexpired request is found.
|
|
const maxRetentionTimeInMs = this._maxRetentionTime * 60 * 1000;
|
|
if (now - entry.timestamp > maxRetentionTimeInMs) {
|
|
await this._queueStore.deleteEntry(entry.id);
|
|
}
|
|
else {
|
|
unexpiredEntries.push(convertEntry(entry));
|
|
}
|
|
}
|
|
return unexpiredEntries;
|
|
}
|
|
/**
|
|
* Returns the number of entries present in the queue.
|
|
* Note that expired entries (per `maxRetentionTime`) are also included in this count.
|
|
*
|
|
* @return {Promise<number>}
|
|
*/
|
|
async size() {
|
|
return await this._queueStore.size();
|
|
}
|
|
/**
|
|
* Adds the entry to the QueueStore and registers for a sync event.
|
|
*
|
|
* @param {Object} entry
|
|
* @param {Request} entry.request
|
|
* @param {Object} [entry.metadata]
|
|
* @param {number} [entry.timestamp=Date.now()]
|
|
* @param {string} operation ('push' or 'unshift')
|
|
* @private
|
|
*/
|
|
async _addRequest({ request, metadata, timestamp = Date.now() }, operation) {
|
|
const storableRequest = await StorableRequest.fromRequest(request.clone());
|
|
const entry = {
|
|
requestData: storableRequest.toObject(),
|
|
timestamp,
|
|
};
|
|
// Only include metadata if it's present.
|
|
if (metadata) {
|
|
entry.metadata = metadata;
|
|
}
|
|
switch (operation) {
|
|
case 'push':
|
|
await this._queueStore.pushEntry(entry);
|
|
break;
|
|
case 'unshift':
|
|
await this._queueStore.unshiftEntry(entry);
|
|
break;
|
|
}
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.log(`Request for '${getFriendlyURL(request.url)}' has ` +
|
|
`been added to background sync queue '${this._name}'.`);
|
|
}
|
|
// Don't register for a sync if we're in the middle of a sync. Instead,
|
|
// we wait until the sync is complete and call register if
|
|
// `this._requestsAddedDuringSync` is true.
|
|
if (this._syncInProgress) {
|
|
this._requestsAddedDuringSync = true;
|
|
}
|
|
else {
|
|
await this.registerSync();
|
|
}
|
|
}
|
|
/**
|
|
* Removes and returns the first or last (depending on `operation`) entry
|
|
* from the QueueStore that's not older than the `maxRetentionTime`.
|
|
*
|
|
* @param {string} operation ('pop' or 'shift')
|
|
* @return {Object|undefined}
|
|
* @private
|
|
*/
|
|
async _removeRequest(operation) {
|
|
const now = Date.now();
|
|
let entry;
|
|
switch (operation) {
|
|
case 'pop':
|
|
entry = await this._queueStore.popEntry();
|
|
break;
|
|
case 'shift':
|
|
entry = await this._queueStore.shiftEntry();
|
|
break;
|
|
}
|
|
if (entry) {
|
|
// Ignore requests older than maxRetentionTime. Call this function
|
|
// recursively until an unexpired request is found.
|
|
const maxRetentionTimeInMs = this._maxRetentionTime * 60 * 1000;
|
|
if (now - entry.timestamp > maxRetentionTimeInMs) {
|
|
return this._removeRequest(operation);
|
|
}
|
|
return convertEntry(entry);
|
|
}
|
|
else {
|
|
return undefined;
|
|
}
|
|
}
|
|
/**
|
|
* Loops through each request in the queue and attempts to re-fetch it.
|
|
* If any request fails to re-fetch, it's put back in the same position in
|
|
* the queue (which registers a retry for the next sync event).
|
|
*/
|
|
async replayRequests() {
|
|
let entry;
|
|
while ((entry = await this.shiftRequest())) {
|
|
try {
|
|
await fetch(entry.request.clone());
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.log(`Request for '${getFriendlyURL(entry.request.url)}' ` +
|
|
`has been replayed in queue '${this._name}'`);
|
|
}
|
|
}
|
|
catch (error) {
|
|
await this.unshiftRequest(entry);
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.log(`Request for '${getFriendlyURL(entry.request.url)}' ` +
|
|
`failed to replay, putting it back in queue '${this._name}'`);
|
|
}
|
|
throw new WorkboxError('queue-replay-failed', { name: this._name });
|
|
}
|
|
}
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.log(`All requests in queue '${this.name}' have successfully ` +
|
|
`replayed; the queue is now empty!`);
|
|
}
|
|
}
|
|
/**
|
|
* Registers a sync event with a tag unique to this instance.
|
|
*/
|
|
async registerSync() {
|
|
// See https://github.com/GoogleChrome/workbox/issues/2393
|
|
if ('sync' in self.registration && !this._forceSyncFallback) {
|
|
try {
|
|
await self.registration.sync.register(`${TAG_PREFIX}:${this._name}`);
|
|
}
|
|
catch (err) {
|
|
// This means the registration failed for some reason, possibly due to
|
|
// the user disabling it.
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.warn(`Unable to register sync event for '${this._name}'.`, err);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
/**
|
|
* In sync-supporting browsers, this adds a listener for the sync event.
|
|
* In non-sync-supporting browsers, or if _forceSyncFallback is true, this
|
|
* will retry the queue on service worker startup.
|
|
*
|
|
* @private
|
|
*/
|
|
_addSyncListener() {
|
|
// See https://github.com/GoogleChrome/workbox/issues/2393
|
|
if ('sync' in self.registration && !this._forceSyncFallback) {
|
|
self.addEventListener('sync', (event) => {
|
|
if (event.tag === `${TAG_PREFIX}:${this._name}`) {
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.log(`Background sync for tag '${event.tag}' ` + `has been received`);
|
|
}
|
|
const syncComplete = async () => {
|
|
this._syncInProgress = true;
|
|
let syncError;
|
|
try {
|
|
await this._onSync({ queue: this });
|
|
}
|
|
catch (error) {
|
|
if (error instanceof Error) {
|
|
syncError = error;
|
|
// Rethrow the error. Note: the logic in the finally clause
|
|
// will run before this gets rethrown.
|
|
throw syncError;
|
|
}
|
|
}
|
|
finally {
|
|
// New items may have been added to the queue during the sync,
|
|
// so we need to register for a new sync if that's happened...
|
|
// Unless there was an error during the sync, in which
|
|
// case the browser will automatically retry later, as long
|
|
// as `event.lastChance` is not true.
|
|
if (this._requestsAddedDuringSync &&
|
|
!(syncError && !event.lastChance)) {
|
|
await this.registerSync();
|
|
}
|
|
this._syncInProgress = false;
|
|
this._requestsAddedDuringSync = false;
|
|
}
|
|
};
|
|
event.waitUntil(syncComplete());
|
|
}
|
|
});
|
|
}
|
|
else {
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
logger.log(`Background sync replaying without background sync event`);
|
|
}
|
|
// If the browser doesn't support background sync, or the developer has
|
|
// opted-in to not using it, retry every time the service worker starts up
|
|
// as a fallback.
|
|
void this._onSync({ queue: this });
|
|
}
|
|
}
|
|
/**
|
|
* Returns the set of queue names. This is primarily used to reset the list
|
|
* of queue names in tests.
|
|
*
|
|
* @return {Set<string>}
|
|
*
|
|
* @private
|
|
*/
|
|
static get _queueNames() {
|
|
return queueNames;
|
|
}
|
|
}
|
|
export { Queue };
|