@serwist/range-requests 8.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Google LLC, 2019 ShadowWalker w@weiw.io https://weiw.io, 2023 Serwist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+This module's documentation can be found at https://developers.google.com/web/tools/workbox/modules/workbox-range-requests

package/dist/RangeRequestsPlugin.d.ts

@@ -0,0 +1,20 @@
+import type { SerwistPlugin } from "@serwist/core";
+/**
+ * The range request plugin makes it easy for a request with a 'Range' header to
+ * be fulfilled by a cached response.
+ *
+ * It does this by intercepting the `cachedResponseWillBeUsed` plugin callback
+ * and returning the appropriate subset of the cached response body.
+ */
+declare class RangeRequestsPlugin implements SerwistPlugin {
+    /**
+     * @param options
+     * @returns If request contains a 'Range' header, then a
+     * new response with status 206 whose body is a subset of `cachedResponse` is
+     * returned. Otherwise, `cachedResponse` is returned as-is.
+     * @private
+     */
+    cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"];
+}
+export { RangeRequestsPlugin };
+//# sourceMappingURL=RangeRequestsPlugin.d.ts.map

package/dist/RangeRequestsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeRequestsPlugin.d.ts","sourceRoot":"","sources":["../src/RangeRequestsPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD;;;;;;GAMG;AACH,cAAM,mBAAoB,YAAW,aAAa;IAChD;;;;;;OAMG;IACH,wBAAwB,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAUjE;CACH;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/createPartialResponse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Given a `Request` and `Response` objects as input, this will return a
+ * promise for a new `Response`.
+ *
+ * If the original `Response` already contains partial content (i.e. it has
+ * a status of 206), then this assumes it already fulfills the `Range:`
+ * requirements, and will return it as-is.
+ *
+ * @param request A request, which should contain a Range:
+ * header.
+ * @param originalResponse A response.
+ * @returns Either a `206 Partial Content` response, with
+ * the response body set to the slice of content specified by the request's
+ * `Range:` header, or a `416 Range Not Satisfiable` response if the
+ * conditions of the `Range:` header can't be met.
+ */
+declare function createPartialResponse(request: Request, originalResponse: Response): Promise<Response>;
+export { createPartialResponse };
+//# sourceMappingURL=createPartialResponse.d.ts.map

