@thi.ng/server 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-03-17T13:40:35Z
+- **Last updated**: 2025-03-22T12:33:45Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,19 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.9.0) (2025-03-22)
+
+#### 🚀 Features
+
+- update static file serving ([e3ee3d6](https://github.com/thi-ng/umbrella/commit/e3ee3d6))
+  - update `StaticOpts` to support multiple `filters` & individual `headers` per file
+  - update `StaticOpts.prefix` type
+  - consolidate GET & HEAD handlers
+  - update `__fileHeaders()` to perform more checks and inject headers
+  - update `etagFileTimeModified()` to return base36 timestamp
+  - add `pathFilterASCII()` and `pathMaxLength()` filter predicates
+  - use `pathFilterASCII()` as default filter
+
 ## [0.8.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.8.0) (2025-03-13)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 203 standalone projects, maintained as part
+> This is one of 204 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -20,6 +20,7 @@
     - [Available interceptors](#available-interceptors)
     - [Custom interceptors](#custom-interceptors)
     - [Using interceptors](#using-interceptors)
+  - [Static file serving](#static-file-serving)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -49,9 +50,9 @@ implementations.
     - Global interceptors for all routes and/or local for individual routes & HTTP methods
 - Automatic parsing of cookies and URL query strings (incl. nested params)
 - In-memory session storage & route interceptor
-- Configurable file serving (`ReadableStream`-based) with automatic MIME-type
-  detection and support for Etags, as well as Brotli, Gzip and Deflate
-  compression
+- Configurable [static file serving](#static-file-serving)
+  (`ReadableStream`-based) with automatic MIME-type detection and support for
+  Etags, as well as Brotli, Gzip and Deflate compression
 - Utilities for parsing form-encoded multipart request bodies
 
 ### Interceptors
@@ -118,6 +119,19 @@ import { cacheControl } from "@thi.ng/server";
 }
 ```
 
+### Static file serving
+
+The
+[`staticFiles()`](https://docs.thi.ng/umbrella/server/functions/staticFiles.html)
+route provider can be used to serve files from a given local root directory.
+Multiple such routes can be defined. The handler is highly configurable in terms
+of path validation/filtering, global and/or per-file headers, Etag generation,
+compression. It also supports its own set of [interceptors](#interceptors).
+
+See
+[`StaticOpts`](https://docs.thi.ng/umbrella/server/interfaces/StaticOpts.html)
+and example below for more details.
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -150,7 +164,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 6.15 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 6.25 KB
 
 ## Dependencies
 
@@ -220,7 +234,7 @@ const app = srv.server<AppCtx>({
             // use compression (if client supports it)
             compress: true,
             // route prefix
-            prefix: "assets",
+            prefix: "/assets",
             // map to current CWD
             rootDir: ".",
             // strategy for computing etags (optional)

package/interceptors/static.d.ts

@@ -0,0 +1,96 @@
+import type { Fn, MaybePromise, Predicate } from "@thi.ng/api";
+import { type HashAlgo } from "@thi.ng/file-io";
+import type { OutgoingHttpHeaders } from "node:http";
+import type { Interceptor, RequestCtx, ServerRoute } from "./api.js";
+/**
+ * Static file configuration options.
+ */
+export interface StaticOpts<CTX extends RequestCtx = RequestCtx> {
+	/**
+	 * Path to local root directory for static assets. Also see
+	 * {@link StaticOpts.prefix}
+	 *
+	 * @defaultValue `.` (current cwd)
+	 */
+	rootDir: string;
+	/**
+	 * Filter predicate to exclude files from being served. Called with the
+	 * absolute local file path. If the function returns false, the server
+	 * produces a 404 response. By default all files (within
+	 * {@link StaticOpts.rootDir}) will be allowed.
+	 */
+	filter: Predicate<string>;
+	/**
+	 * Base URL prefix for static assets.  Also see {@link StaticOpts.rootDir}
+	 *
+	 * @defaultValue "static"
+	 */
+	prefix: string;
+	/**
+	 * Additional route specific interceptors.
+	 */
+	intercept: Interceptor<CTX>[];
+	/**
+	 * Additional common headers (e.g. cache control) for all static files
+	 */
+	headers: OutgoingHttpHeaders;
+	/**
+	 * If true (default: false), files will be served with brotli, gzip or deflate
+	 * compression (if the client supports it).
+	 *
+	 * @defaultValue false
+	 */
+	compress: boolean;
+	/**
+	 * User defined function to compute an Etag value for given file path. The
+	 * file is guaranteed to exist when this function is called.
+	 */
+	etag: Fn<string, MaybePromise<string>>;
+	/**
+	 * If true, the route will have its `auth` flag enabled, e.g. for use with
+	 * the {@link authenticateWith} interceptor.
+	 *
+	 * @defaultValue false
+	 */
+	auth: boolean;
+}
+/**
+ * Defines a configurable {@link ServerRoute} and handler for serving static
+ * files from a local directory (optionally with compression, see
+ * {@link StaticOpts.compress} for details).
+ *
+ * @param opts
+ */
+export declare const staticFiles: <CTX extends RequestCtx = RequestCtx>({
+	prefix,
+	rootDir,
+	intercept,
+	filter,
+	compress,
+	auth,
+	etag,
+	headers,
+}?: Partial<StaticOpts<CTX>>) => ServerRoute<CTX>;
+/**
+ * Etag header value function for {@link StaticOpts.etag}. Computes Etag based
+ * on file modified date.
+ *
+ * @remarks
+ * Also see {@link etagFileHash}.
+ *
+ * @param path
+ */
+export declare const etagFileTimeModified: (path: string) => string;
+/**
+ * Higher-order Etag header value function for {@link StaticOpts.etag}. Computes
+ * Etag value by computing the hash digest of a given file. Uses MD5 by default.
+ *
+ * @remarks
+ * Also see {@link etagFileTimeModified}.
+ *
+ * @param algo
+ */
+export declare const etagFileHash: (
+	algo?: HashAlgo
+) => (path: string) => Promise<string>;
+//# sourceMappingURL=static.d.ts.map

package/interceptors/static.js

@@ -0,0 +1,73 @@
+import { fileHash as $fileHash } from "@thi.ng/file-io";
+import { preferredTypeForPath } from "@thi.ng/mime";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { isUnmodified } from "../utils/cache.js";
+const staticFiles = ({
+  prefix = "static",
+  rootDir = ".",
+  intercept = [],
+  filter = () => true,
+  compress = false,
+  auth = false,
+  etag,
+  headers
+} = {}) => ({
+  id: "__static",
+  match: [prefix, "+"],
+  auth,
+  handlers: {
+    head: {
+      fn: async (ctx) => {
+        const path = join(rootDir, ...ctx.match.rest);
+        ctx.logger.debug("path", path);
+        const $headers = await __fileHeaders(
+          path,
+          ctx,
+          filter,
+          etag,
+          headers
+        );
+        if (!$headers) return;
+        ctx.res.writeHead(200, {
+          "content-type": preferredTypeForPath(path),
+          ...$headers
+        });
+      },
+      intercept
+    },
+    get: {
+      fn: async (ctx) => {
+        const path = join(rootDir, ...ctx.match.rest);
+        ctx.logger.debug("path", path);
+        const $headers = await __fileHeaders(
+          path,
+          ctx,
+          filter,
+          etag,
+          headers
+        );
+        if (!$headers) return;
+        return ctx.server.sendFile(ctx, path, $headers, compress);
+      },
+      intercept
+    }
+  }
+});
+const __fileHeaders = async (path, ctx, filter, etag, headers) => {
+  if (!(existsSync(path) && filter(path))) {
+    return ctx.res.missing();
+  }
+  if (etag) {
+    const etagValue = await etag(path);
+    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.res.unmodified() : { ...headers, etag: etagValue };
+  }
+  return { ...headers };
+};
+const etagFileTimeModified = (path) => String(statSync(path).mtimeMs);
+const etagFileHash = (algo = "md5") => (path) => $fileHash(path, void 0, algo);
+export {
+  etagFileHash,
+  etagFileTimeModified,
+  staticFiles
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -39,20 +39,20 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.23",
-    "@thi.ng/arrays": "^2.10.20",
-    "@thi.ng/cache": "^2.3.28",
-    "@thi.ng/checks": "^3.7.3",
-    "@thi.ng/errors": "^2.5.29",
-    "@thi.ng/file-io": "^2.1.32",
-    "@thi.ng/leaky-bucket": "^0.2.1",
-    "@thi.ng/logger": "^3.1.4",
-    "@thi.ng/mime": "^2.7.5",
-    "@thi.ng/paths": "^5.2.6",
-    "@thi.ng/router": "^4.1.23",
-    "@thi.ng/strings": "^3.9.8",
-    "@thi.ng/timestamp": "^1.1.8",
-    "@thi.ng/uuid": "^1.1.20"
+    "@thi.ng/api": "^8.11.24",
+    "@thi.ng/arrays": "^2.10.21",
+    "@thi.ng/cache": "^2.3.29",
+    "@thi.ng/checks": "^3.7.4",
+    "@thi.ng/errors": "^2.5.30",
+    "@thi.ng/file-io": "^2.1.33",
+    "@thi.ng/leaky-bucket": "^0.2.2",
+    "@thi.ng/logger": "^3.1.5",
+    "@thi.ng/mime": "^2.7.6",
+    "@thi.ng/paths": "^5.2.7",
+    "@thi.ng/router": "^4.1.24",
+    "@thi.ng/strings": "^3.9.9",
+    "@thi.ng/timestamp": "^1.1.9",
+    "@thi.ng/uuid": "^1.1.21"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
@@ -167,5 +167,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "dfecb91b5b6a05db32d96f261e0c0ac6319240b9\n"
+  "gitHead": "0e2dadea20613d4a349177a669d73d7a4257898d\n"
 }

package/server.js

@@ -140,7 +140,7 @@ class Server {
         res.notAllowed();
       }
     } catch (e) {
-      this.logger.warn("error:", e.message);
+      this.logger.warn(`error:`, req.url, e.message);
       res.writeHead(500).end();
     }
   }

package/static.d.ts

@@ -14,30 +14,40 @@ export interface StaticOpts<CTX extends RequestCtx = RequestCtx> {
      */
     rootDir: string;
     /**
-     * Filter predicate to exclude files from being served. Called with the
-     * absolute local file path. If the function returns false, the server
-     * produces a 404 response. By default all files (within
-     * {@link StaticOpts.rootDir}) will be allowed.
+     * Filter predicates to validate & exclude file paths from being served.
+     * Executed in given order and each one called with the absolute local file
+     * path. If any of the predicates returns false, the server produces a 404
+     * response. By default only uses {@link pathFilterASCII}.
      */
-    filter: Predicate<string>;
+    filters: Predicate<string>[];
     /**
-     * Base URL prefix for static assets.  Also see {@link StaticOpts.rootDir}
+     * URL path prefix for defining the static assets route. Also see
+     * {@link StaticOpts.rootDir}.
+     *
+     * @remarks
+     * If given as array, each item is a path component, i.e. `["public",
+     * "img"]` is the same as `"/public/img"`.
      *
      * @defaultValue "static"
      */
-    prefix: string;
+    prefix: string | string[];
     /**
      * Additional route specific interceptors.
      */
     intercept: Interceptor<CTX>[];
     /**
-     * Additional common headers (e.g. cache control) for all static files
+     * Additional common headers (e.g. cache control) for a file. If given as
+     * function, it will be called with the absolute path (the function will
+     * only be called if the path exists and already has passed validation).
      */
-    headers: OutgoingHttpHeaders;
+    headers: OutgoingHttpHeaders | Fn<string, OutgoingHttpHeaders>;
     /**
      * If true (default: false), files will be served with brotli, gzip or deflate
      * compression (if the client supports it).
      *
+     * @remarks
+     * Note: Whilst compression can
+     *
      * @defaultValue false
      */
     compress: boolean;
@@ -61,10 +71,10 @@ export interface StaticOpts<CTX extends RequestCtx = RequestCtx> {
  *
  * @param opts
  */
-export declare const staticFiles: <CTX extends RequestCtx = RequestCtx>({ prefix, rootDir, intercept, filter, compress, auth, etag, headers, }?: Partial<StaticOpts<CTX>>) => ServerRoute<CTX>;
+export declare const staticFiles: <CTX extends RequestCtx = RequestCtx>({ prefix, rootDir, intercept, filters, compress, auth, etag, headers, }?: Partial<StaticOpts<CTX>>) => ServerRoute<CTX>;
 /**
  * Etag header value function for {@link StaticOpts.etag}. Computes Etag based
- * on file modified date.
+ * on base36-encoded file modified timestamp.
  *
  * @remarks
  * Also see {@link etagFileHash}.
@@ -82,4 +92,20 @@ export declare const etagFileTimeModified: (path: string) => string;
  * @param algo
  */
 export declare const etagFileHash: (algo?: HashAlgo) => (path: string) => Promise<string>;
+/**
+ * Default path filter predicate for {@link StaticOpts.filter}. Rejects a file
+ * path which contains non-printable ASCII chars (i.e. outside the
+ * `[0x20,0x7fe]` range).
+ *
+ * @param path
+ */
+export declare const pathFilterASCII: (path: string) => boolean;
+/**
+ * Higher order path filter predicate for {@link StaticOpts.filter}. The
+ * returned predicate rejects an absolute file path if its length exceeds given
+ * `limit`.
+ *
+ * @param limit
+ */
+export declare const pathMaxLength: (limit: number) => Predicate<string>;
 //# sourceMappingURL=static.d.ts.map

package/static.js

@@ -1,71 +1,71 @@
+import { isFunction, isString } from "@thi.ng/checks";
 import { fileHash as $fileHash } from "@thi.ng/file-io";
 import { preferredTypeForPath } from "@thi.ng/mime";
 import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { isUnmodified } from "./utils/cache.js";
 const staticFiles = ({
   prefix = "static",
   rootDir = ".",
   intercept = [],
-  filter = () => true,
+  filters = [pathFilterASCII],
   compress = false,
   auth = false,
   etag,
   headers
-} = {}) => ({
-  id: "__static",
-  match: [prefix, "+"],
-  auth,
-  handlers: {
-    head: {
-      fn: async (ctx) => {
-        const path = join(rootDir, ...ctx.match.rest);
-        const $headers = await __fileHeaders(
-          path,
-          ctx,
-          filter,
-          etag,
-          headers
-        );
-        if (!$headers) return;
-        ctx.res.writeHead(200, {
-          "content-type": preferredTypeForPath(path),
-          ...$headers
-        });
-      },
-      intercept
-    },
-    get: {
-      fn: async (ctx) => {
-        const path = join(rootDir, ...ctx.match.rest);
-        const $headers = await __fileHeaders(
-          path,
-          ctx,
-          filter,
-          etag,
-          headers
-        );
-        if (!$headers) return;
-        return ctx.server.sendFile(ctx, path, $headers, compress);
-      },
-      intercept
+} = {}) => {
+  rootDir = resolve(rootDir);
+  const filter = (path) => filters.every((f) => f(path));
+  return {
+    id: "__static",
+    match: isString(prefix) ? prefix + "/+" : [...prefix, "+"],
+    auth,
+    handlers: {
+      get: {
+        fn: async (ctx) => {
+          const path = resolve(join(rootDir, ...ctx.match.rest));
+          const $headers = await __fileHeaders(
+            rootDir,
+            path,
+            ctx,
+            filter,
+            etag,
+            headers
+          );
+          if (!$headers) return;
+          if (ctx.origMethod === "head") {
+            ctx.res.writeHead(200, {
+              "content-type": preferredTypeForPath(path),
+              ...$headers
+            });
+            return;
+          }
+          return ctx.server.sendFile(ctx, path, $headers, compress);
+        },
+        intercept
+      }
     }
-  }
-});
-const __fileHeaders = async (path, ctx, filter, etag, headers) => {
-  if (!(existsSync(path) && filter(path))) {
+  };
+};
+const __fileHeaders = async (rootDir, path, ctx, filter, etag, headers) => {
+  if (!(path.length > rootDir.length && filter(path) && existsSync(path))) {
     return ctx.res.missing();
   }
+  const $headers = isFunction(headers) ? headers(path) : headers;
   if (etag) {
     const etagValue = await etag(path);
-    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.res.unmodified() : { ...headers, etag: etagValue };
+    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.res.unmodified() : { ...$headers, etag: etagValue };
   }
-  return { ...headers };
+  return { ...$headers };
 };
-const etagFileTimeModified = (path) => String(statSync(path).mtimeMs);
+const etagFileTimeModified = (path) => statSync(path).mtimeMs.toString(36);
 const etagFileHash = (algo = "md5") => (path) => $fileHash(path, void 0, algo);
+const pathFilterASCII = (path) => !/[^\x20-\x7e]/.test(path);
+const pathMaxLength = (limit) => (path) => path.length < limit;
 export {
   etagFileHash,
   etagFileTimeModified,
+  pathFilterASCII,
+  pathMaxLength,
   staticFiles
 };