partial-content 1.0.0

package/dist/fs.js

@@ -0,0 +1,375 @@
+/**
+ * Local filesystem ObjectStore adapter for partial-content.
+ *
+ * Implements the read-only {@link ObjectStore} interface using Node.js
+ * `fs.stat()` and `fs.createReadStream()`. Suitable for:
+ *   - Development servers
+ *   - Small/medium deployments
+ *   - Hybrid architectures (local cache + cloud primary)
+ *   - Testing and CI pipelines
+ *
+ * Security: all keys are resolved relative to a fixed root directory.
+ * Path traversal attempts (`..`), absolute paths, and null bytes are
+ * rejected with ObjectNotFoundError. Symbolic links inside the root ARE
+ * followed (matching nginx/caddy defaults); do not place untrusted
+ * symlinks under the root if it must be a strict sandbox.
+ *
+ * @example
+ * ```typescript
+ * import { fsStore } from "partial-content/fs";
+ * import { serveObject } from "partial-content/web";
+ *
+ * const store = fsStore({ root: "/var/data/uploads" });
+ *
+ * // Use with the web adapter:
+ * const handler = serveObject(store, { disposition: "inline" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { open, stat } from "node:fs/promises";
+import { resolve, relative, sep, isAbsolute } from "node:path";
+import { ObjectNotFoundError, nodeStreamToWeb, } from "./index.js";
+// Re-export for convenience (consumers can catch without importing the kernel)
+export { ObjectNotFoundError };
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create an {@link ObjectStore} backed by the local filesystem.
+ *
+ * @example
+ * ```typescript
+ * import { fsStore } from "partial-content/fs";
+ *
+ * const store = fsStore({ root: "/var/data/uploads" });
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export function fsStore(opts) {
+    const root = resolve(opts.root);
+    const cacheTtl = opts.cache?.ttlMs ?? 0;
+    const cacheMax = opts.cache?.maxEntries ?? 1024;
+    const cacheMaxBytes = opts.cache?.maxBytes ?? DEFAULT_CACHE_MAX_BYTES;
+    const cache = cacheTtl > 0 ? new Map() : null;
+    // Total bytes held by cached bodies, maintained by cacheDelete/cacheSet.
+    // Metadata-only entries contribute zero.
+    let cacheBytes = 0;
+    /** Remove an entry, keeping the body byte accounting exact. */
+    function cacheDelete(key) {
+        const prev = cache.get(key);
+        if (prev === undefined)
+            return false;
+        cacheBytes -= prev.bytes ? prev.bytes.byteLength : 0;
+        cache.delete(key);
+        return true;
+    }
+    /** Evict the least recently used entry (first in insertion order). */
+    function evictOldest() {
+        const oldest = cache.keys().next();
+        if (!oldest.done)
+            cacheDelete(oldest.value);
+    }
+    function cacheGet(key) {
+        if (!cache)
+            return null;
+        const entry = cache.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt < Date.now()) {
+            cacheDelete(key);
+            return null;
+        }
+        // LRU touch: Map preserves insertion order; re-insert marks as recent.
+        // Same entry out and in, so the byte accounting is untouched.
+        cache.delete(key);
+        cache.set(key, entry);
+        return entry;
+    }
+    function cacheSet(key, entry) {
+        if (!cache)
+            return;
+        const prev = cache.get(key);
+        // Preserve a cached body across a metadata-only write-back: a range GET
+        // refreshes metadata but carries no bytes, and blindly replacing the
+        // entry would evict a still-valid full body (same representation) and
+        // force the next full GET back to disk. Keep the bytes when the
+        // representation is unchanged (same weak/strong validator); drop them
+        // when the etag moved (the file changed -> old bytes are stale).
+        const carried = (entry.bytes === undefined && prev?.bytes && prev.etag === entry.etag)
+            ? { ...entry, bytes: prev.bytes }
+            : entry;
+        // A body that alone exceeds the byte budget can never fit: store the
+        // entry metadata-only rather than evicting every other body and still
+        // failing. The object itself is unaffected (this GET already served it).
+        const stored = carried.bytes && carried.bytes.byteLength > cacheMaxBytes
+            ? { totalSize: carried.totalSize, lastModified: carried.lastModified, etag: carried.etag }
+            : carried;
+        // Delete-before-set: Map.set on an existing key keeps its old insertion
+        // order, so a refresh must re-insert to reach the most-recent LRU slot.
+        // It also makes eviction conditional on genuinely growing the map --
+        // refreshing a hot key at capacity must not evict an unrelated entry.
+        const existed = cacheDelete(key);
+        if (!existed && cache.size >= cacheMax) {
+            evictOldest();
+        }
+        // Byte budget: evict least-recent entries until the new body fits.
+        const newBytes = stored.bytes ? stored.bytes.byteLength : 0;
+        while (newBytes > 0 && cacheBytes + newBytes > cacheMaxBytes && cache.size > 0) {
+            evictOldest();
+        }
+        cache.set(key, { ...stored, expiresAt: Date.now() + cacheTtl });
+        cacheBytes += newBytes;
+    }
+    /**
+     * Resolve a key to an absolute path within the root directory.
+     * Rejects path traversal attempts that escape the root.
+     */
+    function safePath(key) {
+        // Null bytes are invalid in every filesystem and are a classic probe for
+        // C-string truncation bugs in lower layers. Treat as "no such object"
+        // rather than letting fs throw ERR_INVALID_ARG_VALUE (which would map
+        // to a misleading 502 upstream).
+        if (key.includes("\0")) {
+            throw new ObjectNotFoundError(key);
+        }
+        // Windows-only hardening (sep === "\\"). ':' is illegal in a normal
+        // Windows filename -- it only appears in a drive designator ("D:\x")
+        // or an NTFS alternate-data-stream name ("secret.txt::$DATA"). Rejecting
+        // it early stops a cross-volume escape (resolve() would turn "D:\x" into
+        // an absolute path on another drive) and hidden-stream access. Reserved
+        // device names (NUL, CON, COM1...) map to hardware from ANY directory,
+        // so open() on them never touches a file under the root.
+        if (sep === "\\") {
+            if (key.includes(":")) {
+                throw new ObjectNotFoundError(key);
+            }
+            const base = key.slice(Math.max(key.lastIndexOf("/"), key.lastIndexOf("\\")) + 1);
+            if (/^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i.test(base)) {
+                throw new ObjectNotFoundError(key);
+            }
+        }
+        const resolved = resolve(root, key);
+        const rel = relative(root, resolved);
+        // rel escapes the root when it climbs out ("..") or is itself absolute.
+        // A cross-drive key resolves onto another volume and relative() then
+        // returns that absolute path unchanged, which a bare startsWith("..")
+        // check would wave through.
+        if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) {
+            throw new ObjectNotFoundError(key);
+        }
+        return resolved;
+    }
+    return {
+        supportsRange: true,
+        async headObject(key, opts) {
+            opts?.signal?.throwIfAborted();
+            const cached = cacheGet(key);
+            if (cached) {
+                return {
+                    contentLength: cached.totalSize,
+                    lastModified: cached.lastModified,
+                    etag: cached.etag,
+                };
+            }
+            const filePath = safePath(key);
+            let stats;
+            try {
+                stats = await stat(filePath, { bigint: true });
+            }
+            catch (err) {
+                if (isFileNotFound(err))
+                    throw new ObjectNotFoundError(key, err);
+                throw err;
+            }
+            if (!stats.isFile()) {
+                throw new ObjectNotFoundError(key);
+            }
+            const meta = {
+                totalSize: Number(stats.size),
+                lastModified: stats.mtime.toUTCString(),
+                // Derive the weak validator once per stat instead of letting the
+                // orchestrator re-parse the Last-Modified string on every request
+                // (Date.parse on the serve hot path is measurable at 10k req/s).
+                etag: weakFsETag(stats.size, stats.mtimeNs),
+            };
+            cacheSet(key, meta);
+            return {
+                contentLength: meta.totalSize,
+                lastModified: meta.lastModified,
+                etag: meta.etag,
+            };
+        },
+        async getObject(key, opts) {
+            const { range, signal } = opts ?? {};
+            signal?.throwIfAborted();
+            // Hot path: a cached small body serves ranges and full reads as
+            // zero-copy subarray views -- no syscalls at all. Metadata-only
+            // entries (from headObject) cannot serve bytes and fall through.
+            const cached = cacheGet(key);
+            if (cached?.bytes) {
+                if (range && range.start >= cached.totalSize) {
+                    // Unsatisfiable ranges are the orchestrator's job to reject
+                    // (parseRangeHeader 416s them first); a direct caller gets a loud
+                    // error instead of an empty body with lying bounds.
+                    throw new RangeError(`fsStore ${key}: range start ${range.start} is beyond object size ${cached.totalSize}`);
+                }
+                // Clamp so ObjectStream.range always reports the bounds actually
+                // served, even for a direct caller passing an unclamped range.
+                const bytes = range
+                    ? cached.bytes.subarray(range.start, Math.min(range.end + 1, cached.totalSize))
+                    : cached.bytes;
+                return {
+                    // Node fs read buffers are ArrayBuffer-backed; narrow so the body is
+                    // `new Response(...)`-assignable under DOM lib (F5).
+                    body: bytes,
+                    contentLength: bytes.length,
+                    totalSize: cached.totalSize,
+                    range: range ? { start: range.start, end: range.start + bytes.length - 1 } : undefined,
+                    lastModified: cached.lastModified,
+                    etag: cached.etag,
+                };
+            }
+            const filePath = safePath(key);
+            // Open once and both stat and stream from the same file handle. A
+            // stat-then-reopen sequence races against file replacement: the stream
+            // could read a different (shorter) file than the one measured, producing
+            // a Content-Length that doesn't match the bytes sent.
+            let handle;
+            try {
+                handle = await open(filePath, "r");
+            }
+            catch (err) {
+                if (isFileNotFound(err))
+                    throw new ObjectNotFoundError(key, err);
+                throw err;
+            }
+            let stats;
+            try {
+                stats = await handle.stat({ bigint: true });
+                if (!stats.isFile())
+                    throw new ObjectNotFoundError(key);
+            }
+            catch (err) {
+                await handle.close().catch(() => {
+                    // Best-effort close; the stat/isFile error is the one that matters
+                });
+                throw err;
+            }
+            const totalSize = Number(stats.size);
+            const lastModified = stats.mtime.toUTCString();
+            const etag = weakFsETag(stats.size, stats.mtimeNs);
+            if (range && range.start >= totalSize) {
+                await handle.close().catch(() => {
+                    // Best-effort close; the range error is the one that matters
+                });
+                throw new RangeError(`fsStore ${key}: range start ${range.start} is beyond object size ${totalSize}`);
+            }
+            // Clamp the end so served bounds always reflect the file's actual
+            // size (the orchestrator pre-clamps; direct callers may not).
+            const end = range ? Math.min(range.end, totalSize - 1) : totalSize - 1;
+            const contentLength = range ? end - range.start + 1 : totalSize;
+            // Small transfers: one exact-length positional read, close, and a
+            // single-chunk stream. Skips the ReadStream + async-iterator bridge
+            // machinery entirely, which dominates per-request cost for small
+            // files (the memory bound is SMALL_READ_LIMIT per in-flight request).
+            if (contentLength <= SMALL_READ_LIMIT) {
+                // Cache-destined buffers are allocated off-pool: for small sizes
+                // allocUnsafe returns a view into Node's shared 8 KiB slab, and a
+                // long-lived cache entry would pin the whole slab and expose
+                // adjacent slab bytes to any consumer that reads `.buffer` without
+                // honoring byteOffset. Only full-object reads populate bytes: a
+                // range slice is not the whole body, and mixing partial bytes into
+                // the cache would serve wrong content for other ranges.
+                const willCache = cache !== null && !range && contentLength === totalSize;
+                const buffer = willCache
+                    ? Buffer.allocUnsafeSlow(contentLength)
+                    : Buffer.allocUnsafe(contentLength);
+                try {
+                    const { bytesRead } = await handle.read(buffer, 0, contentLength, range?.start ?? 0);
+                    // The handle's own stat promised these bytes; a short read means
+                    // the file was truncated mid-request. Failing here (502, before
+                    // headers) beats the streaming path's only option of a torn body.
+                    if (bytesRead < contentLength) {
+                        throw new Error(`fsStore ${key}: file shrank during read (expected ${contentLength} bytes, got ${bytesRead})`);
+                    }
+                }
+                finally {
+                    await handle.close().catch(() => {
+                        // Best-effort close; the bytes (or the read error) already decide the outcome
+                    });
+                }
+                if (willCache) {
+                    cacheSet(key, { totalSize, lastModified, etag, bytes: buffer });
+                }
+                else {
+                    // Metadata write-back: every disk read refreshes the entry so
+                    // HEAD/conditional traffic converges on the representation this
+                    // GET actually served instead of a stale headObject snapshot.
+                    cacheSet(key, { totalSize, lastModified, etag });
+                }
+                return {
+                    body: buffer,
+                    contentLength,
+                    totalSize,
+                    range: range ? { start: range.start, end } : undefined,
+                    lastModified,
+                    etag,
+                };
+            }
+            // autoClose (default true) closes the handle when the stream ends or
+            // is destroyed, covering completion, cancel, and abort paths.
+            const nodeStream = handle.createReadStream(range ? { start: range.start, end } : {});
+            // expectedBytes mirrors the small-read path's short-read guard onto the
+            // streaming path: an in-place truncation mid-serve ends the ReadStream
+            // early, and without this the body would under-run the committed
+            // Content-Length silently. The atomic write-temp+rename overwrite pattern
+            // does not trip it (the open handle keeps reading the original inode).
+            const webStream = nodeStreamToWeb(nodeStream, { signal, expectedBytes: contentLength });
+            // Metadata write-back (bytes stay uncached above the single-read
+            // limit): keeps HEAD/conditional responses coherent with the
+            // representation this GET is serving.
+            cacheSet(key, { totalSize, lastModified, etag });
+            return {
+                body: webStream,
+                contentLength,
+                totalSize,
+                range: range ? { start: range.start, end } : undefined,
+                lastModified,
+                etag,
+            };
+        },
+    };
+}
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+/**
+ * Transfers at or below this size are served by a single positional read
+ * instead of a ReadStream. 128 KiB covers typical documents, thumbnails,
+ * and range chunks while bounding per-request buffering.
+ */
+const SMALL_READ_LIMIT = 128 * 1024;
+/**
+ * Default total byte budget for cached bodies (64 MiB). Together with the
+ * entry cap this bounds the cache's worst-case footprint explicitly, instead
+ * of leaving it implied by `maxEntries * SMALL_READ_LIMIT`.
+ */
+const DEFAULT_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * Weak validator from size + NANOSECOND mtime (bigint stat).
+ *
+ * The kernel's generic formatter floors mtime to whole seconds; on a
+ * filesystem store that recreates the classic weak-ETag hazard: two
+ * same-length writes within one second are indistinguishable, and a
+ * revalidating client gets a false-fresh 304 for changed bytes. Nanosecond
+ * resolution closes that window on ext4/APFS/NTFS; filesystems with coarse
+ * timestamps (FAT: 2 s) keep a residual window, documented in DESIGN.md.
+ */
+function weakFsETag(size, mtimeNs) {
+    return `W/"${size.toString(16)}-${mtimeNs.toString(16)}"`;
+}
+function isFileNotFound(err) {
+    if (err instanceof Error && "code" in err) {
+        const code = err.code;
+        return code === "ENOENT" || code === "ENOTDIR";
+    }
+    return false;
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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"}

package/dist/gcs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Google Cloud Storage ObjectStore adapter for partial-content.
+ *
+ * Wraps `@google-cloud/storage` to implement the {@link ObjectStore} interface.
+ *
+ * @example
+ * ```typescript
+ * import { Storage } from "@google-cloud/storage";
+ * import { gcsStore } from "partial-content/gcs";
+ *
+ * const storage = new Storage();
+ * const store = gcsStore({ storage, bucket: "my-bucket" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError, type ObjectStore } from "./index.js";
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+/**
+ * Minimal GCS Storage interface.
+ *
+ * Declared locally to avoid a hard dependency on `@google-cloud/storage`.
+ * Users who import `partial-content/gcs` will have it installed as an
+ * optional peer dependency.
+ */
+interface GcsStorage {
+    bucket(name: string): GcsBucket;
+}
+interface GcsBucket {
+    file(name: string, opts?: {
+        generation?: string | number;
+    }): GcsFile;
+}
+interface GcsFile {
+    getMetadata(): Promise<[GcsFileMetadata]>;
+    createReadStream(opts?: {
+        start?: number;
+        end?: number;
+    }): NodeJS.ReadableStream & AsyncIterable<Buffer>;
+}
+interface GcsFileMetadata {
+    size: string;
+    etag?: string;
+    /** Object generation: changes on every overwrite. Used to pin reads. */
+    generation?: string | number;
+    updated?: string;
+    md5Hash?: string;
+    crc32c?: string;
+    metadata?: Record<string, string>;
+}
+export interface GcsStoreOptions {
+    /** Pre-configured @google-cloud/storage instance. */
+    storage: GcsStorage;
+    /** GCS bucket name. */
+    bucket: string;
+}
+/**
+ * Create an {@link ObjectStore} backed by a Google Cloud Storage bucket.
+ *
+ * @example
+ * ```typescript
+ * import { Storage } from "@google-cloud/storage";
+ * import { gcsStore } from "partial-content/gcs";
+ *
+ * const storage = new Storage();
+ * const store = gcsStore({ storage, bucket: "my-bucket" });
+ *
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export declare function gcsStore(opts: GcsStoreOptions): ObjectStore;
+//# sourceMappingURL=gcs.d.ts.map

package/dist/gcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs.d.ts","sourceRoot":"","sources":["../src/gcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EAGrB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;AAI1E;;;;;;GAMG;AACH,UAAU,UAAU;IAClB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,UAAU,SAAS;IACjB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;CACtE;AAED,UAAU,OAAO;IACf,WAAW,IAAI,OAAO,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1C,gBAAgB,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1G;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAID,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,OAAO,EAAE,UAAU,CAAC;IACpB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAsH3D"}

package/dist/gcs.js

@@ -0,0 +1,202 @@
+/**
+ * Google Cloud Storage ObjectStore adapter for partial-content.
+ *
+ * Wraps `@google-cloud/storage` to implement the {@link ObjectStore} interface.
+ *
+ * @example
+ * ```typescript
+ * import { Storage } from "@google-cloud/storage";
+ * import { gcsStore } from "partial-content/gcs";
+ *
+ * const storage = new Storage();
+ * const store = gcsStore({ storage, bucket: "my-bucket" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError, classifyStoreRead, nodeStreamToWeb, } from "./index.js";
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create an {@link ObjectStore} backed by a Google Cloud Storage bucket.
+ *
+ * @example
+ * ```typescript
+ * import { Storage } from "@google-cloud/storage";
+ * import { gcsStore } from "partial-content/gcs";
+ *
+ * const storage = new Storage();
+ * const store = gcsStore({ storage, bucket: "my-bucket" });
+ *
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export function gcsStore(opts) {
+    const bucket = opts.storage.bucket(opts.bucket);
+    return {
+        supportsRange: true,
+        async headObject(key, opts) {
+            opts?.signal?.throwIfAborted();
+            const [metadata] = await classifyStoreRead(key, () => bucket.file(key).getMetadata(), gcsClassifiers);
+            return {
+                contentLength: parseInt(metadata.size, 10),
+                etag: metadata.etag,
+                lastModified: metadata.updated
+                    ? new Date(metadata.updated).toUTCString()
+                    : undefined,
+                // A generation names an immutable object version, so it can carry
+                // everything getObject would otherwise re-fetch. No generation
+                // (emulators, mocks) means no pin: getObject falls back to its own
+                // metadata read.
+                pin: metadata.generation !== undefined
+                    ? encodeGcsPin(metadata)
+                    : undefined,
+            };
+        },
+        async getObject(key, opts) {
+            const { range, signal, ifMatch, pin } = opts ?? {};
+            signal?.throwIfAborted();
+            // A pin from our own headObject carries the generation, size, and
+            // validators of the exact representation the caller validated, so the
+            // metadata re-fetch is skipped entirely: one backend read per GET.
+            // A pin whose etag disagrees with ifMatch (or that fails to decode)
+            // is ignored and the metadata path revalidates from scratch. When an
+            // ifMatch is present the pin must carry a matching etag to be trusted:
+            // a pin lacking the validator cannot silently satisfy the precondition,
+            // it falls through to the metadata path that actually enforces ifMatch.
+            const pinned = pin ? decodeGcsPin(pin) : null;
+            const usablePin = pinned && (!ifMatch || pinned.etag === ifMatch)
+                ? pinned
+                : null;
+            let generation;
+            let totalSize;
+            let etag;
+            let lastModified;
+            if (usablePin) {
+                generation = usablePin.generation;
+                totalSize = usablePin.size;
+                etag = usablePin.etag;
+                lastModified = usablePin.lastModified;
+            }
+            else {
+                // GCS streams carry no total size, the ifMatch check needs the
+                // current etag, and generation pinning needs the current generation.
+                const [metadata] = await classifyStoreRead(key, () => bucket.file(key).getMetadata(), gcsClassifiers);
+                // Caller pin: the object must still match the validator captured at
+                // HEAD time. GCS etags change on every overwrite, so a mismatch means
+                // the representation the caller validated no longer exists.
+                if (ifMatch && metadata.etag && metadata.etag !== ifMatch) {
+                    throw new ObjectChangedError(key);
+                }
+                generation = metadata.generation;
+                totalSize = parseInt(metadata.size, 10);
+                etag = metadata.etag;
+                lastModified = metadata.updated
+                    ? new Date(metadata.updated).toUTCString()
+                    : undefined;
+            }
+            if (range && range.start >= totalSize) {
+                // Unsatisfiable ranges are the orchestrator's job to reject
+                // (parseRangeHeader 416s them first); a direct caller gets a loud
+                // error instead of a truncated body under an inflated Content-Length.
+                throw new RangeError(`gcsStore ${key}: range start ${range.start} is beyond object size ${totalSize}`);
+            }
+            // Clamp the end so contentLength and the reported range match what
+            // the backend stream will actually deliver (createReadStream clamps
+            // to EOF silently; the reported bounds must not diverge from it).
+            const end = range ? Math.min(range.end, totalSize - 1) : totalSize - 1;
+            const streamOpts = range
+                ? { start: range.start, end }
+                : undefined;
+            // Pin the stream to the generation just measured (or the caller's
+            // pinned generation): metadata and bytes come from the SAME object
+            // version even if it is overwritten between the two calls (reading a
+            // specific generation is immutable in GCS).
+            const pinnedFile = generation !== undefined
+                ? bucket.file(key, { generation })
+                : bucket.file(key);
+            const nodeStream = pinnedFile.createReadStream(streamOpts);
+            const contentLength = range
+                ? (end - range.start + 1)
+                : totalSize;
+            // nodeStreamToWeb auto-detects the stream's destroy() capability.
+            // expectedBytes guards a graceful short-read: a truncated GCS download
+            // that ends cleanly below the committed length errors the body instead
+            // of under-running the Content-Length undetected.
+            const webStream = nodeStreamToWeb(nodeStream, { signal, expectedBytes: contentLength });
+            return {
+                body: webStream,
+                contentLength,
+                totalSize,
+                range: range ? { start: range.start, end } : undefined,
+                etag,
+                lastModified,
+            };
+        },
+    };
+}
+function encodeGcsPin(metadata) {
+    const pin = {
+        generation: metadata.generation,
+        size: parseInt(metadata.size, 10),
+        etag: metadata.etag,
+        lastModified: metadata.updated
+            ? new Date(metadata.updated).toUTCString()
+            : undefined,
+    };
+    return JSON.stringify(pin);
+}
+/** Decode a pin token; null for foreign/corrupt tokens (fall back to metadata). */
+function decodeGcsPin(pin) {
+    try {
+        const parsed = JSON.parse(pin);
+        if (typeof parsed === "object" && parsed !== null &&
+            "generation" in parsed && "size" in parsed &&
+            typeof parsed.size === "number" &&
+            Number.isFinite(parsed.size) &&
+            // `generation` flows straight into bucket.file(key, { generation }) and
+            // selects the immutable version served. Only a non-empty string or a
+            // finite number is a real generation; anything else (object, array,
+            // null) is a corrupt/hostile token that must revalidate from scratch,
+            // never index an arbitrary version.
+            isValidGeneration(parsed.generation)) {
+            return parsed;
+        }
+    }
+    catch { /* not our token: revalidate via metadata instead */ }
+    return null;
+}
+/** A GCS generation is a non-empty string or a finite number; nothing else. */
+function isValidGeneration(gen) {
+    return (typeof gen === "string" && gen.length > 0) ||
+        (typeof gen === "number" && Number.isFinite(gen));
+}
+function isGcsNotFound(err) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+        return err.code === 404;
+    }
+    return false;
+}
+/**
+ * Whether a GCS error is a transient throttle/overload the client should retry
+ * (mapped to a 503, not a 502). The Cloud Storage client surfaces the HTTP
+ * status on `err.code`: 429 (rate limit) or 503 (backend unavailable).
+ */
+function isGcsThrottled(err) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+        const code = err.code;
+        return code === 429 || code === 503;
+    }
+    return false;
+}
+/**
+ * The error-classification set shared by both metadata reads. GCS has no
+ * `changed` predicate: its pin is an etag comparison (handled inline, throwing
+ * {@link ObjectChangedError} directly), not a native conditional error.
+ */
+const gcsClassifiers = {
+    notFound: isGcsNotFound,
+    throttled: isGcsThrottled,
+};
+//# sourceMappingURL=gcs.js.map