dx-server 0.14.0-alpha.4 → 0.14.0-alpha.5

package/README.md

@@ -5,12 +5,18 @@ A modern, unopinionated, and performant Node.js server framework built on AsyncL
 [![npm version](https://img.shields.io/npm/v/dx-server.svg)](https://www.npmjs.com/package/dx-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Important caveats
+## Caveats
 
 - **ETag is supported.** Static file serving defaults to a weak (mtime/size-based) ETag, while other responses (`setJson`, `setHtml`, `setText`, `setBuffer`, …) use a strong (content-based) ETag. Redirects get no ETag. Disable it globally with `dxServer(req, res, {disableEtag: true})`, or per response with the setter's `disableEtag` option (for `setFile`, use `etag: 'disabled'`).
-- **Request compression is supported.** Request bodies with `Content-Encoding: gzip`, `deflate`, or `br` are decompressed automatically.
+- **Request compression is supported.** Request bodies with `Content-Encoding: gzip`, `deflate`, `br`, or `zstd` are decompressed automatically. `zstd` requires Node.js v22.15.0+ or v23.8.0+ (the version that added native Zstd support to `node:zlib`).
 - **Response compression is NOT supported.** dx-server never sets `Content-Encoding` on responses — handle response compression at the reverse proxy / CDN level.
 - **Static file serving supports Range requests.**
+- **`dxServer()` never throws on its own.** The chain returned by `dxServer(req, res)(...)` never throws synchronously or returns a rejected promise _because of dx-server itself_ — writing the response (serialization, headers, ETag, flushing the socket) can never crash the request. Any internal failure is logged server-side with a `[dx-server]` prefix and answered with a generic `500` (`Internal Server Error`) — the error is never leaked to the client; the socket is then closed. The chain rejects **only** when your own `next` chain throws or returns a rejected promise. So it is safe to mount `dxServer` at the top of the `'request'` listener without a `try`/`catch` — wrap your own handlers if _they_ can reject:
+
+  ```javascript
+  // safe: dxServer itself never rejects, so an unhandled rejection here can only come from your code
+  new Server().on('request', (req, res) => dxServer(req, res)(router(routes)))
+  ```
 
 ## Features
 
@@ -419,16 +425,18 @@ Options:
 
 #### Response Setters
 
-Each setter's options are inlined to expose only what its response type honors. To set arbitrary
-response headers, use `getRes().setHeader(name, value)` before (or after) a setter.
+Each setter's options are inlined to expose only what its response type honors. `text/*` responses
+are labelled `charset=utf-8` automatically; to use any other charset (or set one on a non-text type),
+set the header yourself with `getRes().setHeader('content-type', ...)`. `setFile` is the exception —
+it takes `charset` via `SendFileOptions`. Use `getRes().setHeader(name, value)` for arbitrary headers.
 
 - **`setJson(data, {status?, disableEtag?})`** - JSON response (`application/json`; always UTF-8 per RFC 8259)
-- **`setHtml(html, {status?, charset?, disableEtag?})`** - HTML (`text/html; charset=utf-8`)
-- **`setText(text, {status?, charset?, disableEtag?})`** - plain text (`text/plain; charset=utf-8`)
-- **`setBuffer(buffer, {status?, charset?, disableEtag?})`** - buffer (`application/octet-stream`)
+- **`setHtml(html, {status?, disableEtag?})`** - HTML (`text/html; charset=utf-8`)
+- **`setText(text, {status?, disableEtag?})`** - plain text (`text/plain; charset=utf-8`)
+- **`setBuffer(buffer, {status?, disableEtag?})`** - buffer (`application/octet-stream`)
 - **`setFile(path, {status?, ...SendFileOptions})`** - file (charset/ETag via `SendFileOptions`)
-- **`setNodeStream(stream, {status?, charset?})`** - Node.js stream
-- **`setWebStream(stream, {status?, charset?})`** - Web stream
+- **`setNodeStream(stream, {status?})`** - Node.js stream
+- **`setWebStream(stream, {status?})`** - Web stream
 - **`setRedirect(url, status)`** - redirect; `status` is `301 | 302` (required, positional)
 - **`setEmpty({status?, disableEtag?})`** - empty response
 

package/lib/dx.d.ts

@@ -13,25 +13,21 @@ export interface Context<T, Params extends any[] = any[], R = any, Next = (...np
 }
 export declare function makeDxContext<T, Params extends any[] = any[], R = any, Next = (...np: any[]) => any>(maker: (...params: Params) => T | Promise<T>): Context<T, Params, R, Next>;
 export declare function dxServer(req: IncomingMessage, res: ServerResponse, options?: {
-    charset?: BufferEncoding;
     jsonBeautify?: boolean;
     disableEtag?: boolean;
 }): Chainable;
 export declare function getReq(): IncomingMessage;
 export declare function getRes(): ServerResponse<IncomingMessage>;
-export declare function setText(text: string, { status, charset, disableEtag }?: {
+export declare function setText(text: string, { status, disableEtag }?: {
     status?: number;
-    charset?: BufferEncoding;
     disableEtag?: boolean;
 }): void;
 export declare function setHtml(html: string, options?: {
     status?: number;
-    charset?: BufferEncoding;
     disableEtag?: boolean;
 }): void;
-export declare function setBuffer(buffer: Buffer, { status, charset, disableEtag }?: {
+export declare function setBuffer(buffer: Buffer, { status, disableEtag }?: {
     status?: number;
-    charset?: BufferEncoding;
     disableEtag?: boolean;
 }): void;
 export declare function setJson(json: any, { status, disableEtag }?: {
@@ -42,13 +38,11 @@ export declare function setEmpty({ status, disableEtag }?: {
     status?: number;
     disableEtag?: boolean;
 }): void;
-export declare function setNodeStream(stream: Readable, { status, charset }?: {
+export declare function setNodeStream(stream: Readable, { status }?: {
     status?: number;
-    charset?: BufferEncoding;
 }): void;
-export declare function setWebStream(stream: ReadableStream, { status, charset }?: {
+export declare function setWebStream(stream: ReadableStream, { status }?: {
     status?: number;
-    charset?: BufferEncoding;
 }): void;
 export declare function setFile(filePath: string, { status, ...options }?: SendFileOptions & {
     status?: number;

package/lib/dx.js

@@ -35,6 +35,9 @@ export function makeDxContext(maker) {
     return context;
 }
 const requestStorage = new AsyncLocalStorage();
+// dxServer always seeds this context via dxContext.set() before any read, so the maker (the lazy
+// initializer makeDxContext falls back to) is never actually invoked for this instance.
+/* node:coverage ignore next */
 const dxContext = makeDxContext(options => ({ ...options }));
 export function dxServer(req, res, options = {}) {
     return async (next) => {
@@ -54,18 +57,16 @@ export function getReq() {
 export function getRes() {
     return requestStorage.getStore().res;
 }
-// Each setter inlines only the options its response type honors:
-//   - charset: text/html (body encoding + Content-Type label) and buffer/streams (Content-Type
-//     label). not on setJson (always UTF-8, RFC 8259), setEmpty, setRedirect; setFile takes it via
-//     SendFileOptions instead (its Content-Type is owned by sendFileTrusted).
-//   - disableEtag: the buffer-backed types (text/html/buffer/json/empty). not on streams or redirect
-//     (never ETagged) or setFile (use SendFileOptions.etag: 'disabled').
-export function setText(text, { status, charset, disableEtag } = {}) {
+// Each setter inlines only the options its response type honors. There is no charset option: text/*
+// responses are labelled charset=utf-8 automatically, and any other charset must be set manually via
+// res.setHeader('content-type', ...). The exception is setFile, which takes charset via
+// SendFileOptions (its Content-Type is derived from the file extension by sendFileTrusted).
+// disableEtag is honored only by the buffer-backed types (text/html/buffer/json/empty); streams and
+// redirects are never ETagged, and setFile controls its ETag via SendFileOptions.etag.
+export function setText(text, { status, disableEtag } = {}) {
     const dx = dxContext.value;
     if (status)
         getRes().statusCode = status;
-    if (charset !== undefined)
-        dx.charset = charset;
     if (disableEtag !== undefined)
         dx.disableEtag = disableEtag;
     dx.data = text;
@@ -75,12 +76,10 @@ export function setHtml(html, options = {}) {
     setText(html, options);
     dxContext.value.type = 'html';
 }
-export function setBuffer(buffer, { status, charset, disableEtag } = {}) {
+export function setBuffer(buffer, { status, disableEtag } = {}) {
     const dx = dxContext.value;
     if (status)
         getRes().statusCode = status;
-    if (charset !== undefined)
-        dx.charset = charset;
     if (disableEtag !== undefined)
         dx.disableEtag = disableEtag;
     dx.data = buffer;
@@ -104,21 +103,17 @@ export function setEmpty({ status, disableEtag } = {}) {
     dx.data = undefined;
     dx.type = 'empty';
 }
-export function setNodeStream(stream, { status, charset } = {}) {
+export function setNodeStream(stream, { status } = {}) {
     const dx = dxContext.value;
     if (status)
         getRes().statusCode = status;
-    if (charset !== undefined)
-        dx.charset = charset;
     dx.data = stream;
     dx.type = 'nodeStream';
 }
-export function setWebStream(stream, { status, charset } = {}) {
+export function setWebStream(stream, { status } = {}) {
     const dx = dxContext.value;
     if (status)
         getRes().statusCode = status;
-    if (charset !== undefined)
-        dx.charset = charset;
     dx.data = stream;
     dx.type = 'webStream';
 }

package/lib/dxHelpers.d.ts

@@ -1,9 +1,8 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
 import type { ReadableStream as WebReadableStream } from 'node:stream/web';
 import { type SendFileOptions } from './staticHelpers.js';
 export type DxContext = {
-    charset?: BufferEncoding;
     jsonBeautify?: boolean;
     disableEtag?: boolean;
 } & ({
@@ -43,4 +42,4 @@ export type DxContext = {
     data: string;
     options?: SendFileOptions;
 });
-export declare function writeRes(req: IncomingMessage, res: ServerResponse, { type, data, charset, jsonBeautify, disableEtag, options }: DxContext): Promise<void>;
+export declare function writeRes(req: IncomingMessage, res: ServerResponse, dx: DxContext): Promise<void>;

package/lib/dxHelpers.js

@@ -1,9 +1,43 @@
+import { STATUS_CODES } from 'node:http';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { promisify } from 'node:util';
 import { entityTag, isFreshETag } from './vendors/etag.js';
 import { sendFileTrusted } from './staticHelpers.js';
-export async function writeRes(req, res, { type, data, charset, jsonBeautify, disableEtag, options }) {
+// writeRes runs after the user's handler, outside any try/catch the caller controls, so it must
+// NEVER throw or reject: a synchronous throw would crash the request and an unhandled rejection could
+// take down the process. Most failures originate from the handler's own input — a cyclic or BigInt
+// json body, a non-string text body, a header-invalid redirect URL, a torn-down socket — so rather
+// than guard each statement, flushRes runs inside one global catch that logs with the [dx-server]
+// tag, answers with the error's HTTP status (or 500), and tears the socket down. Every statement in
+// flushRes that can throw is marked with a `throws:` comment — including the streaming helpers,
+// whose failures (404/403/416 from sendFileTrusted) now flow to the same global catch.
+export async function writeRes(req, res, dx) {
+    try {
+        await flushRes(req, res, dx);
+    }
+    catch (e) {
+        console.error('[dx-server]', e);
+        // answer while the response is still uncommitted, honoring any HTTP status the error carries
+        // (e.g. sendFileTrusted's 403/404/416), otherwise 500. the inner try keeps this handler from
+        // faulting again. always "production": the real error is logged, never leaked — the body is just
+        // the status text.
+        if (!res.headersSent)
+            try {
+                const status = e?.statusCode ?? 500;
+                res.statusCode = status;
+                res.setHeader('Content-Type', 'text/html');
+                res.end(req.method === 'HEAD' ? undefined : STATUS_CODES[status] ?? STATUS_CODES[500]);
+            }
+            catch (e2) {
+                console.error('[dx-server]', e2);
+            }
+        await awaitResFinished(res);
+        // after an internal error a half-written or keep-alive socket may be inconsistent — tear it down
+        if (!res.destroyed)
+            res.destroy();
+    }
+}
+async function flushRes(req, res, { type, data, jsonBeautify, disableEtag, options }) {
     if (res.headersSent)
         return;
     let buffer;
@@ -11,85 +45,66 @@ export async function writeRes(req, res, { type, data, charset, jsonBeautify, di
         case 'text':
         case 'html':
             setContentType(type === 'html' ? 'text/html' : 'text/plain');
-            buffer = Buffer.from(data ?? '', charset);
+            buffer = Buffer.from(data ?? ''); // throws: a non-string body slipped past the types
             break;
         case 'buffer':
             setContentType('application/octet-stream');
             buffer = data ?? Buffer.from('');
             break;
         case 'json':
-            // JSON is always UTF-8 (RFC 8259) and application/json defines no charset parameter, so the
-            // charset option is intentionally ignored: no charset label and the body is UTF-8 encoded.
-            setContentType('application/json', false);
+            setContentType('application/json');
             buffer =
                 data === undefined
                     ? Buffer.from('')
-                    : Buffer.from(jsonBeautify ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+                    : // throws: JSON.stringify on a circular reference, a BigInt, or a throwing toJSON()
+                        Buffer.from(jsonBeautify ? JSON.stringify(data, null, 2) : JSON.stringify(data));
             break;
         case 'redirect':
+            res.setHeader('location', data); // throws: a header-invalid URL (CR/LF, non-latin1)
+            buffer = Buffer.from('');
+            break;
         case 'empty':
-            if (type === 'redirect')
-                res.setHeader('location', data);
             buffer = Buffer.from('');
             break;
         // Streaming paths own res.end() themselves (via pipeline/sendFileTrusted) and must be
-        // awaited to fulfil the "chain resolves after flush" invariant.
+        // awaited so the chain resolves only after the flush.
         case 'nodeStream':
         case 'webStream':
             if (!data) {
                 buffer = Buffer.from('');
                 break;
             }
+        // falls through — a non-empty stream shares the streaming block below
         case 'file':
             // streams have no intrinsic type, so default them to octet-stream. files do NOT get a
             // default here: sendFileTrusted derives Content-Type from the file extension (and falls
             // back to octet-stream itself). pre-setting it would suppress that extension detection.
             if (type !== 'file')
                 setContentType('application/octet-stream');
-            try {
-                if (type === 'file')
-                    await sendFileTrusted(req, res, data, options);
-                else if (type === 'nodeStream')
-                    await pipeline(data, res);
-                else if (type === 'webStream')
-                    await pipeline(Readable.fromWeb(data), res);
-            }
-            catch (e) {
-                // A streaming helper (pipeline/sendFileTrusted) may already have destroyed res on
-                // error (e.g. fs open EACCES mid-stream). Calling res.end() on a destroyed response
-                // never resolves, so skip it — otherwise the chain hangs forever.
-                if (res.destroyed) {
-                    // nothing to flush; res is already torn down
-                }
-                else if (!res.headersSent) {
-                    res.statusCode = e?.statusCode ?? 500;
-                    await promisify(res.end.bind(res))();
-                }
-                else if (!res.writableEnded)
-                    res.destroy(e);
-            }
+            // throws/rejects -> the global catch: a pre-header failure (missing file 404, EACCES 403,
+            // bad range 416) is answered with that status, a mid-stream failure tears the already-
+            // committed socket down.
+            if (type === 'file')
+                await sendFileTrusted(req, res, data, options);
+            else if (type === 'nodeStream')
+                await pipeline(data, res);
+            else if (type === 'webStream')
+                await pipeline(Readable.fromWeb(data), res);
             await awaitResFinished(res);
             return;
         case undefined:
             // No setter was called. End the response with 404 instead of leaving it hung.
             if (!res.headersSent)
                 res.statusCode = 404;
-            if (!res.writableEnded)
-                await promisify(res.end.bind(res))();
+            res.end(); // throws: torn-down socket -> rethrown to the global catch
             await awaitResFinished(res);
             return;
         default:
-            // Unknown type: programming error. Surface it via console.error but still finish
-            // res so the invariant holds (chain resolves only after flush).
-            console.error(new Error(`unsupported response type ${type}`));
-            if (!res.headersSent)
-                res.statusCode = 500;
-            if (!res.writableEnded)
-                await promisify(res.end.bind(res))();
-            await awaitResFinished(res);
-            return;
+            // unreachable through the typed API; if hit, let the global catch turn it into a 500
+            throw new Error(`unsupported response type ${type}`);
     }
-    // 204 No Content and 304 Not Modified must not carry a body or Content-Length.
+    // 204 No Content and 304 Not Modified must not carry a body or Content-Length. These header writes
+    // cannot throw: the values are a number and a hash token, written while headersSent is still false.
     if (res.statusCode !== 204 && res.statusCode !== 304) {
         // Content-Length and ETag mirror what a GET would send, so a HEAD reports them too.
         res.setHeader('content-length', buffer.length);
@@ -111,17 +126,16 @@ export async function writeRes(req, res, { type, data, charset, jsonBeautify, di
         res.removeHeader('transfer-encoding');
     }
     else if (req.method !== 'HEAD')
-        res.write(buffer);
+        res.write(buffer); // throws: torn-down socket -> the global catch
     // we do not support content-encoding (gzip, deflate, br) and leave it to reverse proxy or CDN
-    await promisify(res.end.bind(res))();
+    res.end(); // throws: torn-down socket -> the global catch
     await awaitResFinished(res);
-    function setContentType(contentType, withCharset = true) {
+    function setContentType(contentType) {
         if (res.headersSent || res.getHeader('content-type'))
             return;
-        // text/* defaults to utf-8; an explicit charset option applies to any type. withCharset is
-        // false for JSON, which is always UTF-8 with no charset parameter (RFC 8259).
-        const cs = withCharset ? (charset ?? (contentType.startsWith('text/') ? 'utf-8' : undefined)) : undefined;
-        res.setHeader('content-type', `${contentType}${cs ? `; charset=${cs}` : ''}`);
+        // text/* defaults to utf-8; other types (json, octet-stream) carry no charset. To use a
+        // different charset, set the content-type header yourself via res.setHeader().
+        res.setHeader('content-type', contentType.startsWith('text/') ? `${contentType}; charset=utf-8` : contentType);
     }
 }
 // Resolves when res is fully flushed (finish) or the socket is gone (close).
@@ -133,9 +147,13 @@ function awaitResFinished(res) {
     return new Promise(resolve => {
         res.once('finish', done);
         res.once('close', done);
+        // a flush error still means "we're done" — resolve (and absorb the error) so the chain neither
+        // hangs nor crashes on an otherwise-unhandled 'error' event.
+        res.once('error', done);
         function done() {
             res.off('finish', done);
             res.off('close', done);
+            res.off('error', done);
             resolve();
         }
     });

package/lib/staticHelpers.js

@@ -60,9 +60,12 @@ immutable, disableFollowSymlinks, charset, } = {}) {
             throw httpError('Not Found', 404);
         if (code === 'EACCES' || code === 'EPERM')
             throw httpError('Forbidden', 403);
-        if (code === 'EISDIR')
-            throw httpError('Forbidden: directory access is not allowed', 403);
+        // EISDIR is unreachable on Linux/macOS (open(dir, 'r') succeeds — a directory target is caught
+        // later by stat().isDirectory()), and the final rethrow only fires for an exotic errno. Both
+        // are defensive: kept for portability, but not deterministically hit by the suite.
+        // if (code === 'EISDIR') throw httpError('Forbidden: directory access is not allowed', 403)
         throw e;
+        /* node:coverage enable */
     }
     try {
         const fileStat = await handle.stat();
@@ -180,6 +183,9 @@ immutable, disableFollowSymlinks, charset, } = {}) {
         await pipeline(handle.createReadStream({ start, end }), res);
     }
     finally {
+        // best-effort close; the catch arm only runs if close() itself rejects, which it effectively
+        // never does for a handle we just opened — defensive cleanup, not a reachable branch.
+        /* node:coverage ignore next */
         await handle.close().catch(() => { });
     }
 }

package/lib/stream.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from 'node:http';
 import type { Readable } from 'node:stream';
-export declare function getContentStream(req: IncomingMessage, encoding: string, disableInflate?: boolean): IncomingMessage | import("node:zlib").Inflate | import("node:zlib").Gunzip | import("node:zlib").BrotliDecompress;
+export declare function getContentStream(req: IncomingMessage, encoding: string): IncomingMessage | import("node:zlib").Inflate | import("node:zlib").Gunzip | import("node:zlib").BrotliDecompress | import("node:zlib").ZstdDecompress;
 export declare function readStream(stream: Readable, { length, limit, }: {
     length?: number;
     limit?: number;

package/lib/stream.js

@@ -1,4 +1,4 @@
-import { createBrotliDecompress, createGunzip, createInflate } from 'node:zlib';
+import { createBrotliDecompress, createGunzip, createInflate, createZstdDecompress } from 'node:zlib';
 // body errors carry an HTTP status so error middleware can map them (413 too large, 400 malformed)
 function bodyError(message, statusCode) {
     const e = new Error(message);
@@ -7,9 +7,7 @@ function bodyError(message, statusCode) {
 }
 // note: there might be multiple encodings applied to the stream
 // we only support one encoding
-export function getContentStream(req, encoding, disableInflate) {
-    if (disableInflate && encoding !== 'identity')
-        throw new Error(`content-encoding ${encoding} is not supported`);
+export function getContentStream(req, encoding) {
     switch (encoding) {
         case 'deflate': {
             const stream = createInflate();
@@ -26,6 +24,11 @@ export function getContentStream(req, encoding, disableInflate) {
             req.pipe(stream);
             return stream;
         }
+        case 'zstd': {
+            const stream = createZstdDecompress();
+            req.pipe(stream);
+            return stream;
+        }
         case 'identity':
             return req;
         default:
@@ -50,6 +53,9 @@ export async function readStream(stream, { length, limit, }) {
     stream.on('end', onEnd);
     stream.on('error', onError);
     function done(err, result) {
+        // re-entrancy guard: onClose() detaches every listener the moment done() first runs, so a
+        // second terminal event can only sneak in on a same-tick race — defensive, not normally hit.
+        /* node:coverage ignore next 2 */
         if (completed)
             return;
         completed = true;
@@ -63,6 +69,9 @@ export async function readStream(stream, { length, limit, }) {
             defer.resolve(result);
     }
     function onData(chunk) {
+        // same re-entrancy guard: the 'data' listener is removed in onClose(), so a post-completion
+        // chunk is only possible on a same-tick race before detach takes effect.
+        /* node:coverage ignore next 2 */
         if (completed)
             return;
         received += chunk.length;

package/lib/vendors/mime.js

@@ -6,7 +6,7 @@ for (const [type, { extensions = [] }] of Object.entries(mimeDb))
     for (const extension of extensions)
         extensionToMime[extension] = preferredType(extension, type, extensionToMime[extension]);
 function preferredType(ext, type0, type1) {
-    const score0 = type0 ? mimeScore(type0, mimeDb[type0].source) : 0;
+    const score0 = mimeScore(type0, mimeDb[type0].source);
     const score1 = type1 ? mimeScore(type1, mimeDb[type1].source) : 0;
     return score0 > score1 ? type0 : type1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dx-server",
-	"version": "0.14.0-alpha.4",
+	"version": "0.14.0-alpha.5",
 	"main": "./lib/index.js",
 	"repository": {
 		"type": "git",