@serwist/expiration 8.0.0

package/dist/index.js

@@ -0,0 +1,521 @@
+import { assert, SerwistError, logger, dontWaitFor, privateCacheNames, getFriendlyURL } from '@serwist/core/internal';
+import { deleteDB, openDB } from 'idb';
+import { registerQuotaErrorCallback } from '@serwist/core';
+
+const DB_NAME = "serwist-expiration";
+const CACHE_OBJECT_STORE = "cache-entries";
+const normalizeURL = (unNormalizedUrl)=>{
+    const url = new URL(unNormalizedUrl, location.href);
+    url.hash = "";
+    return url.href;
+};
+/**
+ * Returns the timestamp model.
+ *
+ * @private
+ */ class CacheTimestampsModel {
+    _cacheName;
+    _db = null;
+    /**
+   *
+   * @param cacheName
+   *
+   * @private
+   */ constructor(cacheName){
+        this._cacheName = cacheName;
+    }
+    /**
+   * Performs an upgrade of indexedDB.
+   *
+   * @param db
+   *
+   * @private
+   */ _upgradeDb(db) {
+        // TODO(philipwalton): EdgeHTML doesn't support arrays as a keyPath, so we
+        // have to use the `id` keyPath here and create our own values (a
+        // concatenation of `url + cacheName`) instead of simply using
+        // `keyPath: ['url', 'cacheName']`, which is supported in other browsers.
+        const objStore = db.createObjectStore(CACHE_OBJECT_STORE, {
+            keyPath: "id"
+        });
+        // TODO(philipwalton): once we don't have to support EdgeHTML, we can
+        // create a single index with the keyPath `['cacheName', 'timestamp']`
+        // instead of doing both these indexes.
+        objStore.createIndex("cacheName", "cacheName", {
+            unique: false
+        });
+        objStore.createIndex("timestamp", "timestamp", {
+            unique: false
+        });
+    }
+    /**
+   * Performs an upgrade of indexedDB and deletes deprecated DBs.
+   *
+   * @param db
+   *
+   * @private
+   */ _upgradeDbAndDeleteOldDbs(db) {
+        this._upgradeDb(db);
+        if (this._cacheName) {
+            void deleteDB(this._cacheName);
+        }
+    }
+    /**
+   * @param url
+   * @param timestamp
+   *
+   * @private
+   */ async setTimestamp(url, timestamp) {
+        url = normalizeURL(url);
+        const entry = {
+            url,
+            timestamp,
+            cacheName: this._cacheName,
+            // Creating an ID from the URL and cache name won't be necessary once
+            // Edge switches to Chromium and all browsers we support work with
+            // array keyPaths.
+            id: this._getId(url)
+        };
+        const db = await this.getDb();
+        const tx = db.transaction(CACHE_OBJECT_STORE, "readwrite", {
+            durability: "relaxed"
+        });
+        await tx.store.put(entry);
+        await tx.done;
+    }
+    /**
+   * Returns the timestamp stored for a given URL.
+   *
+   * @param url
+   * @returns
+   * @private
+   */ async getTimestamp(url) {
+        const db = await this.getDb();
+        const entry = await db.get(CACHE_OBJECT_STORE, this._getId(url));
+        return entry?.timestamp;
+    }
+    /**
+   * Iterates through all the entries in the object store (from newest to
+   * oldest) and removes entries once either `maxCount` is reached or the
+   * entry's timestamp is less than `minTimestamp`.
+   *
+   * @param minTimestamp
+   * @param maxCount
+   * @returns
+   * @private
+   */ async expireEntries(minTimestamp, maxCount) {
+        const db = await this.getDb();
+        let cursor = await db.transaction(CACHE_OBJECT_STORE).store.index("timestamp").openCursor(null, "prev");
+        const entriesToDelete = [];
+        let entriesNotDeletedCount = 0;
+        while(cursor){
+            const result = cursor.value;
+            // TODO(philipwalton): once we can use a multi-key index, we
+            // won't have to check `cacheName` here.
+            if (result.cacheName === this._cacheName) {
+                // Delete an entry if it's older than the max age or
+                // if we already have the max number allowed.
+                if (minTimestamp && result.timestamp < minTimestamp || maxCount && entriesNotDeletedCount >= maxCount) {
+                    // TODO(philipwalton): we should be able to delete the
+                    // entry right here, but doing so causes an iteration
+                    // bug in Safari stable (fixed in TP). Instead we can
+                    // store the keys of the entries to delete, and then
+                    // delete the separate transactions.
+                    // https://github.com/GoogleChrome/workbox/issues/1978
+                    // cursor.delete();
+                    // We only need to return the URL, not the whole entry.
+                    entriesToDelete.push(cursor.value);
+                } else {
+                    entriesNotDeletedCount++;
+                }
+            }
+            cursor = await cursor.continue();
+        }
+        // TODO(philipwalton): once the Safari bug in the following issue is fixed,
+        // we should be able to remove this loop and do the entry deletion in the
+        // cursor loop above:
+        // https://github.com/GoogleChrome/workbox/issues/1978
+        const urlsDeleted = [];
+        for (const entry of entriesToDelete){
+            await db.delete(CACHE_OBJECT_STORE, entry.id);
+            urlsDeleted.push(entry.url);
+        }
+        return urlsDeleted;
+    }
+    /**
+   * Takes a URL and returns an ID that will be unique in the object store.
+   *
+   * @param url
+   * @returns
+   * @private
+   */ _getId(url) {
+        // Creating an ID from the URL and cache name won't be necessary once
+        // Edge switches to Chromium and all browsers we support work with
+        // array keyPaths.
+        return this._cacheName + "|" + normalizeURL(url);
+    }
+    /**
+   * Returns an open connection to the database.
+   *
+   * @private
+   */ async getDb() {
+        if (!this._db) {
+            this._db = await openDB(DB_NAME, 1, {
+                upgrade: this._upgradeDbAndDeleteOldDbs.bind(this)
+            });
+        }
+        return this._db;
+    }
+}
+
+/**
+ * The `CacheExpiration` class allows you define an expiration and / or
+ * limit on the number of responses stored in a
+ * [`Cache`](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
+ */ class CacheExpiration {
+    _isRunning = false;
+    _rerunRequested = false;
+    _maxEntries;
+    _maxAgeSeconds;
+    _matchOptions;
+    _cacheName;
+    _timestampModel;
+    /**
+   * To construct a new CacheExpiration instance you must provide at least
+   * one of the `config` properties.
+   *
+   * @param cacheName Name of the cache to apply restrictions to.
+   * @param config
+   */ constructor(cacheName, config = {}){
+        if (process.env.NODE_ENV !== "production") {
+            assert.isType(cacheName, "string", {
+                moduleName: "@serwist/expiration",
+                className: "CacheExpiration",
+                funcName: "constructor",
+                paramName: "cacheName"
+            });
+            if (!(config.maxEntries || config.maxAgeSeconds)) {
+                throw new SerwistError("max-entries-or-age-required", {
+                    moduleName: "@serwist/expiration",
+                    className: "CacheExpiration",
+                    funcName: "constructor"
+                });
+            }
+            if (config.maxEntries) {
+                assert.isType(config.maxEntries, "number", {
+                    moduleName: "@serwist/expiration",
+                    className: "CacheExpiration",
+                    funcName: "constructor",
+                    paramName: "config.maxEntries"
+                });
+            }
+            if (config.maxAgeSeconds) {
+                assert.isType(config.maxAgeSeconds, "number", {
+                    moduleName: "@serwist/expiration",
+                    className: "CacheExpiration",
+                    funcName: "constructor",
+                    paramName: "config.maxAgeSeconds"
+                });
+            }
+        }
+        this._maxEntries = config.maxEntries;
+        this._maxAgeSeconds = config.maxAgeSeconds;
+        this._matchOptions = config.matchOptions;
+        this._cacheName = cacheName;
+        this._timestampModel = new CacheTimestampsModel(cacheName);
+    }
+    /**
+   * Expires entries for the given cache and given criteria.
+   */ async expireEntries() {
+        if (this._isRunning) {
+            this._rerunRequested = true;
+            return;
+        }
+        this._isRunning = true;
+        const minTimestamp = this._maxAgeSeconds ? Date.now() - this._maxAgeSeconds * 1000 : 0;
+        const urlsExpired = await this._timestampModel.expireEntries(minTimestamp, this._maxEntries);
+        // Delete URLs from the cache
+        const cache = await self.caches.open(this._cacheName);
+        for (const url of urlsExpired){
+            await cache.delete(url, this._matchOptions);
+        }
+        if (process.env.NODE_ENV !== "production") {
+            if (urlsExpired.length > 0) {
+                logger.groupCollapsed(`Expired ${urlsExpired.length} ` + `${urlsExpired.length === 1 ? "entry" : "entries"} and removed ` + `${urlsExpired.length === 1 ? "it" : "them"} from the ` + `'${this._cacheName}' cache.`);
+                logger.log(`Expired the following ${urlsExpired.length === 1 ? "URL" : "URLs"}:`);
+                urlsExpired.forEach((url)=>logger.log(`    ${url}`));
+                logger.groupEnd();
+            } else {
+                logger.debug(`Cache expiration ran and found no entries to remove.`);
+            }
+        }
+        this._isRunning = false;
+        if (this._rerunRequested) {
+            this._rerunRequested = false;
+            dontWaitFor(this.expireEntries());
+        }
+    }
+    /**
+   * Update the timestamp for the given URL. This ensures the when
+   * removing entries based on maximum entries, most recently used
+   * is accurate or when expiring, the timestamp is up-to-date.
+   *
+   * @param url
+   */ async updateTimestamp(url) {
+        if (process.env.NODE_ENV !== "production") {
+            assert.isType(url, "string", {
+                moduleName: "@serwist/expiration",
+                className: "CacheExpiration",
+                funcName: "updateTimestamp",
+                paramName: "url"
+            });
+        }
+        await this._timestampModel.setTimestamp(url, Date.now());
+    }
+    /**
+   * Can be used to check if a URL has expired or not before it's used.
+   *
+   * This requires a look up from IndexedDB, so can be slow.
+   *
+   * Note: This method will not remove the cached entry, call
+   * `expireEntries()` to remove indexedDB and Cache entries.
+   *
+   * @param url
+   * @returns
+   */ async isURLExpired(url) {
+        if (!this._maxAgeSeconds) {
+            if (process.env.NODE_ENV !== "production") {
+                throw new SerwistError(`expired-test-without-max-age`, {
+                    methodName: "isURLExpired",
+                    paramName: "maxAgeSeconds"
+                });
+            }
+            return false;
+        } else {
+            const timestamp = await this._timestampModel.getTimestamp(url);
+            const expireOlderThan = Date.now() - this._maxAgeSeconds * 1000;
+            return timestamp !== undefined ? timestamp < expireOlderThan : true;
+        }
+    }
+    /**
+   * Removes the IndexedDB object store used to keep track of cache expiration
+   * metadata.
+   */ async delete() {
+        // Make sure we don't attempt another rerun if we're called in the middle of
+        // a cache expiration.
+        this._rerunRequested = false;
+        await this._timestampModel.expireEntries(Infinity); // Expires all.
+    }
+}
+
+/**
+ * This plugin can be used in a `@serwist/strategies` Strategy to regularly enforce a
+ * limit on the age and / or the number of cached requests.
+ *
+ * It can only be used with Strategy instances that have a
+ * [custom `cacheName` property set](/web/tools/workbox/guides/configure-workbox#custom_cache_names_in_strategies).
+ * In other words, it can't be used to expire entries in strategy that uses the
+ * default runtime cache name.
+ *
+ * Whenever a cached response is used or updated, this plugin will look
+ * at the associated cache and remove any old or extra responses.
+ *
+ * When using `maxAgeSeconds`, responses may be used *once* after expiring
+ * because the expiration clean up will not have occurred until *after* the
+ * cached response has been used. If the response has a "Date" header, then
+ * a light weight expiration check is performed and the response will not be
+ * used immediately.
+ *
+ * When using `maxEntries`, the entry least-recently requested will be removed
+ * from the cache first.
+ */ class ExpirationPlugin {
+    _config;
+    _maxAgeSeconds;
+    _cacheExpirations;
+    /**
+   * @param config
+   */ constructor(config = {}){
+        if (process.env.NODE_ENV !== "production") {
+            if (!(config.maxEntries || config.maxAgeSeconds)) {
+                throw new SerwistError("max-entries-or-age-required", {
+                    moduleName: "@serwist/expiration",
+                    className: "Plugin",
+                    funcName: "constructor"
+                });
+            }
+            if (config.maxEntries) {
+                assert.isType(config.maxEntries, "number", {
+                    moduleName: "@serwist/expiration",
+                    className: "Plugin",
+                    funcName: "constructor",
+                    paramName: "config.maxEntries"
+                });
+            }
+            if (config.maxAgeSeconds) {
+                assert.isType(config.maxAgeSeconds, "number", {
+                    moduleName: "@serwist/expiration",
+                    className: "Plugin",
+                    funcName: "constructor",
+                    paramName: "config.maxAgeSeconds"
+                });
+            }
+        }
+        this._config = config;
+        this._maxAgeSeconds = config.maxAgeSeconds;
+        this._cacheExpirations = new Map();
+        if (config.purgeOnQuotaError) {
+            registerQuotaErrorCallback(()=>this.deleteCacheAndMetadata());
+        }
+    }
+    /**
+   * A simple helper method to return a CacheExpiration instance for a given
+   * cache name.
+   *
+   * @param cacheName
+   * @returns
+   * @private
+   */ _getCacheExpiration(cacheName) {
+        if (cacheName === privateCacheNames.getRuntimeName()) {
+            throw new SerwistError("expire-custom-caches-only");
+        }
+        let cacheExpiration = this._cacheExpirations.get(cacheName);
+        if (!cacheExpiration) {
+            cacheExpiration = new CacheExpiration(cacheName, this._config);
+            this._cacheExpirations.set(cacheName, cacheExpiration);
+        }
+        return cacheExpiration;
+    }
+    /**
+   * A "lifecycle" callback that will be triggered automatically by the
+   * `@serwist/strategies` handlers when a `Response` is about to be returned
+   * from a [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to
+   * the handler. It allows the `Response` to be inspected for freshness and
+   * prevents it from being used if the `Response`'s `Date` header value is
+   * older than the configured `maxAgeSeconds`.
+   *
+   * @param options
+   * @returns Either the `cachedResponse`, if it's fresh, or `null` if the `Response`
+   * is older than `maxAgeSeconds`.
+   * @private
+   */ cachedResponseWillBeUsed = async ({ event, request, cacheName, cachedResponse })=>{
+        if (!cachedResponse) {
+            return null;
+        }
+        const isFresh = this._isResponseDateFresh(cachedResponse);
+        // Expire entries to ensure that even if the expiration date has
+        // expired, it'll only be used once.
+        const cacheExpiration = this._getCacheExpiration(cacheName);
+        dontWaitFor(cacheExpiration.expireEntries());
+        // Update the metadata for the request URL to the current timestamp,
+        // but don't `await` it as we don't want to block the response.
+        const updateTimestampDone = cacheExpiration.updateTimestamp(request.url);
+        if (event) {
+            try {
+                event.waitUntil(updateTimestampDone);
+            } catch (error) {
+                if (process.env.NODE_ENV !== "production") {
+                    // The event may not be a fetch event; only log the URL if it is.
+                    if ("request" in event) {
+                        logger.warn(`Unable to ensure service worker stays alive when ` + `updating cache entry for ` + `'${getFriendlyURL(event.request.url)}'.`);
+                    }
+                }
+            }
+        }
+        return isFresh ? cachedResponse : null;
+    };
+    /**
+   * @param cachedResponse
+   * @returns
+   * @private
+   */ _isResponseDateFresh(cachedResponse) {
+        if (!this._maxAgeSeconds) {
+            // We aren't expiring by age, so return true, it's fresh
+            return true;
+        }
+        // Check if the 'date' header will suffice a quick expiration check.
+        // See https://github.com/GoogleChromeLabs/sw-toolbox/issues/164 for
+        // discussion.
+        const dateHeaderTimestamp = this._getDateHeaderTimestamp(cachedResponse);
+        if (dateHeaderTimestamp === null) {
+            // Unable to parse date, so assume it's fresh.
+            return true;
+        }
+        // If we have a valid headerTime, then our response is fresh iff the
+        // headerTime plus maxAgeSeconds is greater than the current time.
+        const now = Date.now();
+        return dateHeaderTimestamp >= now - this._maxAgeSeconds * 1000;
+    }
+    /**
+   * This method will extract the data header and parse it into a useful
+   * value.
+   *
+   * @param cachedResponse
+   * @returns
+   * @private
+   */ _getDateHeaderTimestamp(cachedResponse) {
+        if (!cachedResponse.headers.has("date")) {
+            return null;
+        }
+        const dateHeader = cachedResponse.headers.get("date");
+        const parsedDate = new Date(dateHeader);
+        const headerTime = parsedDate.getTime();
+        // If the Date header was invalid for some reason, parsedDate.getTime()
+        // will return NaN.
+        if (isNaN(headerTime)) {
+            return null;
+        }
+        return headerTime;
+    }
+    /**
+   * A "lifecycle" callback that will be triggered automatically by the
+   * `@serwist/strategies` handlers when an entry is added to a cache.
+   *
+   * @param options
+   * @private
+   */ cacheDidUpdate = async ({ cacheName, request })=>{
+        if (process.env.NODE_ENV !== "production") {
+            assert.isType(cacheName, "string", {
+                moduleName: "@serwist/expiration",
+                className: "Plugin",
+                funcName: "cacheDidUpdate",
+                paramName: "cacheName"
+            });
+            assert.isInstance(request, Request, {
+                moduleName: "@serwist/expiration",
+                className: "Plugin",
+                funcName: "cacheDidUpdate",
+                paramName: "request"
+            });
+        }
+        const cacheExpiration = this._getCacheExpiration(cacheName);
+        await cacheExpiration.updateTimestamp(request.url);
+        await cacheExpiration.expireEntries();
+    };
+    /**
+   * This is a helper method that performs two operations:
+   *
+   * - Deletes *all* the underlying Cache instances associated with this plugin
+   * instance, by calling caches.delete() on your behalf.
+   * - Deletes the metadata from IndexedDB used to keep track of expiration
+   * details for each Cache instance.
+   *
+   * When using cache expiration, calling this method is preferable to calling
+   * `caches.delete()` directly, since this will ensure that the IndexedDB
+   * metadata is also cleanly removed and open IndexedDB instances are deleted.
+   *
+   * Note that if you're *not* using cache expiration for a given cache, calling
+   * `caches.delete()` and passing in the cache's name should be sufficient.
+   * There is no Serwist-specific method needed for cleanup in that case.
+   */ async deleteCacheAndMetadata() {
+        // Do this one at a time instead of all at once via `Promise.all()` to
+        // reduce the chance of inconsistency if a promise rejects.
+        for (const [cacheName, cacheExpiration] of this._cacheExpirations){
+            await self.caches.delete(cacheName);
+            await cacheExpiration.delete();
+        }
+        // Reset this._cacheExpirations to its initial state.
+        this._cacheExpirations = new Map();
+    }
+}
+
+export { CacheExpiration, ExpirationPlugin };