zip-peek 0.1.0

package/README.md

@@ -0,0 +1,392 @@
+# zip-peek
+
+`zip-peek` lets browser applications load files from a remote `.zip` archive by only requesting the needed range of bytes without downloading and extracting the full ZIP file.
+
+It registers a service worker that intercepts requests like:
+
+```text
+https://cdn.example.com/packages/session.zip/path/to/asset.png
+```
+
+The service worker fetches only the byte range needed for the requested ZIP entry, inflates the file when required, caches the extracted response, and returns it to the browser as a normal asset response.
+
+## When Is This Package Useful?
+
+Use this package when your app receives a base path and later appends folders and file names to fetch assets from that path.
+
+For example, your app may normally treat the base path as a directory:
+
+```ts
+const basePath = 'https://cdn.example.com/packages/session';
+const imageUrl = `${basePath}/slides/slide-1/image.png`;
+```
+
+If the same assets are sometimes delivered as a ZIP file instead:
+
+```ts
+const basePath = 'https://cdn.example.com/packages/session.zip';
+const imageUrl = `${basePath}/slides/slide-1/image.png`;
+```
+
+`zip-peek` lets the app keep using the same URL-building pattern. The app does not need to know whether the base path points to a normal directory or a ZIP file, and the ZIP-specific work stays inside the service worker.
+
+## What It Does
+
+The package provides two pieces:
+
+- A browser API, `initZipPeek()`, used by your application.
+- A standalone service worker file, `zipServiceWorker.js`, that must be copied into your app's public output and served by your app. You will find a webpack sample below.
+
+At runtime, the package:
+
+1. Checks whether the provided `zipUrl` points to a `.zip` file.
+2. Registers the ZIP service worker with the configured `workerUrl` and `scopeUrl`.
+3. Reloads once after first service worker install when needed, so the page becomes controlled.
+4. Reads the ZIP central directory using HTTP range requests.
+5. Sends the parsed ZIP manifest to the service worker.
+6. Intercepts asset requests under the ZIP URL.
+7. Fetches only the byte range needed for the requested file.
+8. Inflates deflated files using `fflate`.
+9. Returns the extracted file bytes to the browser request as a normal `Response`.
+10. Caches extracted assets in the browser Cache API.
+
+## Installation
+
+```sh
+pnpm add zip-peek
+```
+
+or:
+
+```sh
+npm install zip-peek
+```
+
+## Basic Usage
+
+```ts
+import { initZipPeek } from 'zip-peek';
+
+const zipPeekInit = await initZipPeek({
+    zipUrl: 'https://cdn.example.com/packages/zipfile.zip',
+    workerUrl: new URL('/zipServiceWorker.js', window.location.origin).href,
+    scopeUrl: new URL('/', window.location.origin).href,
+});
+
+if (zipPeekInit.reloaded) {
+    return;
+}
+```
+
+After initialization, your app can continue building asset URLs under the ZIP URL:
+
+```ts
+const zipUrl = 'https://cdn.example.com/packages/zipfile.zip';
+const imgUrl = `${zipUrl}/slides/slide-1/image.png`;
+
+// This request will work normally and zip-peek will do the magic in the background:
+fetch(`${imgUrl}`);
+```
+
+The browser requests that URL normally. The service worker intercepts it and serves `slides/slide-1/image.png` from inside the ZIP.
+
+## API
+
+### `initZipPeek(options)`
+
+```ts
+type InitZipPeekOptions = {
+    zipUrl: string;
+    workerUrl: string;
+    scopeUrl: string;
+    reloadOnFirstInstall?: boolean;
+    purgeOtherZipAssets?: boolean;
+    zipAssetCacheName?: string;
+    assetCacheTtlMs?: number;
+    logPrefix?: string;
+};
+```
+
+Returns:
+
+```ts
+type InitZipPeekResult = {
+    reloaded: boolean;
+    initialized: boolean;
+};
+```
+
+### Options
+
+`zipUrl`
+
+The URL of the ZIP package. This can be absolute or relative, but it must point to a path ending in `.zip`. It can also be a presigned url.
+
+Example:
+
+```ts
+zipUrl: 'https://cdn.example.com/packages/zipfile.zip'
+zipUrl: 'https://d3jfe.cloudfront.net/somedir/zipfile.zip?Expires=1798761599&Signature=K2CJW4Z7B3DCM4&Key-Pair-Id=K2CJW4Z7B3DCM4'
+```
+
+`workerUrl`
+
+The URL where the browser can download the service worker JavaScript file. The service worker file must be served from the same origin as the page.
+
+Example:
+
+```ts
+workerUrl: new URL('./zipServiceWorker.js', window.location.href).href
+```
+
+In production, you will usually prefer hashed file to give it a long CacheControl duration:
+
+```text
+zipServiceWorker.a1b2c3d4.js
+```
+
+`scopeUrl`
+
+The service worker scope. The worker can only intercept requests inside this scope.
+
+Examples:
+
+```ts
+scopeUrl: new URL('/', window.location.origin).href
+scopeUrl: new URL('/app/', window.location.origin).href
+```
+
+Choose the smallest scope that includes the pages and asset requests you want the service worker to intercept. For local development, the scope often differs from production because the app may be served from a different path.
+
+`reloadOnFirstInstall`
+
+Defaults to `true`. When a service worker is installed for the first time, the current page may not yet be controlled by it. With this option enabled, the package reloads once and returns `{ reloaded: true, initialized: false }`.
+
+`purgeOtherZipAssets`
+
+Defaults to `true`. Removes cached assets and manifests for other ZIP URLs from this package's Cache API bucket.
+
+`zipAssetCacheName`
+
+Overrides the browser Cache API bucket used by the service worker for ZIP manifests and extracted assets.
+
+Default:
+
+```text
+zip-cache-v1
+```
+
+`assetCacheTtlMs`
+
+Controls how long extracted assets remain valid in the Cache API.
+
+Default:
+
+```ts
+2 * 60 * 60 * 1000
+```
+
+`logPrefix`
+
+Changes the service worker log prefix.
+
+Default:
+
+```text
+[zipSW]
+```
+
+## Required Server Configuration
+
+### 1. The ZIP server must support range requests
+
+The ZIP package URL must support HTTP byte range requests. The package reads the ZIP central directory and individual files using `Range` headers.
+
+The ZIP server should return:
+
+```http
+Accept-Ranges: bytes
+```
+
+For range requests, it must return:
+
+```http
+HTTP/1.1 206 Partial Content
+Content-Range: bytes start-end/total
+```
+
+If the ZIP server does not support range requests, zip-peek cannot stream individual files.
+
+### 2. The service worker file must be same-origin
+
+Browsers require service worker scripts to be served from the same origin as the page.
+
+Valid when the page is also served from `https://app.example.com`:
+
+```text
+https://app.example.com/zipServiceWorker.a1b2c3d4.js
+```
+
+Invalid if the page is on another origin:
+
+```text
+https://static-assets.example.com/zipServiceWorker.a1b2c3d4.js
+```
+
+### 3. Configure `Service-Worker-Allowed`
+
+By default, a service worker can only control pages under its own directory. If the worker file is served from a nested folder but needs to control a wider scope, the response for the worker file must include `Service-Worker-Allowed`.
+
+For an app under `/app/`, configure:
+
+```http
+Service-Worker-Allowed: /app/
+```
+
+If the worker needs to control the full origin, configure:
+
+```http
+Service-Worker-Allowed: /
+```
+
+The header must be returned on the `zipServiceWorker.js` or `zipServiceWorker.<hash>.js` response itself.
+
+### 4. Scope and worker location must match
+
+The registered scope must be allowed by both:
+
+- the worker file location
+- the `Service-Worker-Allowed` header
+
+Example:
+
+```ts
+navigator.serviceWorker.register('/app/zipServiceWorker.a1b2c3d4.js', {
+    scope: '/app/',
+});
+```
+
+This requires:
+
+```http
+Service-Worker-Allowed: /app/
+```
+
+or:
+
+```http
+Service-Worker-Allowed: /
+```
+
+## Bundler Configuration
+
+The package ships the worker as:
+
+```text
+zip-peek/zipServiceWorker.js
+```
+
+Your application must copy this file into its public build output. The browser registers service workers by URL, so the worker must exist as a real served JavaScript file.
+
+### Production with a hashed worker filename
+
+When your app emits hashed assets, copy the worker with a content hash and pass the final worker URL to `initZipPeek()`.
+
+```js
+const CopyPlugin = require('copy-webpack-plugin');
+
+module.exports = {
+    plugins: [
+        new CopyPlugin({
+            patterns: [
+                {
+                    from: require.resolve('zip-peek/zipServiceWorker.js'),
+                    to: 'zipServiceWorker.[contenthash:8].js',
+                },
+            ],
+        }),
+    ],
+};
+```
+
+You then need a way for your runtime code to know the emitted hashed filename. Common approaches include:
+
+- generating an asset manifest
+- injecting the filename at build time
+- using your framework or bundler's asset URL mechanism
+
+For example, after resolving the emitted filename:
+
+```ts
+await initZipPeek({
+    zipUrl,
+    workerUrl: new URL(`/assets/${zipServiceWorkerFilename}`, window.location.origin).href,
+    scopeUrl: new URL('/', window.location.origin).href,
+});
+```
+
+where `zipServiceWorkerFilename` is the final emitted file name, such as:
+
+```text
+zipServiceWorker.a1b2c3d4.js
+```
+
+### Development configuration
+
+In development, it is usually simpler to copy the worker without a hash:
+
+```js
+const CopyPlugin = require('copy-webpack-plugin');
+
+module.exports = {
+    plugins: [
+        new CopyPlugin({
+            patterns: [
+                {
+                    from: require.resolve('zip-peek/zipServiceWorker.js'),
+                    to: 'zipServiceWorker.js',
+                },
+            ],
+        }),
+    ],
+};
+```
+
+Then use:
+
+```ts
+await initZipPeek({
+    zipUrl,
+    workerUrl: new URL('/zipServiceWorker.js', window.location.origin).href,
+    scopeUrl: new URL('/', window.location.origin).href,
+});
+```
+
+If your app is served from a subpath, adjust both `workerUrl` and `scopeUrl` to match that path.
+
+## Caching Behavior
+
+The service worker stores:
+
+- the parsed ZIP manifest
+- extracted full assets
+
+The default cache bucket is:
+
+```text
+zip-cache-v1
+```
+
+Extracted assets expire after two hours by default. Set `assetCacheTtlMs` to customize this.
+
+When `purgeOtherZipAssets` is enabled, initializing one ZIP removes cached ZIP assets for other ZIP URLs in the same cache bucket to avoid taking too much cache size.
+
+## Limitations
+
+- The ZIP URL must end with `.zip`.
+- The ZIP server must support HTTP range requests.
+- The service worker file must be same-origin.
+- The service worker can only intercept requests inside its registered scope.
+- Supported ZIP compression methods are stored (`0`) and deflated (`8`).
+- ZIP64 is not currently supported.
+- The package is browser-only and depends on Service Worker, Cache API, and HTTP range request support.

