partial-content 1.0.0

package/src/gcs.ts

@@ -0,0 +1,290 @@
+/**
+ * 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,
+  type ObjectStore,
+  type ObjectMetadata,
+  type ObjectStream,
+  type ParsedRange,
+  type StoreErrorClassifiers,
+} from "./index.js";
+
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+
+// ─── GCS Types ──────────────────────────────────────────────────────────────
+
+/**
+ * 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; // GCS returns size as a string
+  etag?: string;
+  /** Object generation: changes on every overwrite. Used to pin reads. */
+  generation?: string | number;
+  updated?: string; // ISO 8601
+  md5Hash?: string; // base64-encoded MD5
+  crc32c?: string;
+  metadata?: Record<string, string>;
+}
+
+// ─── Options ────────────────────────────────────────────────────────────────
+
+export interface GcsStoreOptions {
+  /** Pre-configured @google-cloud/storage instance. */
+  storage: GcsStorage;
+  /** GCS bucket name. */
+  bucket: string;
+}
+
+// ─── 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: GcsStoreOptions): ObjectStore {
+  const bucket = opts.storage.bucket(opts.bucket);
+
+  return {
+    supportsRange: true,
+
+    async headObject(key: string, opts?: { signal?: AbortSignal }): Promise<ObjectMetadata> {
+      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: string, opts?: { range?: ParsedRange; signal?: AbortSignal; ifMatch?: string; pin?: string }): Promise<ObjectStream> {
+      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: string | number | undefined;
+      let totalSize: number;
+      let etag: string | undefined;
+      let lastModified: string | undefined;
+
+      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,
+      };
+    },
+  };
+}
+
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+
+/** Shape carried inside the opaque {@link ObjectMetadata.pin} token. */
+interface GcsPin {
+  generation: string | number;
+  size: number;
+  etag?: string;
+  lastModified?: string;
+}
+
+function encodeGcsPin(metadata: GcsFileMetadata): string {
+  const pin: GcsPin = {
+    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: string): GcsPin | null {
+  try {
+    const parsed: unknown = JSON.parse(pin);
+    if (
+      typeof parsed === "object" && parsed !== null &&
+      "generation" in parsed && "size" in parsed &&
+      typeof (parsed as GcsPin).size === "number" &&
+      Number.isFinite((parsed as GcsPin).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 as GcsPin).generation)
+    ) {
+      return parsed as GcsPin;
+    }
+  } 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: unknown): gen is string | number {
+  return (typeof gen === "string" && gen.length > 0) ||
+    (typeof gen === "number" && Number.isFinite(gen));
+}
+
+function isGcsNotFound(err: unknown): boolean {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    return (err as { code: unknown }).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: unknown): boolean {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = (err as { code: unknown }).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: StoreErrorClassifiers = {
+  notFound: isGcsNotFound,
+  throttled: isGcsThrottled,
+};

package/src/hono.ts

@@ -0,0 +1,123 @@
+/**
+ * Hono middleware adapter for partial-content.
+ *
+ * Wraps an {@link ObjectStore} into a Hono-compatible middleware that handles
+ * the full HTTP file-serving protocol (200, 206, 304, 412, 416, HEAD).
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { serveObject } from "partial-content/hono";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const store = s3Store({ client, bucket: "documents" });
+ * const app = new Hono();
+ *
+ * app.get("/files/:key", serveObject(store, {
+ *   key: (c) => c.req.param("key"),
+ *   disposition: "inline",
+ * }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { serveObject as serveObjectWeb, type ServeObjectOptions, type ServeContext } from "./web.js";
+import type { ObjectStore } from "./index.js";
+
+// Re-export for convenience
+export type { ServeObjectOptions, ServeContext } from "./web.js";
+export type { ObjectStore } from "./index.js";
+
+// ─── Hono Types ─────────────────────────────────────────────────────────────
+
+/**
+ * Minimal Hono context interface.
+ *
+ * We declare just enough of the Hono Context shape to avoid a hard
+ * dependency on the `hono` package. Users who import `partial-content/hono`
+ * will have `hono` installed (it's an optional peer dep), but we don't
+ * want to force TypeScript resolution on it at build time for the
+ * published package.
+ */
+interface HonoContext {
+  req: {
+    raw: Request;
+    param: (name: string) => string;
+    header: (name: string) => string | undefined;
+    method: string;
+  };
+}
+
+/** Hono handler return type. */
+type HonoResponse = Response | Promise<Response>;
+
+// ─── Options ────────────────────────────────────────────────────────────────
+
+export interface HonoServeOptions extends ServeObjectOptions {
+  /**
+   * Extract the storage key from the Hono context.
+   *
+   * @example
+   * ```ts
+   * key: (c) => c.req.param("key")
+   * key: (c) => c.req.param("path")
+   * ```
+   */
+  key: (c: HonoContext) => string | Promise<string>;
+
+  /**
+   * Extract the MIME type from the Hono context.
+   * When omitted, defaults to "application/octet-stream".
+   */
+  mime?: (c: HonoContext) => string | undefined;
+
+  /**
+   * Extract the filename from the Hono context (for Content-Disposition).
+   * When omitted, no filename is set.
+   */
+  filename?: (c: HonoContext) => string | undefined;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Hono middleware handler that serves files from an {@link ObjectStore}.
+ *
+ * Uses the standard Request/Response API under the hood, so it works on
+ * all Hono runtimes (Cloudflare Workers, Bun, Deno, Node.js).
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { serveObject } from "partial-content/hono";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const app = new Hono();
+ * const store = s3Store({ client, bucket: "media" });
+ *
+ * app.get("/media/:key", serveObject(store, {
+ *   key: (c) => c.req.param("key"),
+ *   disposition: "inline",
+ *   cacheControl: "public, max-age=31536000, immutable",
+ * }));
+ * ```
+ */
+export function serveObject(
+  store: ObjectStore,
+  opts: HonoServeOptions,
+): (c: HonoContext) => HonoResponse {
+  const { key: keyFn, mime: mimeFn, filename: filenameFn, ...serveOpts } = opts;
+  const handler = serveObjectWeb(store, serveOpts);
+
+  return async function honoHandler(c: HonoContext): Promise<Response> {
+    const key = await keyFn(c);
+    const ctx: ServeContext = {
+      key,
+      mime: mimeFn?.(c),
+      filename: filenameFn?.(c),
+    };
+
+    return handler(c.req.raw, ctx);
+  };
+}