@nifrajs/node 4.0.2 → 5.1.0

package/README.md

@@ -53,10 +53,12 @@ The optional `static` root is served before `app.fetch` for GET and HEAD request
 public asset directory and must contain nothing private: no secrets, source maps, build
 metadata, or user uploads. The directory and its ancestor path must be read-only and owned by
 the service (or otherwise protected from untrusted local writers). Nifra resolves and confines
-the file before opening it and refuses symlinked final files, but Node does not expose a native
-per-component `openat` primitive; a process that can mutate the tree concurrently can still
-create a local TOCTOU race. Mutable or attacker-writable static trees are therefore outside the
-adapter's guarantee. Store user-controlled files outside the static root and serve them through
+the file before opening it, and refuses it when its final file or any directory on its path became
+a symlink in the meantime: on macOS the open itself refuses such a path, and on Linux the opened
+descriptor's path is checked. On Windows and other platforms no file API can open without following a
+middle link, so a process that swaps a directory concurrently can still win a local TOCTOU race;
+the check there only makes it need repeated swaps. Mutable or attacker-writable static trees are
+therefore outside the adapter's guarantee on those platforms. Store user-controlled files outside the static root and serve them through
 an application or object-storage path with its own validation policy.
 
 Every file carries a strong `ETag` (from mtime and size), `Last-Modified`, and
@@ -74,6 +76,13 @@ process signals should be a deliberate choice):
 await serve(app, { port: 3000, signals: true })
 ```
 
+In-flight requests get 10 s to finish before the stop forces them closed. Set the window to fit
+the platform's kill grace period:
+
+```ts
+await serve(app, { port: 3000, signals: { drainMs: 8_000 } })
+```
+
 ## What you get for free
 
 The request timeout (`server({ requestTimeoutMs })` → `503 request_timeout`) and body-size
@@ -81,6 +90,10 @@ cap live **inside `app.fetch`**, not Bun's `listen()` - so they apply through th
 with no extra wiring. Slow-client / slow-loris protection is Node's built-in
 `requestTimeout` (300s) and `headersTimeout` (60s) defaults.
 
+A hook that throws past `app.fetch`, or a response Node refuses to write (a header value carrying
+CR/LF, say), answers `500` and is logged through the app's own `logger`, as Bun's `listen()` logs it. The `req` a hook sees is a lazy stand-in for Node's request: copy it
+with `req.clone()`, not `new Request(req)`, which Node's `Request` constructor refuses.
+
 Works with any `{ fetch(req): Promise<Response> }` handler, not just nifra. ESM-only. MIT.
 
 ## For AI agents

package/dist/index.d.ts

@@ -49,6 +49,8 @@ type WsUpgradeOutcome = {
     readonly data: unknown;
     readonly pubsub: WsPubSub;
     readonly maxPayloadBytes?: number;
+    /** Builds `ws.send` with the route's outbound contract (`validateSend`). */
+    sender?(handler: NifraWsHandler, send: (payload: string | ArrayBufferView | ArrayBuffer) => void, onError: (error: unknown) => void): (payload: string | ArrayBufferView | ArrayBuffer) => void;
 };
 export type RequestProtocol = "http" | "https";
 export type RequestProtocolOption = RequestProtocol | ((request: IncomingMessage) => RequestProtocol);
@@ -64,6 +66,12 @@ export interface ServeStaticOptions {
     readonly prefix?: string;
     /** Emit `cache-control: public, max-age=31536000, immutable` - correct for content-hashed files. Default `true`. */
     readonly immutable?: boolean;
+    /**
+     * URL paths of the content-hashed files, such as a client build manifest's `assets`. When set,
+     * `immutable` applies only to these; any other file is sent with its validators and no
+     * `cache-control`, so a file that keeps its name across deploys still revalidates.
+     */
+    readonly hashedFiles?: Iterable<string>;
     /** Extra headers merged onto every served file. */
     readonly headers?: Readonly<Record<string, string>>;
     /**
@@ -101,13 +109,17 @@ export interface ServeOptions {
      * Install SIGTERM/SIGINT handlers that call `stop()` for a graceful drain on
      * `docker stop` / Ctrl-C. Off by default - taking over process signals is opt-in,
      * mirroring nifra's Bun `listen({ gracefulSignals })`.
+     * `{ drainMs }` sets how long in-flight requests get before the stop forces them closed
+     * (default 10_000).
      *
      * The app-level request timeout (`server({ requestTimeoutMs })` → 503) and body cap
      * are *not* set here - they live inside `app.fetch`, so they already apply through
      * this adapter. Slow-client protection is Node's built-in `requestTimeout` (300s) /
      * `headersTimeout` (60s) defaults.
      */
-    readonly signals?: boolean;
+    readonly signals?: boolean | {
+        readonly drainMs?: number;
+    };
     /**
      * Serve static files from disk for matching GET/HEAD requests *before* the app runs - non-matching
      * requests fall through to `app.fetch` with the node-direct fast path intact (no perf regression on
@@ -132,7 +144,8 @@ export interface NodeServer {
     readonly port: number;
     /**
      * Stop accepting connections, let in-flight requests drain (up to `drainMs`), then
-     * force-close stragglers + idle keep-alives. Mirrors nifra's Bun `stop()`.
+     * force-close stragglers + idle keep-alives. Open WebSockets get a 1001 close at once and are
+     * terminated if still open at the deadline. Mirrors nifra's Bun `stop()`.
      */
     stop(options?: {
         drainMs?: number;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,WAAW,CAAA;AAIlB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAU1C,sGAAsG;AACtG,UAAU,YAAY;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9E;;kEAE8D;IAC9D,uBAAuB,CAAC,CACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,YAAY,GACtB,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAChD;AAKD,4EAA4E;AAC5E,KAAK,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAEtC,uFAAuF;AACvF,UAAU,OAAO;IACf,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,IAAI,CAAA;IACxD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,wGAAwG;AACxG,UAAU,QAAQ;IAChB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAC3C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7C,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;CAClC;AAED,uGAAuG;AACvG,UAAU,cAAc;IACtB,IAAI,CAAC,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,OAAO,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,KAAK,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvE,KAAK,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED,2FAA2F;AAC3F,KAAK,gBAAgB,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACxD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,4EAA4E;IAC5E,MAAM,CAAC,CACL,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,WAAW,KAAK,IAAI,EAC/D,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAChC,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,WAAW,KAAK,IAAI,CAAA;CAC7D,CAAA;AAuBL,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,CAAA;AAC9C,MAAM,MAAM,qBAAqB,GAC7B,eAAe,GACf,CAAC,CAAC,OAAO,EAAE,eAAe,KAAK,eAAe,CAAC,CAAA;AAulBnD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,oHAAoH;IACpH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;IAC1B,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oHAAoH;IACpH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACvC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAA;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAA;IACzB,mGAAmG;IACnG,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAA;IACvE,mGAAmG;IACnG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpD;AAudD,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CA+JnF"}