partial-content 1.0.0

package/src/memory.ts

@@ -0,0 +1,148 @@
+/**
+ * In-memory ObjectStore for partial-content.
+ *
+ * A complete, spec-faithful store over a plain object map. Built for:
+ * - **Consumer test suites** -- exercise your serving routes (ranges,
+ *   conditionals, pinned-read retries) without a storage backend.
+ * - **Demos and examples** -- a working store in three lines.
+ * - **Small embedded assets** -- serve a handful of in-process files with
+ *   the full 200/206/304 protocol.
+ *
+ * Faithful to the contract: real Content-Range fabrication, `ifMatch`
+ * pinning (mismatch throws {@link ObjectChangedError}, so retry logic is
+ * testable), and per-object validators.
+ *
+ * @example
+ * ```typescript
+ * import { memoryStore } from "partial-content/memory";
+ * import { serveObject } from "partial-content/web";
+ *
+ * const store = memoryStore({
+ *   objects: {
+ *     "hello.txt": { body: "Hello, world!", etag: '"v1"' },
+ *   },
+ * });
+ * const handler = serveObject(store);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import {
+  ObjectNotFoundError,
+  ObjectChangedError,
+  type ObjectStore,
+  type ObjectMetadata,
+  type ObjectStream,
+  type ParsedRange,
+} from "./index.js";
+
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError };
+
+// ─── Options ────────────────────────────────────────────────────────────────
+
+/** A stored object: body plus optional validators and integrity metadata. */
+export interface MemoryObject {
+  /** Object content. Strings are encoded as UTF-8. */
+  body: Uint8Array | string;
+  /** Raw ETag (quoted, like a backend would return). */
+  etag?: string;
+  /** Last-Modified (any `Date.parse`-able string). */
+  lastModified?: string;
+  /** RFC 9530 raw base64 SHA-256 digest of the body. */
+  digest?: string;
+}
+
+export interface MemoryStoreOptions {
+  /**
+   * Key -> object map. Held BY REFERENCE: mutate it between requests to
+   * simulate uploads, overwrites (change `etag` to trigger pinned-read
+   * retries), and deletions.
+   */
+  objects: Record<string, MemoryObject>;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create an {@link ObjectStore} over an in-memory object map.
+ */
+export function memoryStore(opts: MemoryStoreOptions): ObjectStore {
+  const encoder = new TextEncoder();
+  // Cache the UTF-8 encoding of string bodies so a hot-served asset is not
+  // re-encoded on every head + get. The map is keyed by the entry and holds
+  // the exact string it encoded: the objects map is mutable by reference
+  // (the documented way to simulate overwrites), so a changed body misses
+  // the cache and re-encodes rather than serving stale bytes.
+  const encodeCache = new WeakMap<MemoryObject, { source: string; bytes: Uint8Array }>();
+
+  function lookup(key: string): { entry: MemoryObject; bytes: Uint8Array } {
+    // Own-property check: the map is a caller-supplied plain object, so an
+    // inherited key ("constructor", "__proto__", "toString") would otherwise
+    // return a truthy prototype member and crash downstream as a 502 instead
+    // of answering the honest 404.
+    const entry = Object.hasOwn(opts.objects, key) ? opts.objects[key] : undefined;
+    if (!entry) throw new ObjectNotFoundError(key);
+    if (typeof entry.body !== "string") return { entry, bytes: entry.body };
+    const cached = encodeCache.get(entry);
+    if (cached && cached.source === entry.body) return { entry, bytes: cached.bytes };
+    const bytes = encoder.encode(entry.body);
+    encodeCache.set(entry, { source: entry.body, bytes });
+    return { entry, bytes };
+  }
+
+  return {
+    supportsRange: true,
+
+    async headObject(key: string, opts?: { signal?: AbortSignal }): Promise<ObjectMetadata> {
+      opts?.signal?.throwIfAborted();
+      const { entry, bytes } = lookup(key);
+      return {
+        contentLength: bytes.length,
+        etag: entry.etag,
+        lastModified: entry.lastModified,
+        digest: entry.digest,
+      };
+    },
+
+    async getObject(
+      key: string,
+      getOpts?: { range?: ParsedRange; signal?: AbortSignal; ifMatch?: string },
+    ): Promise<ObjectStream> {
+      const { range, signal, ifMatch } = getOpts ?? {};
+      signal?.throwIfAborted();
+      const { entry, bytes } = lookup(key);
+
+      // Pinned read: the object must still match the caller's validator.
+      if (ifMatch && entry.etag !== ifMatch) {
+        throw new ObjectChangedError(key);
+      }
+
+      if (range && range.start >= bytes.length) {
+        // 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(
+          `memoryStore ${key}: range start ${range.start} is beyond object size ${bytes.length}`,
+        );
+      }
+      // subarray() clamps to the object size and returns a view (no copy);
+      // the served bytes are read-only, so a view is safe. Derive the reported
+      // range from the actual slice so ObjectStream.range is the SERVED bounds.
+      const slice = range ? bytes.subarray(range.start, range.end + 1) : bytes;
+      return {
+        // In-memory bytes are ArrayBuffer-backed (TextEncoder output or the
+        // caller's view); narrow so the body is `new Response(...)`-assignable
+        // under DOM lib (F5).
+        body: slice as Uint8Array<ArrayBuffer>,
+        contentLength: slice.length,
+        totalSize: bytes.length,
+        range: range ? { start: range.start, end: range.start + slice.length - 1 } : undefined,
+        etag: entry.etag,
+        lastModified: entry.lastModified,
+        digest: entry.digest,
+      };
+    },
+  };
+}

