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

package/README.md

@@ -7,7 +7,7 @@ A modern, unopinionated, and performant Node.js server framework built on AsyncL
 
 ## Important 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.
+- **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.
 - **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.**
@@ -419,18 +419,18 @@ Options:
 
 #### Response Setters
 
-Setters only take a `{status?}` option (except `setRedirect`/`setFile`). To set response
-headers, use `getRes().setHeader(name, value)` before (or after) calling a setter.
+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.
 
-- **`setJson(data, {status?})`** - Send JSON response (`application/json; charset=utf-8`)
-- **`setHtml(html, {status?})`** - Send HTML response (`text/html; charset=utf-8`)
-- **`setText(text, {status?})`** - Send plain text (`text/plain; charset=utf-8`)
-- **`setBuffer(buffer, {status?})`** - Send buffer (`application/octet-stream`)
-- **`setFile(path, options?)`** - Send file (see `SendFileOptions`)
-- **`setNodeStream(stream, {status?})`** - Send Node.js stream
-- **`setWebStream(stream, {status?})`** - Send Web stream
-- **`setRedirect(url, status)`** - Redirect response; `status` is `301 | 302` (required, positional)
-- **`setEmpty({status?})`** - Send empty response
+- **`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`)
+- **`setFile(path, {status?, ...SendFileOptions})`** - file (charset/ETag via `SendFileOptions`)
+- **`setNodeStream(stream, {status?, charset?})`** - Node.js stream
+- **`setWebStream(stream, {status?, charset?})`** - Web stream
+- **`setRedirect(url, status)`** - redirect; `status` is `301 | 302` (required, positional)
+- **`setEmpty({status?, disableEtag?})`** - empty response
 
 #### Context Management
 
@@ -467,6 +467,8 @@ headers, use `getRes().setHeader(name, value)` before (or after) calling a sette
   	etag: 'weak', // 'weak' (default) | 'strong' | 'disabled'
   	disableLastModified: false,
   	disableFollowSymlinks: false, // set true to 403 files whose real path escapes root
