zerobucket 0.0.0-stage → 0.1.0

package/dist/client-C_W0t8My.d.ts

@@ -0,0 +1,319 @@
+import { Pool } from 'pg';
+
+/** Public data types returned by the ZeroBucket SDK. */
+/** A retrieved image, ready to be served or written to disk. `data` is raw bytes, never Base64. */
+interface Image {
+    data: Buffer;
+    mimeType: string;
+    filename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+/** Metadata about a stored image, without the pixel data. */
+interface ImageMetadata {
+    imageId: string;
+    mimeType: string;
+    filename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+/** Outcome of one item in a `putMany()` call. Batches are best-effort, not all-or-nothing. */
+interface BatchPutResult {
+    /** Position in the input array. */
+    index: number;
+    imageId: string | null;
+    error: string | null;
+    success: boolean;
+}
+/** Outcome of one id in a `getMany()` call. A missing id is not an exception here. */
+interface BatchGetResult {
+    imageId: string;
+    image: Image | null;
+    error: string | null;
+    success: boolean;
+}
+/** Outcome of one id in a `deleteMany()` call. `deleted: false` with no error means "did not exist". */
+interface BatchDeleteResult {
+    imageId: string;
+    deleted: boolean;
+    error: string | null;
+    success: boolean;
+}
+/** Emitted to `onOperation` after every storage operation (success or failure). */
+interface OperationEvent {
+    operation: string;
+    durationMs: number;
+    success: boolean;
+    error: string | null;
+    retryCount: number;
+}
+/**
+ * Anything with a pg-style `query()`: a `pg.Client`, a `pg.PoolClient`, or a
+ * transaction handle from a wrapper. Pass one as `connection` to make a
+ * ZeroBucket call participate in YOUR transaction. ZeroBucket then neither
+ * commits, rolls back, nor retries.
+ */
+interface Queryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+}
+/** The row shape a storage backend persists (after validation and checksumming). */
+interface PreparedRow {
+    data: Buffer;
+    mimeType: string;
+    originalFilename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+
+/**
+ * Storage backend interface.
+ *
+ * CRITICAL DESIGN RULE (same as the Python package): backends know nothing about
+ * images. They store and retrieve rows of bytes + metadata columns. All
+ * image-specific logic (validation, optimization, checksums) lives in client.ts.
+ *
+ * Every method accepts an optional `connection`. When omitted, the backend uses
+ * its own pool: each call commits independently and transient failures are
+ * retried. When provided, the backend uses it directly and does NOT commit,
+ * roll back or retry. That is what lets a call join the caller's transaction.
+ */
+
+interface StoredRecord {
+    id: string;
+    data: Buffer;
+    mimeType: string;
+    originalFilename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+type StoredRecordMetadata = Omit<StoredRecord, "data">;
+interface CallOptions {
+    connection?: Queryable;
+}
+interface StreamOptions$1 extends CallOptions {
+    chunkSize: number;
+    /** Inclusive byte range [start, end]; `end` is clamped to the object size. Omit for the whole object. */
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+interface StorageBackend {
+    /** Resolve once the backend is connected and migrated. Safe to call repeatedly. */
+    ready(): Promise<void>;
+    put(row: PreparedRow, opts?: CallOptions): Promise<string>;
+    putMany(rows: PreparedRow[], opts?: CallOptions): Promise<string[]>;
+    get(id: string, opts?: CallOptions): Promise<StoredRecord | null>;
+    /** Missing ids are simply absent. Result order is NOT guaranteed to match input. */
+    getMany(ids: string[], opts?: CallOptions): Promise<StoredRecord[]>;
+    getMetadata(id: string, opts?: CallOptions): Promise<StoredRecordMetadata | null>;
+    /**
+     * Resolves to null if the id does not exist (checked eagerly, before any
+     * chunk is read). A row deleted mid-stream makes iteration throw
+     * StorageError rather than silently truncating.
+     */
+    getStream(id: string, opts: StreamOptions$1): Promise<AsyncIterable<Buffer> | null>;
+    delete(id: string, opts?: CallOptions): Promise<boolean>;
+    /** Returns the ids that were actually deleted. */
+    deleteMany(ids: string[], opts?: CallOptions): Promise<string[]>;
+    exists(id: string, opts?: CallOptions): Promise<boolean>;
+    close(): Promise<void>;
+}
+
+interface OptimizeOptions {
+    /** Downscale (aspect ratio preserved, Lanczos) if wider than this. Never upscales. */
+    maxWidth?: number;
+    /** "jpeg" | "png" | "webp". Defaults to the source format. */
+    format?: string;
+    /** 1-100, JPEG/WebP only (ignored for PNG). */
+    quality?: number;
+}
+interface OptimizationResult {
+    data: Buffer;
+    mimeType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    originalSizeBytes: number;
+}
+declare function optimizeImage(data: Buffer, opts: OptimizeOptions & {
+    maxBytes: number;
+    maxPixels?: number;
+}): Promise<OptimizationResult>;
+
+/** Pluggable content validation (the npm equivalent of Python's ContentValidator). */
+interface ValidatedContent {
+    mimeType: string;
+    sizeBytes: number;
+    width?: number | null;
+    height?: number | null;
+}
+/**
+ * Implement this to let `put()` / `putMany()` accept a content type ZeroBucket
+ * does not natively understand. It must throw (ideally a
+ * `ContentValidationError`) when the content is invalid, and must trust nothing
+ * but the bytes themselves.
+ */
+interface ContentValidator {
+    validate(data: Buffer, opts: {
+        maxBytes: number;
+    }): ValidatedContent | Promise<ValidatedContent>;
+}
+
+/** 8 MiB: a practical ceiling for "small app" images. Override with `maxBytes`. */
+declare const DEFAULT_MAX_BYTES: number;
+/**
+ * What put() accepts:
+ *  - Buffer / Uint8Array / ArrayBuffer: the bytes themselves
+ *  - string: a filesystem PATH (never raw content)
+ *  - Blob / File (e.g. from `request.formData()`)
+ *  - Node Readable or web ReadableStream (read in bounded chunks)
+ */
+type ImageInput = Buffer | Uint8Array | ArrayBuffer | string | Blob | AsyncIterable<Uint8Array | string>;
+type BeforeGetHook<C = unknown> = (imageId: string, context: C | undefined) => boolean | Promise<boolean>;
+type BeforePutHook<C = unknown> = (context: C | undefined) => boolean | Promise<boolean>;
+interface ZeroBucketOptions<C = unknown> {
+    /** PostgreSQL connection string. */
+    connectionString?: string;
+    /** Bring your own pg.Pool. It is NOT closed by close(). */
+    pool?: Pool;
+    /** Advanced: inject a custom StorageBackend instead of building a PostgresBackend. */
+    backend?: StorageBackend;
+    /** Max accepted size in bytes. Default 8 MiB. */
+    maxBytes?: number;
+    /** Decoded-pixel ceiling that rejects decompression bombs. Default ~89 MP. */
+    maxPixels?: number;
+    /** Accepted image formats. Default ["jpeg", "png", "webp"]. */
+    allowedFormats?: readonly string[];
+    autoMigrate?: boolean;
+    maxRetries?: number;
+    retryBaseDelayMs?: number;
+    poolMinSize?: number;
+    poolMaxSize?: number;
+    poolTimeoutMs?: number;
+    /** Fire-and-forget observability. Exceptions thrown inside it are swallowed. */
+    onOperation?: (event: OperationEvent) => void;
+    /**
+     * Authorization hook for get / getMany (per id) / getStream / streamTo / metadata.
+     * Return false to deny. A hook that THROWS fails closed: the exception
+     * propagates (or is captured per item in getMany) and is never treated as allow.
+     * NOT called for exists().
+     */
+    beforeGet?: BeforeGetHook<C>;
+    /** Authorization hook for put / putMany (evaluated once per call). Same fail-closed rule. */
+    beforePut?: BeforePutHook<C>;
+}
+interface PutBase<C> {
+    /** Display filename stored in metadata (never used for validation). */
+    filename?: string;
+    /** `true` = strip metadata only; or pass { maxWidth, format, quality } to resize/re-encode. */
+    optimize?: boolean | OptimizeOptions;
+    /** Store non-image content through the same machinery. Incompatible with `optimize`. */
+    validator?: ContentValidator;
+    /** Join your own transaction. ZeroBucket then does not commit, roll back or retry. */
+    connection?: Queryable;
+    /** Passed to beforePut. */
+    context?: C;
+}
+type PutOptions<C = unknown> = PutBase<C>;
+interface PutManyOptions<C = unknown> extends Omit<PutBase<C>, "filename"> {
+    /** Same length as `images`; use null/undefined entries to fall back to each input's own name. */
+    filenames?: (string | null | undefined)[];
+}
+interface GetOptions<C = unknown> {
+    connection?: Queryable;
+    context?: C;
+}
+interface StreamOptions<C = unknown> extends GetOptions<C> {
+    /** Bytes per chunk. Default 1 MiB. */
+    chunkSize?: number;
+    /** Inclusive byte range, e.g. { start: 0, end: 1023 }. `end` is clamped to the object size. */
+    range?: {
+        start: number;
+        end?: number;
+    };
+}
+/** Anything with write(); e.g. fs.WriteStream, http.ServerResponse, or a custom sink. Backpressure is honoured. */
+interface WritableLike {
+    write(chunk: Buffer): boolean | void | Promise<void>;
+    once?(event: "drain", listener: () => void): unknown;
+}
+declare class ZeroBucket<C = unknown> {
+    private readonly backend;
+    private readonly maxBytes;
+    private readonly maxPixels;
+    private readonly allowedFormats;
+    private readonly beforeGet;
+    private readonly beforePut;
+    constructor(options?: ZeroBucketOptions<C>);
+    /** Construct AND connect/migrate immediately, so a bad DATABASE_URL fails at startup, not on first request. */
+    static connect<C = unknown>(options?: ZeroBucketOptions<C>): Promise<ZeroBucket<C>>;
+    /** Resolves once connected and migrated. Called automatically on first use. */
+    ready(): Promise<void>;
+    private checkBeforeGet;
+    private checkBeforePut;
+    private prepareRow;
+    /** Validate, optionally optimize, checksum and store one image. Returns its id (a UUID). */
+    put(image: ImageInput, options?: PutOptions<C>): Promise<string>;
+    /**
+     * Store many images. Best-effort, not all-or-nothing: one bad image does not
+     * abort the rest. Check each result's `success` / `error`. Settings apply to
+     * every item. Valid items are inserted in ONE transaction.
+     */
+    putMany(images: ImageInput[], options?: PutManyOptions<C>): Promise<BatchPutResult[]>;
+    /** Retrieve a full image including bytes. Throws ImageNotFoundError if missing. */
+    get(imageId: string, options?: GetOptions<C>): Promise<Image>;
+    /**
+     * Retrieve many images in one query. Results come back in input order; a
+     * missing id is `error: "not found"`, not an exception. A hook denial or hook
+     * exception affects only that id.
+     */
+    getMany(imageIds: string[], options?: GetOptions<C>): Promise<BatchGetResult[]>;
+    /**
+     * Stream an image's bytes in chunks without holding the whole image in memory.
+     * Not-found is checked eagerly: the returned promise rejects before any chunk
+     * is read. A concurrent delete mid-stream makes iteration throw StorageError
+     * rather than silently truncating. Pass `range` for partial reads.
+     *
+     * Honest limitation: reduces Node-side memory, not Postgres-side (the server
+     * still handles the full BYTEA value per chunk request).
+     */
+    getStream(imageId: string, options?: StreamOptions<C>): Promise<AsyncIterable<Buffer>>;
+    /** Same as getStream(), as a Web `ReadableStream` you can hand straight to `new Response(...)`. */
+    toWebStream(imageId: string, options?: StreamOptions<C>): Promise<ReadableStream<Uint8Array>>;
+    /** Write an image to `destination` chunk by chunk (honouring backpressure). Returns bytes written. Does not end the destination. */
+    streamTo(imageId: string, destination: WritableLike, options?: StreamOptions<C>): Promise<number>;
+    /** Metadata without pulling the bytes. Gated by the same beforeGet hook as get(). */
+    metadata(imageId: string, options?: GetOptions<C>): Promise<ImageMetadata>;
+    /** Whether an image exists. Deliberately NOT gated by beforeGet (returns no data or metadata). */
+    exists(imageId: string, options?: Pick<CallOptions, "connection">): Promise<boolean>;
+    /** Delete an image. Returns true if it existed. */
+    delete(imageId: string, options?: Pick<CallOptions, "connection">): Promise<boolean>;
+    /** Delete many in one query. Results are in input order; a missing id is `deleted: false`, not an error. */
+    deleteMany(imageIds: string[], options?: Pick<CallOptions, "connection">): Promise<BatchDeleteResult[]>;
+    /** Release the pool (if ZeroBucket created it). */
+    close(): Promise<void>;
+}
+/**
+ * Read any supported input into a Buffer. Streams are consumed in bounded
+ * chunks and rejected as soon as they pass maxBytes (reported size is then a
+ * lower bound), rather than buffering an arbitrarily large upload first.
+ * Files and Blobs are size-checked BEFORE their bytes are read.
+ */
+declare function readInput(image: ImageInput, filename: string | undefined, maxBytes: number): Promise<{
+    data: Buffer;
+    filename: string | undefined;
+}>;
+
+export { type BatchDeleteResult as B, type CallOptions as C, DEFAULT_MAX_BYTES as D, type GetOptions as G, type Image as I, type OperationEvent as O, type PreparedRow as P, type Queryable as Q, type StorageBackend as S, type ValidatedContent as V, type WritableLike as W, ZeroBucket as Z, type StoredRecord as a, type StoredRecordMetadata as b, type StreamOptions$1 as c, type ContentValidator as d, type BatchGetResult as e, type BatchPutResult as f, type BeforeGetHook as g, type BeforePutHook as h, type ImageInput as i, type ImageMetadata as j, type OptimizationResult as k, type OptimizeOptions as l, type PutManyOptions as m, type PutOptions as n, type StreamOptions as o, type ZeroBucketOptions as p, optimizeImage as q, readInput as r };

package/dist/http.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/http.ts
+var http_exports = {};
+__export(http_exports, {
+  createImageHandler: () => createImageHandler,
+  etagMatches: () => etagMatches,
+  parseRange: () => parseRange,
+  toNodeHandler: () => toNodeHandler
+});
+module.exports = __toCommonJS(http_exports);
+var import_node_stream = require("stream");
+
+// src/errors.ts
+var ZeroBucketError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var ImageNotFoundError = class extends ZeroBucketError {
+  constructor(imageId) {
+    super(`No image found with id ${JSON.stringify(imageId)}`);
+    this.imageId = imageId;
+  }
+  imageId;
+};
+var AccessDeniedError = class extends ZeroBucketError {
+  constructor(operation, imageId) {
+    super(
+      imageId !== void 0 ? `${operation} denied for image ${JSON.stringify(imageId)} by the beforeGet hook` : `${operation} denied by the beforePut hook`
+    );
+    this.operation = operation;
+    this.imageId = imageId;
+  }
+  operation;
+  imageId;
+};
+
+// src/http.ts
+function createImageHandler(images, options = {}) {
+  const cacheControl = options.cacheControl ?? "private, no-cache";
+  return async function handle(req, ctx) {
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      return new Response("Method Not Allowed", {
+        status: 405,
+        headers: { Allow: "GET, HEAD" }
+      });
+    }
+    const id = ctx?.id ?? (options.getId ?? defaultGetId)(req);
+    if (!id) return notFound();
+    try {
+      const context = options.getContext ? await options.getContext(req) : void 0;
+      const meta = await images.metadata(id, { context });
+      const etag = `"${meta.checksumSha256}"`;
+      const size = meta.sizeBytes;
+      const base = {
+        ETag: etag,
+        "Cache-Control": cacheControl,
+        "Accept-Ranges": "bytes",
+        "X-Content-Type-Options": "nosniff",
+        "Content-Type": meta.mimeType
+      };
+      if (options.disposition === "attachment") {
+        base["Content-Disposition"] = attachmentHeader(
+          meta.filename ?? "download"
+        );
+      }
+      if (etagMatches(req.headers.get("if-none-match"), etag)) {
+        return new Response(null, {
+          status: 304,
+          headers: { ETag: etag, "Cache-Control": cacheControl }
+        });
+      }
+      let range = null;
+      const rangeHeader = req.headers.get("range");
+      const ifRange = req.headers.get("if-range");
+      if (rangeHeader && (ifRange === null || ifRange.trim() === etag)) {
+        range = parseRange(rangeHeader, size);
+      }
+      if (range === "unsatisfiable") {
+        return new Response(null, {
+          status: 416,
+          headers: {
+            ...base,
+            "Content-Range": `bytes */${size}`,
+            "Content-Length": "0"
+          }
+        });
+      }
+      const status = range ? 206 : 200;
+      const length = range ? range.end - range.start + 1 : size;
+      const headers = {
+        ...base,
+        "Content-Length": String(length)
+      };
+      if (range)
+        headers["Content-Range"] = `bytes ${range.start}-${range.end}/${size}`;
+      if (req.method === "HEAD") return new Response(null, { status, headers });
+      const body = await images.toWebStream(id, {
+        context,
+        chunkSize: options.chunkSize,
+        range: range ? { start: range.start, end: range.end } : void 0
+      });
+      return new Response(body, { status, headers });
+    } catch (exc) {
+      if (exc instanceof ImageNotFoundError) return notFound();
+      if (exc instanceof AccessDeniedError)
+        return new Response("Forbidden", { status: 403 });
+      options.onError?.(exc, req);
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  };
+}
+function toNodeHandler(handler) {
+  return async function nodeHandler(req, res, ctx) {
+    const host = req.headers.host ?? "localhost";
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (Array.isArray(v)) v.forEach((x) => headers.append(k, x));
+      else if (v !== void 0) headers.set(k, v);
+    }
+    const request = new Request(`http://${host}${req.url ?? "/"}`, {
+      method: req.method,
+      headers
+    });
+    const response = await handler(request, ctx);
+    res.writeHead(response.status, Object.fromEntries(response.headers));
+    if (!response.body) {
+      res.end();
+      return;
+    }
+    const nodeStream = import_node_stream.Readable.fromWeb(
+      response.body
+    );
+    res.on("close", () => nodeStream.destroy());
+    nodeStream.on("error", () => res.destroy());
+    nodeStream.pipe(res);
+  };
+}
+function notFound() {
+  return new Response("Not Found", { status: 404 });
+}
+function defaultGetId(req) {
+  const segments = new URL(req.url).pathname.split("/").filter(Boolean);
+  const last = segments[segments.length - 1];
+  return last ? decodeURIComponent(last) : void 0;
+}
+function etagMatches(header, etag) {
+  if (!header) return false;
+  if (header.trim() === "*") return true;
+  const strip = (t) => t.trim().replace(/^W\//, "");
+  return header.split(",").some((t) => strip(t) === etag);
+}
+function parseRange(header, size) {
+  const m = /^bytes=(\d*)-(\d*)$/i.exec(header.trim());
+  if (!m) return null;
+  const [, a, b] = m;
+  if (a === "" && b === "") return null;
+  if (a === "") {
+    const n = Number(b);
+    if (n === 0) return "unsatisfiable";
+    return { start: Math.max(0, size - n), end: size - 1 };
+  }
+  const start = Number(a);
+  if (start >= size) return "unsatisfiable";
+  if (b === "") return { start, end: size - 1 };
+  const end = Number(b);
+  if (end < start) return null;
+  return { start, end: Math.min(end, size - 1) };
+}
+function attachmentHeader(filename) {
+  const ascii = filename.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createImageHandler,
+  etagMatches,
+  parseRange,
+  toNodeHandler
+});
+//# sourceMappingURL=http.cjs.map

package/dist/http.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http.ts","../src/errors.ts"],"sourcesContent":["/**\r\n * HTTP serving helpers: `import { createImageHandler } from \"zerobucket/http\"`.\r\n *\r\n * `createImageHandler()` returns a Web-standard `(Request) => Promise<Response>`,\r\n * which is what Next.js route handlers, Hono, Remix, SvelteKit, Bun, Deno and\r\n * Cloudflare-style runtimes all speak. `toNodeHandler()` adapts it to\r\n * Express / Fastify / plain `node:http`.\r\n *\r\n * Implements: ETag (the content SHA-256) + If-None-Match -> 304; Range /\r\n * If-Range -> 206 (single byte range) with 416 for unsatisfiable ranges;\r\n * HEAD; X-Content-Type-Options: nosniff. Bytes are streamed in chunks, never\r\n * fully buffered.\r\n */\r\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\r\nimport { Readable } from \"node:stream\";\r\nimport { AccessDeniedError, ImageNotFoundError } from \"./errors.js\";\r\nimport type { ZeroBucket } from \"./client.js\";\r\n\r\nexport type ImageHandler = (\r\n  req: Request,\r\n  ctx?: { id?: string },\r\n) => Promise<Response>;\r\n\r\nexport interface ImageHandlerOptions<C = unknown> {\r\n  /** Extract the id from the request. Default: the last non-empty path segment. Ignored if `ctx.id` is passed. */\r\n  getId?: (req: Request) => string | undefined;\r\n  /** Build the context handed to your beforeGet hook (e.g. the signed-in user from cookies). */\r\n  getContext?: (req: Request) => C | undefined | Promise<C | undefined>;\r\n  /**\r\n   * Cache-Control header. The default, \"private, no-cache\", is safe for\r\n   * access-controlled images: browsers always revalidate, and the ETag makes\r\n   * that a cheap 304. For public images pass e.g. \"public, max-age=31536000, immutable\"\r\n   * (ids are never reused and content never mutates).\r\n   */\r\n  cacheControl?: string;\r\n  /** \"inline\" (default) or \"attachment\" (adds the stored filename). */\r\n  disposition?: \"inline\" | \"attachment\";\r\n  /** Bytes per DB read while streaming. Default 1 MiB. */\r\n  chunkSize?: number;\r\n  /** Called with unexpected errors (anything other than not-found / denied) so you can log them. The response is a generic 500. */\r\n  onError?: (error: unknown, req: Request) => void;\r\n}\r\n\r\nexport function createImageHandler<C = unknown>(\r\n  images: ZeroBucket<C>,\r\n  options: ImageHandlerOptions<C> = {},\r\n): ImageHandler {\r\n  const cacheControl = options.cacheControl ?? \"private, no-cache\";\r\n\r\n  return async function handle(req, ctx) {\r\n    if (req.method !== \"GET\" && req.method !== \"HEAD\") {\r\n      return new Response(\"Method Not Allowed\", {\r\n        status: 405,\r\n        headers: { Allow: \"GET, HEAD\" },\r\n      });\r\n    }\r\n\r\n    const id = ctx?.id ?? (options.getId ?? defaultGetId)(req);\r\n    if (!id) return notFound();\r\n\r\n    try {\r\n      const context = options.getContext\r\n        ? await options.getContext(req)\r\n        : undefined;\r\n      const meta = await images.metadata(id, { context });\r\n      const etag = `\"${meta.checksumSha256}\"`;\r\n      const size = meta.sizeBytes;\r\n\r\n      const base: Record<string, string> = {\r\n        ETag: etag,\r\n        \"Cache-Control\": cacheControl,\r\n        \"Accept-Ranges\": \"bytes\",\r\n        \"X-Content-Type-Options\": \"nosniff\",\r\n        \"Content-Type\": meta.mimeType,\r\n      };\r\n      if (options.disposition === \"attachment\") {\r\n        base[\"Content-Disposition\"] = attachmentHeader(\r\n          meta.filename ?? \"download\",\r\n        );\r\n      }\r\n\r\n      if (etagMatches(req.headers.get(\"if-none-match\"), etag)) {\r\n        return new Response(null, {\r\n          status: 304,\r\n          headers: { ETag: etag, \"Cache-Control\": cacheControl },\r\n        });\r\n      }\r\n\r\n      // Range is honoured unless If-Range is present and does not match our (strong) ETag.\r\n      let range: ReturnType<typeof parseRange> = null;\r\n      const rangeHeader = req.headers.get(\"range\");\r\n      const ifRange = req.headers.get(\"if-range\");\r\n      if (rangeHeader && (ifRange === null || ifRange.trim() === etag)) {\r\n        range = parseRange(rangeHeader, size);\r\n      }\r\n\r\n      if (range === \"unsatisfiable\") {\r\n        return new Response(null, {\r\n          status: 416,\r\n          headers: {\r\n            ...base,\r\n            \"Content-Range\": `bytes */${size}`,\r\n            \"Content-Length\": \"0\",\r\n          },\r\n        });\r\n      }\r\n\r\n      const status = range ? 206 : 200;\r\n      const length = range ? range.end - range.start + 1 : size;\r\n      const headers: Record<string, string> = {\r\n        ...base,\r\n        \"Content-Length\": String(length),\r\n      };\r\n      if (range)\r\n        headers[\"Content-Range\"] = `bytes ${range.start}-${range.end}/${size}`;\r\n\r\n      if (req.method === \"HEAD\") return new Response(null, { status, headers });\r\n\r\n      const body = await images.toWebStream(id, {\r\n        context,\r\n        chunkSize: options.chunkSize,\r\n        range: range ? { start: range.start, end: range.end } : undefined,\r\n      });\r\n      return new Response(body, { status, headers });\r\n    } catch (exc) {\r\n      if (exc instanceof ImageNotFoundError) return notFound();\r\n      if (exc instanceof AccessDeniedError)\r\n        return new Response(\"Forbidden\", { status: 403 });\r\n      options.onError?.(exc, req);\r\n      return new Response(\"Internal Server Error\", { status: 500 });\r\n    }\r\n  };\r\n}\r\n\r\n// ---- Node adapter --------------------------------------------------------\r\n\r\n/**\r\n * Adapt an ImageHandler to Node's `(req, res)` signature (Express, Fastify's raw\r\n * handler, plain `http.createServer`).\r\n *\r\n *   app.get(\"/images/:id\", (req, res) => nodeHandler(req, res, { id: req.params.id }));\r\n */\r\nexport function toNodeHandler(handler: ImageHandler) {\r\n  return async function nodeHandler(\r\n    req: IncomingMessage,\r\n    res: ServerResponse,\r\n    ctx?: { id?: string },\r\n  ): Promise<void> {\r\n    const host = req.headers.host ?? \"localhost\";\r\n    const headers = new Headers();\r\n    for (const [k, v] of Object.entries(req.headers)) {\r\n      if (Array.isArray(v)) v.forEach((x) => headers.append(k, x));\r\n      else if (v !== undefined) headers.set(k, v);\r\n    }\r\n    const request = new Request(`http://${host}${req.url ?? \"/\"}`, {\r\n      method: req.method,\r\n      headers,\r\n    });\r\n    const response = await handler(request, ctx);\r\n\r\n    res.writeHead(response.status, Object.fromEntries(response.headers));\r\n    if (!response.body) {\r\n      res.end();\r\n      return;\r\n    }\r\n    const nodeStream = Readable.fromWeb(\r\n      response.body as import(\"node:stream/web\").ReadableStream,\r\n    );\r\n    // If the client disconnects, stop reading from the database.\r\n    res.on(\"close\", () => nodeStream.destroy());\r\n    nodeStream.on(\"error\", () => res.destroy());\r\n    nodeStream.pipe(res);\r\n  };\r\n}\r\n\r\n// ---- helpers (exported for tests) ----------------------------------------\r\n\r\nfunction notFound(): Response {\r\n  return new Response(\"Not Found\", { status: 404 });\r\n}\r\n\r\nfunction defaultGetId(req: Request): string | undefined {\r\n  const segments = new URL(req.url).pathname.split(\"/\").filter(Boolean);\r\n  const last = segments[segments.length - 1];\r\n  return last ? decodeURIComponent(last) : undefined;\r\n}\r\n\r\n/** Weak comparison, per RFC 9110 for If-None-Match. */\r\nexport function etagMatches(header: string | null, etag: string): boolean {\r\n  if (!header) return false;\r\n  if (header.trim() === \"*\") return true;\r\n  const strip = (t: string) => t.trim().replace(/^W\\//, \"\");\r\n  return header.split(\",\").some((t) => strip(t) === etag);\r\n}\r\n\r\n/**\r\n * Parse a single `bytes=` range against a resource of `size` bytes.\r\n *  - returns a clamped inclusive range\r\n *  - \"unsatisfiable\" -> respond 416\r\n *  - null            -> ignore the header and serve the full body (syntax we don't handle, incl. multi-range)\r\n */\r\nexport function parseRange(\r\n  header: string,\r\n  size: number,\r\n): { start: number; end: number } | \"unsatisfiable\" | null {\r\n  const m = /^bytes=(\\d*)-(\\d*)$/i.exec(header.trim());\r\n  if (!m) return null; // also rejects multi-range (\"bytes=0-1,5-6\")\r\n  const [, a, b] = m as unknown as [string, string, string];\r\n  if (a === \"\" && b === \"\") return null;\r\n\r\n  if (a === \"\") {\r\n    const n = Number(b); // suffix: last n bytes\r\n    if (n === 0) return \"unsatisfiable\";\r\n    return { start: Math.max(0, size - n), end: size - 1 };\r\n  }\r\n  const start = Number(a);\r\n  if (start >= size) return \"unsatisfiable\";\r\n  if (b === \"\") return { start, end: size - 1 };\r\n  const end = Number(b);\r\n  if (end < start) return null; // syntactically invalid -> ignore\r\n  return { start, end: Math.min(end, size - 1) };\r\n}\r\n\r\nfunction attachmentHeader(filename: string): string {\r\n  const ascii = filename.replace(/[^\\x20-\\x7e]/g, \"_\").replace(/[\"\\\\]/g, \"_\");\r\n  return `attachment; filename=\"${ascii}\"; filename*=UTF-8''${encodeURIComponent(filename)}`;\r\n}\r\n","/**\r\n * Error hierarchy for ZeroBucket. Mirrors the Python package's exceptions\r\n * one-to-one so behaviour is portable across languages.\r\n *\r\n * Catch broadly with `instanceof ZeroBucketError`, or narrowly with a\r\n * subclass such as `ImageNotFoundError`.\r\n */\r\n\r\nexport class ZeroBucketError extends Error {\r\n  constructor(message: string, options?: { cause?: unknown }) {\r\n    super(message, options);\r\n    this.name = new.target.name;\r\n  }\r\n}\r\n\r\n/** Any content (image or custom-validated) failed validation. */\r\nexport class ContentValidationError extends ZeroBucketError {}\r\n\r\n/** An image failed validation (bad format, too large, corrupted, ...). */\r\nexport class ImageValidationError extends ContentValidationError {}\r\n\r\nexport class ImageTooLargeError extends ImageValidationError {\r\n  constructor(\r\n    public readonly sizeBytes: number,\r\n    public readonly maxBytes: number,\r\n  ) {\r\n    super(\r\n      `Image is ${sizeBytes} bytes, which exceeds the maximum of ${maxBytes} bytes`,\r\n    );\r\n  }\r\n}\r\n\r\nexport class UnsupportedFormatError extends ImageValidationError {\r\n  constructor(\r\n    public readonly detectedFormat: string | null,\r\n    public readonly allowed: readonly string[],\r\n  ) {\r\n    super(\r\n      `Detected format ${JSON.stringify(detectedFormat)} is not supported. ` +\r\n        `Allowed formats: ${JSON.stringify([...allowed].sort())}`,\r\n    );\r\n  }\r\n}\r\n\r\n/** Image bytes could not be decoded despite a recognizable header. */\r\nexport class CorruptedImageError extends ImageValidationError {}\r\n\r\n/** `get()`, `getStream()` or `metadata()` was called with an id that does not exist. */\r\nexport class ImageNotFoundError extends ZeroBucketError {\r\n  constructor(public readonly imageId: string) {\r\n    super(`No image found with id ${JSON.stringify(imageId)}`);\r\n  }\r\n}\r\n\r\n/** Underlying storage / database failure not covered above. */\r\nexport class StorageError extends ZeroBucketError {}\r\n\r\n/**\r\n * A `beforeGet` / `beforePut` hook denied the operation by returning false.\r\n *\r\n * If the hook itself throws, that exception propagates unchanged: it is NOT\r\n * wrapped in AccessDeniedError and NOT treated as an implicit allow. A broken\r\n * authorization check must fail closed, never open.\r\n */\r\nexport class AccessDeniedError extends ZeroBucketError {\r\n  constructor(\r\n    public readonly operation: string,\r\n    public readonly imageId?: string,\r\n  ) {\r\n    super(\r\n      imageId !== undefined\r\n        ? `${operation} denied for image ${JSON.stringify(imageId)} by the beforeGet hook`\r\n        : `${operation} denied by the beforePut hook`,\r\n    );\r\n  }\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/http.d.cts

@@ -0,0 +1,64 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Z as ZeroBucket } from './client-C_W0t8My.cjs';
+import 'pg';
+
+/**
+ * HTTP serving helpers: `import { createImageHandler } from "zerobucket/http"`.
+ *
+ * `createImageHandler()` returns a Web-standard `(Request) => Promise<Response>`,
+ * which is what Next.js route handlers, Hono, Remix, SvelteKit, Bun, Deno and
+ * Cloudflare-style runtimes all speak. `toNodeHandler()` adapts it to
+ * Express / Fastify / plain `node:http`.
+ *
+ * Implements: ETag (the content SHA-256) + If-None-Match -> 304; Range /
+ * If-Range -> 206 (single byte range) with 416 for unsatisfiable ranges;
+ * HEAD; X-Content-Type-Options: nosniff. Bytes are streamed in chunks, never
+ * fully buffered.
+ */
+
+type ImageHandler = (req: Request, ctx?: {
+    id?: string;
+}) => Promise<Response>;
+interface ImageHandlerOptions<C = unknown> {
+    /** Extract the id from the request. Default: the last non-empty path segment. Ignored if `ctx.id` is passed. */
+    getId?: (req: Request) => string | undefined;
+    /** Build the context handed to your beforeGet hook (e.g. the signed-in user from cookies). */
+    getContext?: (req: Request) => C | undefined | Promise<C | undefined>;
+    /**
+     * Cache-Control header. The default, "private, no-cache", is safe for
+     * access-controlled images: browsers always revalidate, and the ETag makes
+     * that a cheap 304. For public images pass e.g. "public, max-age=31536000, immutable"
+     * (ids are never reused and content never mutates).
+     */
+    cacheControl?: string;
+    /** "inline" (default) or "attachment" (adds the stored filename). */
+    disposition?: "inline" | "attachment";
+    /** Bytes per DB read while streaming. Default 1 MiB. */
+    chunkSize?: number;
+    /** Called with unexpected errors (anything other than not-found / denied) so you can log them. The response is a generic 500. */
+    onError?: (error: unknown, req: Request) => void;
+}
+declare function createImageHandler<C = unknown>(images: ZeroBucket<C>, options?: ImageHandlerOptions<C>): ImageHandler;
+/**
+ * Adapt an ImageHandler to Node's `(req, res)` signature (Express, Fastify's raw
+ * handler, plain `http.createServer`).
+ *
+ *   app.get("/images/:id", (req, res) => nodeHandler(req, res, { id: req.params.id }));
+ */
+declare function toNodeHandler(handler: ImageHandler): (req: IncomingMessage, res: ServerResponse, ctx?: {
+    id?: string;
+}) => Promise<void>;
+/** Weak comparison, per RFC 9110 for If-None-Match. */
+declare function etagMatches(header: string | null, etag: string): boolean;
+/**
+ * Parse a single `bytes=` range against a resource of `size` bytes.
+ *  - returns a clamped inclusive range
+ *  - "unsatisfiable" -> respond 416
+ *  - null            -> ignore the header and serve the full body (syntax we don't handle, incl. multi-range)
+ */
+declare function parseRange(header: string, size: number): {
+    start: number;
+    end: number;
+} | "unsatisfiable" | null;
+
+export { type ImageHandler, type ImageHandlerOptions, createImageHandler, etagMatches, parseRange, toNodeHandler };