package/dist/ZipStreamManager.d.ts

@@ -0,0 +1,19 @@
+export type ZipWorkerConfig = {
+    zipAssetCacheName?: string;
+    assetCacheTtlMs?: number;
+    logPrefix?: string;
+};
+export type ZipStreamManagerOptions = {
+    purgeOtherZipAssets?: boolean;
+    workerConfig?: ZipWorkerConfig;
+};
+export declare class ZipStreamManager {
+    /**
+     * Fetches the zip Central Directory and sends the manifest to the
+     * service worker, which then serves individual files via HTTP Range
+     * requests. The full zip is never downloaded.
+     */
+    static init(zipUrl: string, options?: ZipStreamManagerOptions): Promise<void>;
+    private static postWorkerConfig;
+    private static fetchZipManifest;
+}

package/dist/ZipStreamManager.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipStreamManager = void 0;
+const zip_utils_1 = require("./zip-utils");
+class ZipStreamManager {
+    /**
+     * Fetches the zip Central Directory and sends the manifest to the
+     * service worker, which then serves individual files via HTTP Range
+     * requests. The full zip is never downloaded.
+     */
+    static async init(zipUrl, options = {}) {
+        if (!(0, zip_utils_1.isZipPackage)(zipUrl)) {
+            return;
+        }
+        let resolvedZipUrl = '';
+        try {
+            resolvedZipUrl = new URL(zipUrl, window.location.origin).href;
+        }
+        catch {
+            resolvedZipUrl = new URL(zipUrl, window.location.href).href;
+        }
+        let resolveInit;
+        const initPromise = new Promise(res => {
+            resolveInit = res;
+        });
+        try {
+            void navigator.locks.request(`zip-init-${resolvedZipUrl}`, { ifAvailable: true }, async (lock) => {
+                if (!lock) {
+                    console.log('[ZipStreamManager] Another frame is already processing this zip. Skipping.');
+                    resolveInit?.();
+                    return;
+                }
+                this.postWorkerConfig(options.workerConfig);
+                if (options.purgeOtherZipAssets !== false && navigator.serviceWorker.controller) {
+                    const swZipUrl = (0, zip_utils_1.normalizeZipUrlForSw)(resolvedZipUrl);
+                    navigator.serviceWorker.controller.postMessage({
+                        type: 'PURGE_OTHER_ZIP_ASSETS',
+                        zipUrl: swZipUrl,
+                    });
+                }
+                try {
+                    console.log('[ZipStreamManager] Fetching zip manifest for range requests.');
+                    await this.fetchZipManifest(resolvedZipUrl, zipUrl);
+                }
+                catch (err) {
+                    console.error('[ZipStreamManager] Manifest fetch failed', err);
+                }
+                finally {
+                    resolveInit?.();
+                }
+            });
+        }
+        catch (error) {
+            console.error('[ZipStreamManager] Failed to initialize zip stream manager', error);
+            resolveInit?.();
+        }
+        await initPromise;
+    }
+    static postWorkerConfig(workerConfig) {
+        if (!navigator.serviceWorker.controller || !workerConfig) {
+            return;
+        }
+        navigator.serviceWorker.controller.postMessage({
+            type: 'ZIP_SW_CONFIG',
+            config: workerConfig,
+        });
+    }
+    static async fetchZipManifest(resolvedZipUrl, zipUrl) {
+        const response = await fetch(zipUrl, {
+            headers: {
+                Range: 'bytes=-65536',
+            },
+        });
+        if (response.status !== 206) {
+            console.warn('[ZipStreamManager] Range requests not supported (status ' + response.status + ').');
+            return;
+        }
+        const buffer = await response.arrayBuffer();
+        const dataView = new DataView(buffer);
+        let eocdOffset = -1;
+        for (let i = buffer.byteLength - 22; i >= 0; i--) {
+            if (dataView.getUint32(i, true) === 0x06054b50) {
+                eocdOffset = i;
+                break;
+            }
+        }
+        if (eocdOffset === -1) {
+            console.warn('[ZipStreamManager] EOCD not found in last 64KB');
+            return;
+        }
+        const cdOffset = dataView.getUint32(eocdOffset + 16, true);
+        const cdSize = dataView.getUint32(eocdOffset + 12, true);
+        let cdBuffer = buffer;
+        let cdStartInBuf = -1;
+        const contentRange = response.headers.get('Content-Range');
+        let totalSize = 0;
+        if (contentRange) {
+            const match = contentRange.match(/\/(\d+)$/);
+            if (match)
+                totalSize = parseInt(match[1], 10);
+        }
+        if (totalSize > 0) {
+            const rangeStart = totalSize - buffer.byteLength;
+            if (cdOffset >= rangeStart) {
+                cdStartInBuf = cdOffset - rangeStart;
+            }
+            else {
+                const cdResponse = await fetch(zipUrl, {
+                    headers: { Range: `bytes=${cdOffset}-${cdOffset + cdSize - 1}` },
+                });
+                if (cdResponse.status === 206) {
+                    cdBuffer = await cdResponse.arrayBuffer();
+                    cdStartInBuf = 0;
+                }
+                else {
+                    return;
+                }
+            }
+        }
+        else {
+            return;
+        }
+        if (cdStartInBuf === -1)
+            return;
+        const files = [];
+        const cdDataView = new DataView(cdBuffer);
+        let offset = cdStartInBuf;
+        while (offset + 46 <= cdBuffer.byteLength) {
+            if (cdDataView.getUint32(offset, true) !== 0x02014b50) {
+                break;
+            }
+            const compressionMethod = cdDataView.getUint16(offset + 10, true);
+            const compressedSize = cdDataView.getUint32(offset + 20, true);
+            const uncompressedSize = cdDataView.getUint32(offset + 24, true);
+            const fileNameLength = cdDataView.getUint16(offset + 28, true);
+            const extraFieldLength = cdDataView.getUint16(offset + 30, true);
+            const fileCommentLength = cdDataView.getUint16(offset + 32, true);
+            const localHeaderOffset = cdDataView.getUint32(offset + 42, true);
+            if (offset + 46 + fileNameLength > cdBuffer.byteLength) {
+                break;
+            }
+            const fileNameBytes = new Uint8Array(cdBuffer, offset + 46, fileNameLength);
+            const rawName = new TextDecoder().decode(fileNameBytes);
+            const fileName = (0, zip_utils_1.normalizeZipEntryPath)(rawName);
+            if (fileName !== '') {
+                files.push({
+                    filename: fileName,
+                    offset: localHeaderOffset,
+                    compressedSize,
+                    uncompressedSize,
+                    compression: compressionMethod,
+                });
+            }
+            offset += 46 + fileNameLength + extraFieldLength + fileCommentLength;
+        }
+        if (files.length === 0) {
+            console.warn('[ZipStreamManager] No files parsed from Central Directory');
+            return;
+        }
+        files.sort((a, b) => a.offset - b.offset);
+        for (let i = 0; i < files.length; i++) {
+            files[i].nextOffset = i < files.length - 1 ? files[i + 1].offset : cdOffset;
+        }
+        const swZipUrl = (0, zip_utils_1.normalizeZipUrlForSw)(resolvedZipUrl);
+        const allPaths = files.map(f => f.filename);
+        console.log('[ZipStreamManager] manifest all paths', allPaths);
+        console.log('[ZipStreamManager] manifest ready', {
+            zipUrl: swZipUrl,
+            entryCount: files.length,
+            sampleEntries: allPaths.slice(0, 30),
+        });
+        if (navigator.serviceWorker.controller) {
+            navigator.serviceWorker.controller.postMessage({
+                type: 'ZIP_MANIFEST',
+                zipUrl: swZipUrl,
+                files,
+            });
+        }
+    }
+}
+exports.ZipStreamManager = ZipStreamManager;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { ZipWorkerConfig } from './ZipStreamManager';
+import { isZipPackage } from './zip-utils';
+export type InitZipPeekOptions = {
+    zipUrl: string;
+    workerUrl: string;
+    scopeUrl: string;
+    reloadOnFirstInstall?: boolean;
+    purgeOtherZipAssets?: boolean;
+    zipAssetCacheName?: string;
+    assetCacheTtlMs?: number;
+    logPrefix?: string;
+};
+export type InitZipPeekResult = {
+    reloaded: boolean;
+    initialized: boolean;
+};
+export declare function initZipPeek({ zipUrl, workerUrl, scopeUrl, reloadOnFirstInstall, purgeOtherZipAssets, zipAssetCacheName, assetCacheTtlMs, logPrefix, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
+export { isZipPackage };
+export type { ZipWorkerConfig };

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isZipPackage = void 0;
+exports.initZipPeek = initZipPeek;
+const registerZipServiceWorker_1 = require("./registerZipServiceWorker");
+const ZipStreamManager_1 = require("./ZipStreamManager");
+const zip_utils_1 = require("./zip-utils");
+Object.defineProperty(exports, "isZipPackage", { enumerable: true, get: function () { return zip_utils_1.isZipPackage; } });
+async function initZipPeek({ zipUrl, workerUrl, scopeUrl, reloadOnFirstInstall = true, purgeOtherZipAssets = true, zipAssetCacheName, assetCacheTtlMs, logPrefix, }) {
+    if (!(0, zip_utils_1.isZipPackage)(zipUrl)) {
+        return { reloaded: false, initialized: false };
+    }
+    const reloaded = await (0, registerZipServiceWorker_1.ensureZipServiceWorkerRegistered)({
+        workerUrl,
+        scopeUrl,
+        reloadOnFirstInstall,
+    });
+    if (reloaded) {
+        return { reloaded: true, initialized: false };
+    }
+    const workerConfig = {
+        zipAssetCacheName,
+        assetCacheTtlMs,
+        logPrefix,
+    };
+    await ZipStreamManager_1.ZipStreamManager.init(zipUrl, {
+        purgeOtherZipAssets,
+        workerConfig,
+    });
+    return { reloaded: false, initialized: true };
+}

package/dist/registerZipServiceWorker.d.ts

@@ -0,0 +1,12 @@
+type RegisterZipServiceWorkerOptions = {
+    workerUrl: string;
+    scopeUrl: string;
+    reloadOnFirstInstall?: boolean;
+};
+/**
+ * Registers the zip worker script URL with the caller-provided scope.
+ *
+ * @returns true if the page is reloading and callers should abort init.
+ */
+export declare function ensureZipServiceWorkerRegistered({ workerUrl, scopeUrl, reloadOnFirstInstall, }: RegisterZipServiceWorkerOptions): Promise<boolean>;
+export {};