package/dist/createPartialResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPartialResponse.d.ts","sourceRoot":"","sources":["../src/createPartialResponse.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,iBAAe,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8DpG;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { createPartialResponse } from "./createPartialResponse.js";
+import { RangeRequestsPlugin } from "./RangeRequestsPlugin.js";
+export { createPartialResponse, RangeRequestsPlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,181 @@
+import { assert, SerwistError, logger } from '@serwist/core/internal';
+
+/**
+ * @param blob A source blob.
+ * @param start The offset to use as the start of the
+ * slice.
+ * @param end The offset to use as the end of the slice.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the effective boundaries to use given the size of the blob.
+ * @private
+ */ function calculateEffectiveBoundaries(blob, start, end) {
+    if (process.env.NODE_ENV !== "production") {
+        assert.isInstance(blob, Blob, {
+            moduleName: "@serwist/range-requests",
+            funcName: "calculateEffectiveBoundaries",
+            paramName: "blob"
+        });
+    }
+    const blobSize = blob.size;
+    if (end && end > blobSize || start && start < 0) {
+        throw new SerwistError("range-not-satisfiable", {
+            size: blobSize,
+            end,
+            start
+        });
+    }
+    let effectiveStart;
+    let effectiveEnd;
+    if (start !== undefined && end !== undefined) {
+        effectiveStart = start;
+        // Range values are inclusive, so add 1 to the value.
+        effectiveEnd = end + 1;
+    } else if (start !== undefined && end === undefined) {
+        effectiveStart = start;
+        effectiveEnd = blobSize;
+    } else if (end !== undefined && start === undefined) {
+        effectiveStart = blobSize - end;
+        effectiveEnd = blobSize;
+    }
+    return {
+        start: effectiveStart,
+        end: effectiveEnd
+    };
+}
+
+/**
+ * @param rangeHeader A Range: header value.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the parsed value of the Range: header. If either the `start` or `end` are
+ * omitted, then `null` will be returned.
+ * @private
+ */ function parseRangeHeader(rangeHeader) {
+    if (process.env.NODE_ENV !== "production") {
+        assert.isType(rangeHeader, "string", {
+            moduleName: "@serwist/range-requests",
+            funcName: "parseRangeHeader",
+            paramName: "rangeHeader"
+        });
+    }
+    const normalizedRangeHeader = rangeHeader.trim().toLowerCase();
+    if (!normalizedRangeHeader.startsWith("bytes=")) {
+        throw new SerwistError("unit-must-be-bytes", {
+            normalizedRangeHeader
+        });
+    }
+    // Specifying multiple ranges separate by commas is valid syntax, but this
+    // library only attempts to handle a single, contiguous sequence of bytes.
+    // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range#Syntax
+    if (normalizedRangeHeader.includes(",")) {
+        throw new SerwistError("single-range-only", {
+            normalizedRangeHeader
+        });
+    }
+    const rangeParts = /(\d*)-(\d*)/.exec(normalizedRangeHeader);
+    // We need either at least one of the start or end values.
+    if (!rangeParts || !(rangeParts[1] || rangeParts[2])) {
+        throw new SerwistError("invalid-range-values", {
+            normalizedRangeHeader
+        });
+    }
+    return {
+        start: rangeParts[1] === "" ? undefined : Number(rangeParts[1]),
+        end: rangeParts[2] === "" ? undefined : Number(rangeParts[2])
+    };
+}
+
+/**
+ * Given a `Request` and `Response` objects as input, this will return a
+ * promise for a new `Response`.
+ *
+ * If the original `Response` already contains partial content (i.e. it has
+ * a status of 206), then this assumes it already fulfills the `Range:`
+ * requirements, and will return it as-is.
+ *
+ * @param request A request, which should contain a Range:
+ * header.
+ * @param originalResponse A response.
+ * @returns Either a `206 Partial Content` response, with
+ * the response body set to the slice of content specified by the request's
+ * `Range:` header, or a `416 Range Not Satisfiable` response if the
+ * conditions of the `Range:` header can't be met.
+ */ async function createPartialResponse(request, originalResponse) {
+    try {
+        if (process.env.NODE_ENV !== "production") {
+            assert.isInstance(request, Request, {
+                moduleName: "@serwist/range-requests",
+                funcName: "createPartialResponse",
+                paramName: "request"
+            });
+            assert.isInstance(originalResponse, Response, {
+                moduleName: "@serwist/range-requests",
+                funcName: "createPartialResponse",
+                paramName: "originalResponse"
+            });
+        }
+        if (originalResponse.status === 206) {
+            // If we already have a 206, then just pass it through as-is;
+            // see https://github.com/GoogleChrome/workbox/issues/1720
+            return originalResponse;
+        }
+        const rangeHeader = request.headers.get("range");
+        if (!rangeHeader) {
+            throw new SerwistError("no-range-header");
+        }
+        const boundaries = parseRangeHeader(rangeHeader);
+        const originalBlob = await originalResponse.blob();
+        const effectiveBoundaries = calculateEffectiveBoundaries(originalBlob, boundaries.start, boundaries.end);
+        const slicedBlob = originalBlob.slice(effectiveBoundaries.start, effectiveBoundaries.end);
+        const slicedBlobSize = slicedBlob.size;
+        const slicedResponse = new Response(slicedBlob, {
+            // Status code 206 is for a Partial Content response.
+            // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206
+            status: 206,
+            statusText: "Partial Content",
+            headers: originalResponse.headers
+        });
+        slicedResponse.headers.set("Content-Length", String(slicedBlobSize));
+        slicedResponse.headers.set("Content-Range", `bytes ${effectiveBoundaries.start}-${effectiveBoundaries.end - 1}/` + `${originalBlob.size}`);
+        return slicedResponse;
+    } catch (error) {
+        if (process.env.NODE_ENV !== "production") {
+            logger.warn(`Unable to construct a partial response; returning a ` + `416 Range Not Satisfiable response instead.`);
+            logger.groupCollapsed(`View details here.`);
+            logger.log(error);
+            logger.log(request);
+            logger.log(originalResponse);
+            logger.groupEnd();
+        }
+        return new Response("", {
+            status: 416,
+            statusText: "Range Not Satisfiable"
+        });
+    }
+}
+
+/**
+ * The range request plugin makes it easy for a request with a 'Range' header to
+ * be fulfilled by a cached response.
+ *
+ * It does this by intercepting the `cachedResponseWillBeUsed` plugin callback
+ * and returning the appropriate subset of the cached response body.
+ */ class RangeRequestsPlugin {
+    /**
+   * @param options
+   * @returns If request contains a 'Range' header, then a
+   * new response with status 206 whose body is a subset of `cachedResponse` is
+   * returned. Otherwise, `cachedResponse` is returned as-is.
+   * @private
+   */ cachedResponseWillBeUsed = async ({ request, cachedResponse })=>{
+        // Only return a sliced response if there's something valid in the cache,
+        // and there's a Range: header in the request.
+        if (cachedResponse && request.headers.has("range")) {
+            return await createPartialResponse(request, cachedResponse);
+        }
+        // If there was no Range: header, or if cachedResponse wasn't valid, just
+        // pass it through as-is.
+        return cachedResponse;
+    };
+}
+
+export { RangeRequestsPlugin, createPartialResponse };

package/dist/index.old.cjs

@@ -0,0 +1,184 @@
+'use strict';
+
+var internal = require('@serwist/core/internal');
+
+/**
+ * @param blob A source blob.
+ * @param start The offset to use as the start of the
+ * slice.
+ * @param end The offset to use as the end of the slice.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the effective boundaries to use given the size of the blob.
+ * @private
+ */ function calculateEffectiveBoundaries(blob, start, end) {
+    if (process.env.NODE_ENV !== "production") {
+        internal.assert.isInstance(blob, Blob, {
+            moduleName: "@serwist/range-requests",
+            funcName: "calculateEffectiveBoundaries",
+            paramName: "blob"
+        });
+    }
+    const blobSize = blob.size;
+    if (end && end > blobSize || start && start < 0) {
+        throw new internal.SerwistError("range-not-satisfiable", {
+            size: blobSize,
+            end,
+            start
+        });
+    }
+    let effectiveStart;
+    let effectiveEnd;
+    if (start !== undefined && end !== undefined) {
+        effectiveStart = start;
+        // Range values are inclusive, so add 1 to the value.
+        effectiveEnd = end + 1;
+    } else if (start !== undefined && end === undefined) {
+        effectiveStart = start;
+        effectiveEnd = blobSize;
+    } else if (end !== undefined && start === undefined) {
+        effectiveStart = blobSize - end;
+        effectiveEnd = blobSize;
+    }
+    return {
+        start: effectiveStart,
+        end: effectiveEnd
+    };
+}
+
+/**
+ * @param rangeHeader A Range: header value.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the parsed value of the Range: header. If either the `start` or `end` are
+ * omitted, then `null` will be returned.
+ * @private
+ */ function parseRangeHeader(rangeHeader) {
+    if (process.env.NODE_ENV !== "production") {
+        internal.assert.isType(rangeHeader, "string", {
+            moduleName: "@serwist/range-requests",
+            funcName: "parseRangeHeader",
+            paramName: "rangeHeader"
+        });
+    }
+    const normalizedRangeHeader = rangeHeader.trim().toLowerCase();
+    if (!normalizedRangeHeader.startsWith("bytes=")) {
+        throw new internal.SerwistError("unit-must-be-bytes", {
+            normalizedRangeHeader
+        });
+    }
+    // Specifying multiple ranges separate by commas is valid syntax, but this
+    // library only attempts to handle a single, contiguous sequence of bytes.
+    // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range#Syntax
+    if (normalizedRangeHeader.includes(",")) {
+        throw new internal.SerwistError("single-range-only", {
+            normalizedRangeHeader
+        });
+    }
+    const rangeParts = /(\d*)-(\d*)/.exec(normalizedRangeHeader);
+    // We need either at least one of the start or end values.
+    if (!rangeParts || !(rangeParts[1] || rangeParts[2])) {
+        throw new internal.SerwistError("invalid-range-values", {
+            normalizedRangeHeader
+        });
+    }
+    return {
+        start: rangeParts[1] === "" ? undefined : Number(rangeParts[1]),
+        end: rangeParts[2] === "" ? undefined : Number(rangeParts[2])
+    };
+}
+
+/**
+ * Given a `Request` and `Response` objects as input, this will return a
+ * promise for a new `Response`.
+ *
+ * If the original `Response` already contains partial content (i.e. it has
+ * a status of 206), then this assumes it already fulfills the `Range:`
+ * requirements, and will return it as-is.
+ *
+ * @param request A request, which should contain a Range:
+ * header.
+ * @param originalResponse A response.
+ * @returns Either a `206 Partial Content` response, with
+ * the response body set to the slice of content specified by the request's
+ * `Range:` header, or a `416 Range Not Satisfiable` response if the
+ * conditions of the `Range:` header can't be met.
+ */ async function createPartialResponse(request, originalResponse) {
+    try {
+        if (process.env.NODE_ENV !== "production") {
+            internal.assert.isInstance(request, Request, {
+                moduleName: "@serwist/range-requests",
+                funcName: "createPartialResponse",
+                paramName: "request"
+            });
+            internal.assert.isInstance(originalResponse, Response, {
+                moduleName: "@serwist/range-requests",
+                funcName: "createPartialResponse",
+                paramName: "originalResponse"
+            });
+        }
+        if (originalResponse.status === 206) {
+            // If we already have a 206, then just pass it through as-is;
+            // see https://github.com/GoogleChrome/workbox/issues/1720
+            return originalResponse;
+        }
+        const rangeHeader = request.headers.get("range");
+        if (!rangeHeader) {
+            throw new internal.SerwistError("no-range-header");
+        }
+        const boundaries = parseRangeHeader(rangeHeader);
+        const originalBlob = await originalResponse.blob();
+        const effectiveBoundaries = calculateEffectiveBoundaries(originalBlob, boundaries.start, boundaries.end);
+        const slicedBlob = originalBlob.slice(effectiveBoundaries.start, effectiveBoundaries.end);
+        const slicedBlobSize = slicedBlob.size;
+        const slicedResponse = new Response(slicedBlob, {
+            // Status code 206 is for a Partial Content response.
+            // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206
+            status: 206,
+            statusText: "Partial Content",
+            headers: originalResponse.headers
+        });
+        slicedResponse.headers.set("Content-Length", String(slicedBlobSize));
+        slicedResponse.headers.set("Content-Range", `bytes ${effectiveBoundaries.start}-${effectiveBoundaries.end - 1}/` + `${originalBlob.size}`);
+        return slicedResponse;
+    } catch (error) {
+        if (process.env.NODE_ENV !== "production") {
+            internal.logger.warn(`Unable to construct a partial response; returning a ` + `416 Range Not Satisfiable response instead.`);
+            internal.logger.groupCollapsed(`View details here.`);
+            internal.logger.log(error);
+            internal.logger.log(request);
+            internal.logger.log(originalResponse);
+            internal.logger.groupEnd();
+        }
+        return new Response("", {
+            status: 416,
+            statusText: "Range Not Satisfiable"
+        });
+    }
+}
+
+/**
+ * The range request plugin makes it easy for a request with a 'Range' header to
+ * be fulfilled by a cached response.
+ *
+ * It does this by intercepting the `cachedResponseWillBeUsed` plugin callback
+ * and returning the appropriate subset of the cached response body.
+ */ class RangeRequestsPlugin {
+    /**
+   * @param options
+   * @returns If request contains a 'Range' header, then a
+   * new response with status 206 whose body is a subset of `cachedResponse` is
+   * returned. Otherwise, `cachedResponse` is returned as-is.
+   * @private
+   */ cachedResponseWillBeUsed = async ({ request, cachedResponse })=>{
+        // Only return a sliced response if there's something valid in the cache,
+        // and there's a Range: header in the request.
+        if (cachedResponse && request.headers.has("range")) {
+            return await createPartialResponse(request, cachedResponse);
+        }
+        // If there was no Range: header, or if cachedResponse wasn't valid, just
+        // pass it through as-is.
+        return cachedResponse;
+    };
+}
+
+exports.RangeRequestsPlugin = RangeRequestsPlugin;
+exports.createPartialResponse = createPartialResponse;

package/dist/utils/calculateEffectiveBoundaries.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @param blob A source blob.
+ * @param start The offset to use as the start of the
+ * slice.
+ * @param end The offset to use as the end of the slice.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the effective boundaries to use given the size of the blob.
+ * @private
+ */
+declare function calculateEffectiveBoundaries(blob: Blob, start?: number, end?: number): {
+    start: number;
+    end: number;
+};
+export { calculateEffectiveBoundaries };
+//# sourceMappingURL=calculateEffectiveBoundaries.d.ts.map

package/dist/utils/calculateEffectiveBoundaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculateEffectiveBoundaries.d.ts","sourceRoot":"","sources":["../../src/utils/calculateEffectiveBoundaries.ts"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH,iBAAS,4BAA4B,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAsC9G;AAED,OAAO,EAAE,4BAA4B,EAAE,CAAC"}

