partial-content 1.0.0

package/dist/node.js

@@ -0,0 +1,215 @@
+/**
+ * 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 { serveObjectRaw } from "./web.js";
+/** 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, opts) {
+    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, res) {
+        // 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) {
+                    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;
+        try {
+            const key = await keyFn(req);
+            const ctx = {
+                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((resolve, reject) => {
+                            let timer;
+                            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);
+        }
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

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