package/src/mime.ts

@@ -0,0 +1,160 @@
+/**
+ * Minimal MIME type lookup for file serving.
+ *
+ * A curated extension -> MIME map covering the formats that actually flow
+ * through document/media serving: office documents, images, audio/video,
+ * archives, fonts, and web assets. Deliberately small and auditable rather
+ * than exhaustive -- for the long tail, pass an explicit `mime` to the
+ * serve handler or bring a full database (`mime-types`, `mrmime`).
+ *
+ * Zero dependencies, aligned with IANA registrations and the WHATWG
+ * mimesniff living standard.
+ *
+ * @example
+ * ```typescript
+ * import { serveObject } from "partial-content/node";
+ * import { fsStore } from "partial-content/fs";
+ * import { lookupMime } from "partial-content/mime";
+ *
+ * const handler = serveObject(fsStore({ root: "/data" }), {
+ *   key: (req) => req.params.key,
+ *   mime: (req) => lookupMime(req.params.key),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// ─── Extension Map ──────────────────────────────────────────────────────────
+
+/**
+ * Extension (lowercase, no dot) -> MIME type.
+ *
+ * Security-relevant choices:
+ * - `html`/`htm`/`xhtml` are intentionally ABSENT: serving stored user
+ *   uploads as `text/html` is stored XSS. If you serve trusted HTML, pass
+ *   the MIME explicitly so the decision is visible at the call site.
+ * - Several mapped types are ACTIVE CONTENT that can execute script when
+ *   rendered `inline` from your own origin. For untrusted uploads serve
+ *   them `attachment` (the library's default disposition) or behind a
+ *   strict CSP -- never plain `inline`:
+ *     - `svg`  -> `image/svg+xml`   (embedded `<script>`, event handlers)
+ *     - `pdf`  -> `application/pdf` (embedded JavaScript in the viewer)
+ *     - `xml`  -> `application/xml` (`<?xml-stylesheet?>` can run XSLT)
+ *   `X-Content-Type-Options: nosniff` and the default `attachment`
+ *   disposition already protect the built-in serve path; the warning
+ *   matters when a caller overrides `disposition: "inline"`.
+ */
+const MIME_TYPES: Record<string, string> = {
+  // Documents
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  csv: "text/csv",
+  json: "application/json",
+  xml: "application/xml",
+  rtf: "application/rtf",
+  epub: "application/epub+zip",
+  ics: "text/calendar",
+  vcf: "text/vcard",
+
+  // Office (OOXML + legacy + OpenDocument)
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  odt: "application/vnd.oasis.opendocument.text",
+  ods: "application/vnd.oasis.opendocument.spreadsheet",
+  odp: "application/vnd.oasis.opendocument.presentation",
+
+  // Images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+  bmp: "image/bmp",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  heic: "image/heic",
+
+  // Audio
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  oga: "audio/ogg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  flac: "audio/flac",
+  opus: "audio/opus",
+
+  // Video
+  mp4: "video/mp4",
+  m4v: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo",
+  mkv: "video/x-matroska",
+  ogv: "video/ogg",
+
+  // Archives
+  zip: "application/zip",
+  gz: "application/gzip",
+  tar: "application/x-tar",
+  "7z": "application/x-7z-compressed",
+  rar: "application/vnd.rar",
+
+  // Fonts
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+
+  // Web assets
+  js: "text/javascript",
+  mjs: "text/javascript",
+  css: "text/css",
+  wasm: "application/wasm",
+};
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Look up the MIME type for a filename, path, storage key, or bare extension.
+ *
+ * Matching is case-insensitive and uses the LAST dot segment, so keys like
+ * `2025/reports/Q4 Report.PDF` and `archive.tar.gz` resolve correctly
+ * (`application/pdf`, `application/gzip`).
+ *
+ * Returns `undefined` for unknown or missing extensions so the caller
+ * controls the fallback (the serve handlers default to
+ * `application/octet-stream`, the safe choice for unknown content).
+ *
+ * @example
+ * ```typescript
+ * lookupMime("report.pdf");          // "application/pdf"
+ * lookupMime("Q4 Report.PDF");       // "application/pdf"
+ * lookupMime("archive.tar.gz");      // "application/gzip"
+ * lookupMime("pdf");                 // "application/pdf" (bare extension)
+ * lookupMime("unknown.xyz");         // undefined
+ * lookupMime("no-extension");        // undefined (unless it IS an extension)
+ * ```
+ */
+export function lookupMime(filenameOrExt: string | null | undefined): string | undefined {
+  if (!filenameOrExt) return undefined;
+
+  const lastDot = filenameOrExt.lastIndexOf(".");
+  // No dot: treat the whole input as a bare extension ("pdf" -> pdf).
+  // Trailing dot ("file.") yields an empty extension -> undefined.
+  const ext = lastDot === -1
+    ? filenameOrExt
+    : filenameOrExt.slice(lastDot + 1);
+
+  if (!ext) return undefined;
+  return MIME_TYPES[ext.toLowerCase()];
+}