+  	charset: undefined, // override the Content-Type charset; default comes from the file extension
+  	// (text/* -> utf-8). e.g. set 'utf-8' to force a charset on a type that has none.
   })
   ```
 

package/lib/dx.d.ts

@@ -13,31 +13,44 @@ 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 }?: {
+export declare function setText(text: string, { status, charset, disableEtag }?: {
     status?: number;
+    charset?: BufferEncoding;
+    disableEtag?: boolean;
 }): void;
-export declare function setEmpty({ status }?: {
+export declare function setHtml(html: string, options?: {
     status?: number;
+    charset?: BufferEncoding;
+    disableEtag?: boolean;
 }): void;
-export declare function setHtml(html: string, opts?: {
+export declare function setBuffer(buffer: Buffer, { status, charset, disableEtag }?: {
     status?: number;
+    charset?: BufferEncoding;
+    disableEtag?: boolean;
 }): void;
-export declare function setFile(filePath: string, options?: SendFileOptions): void;
-export declare function setBuffer(buffer: Buffer, { status }?: {
+export declare function setJson(json: any, { status, disableEtag }?: {
     status?: number;
+    disableEtag?: boolean;
+}): void;
+export declare function setEmpty({ status, disableEtag }?: {
+    status?: number;
+    disableEtag?: boolean;
 }): void;
-export declare function setNodeStream(stream: Readable, { status }?: {
+export declare function setNodeStream(stream: Readable, { status, charset }?: {
     status?: number;
+    charset?: BufferEncoding;
 }): void;
-export declare function setWebStream(stream: ReadableStream, { status }?: {
+export declare function setWebStream(stream: ReadableStream, { status, charset }?: {
     status?: number;
+    charset?: BufferEncoding;
 }): void;
-export declare function setJson(json: any, { status }?: {
+export declare function setFile(filePath: string, { status, ...options }?: SendFileOptions & {
     status?: number;
 }): void;
 export declare function setRedirect(url: string, status: 301 | 302): void;

package/lib/dx.js

@@ -54,69 +54,86 @@ export function getReq() {
 export function getRes() {
     return requestStorage.getStore().res;
 }
-export function setText(text, { status } = {}) {
-    const res = getRes();
+// 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 } = {}) {
     const dx = dxContext.value;
     if (status)
-        res.statusCode = status;
+        getRes().statusCode = status;
+    if (charset !== undefined)
+        dx.charset = charset;
+    if (disableEtag !== undefined)
+        dx.disableEtag = disableEtag;
     dx.data = text;
     dx.type = 'text';
 }
-export function setEmpty({ status } = {}) {
-    const res = getRes();
-    const dx = dxContext.value;
-    if (status)
-        res.statusCode = status;
-    dx.data = undefined;
-    dx.type = 'empty';
+export function setHtml(html, options = {}) {
+    setText(html, options);
+    dxContext.value.type = 'html';
 }
-export function setHtml(html, opts = {}) {
-    setText(html, opts);
+export function setBuffer(buffer, { status, charset, disableEtag } = {}) {
     const dx = dxContext.value;
-    dx.type = 'html';
+    if (status)
+        getRes().statusCode = status;
+    if (charset !== undefined)
+        dx.charset = charset;
+    if (disableEtag !== undefined)
+        dx.disableEtag = disableEtag;
+    dx.data = buffer;
+    dx.type = 'buffer';
 }
-export function setFile(filePath, options) {
+export function setJson(json, { status, disableEtag } = {}) {
     const dx = dxContext.value;
-    dx.data = filePath;
-    dx.type = 'file';
-    dx.options = options;
+    if (status)
+        getRes().statusCode = status;
+    if (disableEtag !== undefined)
+        dx.disableEtag = disableEtag;
+    dx.data = json;
+    dx.type = 'json';
 }
-export function setBuffer(buffer, { status } = {}) {
-    const res = getRes();
+export function setEmpty({ status, disableEtag } = {}) {
     const dx = dxContext.value;
     if (status)
-        res.statusCode = status;
-    dx.data = buffer;
-    dx.type = 'buffer';
+        getRes().statusCode = status;
+    if (disableEtag !== undefined)
+        dx.disableEtag = disableEtag;
+    dx.data = undefined;
+    dx.type = 'empty';
 }
-export function setNodeStream(stream, { status } = {}) {
-    const res = getRes();
+export function setNodeStream(stream, { status, charset } = {}) {
     const dx = dxContext.value;
     if (status)
-        res.statusCode = status;
+        getRes().statusCode = status;
+    if (charset !== undefined)
+        dx.charset = charset;
     dx.data = stream;
     dx.type = 'nodeStream';
 }
-export function setWebStream(stream, { status } = {}) {
-    const res = getRes();
+export function setWebStream(stream, { status, charset } = {}) {
     const dx = dxContext.value;
     if (status)
-        res.statusCode = status;
+        getRes().statusCode = status;
+    if (charset !== undefined)
+        dx.charset = charset;
     dx.data = stream;
     dx.type = 'webStream';
 }
-export function setJson(json, { status } = {}) {
-    const res = getRes();
-    if (status)
-        res.statusCode = status;
+export function setFile(filePath, { status, ...options } = {}) {
+    // charset/etag for files come from SendFileOptions (stay in `options`), handled by sendFileTrusted
     const dx = dxContext.value;
-    dx.data = json;
-    dx.type = 'json';
+    if (status)
+        getRes().statusCode = status;
+    dx.data = filePath;
+    dx.type = 'file';
+    dx.options = options;
 }
 export function setRedirect(url, status) {
-    const res = getRes();
     const dx = dxContext.value;
-    res.statusCode = status;
+    getRes().statusCode = status;
     dx.data = url;
     dx.type = 'redirect';
 }

package/lib/dxHelpers.js

@@ -15,31 +15,37 @@ export async function writeRes(req, res, { type, data, charset, jsonBeautify, di
             break;
         case 'buffer':
             setContentType('application/octet-stream');
-            buffer = data ?? Buffer.from('', charset);
+            buffer = data ?? Buffer.from('');
             break;
         case 'json':
-            setContentType('application/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);
             buffer =
                 data === undefined
-                    ? Buffer.from('', charset)
-                    : Buffer.from(jsonBeautify ? JSON.stringify(data, null, 2) : JSON.stringify(data), charset);
+                    ? Buffer.from('')
+                    : Buffer.from(jsonBeautify ? JSON.stringify(data, null, 2) : JSON.stringify(data));
             break;
         case 'redirect':
         case 'empty':
             if (type === 'redirect')
                 res.setHeader('location', data);
-            buffer = Buffer.from('', charset);
+            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.
         case 'nodeStream':
         case 'webStream':
             if (!data) {
-                buffer = Buffer.from('', charset);
+                buffer = Buffer.from('');
                 break;
             }
         case 'file':
-            setContentType('application/octet-stream');
+            // 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);
@@ -109,11 +115,12 @@ export async function writeRes(req, res, { type, data, charset, jsonBeautify, di
     // we do not support content-encoding (gzip, deflate, br) and leave it to reverse proxy or CDN
     await promisify(res.end.bind(res))();
     await awaitResFinished(res);
-    function setContentType(contentType) {
+    function setContentType(contentType, withCharset = true) {
         if (res.headersSent || res.getHeader('content-type'))
             return;
-        // only text/* carries a charset; binary (octet-stream) and JSON (always UTF-8 per RFC 8259) do not
-        const cs = charset ?? (contentType.startsWith('text/') ? 'utf-8' : undefined);
+        // 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}` : ''}`);
     }
 }

package/lib/staticHelpers.d.ts

@@ -11,10 +11,11 @@ export interface SendFileOptions {
     disableCacheControl?: boolean;
     maxAge?: number;
     immutable?: boolean;
+    charset?: BufferEncoding;
     disableFollowSymlinks?: boolean;
     end?: number;
     start?: number;
 }
 export declare function sendFileTrusted(req: IncomingMessage, res: ServerResponse, pathname: string, // plain path, not URI-encoded
 { root, allowDotfiles, start, end, disableAcceptRanges, disableLastModified, etag, disableCacheControl, maxAge, // 1 year
-immutable, disableFollowSymlinks, }?: SendFileOptions): Promise<undefined>;
+immutable, disableFollowSymlinks, charset, }?: SendFileOptions): Promise<undefined>;

package/lib/staticHelpers.js

@@ -15,7 +15,7 @@ const bytesRangeRegexp = /^ *bytes=/;
 const upPathRegexp = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export async function sendFileTrusted(req, res, pathname, // plain path, not URI-encoded
 { root, allowDotfiles, start = 0, end, disableAcceptRanges, disableLastModified, etag = 'weak', disableCacheControl, maxAge = 60 * 60 * 24 * 365 * 1000, // 1 year
-immutable, disableFollowSymlinks, } = {}) {
+immutable, disableFollowSymlinks, charset, } = {}) {
     // null byte(s)
     if (pathname.includes('\0'))
         throw httpError('Forbidden', 403);
@@ -89,7 +89,7 @@ immutable, disableFollowSymlinks, } = {}) {
         //endregion set header fields
         // content-type
         if (!res.getHeader('Content-Type'))
-            res.setHeader('Content-Type', contentTypeForExtension(path.extname(pathname).slice(1)) || 'application/octet-stream');
+            res.setHeader('Content-Type', contentTypeForExtension(path.extname(pathname).slice(1), charset));
         // conditional GET support
         // isConditionalGET
         if (req.headers['if-match'] ||

package/lib/vendors/mime.d.ts

@@ -1 +1 @@
-export declare function contentTypeForExtension(extension: string): string | undefined;
+export declare function contentTypeForExtension(extension: string, charset?: string): string;

package/lib/vendors/mime.js

@@ -10,16 +10,12 @@ function preferredType(ext, type0, type1) {
     const score1 = type1 ? mimeScore(type1, mimeDb[type1].source) : 0;
     return score0 > score1 ? type0 : type1;
 }
-export function contentTypeForExtension(extension) {
-    const mimeType = extensionToMime[extension.toLowerCase()];
-    if (!mimeType)
-        return;
-    if (!mimeType.includes('charset')) {
-        const charset = determineCharset(mimeType);
-        if (charset)
-            return mimeType + '; charset=' + charset.toLowerCase();
-    }
-    return mimeType;
+export function contentTypeForExtension(extension, charset) {
+    // unknown extension: octet-stream is binary, so add a charset only when one is explicitly given
+    const mimeType = extensionToMime[extension.toLowerCase()] ?? 'application/octet-stream';
+    // known text/* (and mime-db charset types) default to their charset; an explicit charset overrides it
+    charset ??= determineCharset(mimeType);
+    return `${mimeType}${charset ? '; charset=' + charset.toLowerCase() : ''}`;
 }
 const extractTypeRegexp = /^\s*([^;\s]*)(?:;|\s|$)/;
 const textTypeRegexp = /^text\//i;

package/package.json

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