package/dist/utils/parseRangeHeader.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param rangeHeader A Range: header value.
+ * @returns An object with `start` and `end` properties, reflecting
+ * the parsed value of the Range: header. If either the `start` or `end` are
+ * omitted, then `null` will be returned.
+ * @private
+ */
+declare function parseRangeHeader(rangeHeader: string): {
+    start?: number;
+    end?: number;
+};
+export { parseRangeHeader };
+//# sourceMappingURL=parseRangeHeader.d.ts.map

package/dist/utils/parseRangeHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseRangeHeader.d.ts","sourceRoot":"","sources":["../../src/utils/parseRangeHeader.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,iBAAS,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CA+BA;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@serwist/range-requests",
+  "version": "8.0.0",
+  "type": "module",
+  "description": "This library creates a new Response, given a source Response and a Range header value.",
+  "files": [
+    "dist",
+    "!dist/**/dts"
+  ],
+  "keywords": [
+    "serwist",
+    "serwistjs",
+    "service worker",
+    "sw",
+    "caching",
+    "cache",
+    "range",
+    "media",
+    "serwist-plugin"
+  ],
+  "author": "Google's Web DevRel Team, Serwist's Team",
+  "license": "MIT",
+  "repository": "serwist/serwist",
+  "bugs": "https://github.com/serwist/serwist/issues",
+  "homepage": "https://ducanh-next-pwa.vercel.app",
+  "module": "./dist/index.js",
+  "main": "./dist/index.old.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.old.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@serwist/core": "8.0.0"
+  },
+  "devDependencies": {
+    "rollup": "3.28.1",
+    "@serwist/constants": "8.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && cross-env NODE_ENV=production rollup --config rollup.config.js",
+    "lint": "eslint src --ext ts,tsx,js,jsx,cjs,mjs",
+    "typecheck": "tsc"
+  }
+}