package/src/node.ts

@@ -0,0 +1,261 @@
+/**
+ * Node.js HTTP adapter for partial-content.
+ *
+ * Bridges the gap between Node.js `IncomingMessage`/`ServerResponse` and the
+ * Fetch-based `partial-content/web` handler. Works with Express, Fastify
+ * (in compatibility mode), Koa, raw `http.createServer`, and any Node.js
+ * HTTP framework that exposes the standard request/response objects.
+ *
+ * @example Express
+ * ```typescript
+ * import express from "express";
+ * import { serveObject } from "partial-content/node";
+ * import { fsStore } from "partial-content/fs";
+ *
+ * const store = fsStore({ root: "./uploads" });
+ * const app = express();
+ *
+ * app.get("/files/:key", serveObject(store, {
+ *   key: (req) => req.params.key,
+ *   disposition: "inline",
+ * }));
+ * ```
+ *
+ * @example raw http.createServer
+ * ```typescript
+ * import { createServer } from "node:http";
+ * import { serveObject } from "partial-content/node";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const store = s3Store({ client, bucket: "docs" });
+ * const handler = serveObject(store, {
+ *   key: (req) => new URL(req.url!, `http://${req.headers.host}`).pathname.slice(1),
+ * });
+ *
+ * createServer((req, res) => handler(req, res)).listen(3000);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { serveObjectRaw, type RawResponseParts, type ServeObjectOptions, type ServeContext } from "./web.js";
+import type { ObjectStore } from "./index.js";
+
+// ─── Options ────────────────────────────────────────────────────────────────
+
+export interface NodeServeOptions extends ServeObjectOptions {
+  /**
+   * Extract the storage key from the incoming request.
+   * The request object is the raw Node.js IncomingMessage, so you have
+   * access to URL, params (if using Express/Fastify), headers, etc.
+   */
+  key: (req: IncomingMessage) => string | Promise<string>;
+
+  /**
+   * Extract the MIME type from the request.
+   * When omitted, defaults to "application/octet-stream".
+   */
+  mime?: (req: IncomingMessage) => string | undefined;
+
+  /**
+   * Extract the filename from the request (for Content-Disposition).
+   * When omitted, no filename is set.
+   */
+  filename?: (req: IncomingMessage) => string | undefined;
+
+  /**
+   * Max milliseconds to wait for a single backpressure `drain` while streaming
+   * before treating the client as stalled and tearing the transfer down.
+   *
+   * A client that stops reading but holds its socket open (a slow-read attack)
+   * fills the send buffer, so `res.write()` returns false and `drain` never
+   * fires. Without a bound the stream pump would wait forever, pinning the
+   * backend storage socket (and its connection-pool slot). A stall reliably
+   * tears down via the existing error path (cancel the reader, destroy the
+   * response). Set to `0` to disable and rely on an upstream proxy / socket
+   * timeout instead.
+   *
+   * @default 60000
+   */
+  writeStallTimeoutMs?: number;
+}
+
+/** Default backpressure stall bound: 60s of zero drain is a stalled reader. */
+const DEFAULT_WRITE_STALL_MS = 60_000;
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Node.js request handler that serves files from an {@link ObjectStore}.
+ *
+ * Converts Node.js `IncomingMessage` to a Fetch `Request`, delegates to the
+ * web adapter's `serveObject`, then writes the Fetch `Response` back to the
+ * Node.js `ServerResponse`.
+ */
+export function serveObject(
+  store: ObjectStore,
+  opts: NodeServeOptions,
+) {
+  const { key: keyFn, mime: mimeFn, filename: filenameFn, writeStallTimeoutMs, ...serveOpts } = opts;
+  const handler = serveObjectRaw(store, serveOpts);
+  const stallMs = writeStallTimeoutMs ?? DEFAULT_WRITE_STALL_MS;
+
+  return async function handleNodeServe(
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<void> {
+    // Wire up client-disconnect detection: when the Node.js request closes
+    // (client navigates away, connection drops), signal the web adapter to
+    // cancel the storage stream and stop transferring bytes.
+    //
+    // The listener MUST be detached once the response is fully written:
+    // IncomingMessage emits "close" after every NORMAL completion too, and
+    // an abort() there constructs a DOMException and notifies the store's
+    // abort listener on every request -- measured at ~8% of serve CPU.
+    const ac = new AbortController();
+    const onClientGone = () => ac.abort();
+    req.once("close", onClientGone);
+
+    // Lightweight ServableRequest view: the orchestrator only reads method,
+    // headers.get, and signal, so constructing real fetch primitives
+    // (undici Request + Headers) per request would be pure overhead. Node
+    // already lower-cases incoming header names, so reads go straight to
+    // req.headers with no per-request copy; join() matches how Node folds
+    // repeated headers (request headers are never Set-Cookie).
+    const nodeHeaders = req.headers;
+    const fetchRequest = {
+      method: req.method ?? "GET",
+      headers: {
+        get(name: string): string | null {
+          const value = nodeHeaders[name.toLowerCase()];
+          if (value === undefined) return null;
+          return Array.isArray(value) ? value.join(", ") : value;
+        },
+      },
+      signal: ac.signal,
+    };
+
+    // Resolve context and delegate to the web adapter. Guarded: a throwing
+    // key/mime/filename extractor (caller code) must become a 500 response,
+    // not a rejected handler -- in Express 4 an async handler rejection is
+    // an unhandled promise rejection, which kills the process.
+    let parts: RawResponseParts;
+    try {
+      const key = await keyFn(req);
+      const ctx: ServeContext = {
+        key,
+        mime: mimeFn?.(req),
+        filename: filenameFn?.(req),
+      };
+      parts = await handler(fetchRequest, ctx);
+    } catch {
+      if (!res.headersSent) {
+        const body = "Internal Server Error";
+        res.writeHead(500, {
+          "Content-Type": "text/plain; charset=utf-8",
+          "Content-Length": String(body.length),
+          "X-Content-Type-Options": "nosniff",
+        });
+        res.end(body);
+      } else if (!res.destroyed) {
+        res.destroy();
+      }
+      req.off("close", onClientGone);
+      return;
+    }
+
+    // Write the raw parts straight to the ServerResponse: no fetch
+    // primitives were constructed anywhere on this path. Preserves custom
+    // reason phrases (e.g. 499 Client Closed Request). The outer try/finally
+    // is load-bearing: writeHead and end can throw SYNCHRONOUSLY (socket
+    // destroyed in the await window, a header value the runtime rejects),
+    // and that throw must not leak the storage stream, leave the disconnect
+    // listener attached, or escape as an unhandled rejection (which kills
+    // Express 4 processes).
+    try {
+      res.writeHead(parts.status, parts.statusText || undefined, parts.headers);
+
+      if (!parts.body) {
+        res.end();
+        return;
+      }
+
+      // Byte bodies (in-memory stores, fs small-transfer fast path, error
+      // pages): a single write, no reader machinery.
+      if (parts.body instanceof Uint8Array) {
+        res.end(parts.body);
+        return;
+      }
+
+      // Stream the response body with backpressure. Client disconnects abort
+      // the storage stream (via the signal above), which rejects reader.read();
+      // that rejection must be contained here, not escape the handler.
+      const reader = parts.body.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (res.destroyed) {
+            // Client is gone; stop pulling and release the storage stream.
+            await reader.cancel();
+            break;
+          }
+          const canContinue = res.write(value);
+          if (!canContinue) {
+            // Backpressure: wait for drain, or for the response to close
+            // (client disconnect) so a stalled socket cannot hang this loop.
+            // A stall timeout bounds a reader that stops consuming but holds
+            // the socket open: it rejects into the catch below, which cancels
+            // the storage reader and destroys the response.
+            await new Promise<void>((resolve, reject) => {
+              let timer: ReturnType<typeof setTimeout> | undefined;
+              const cleanup = () => {
+                if (timer !== undefined) clearTimeout(timer);
+                res.off("drain", onDone);
+                res.off("close", onDone);
+              };
+              const onDone = () => {
+                cleanup();
+                resolve();
+              };
+              if (stallMs > 0) {
+                timer = setTimeout(() => {
+                  cleanup();
+                  reject(new Error("partial-content: response write stalled"));
+                }, stallMs);
+                // Do not keep the event loop alive solely for this timer.
+                timer.unref?.();
+              }
+              res.once("drain", onDone);
+              res.once("close", onDone);
+            });
+          }
+        }
+        res.end();
+      } catch {
+        // Transfer failed mid-stream (disconnect or storage error). Headers are
+        // already sent, so no error response is possible; tear the socket down
+        // so the client sees a truncated transfer instead of a hang.
+        await reader.cancel().catch(() => {
+          // Stream may already be errored; cancel is best-effort
+        });
+        if (!res.destroyed) res.destroy();
+      } finally {
+        reader.releaseLock();
+      }
+    } catch {
+      // writeHead/end threw synchronously. The pump above never rethrows, so
+      // this only catches pre-stream failures: release an unconsumed stream
+      // body (fs handle / backend socket) and tear the connection down.
+      if (parts.body instanceof ReadableStream) {
+        await parts.body.cancel().catch(() => {
+          // Already locked or errored; best-effort release
+        });
+      }
+      if (!res.destroyed) res.destroy();
+    } finally {
+      req.off("close", onClientGone);
+    }
+  };
+}