@thi.ng/server 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-02-10T21:44:04Z
+- **Last updated**: 2025-02-19T20:59:58Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,20 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.5.0) (2025-02-19)
+
+#### 🚀 Features
+
+- update interceptor handling ([9cdb8b8](https://github.com/thi-ng/umbrella/commit/9cdb8b8))
+  - update post-interceptor execution logic & return values
+  - update `Server.runHandler()`, `Server.compileRoute()`
+  - update `logResponse()`, `measure()` interceptors
+
+#### ♻️ Refactoring
+
+- rename `serverSession()` => `sessionInterceptor()` ([2ada168](https://github.com/thi-ng/umbrella/commit/2ada168))
+  - add docs
+
 ## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.4.0) (2025-02-10)
 
 #### 🚀 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 201 standalone projects, maintained as part
+> This is one of 202 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -80,7 +80,7 @@ for more details.
 - [`logResponse()`](https://docs.thi.ng/umbrella/server/functions/logResponse.html): Response logging
 - [`rateLimiter()`](https://docs.thi.ng/umbrella/server/functions/rateLimiter-1.html): Configurable rate limiting
 - [`referrerPolicy()`](https://docs.thi.ng/umbrella/server/functions/referrerPolicy-1.html): Policy header injection
-- [`serverSession()`](https://docs.thi.ng/umbrella/server/functions/serverSession-1.html): User defined in-memory sessions with TTL
+- [`sessionInterceptor()`](https://docs.thi.ng/umbrella/server/functions/sessionInterceptor-1.html): User defined in-memory sessions with TTL
 - [`strictTransportSecurity()`](https://docs.thi.ng/umbrella/server/functions/strictTransportSecurity.html): Policy header injection
 
 #### Custom interceptors
@@ -149,7 +149,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.24 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.28 KB
 
 ## Dependencies
 
@@ -192,7 +192,9 @@ interface AppSession extends srv.ServerSession {
 
 // interceptor for injecting/managing sessions
 // by default uses in-memory storage/cache
-const session = srv.serverSession<AppCtx, AppSession>();
+const session = srv.sessionInterceptor<AppCtx, AppSession>({
+    factory: srv.createSession
+});
 
 // create server with given config
 const app = srv.server<AppCtx>({

package/api.d.ts

@@ -74,7 +74,8 @@ export interface RequestCtx {
     session?: ServerSession;
 }
 export type HandlerResult = MaybePromise<void>;
-export type InterceptorResult = MaybePromise<boolean>;
+export type PreInterceptorResult = MaybePromise<boolean>;
+export type PostInterceptorResult = MaybePromise<void>;
 export type RequestHandler<CTX extends RequestCtx = RequestCtx> = Fn<CTX, HandlerResult> | InterceptedRequestHandler<CTX>;
 export interface InterceptedRequestHandler<CTX extends RequestCtx = RequestCtx> {
     fn: Fn<CTX, HandlerResult>;
@@ -98,25 +99,27 @@ export interface InterceptedRequestHandler<CTX extends RequestCtx = RequestCtx>
 }
 export interface CompiledHandler<CTX extends RequestCtx = RequestCtx> {
     fn: Fn<CTX, HandlerResult>;
-    pre?: Fn<CTX, InterceptorResult>[];
-    post?: Fn<CTX, InterceptorResult>[];
+    pre?: Maybe<Fn<CTX, PreInterceptorResult>>[];
+    post?: Maybe<Fn<CTX, PostInterceptorResult>>[];
 }
 export interface Interceptor<CTX extends RequestCtx = RequestCtx> {
     /**
      * Interceptor function which will be run BEFORE the main route handler (aka
      * {@link InterceptedRequestHandler.fn}). If an interceptor needs to cancel
      * the request processing it must return `false`. In this case any further
-     * pre-interceptors, the main handler and all post-interceptors will be
-     * skipped.
+     * pre-interceptors and the main handler will be skipped. In the post-phase,
+     * only the interceptors preceding the failed one will be run (though in
+     * reverse order). E.g. If the 3rd pre-interceptor failed, only the post
+     * phases of the first two will still be run (if available)...
      */
-    pre?: Fn<CTX, InterceptorResult>;
+    pre?: Fn<CTX, PreInterceptorResult>;
     /**
      * Interceptor function which will be run AFTER the main route handler (aka
-     * {@link InterceptedRequestHandler.fn}). If an interceptor needs to cancel
-     * the request processing it must return `false`. In this case any further
-     * post-interceptors will be skipped.
+     * {@link InterceptedRequestHandler.fn}). Post-interceptors cannot cancel
+     * request processing and are mainly intended for logging or clean-up
+     * purposes. Post interceptors
      */
-    post?: Fn<CTX, InterceptorResult>;
+    post?: Fn<CTX, PostInterceptorResult>;
 }
 export interface ServerSession {
     /**

package/interceptors/auth-route.d.ts

@@ -2,14 +2,15 @@ import type { Predicate } from "@thi.ng/api";
 import type { Interceptor, RequestCtx } from "../api.js";
 /**
  * Pre-interceptor. Checks if current route has `auth` flag enabled and if so
- * applies given predicate function to {@link RequestCtx}. If the predicate
- * returns false, the server responds with {@link Server.unauthorized} and any
- * following pre-interceptors and the main route handler will be skipped. Only
- * post-interceptors (if any) will still be executed.
+ * applies given predicate function to current {@link RequestCtx}. If the
+ * predicate returns false, the server responds with
+ * {@link ServerResponse.unauthorized} and any following pre-interceptors and
+ * the main route handler will be skipped. Only post-interceptors (if any) will
+ * still be executed.
  *
  * @remarks
- * If this interceptor is used with the {@link serverSession} interceptor, it
- * MUST come after it, otherwise the session information will not yet be
+ * If this interceptor is used with the {@link sessionInterceptor} interceptor,
+ * it MUST come after it, otherwise the session information will not yet be
  * available in the context object given to the predicate.
  *
  * @param pred

package/interceptors/logging.d.ts

@@ -9,7 +9,7 @@ import type { Interceptor } from "../api.js";
  */
 export declare const logRequest: (level?: LogLevel | LogLevelName) => Interceptor;
 /**
- * Pre-interceptor to log response details (status, route, headers) using the
+ * Post-interceptor to log response details (status, route, headers) using the
  * server's {@link ServerOpts.logger}. The `level` arg can be used to customize
  * which log level to use.
  *

package/interceptors/logging.js

@@ -17,7 +17,6 @@ const logResponse = (level = "INFO") => {
     post: ({ logger, match, res }) => {
       logger[method]("response status", res.statusCode, match);
       logger[method]("response headers", res.getHeaders());
-      return true;
     }
   };
 };

package/interceptors/measure.js

@@ -18,7 +18,6 @@ const measure = (level = "DEBUG") => {
           `request processed in: ${timeDiff(t0).toFixed(3)}ms`
         );
       }
-      return true;
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -39,24 +39,24 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.19",
-    "@thi.ng/arrays": "^2.10.14",
-    "@thi.ng/cache": "^2.3.22",
-    "@thi.ng/checks": "^3.6.22",
-    "@thi.ng/errors": "^2.5.25",
-    "@thi.ng/file-io": "^2.1.26",
-    "@thi.ng/logger": "^3.1.0",
-    "@thi.ng/mime": "^2.7.1",
-    "@thi.ng/paths": "^5.2.0",
-    "@thi.ng/router": "^4.1.17",
-    "@thi.ng/strings": "^3.9.4",
-    "@thi.ng/timestamp": "^1.1.4",
-    "@thi.ng/uuid": "^1.1.16"
+    "@thi.ng/api": "^8.11.21",
+    "@thi.ng/arrays": "^2.10.16",
+    "@thi.ng/cache": "^2.3.24",
+    "@thi.ng/checks": "^3.6.24",
+    "@thi.ng/errors": "^2.5.27",
+    "@thi.ng/file-io": "^2.1.28",
+    "@thi.ng/logger": "^3.1.2",
+    "@thi.ng/mime": "^2.7.3",
+    "@thi.ng/paths": "^5.2.2",
+    "@thi.ng/router": "^4.1.19",
+    "@thi.ng/strings": "^3.9.6",
+    "@thi.ng/timestamp": "^1.1.6",
+    "@thi.ng/uuid": "^1.1.18"
   },
   "devDependencies": {
-    "@types/node": "^22.10.10",
-    "esbuild": "^0.24.2",
-    "typedoc": "^0.27.6",
+    "@types/node": "^22.13.1",
+    "esbuild": "^0.25.0",
+    "typedoc": "^0.27.7",
     "typescript": "^5.7.3"
   },
   "keywords": [
@@ -163,5 +163,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "dcc1dbfa6eae31ac65e12843987b94d4a7edc144\n"
+  "gitHead": "bee617702ac61d093465b967f8f973dc566faa6b\n"
 }

package/server.js

@@ -127,19 +127,25 @@ class Server {
     }
   }
   async runHandler({ fn, pre, post }, ctx) {
-    const runPhase = async (fns) => {
-      for (let f of fns) {
-        if (!await f(ctx)) {
-          ctx.res.end();
-          return false;
+    try {
+      let failed;
+      if (pre) {
+        for (let i = 0, n = pre.length; i < n; i++) {
+          const fn2 = pre[i];
+          if (fn2 && !await fn2(ctx)) {
+            ctx.res.end();
+            failed = i;
+            break;
+          }
+        }
+      }
+      if (failed === void 0) await fn(ctx);
+      if (post) {
+        for (let i = failed ?? post.length; --i >= 0; ) {
+          const fn2 = post[i];
+          if (fn2) await fn2(ctx);
         }
       }
-      return true;
-    };
-    try {
-      if (pre && !await runPhase(pre)) return;
-      await fn(ctx);
-      if (post && !await runPhase(post)) return;
       ctx.res.end();
     } catch (e) {
       this.logger.warn(`handler error:`, e);
@@ -150,16 +156,18 @@ class Server {
   }
   compileRoute(route) {
     const compilePhase = (handler, phase) => {
-      const fns = [];
-      for (let x of this.opts.intercept ?? []) {
-        if (x[phase]) fns.push(x[phase].bind(x));
-      }
-      if (!isFunction(handler)) {
-        for (let x of handler.intercept ?? []) {
-          if (x[phase]) fns.push(x[phase].bind(x));
+      let isPhaseUsed = false;
+      const $bind = (iceps) => (iceps ?? []).map((x) => {
+        if (x[phase]) {
+          isPhaseUsed = true;
+          return x[phase].bind(x);
         }
+      });
+      const fns = [...$bind(this.opts.intercept)];
+      if (!isFunction(handler)) {
+        fns.push(...$bind(handler.intercept));
       }
-      return fns.length ? phase === "post" ? fns.reverse() : fns : void 0;
+      return isPhaseUsed ? fns : void 0;
     };
     const result = { ...route, handlers: {} };
     for (let method in route.handlers) {

package/session/memory.d.ts

@@ -21,8 +21,8 @@ export interface InMemorySessionOpts<T extends ServerSession = ServerSession> {
     initial: Record<string, T>;
 }
 /**
- * Session storage implementation for use with {@link serverSession}, using an
- * in-memory TLRU Cache with configurable TTL.
+ * Session storage implementation for use with {@link sessionInterceptor}, using
+ * an in-memory TLRU Cache with configurable TTL.
  */
 export declare class InMemorySessionStore<T extends ServerSession = ServerSession> implements ISessionStore<T> {
     readonly ttl: number;

package/session/session.d.ts

@@ -1,9 +1,13 @@
 import type { Fn } from "@thi.ng/api";
 import { ServerResponse } from "node:http";
 import type { Interceptor, ISessionStore, RequestCtx, ServerSession } from "../api.js";
+/**
+ * Configuration options for {@link SessionInterceptor}.
+ */
 export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> {
     /**
-     * Factory function to create a new session object. See {@link createSession}.
+     * Factory function to create a new session object. See
+     * {@link createSession} for a base implementation.
      */
     factory: Fn<CTX, SESSION>;
     /**
@@ -28,6 +32,13 @@ export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extend
      */
     secret?: number | string | Buffer;
 }
+/**
+ * Pre-interceptor which parses & validates session cookie (if available) from
+ * current request and injects/updates session cookie in response. Only a signed
+ * session ID will be stored in the cookie. Thr actual session data is held
+ * server side, via configured session storage (see {@link SessionOpts.store})
+ * (by default uses {@link InMemorySessionStore}).
+ */
 export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> implements Interceptor<CTX> {
     factory: Fn<CTX, SESSION>;
     store: ISessionStore<SESSION>;
@@ -36,7 +47,25 @@ export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SES
     secret: Buffer;
     constructor({ factory, store, cookieName, cookieOpts, secret, }: SessionOpts<CTX, SESSION>);
     pre(ctx: CTX): Promise<boolean>;
+    /**
+     * Attempts to delete session for given ID and if successful also sets
+     * force-expired cookie in response.
+     *
+     * @remarks
+     * Intended for logout handlers and/or switching sessions when a user has
+     * successfully authenticated (to avoid session fixation).
+     *
+     * @param ctx
+     * @param sessionID
+     */
     deleteSession(ctx: CTX, sessionID: string): Promise<void>;
+    /**
+     * Creates a new session object (via configured {@link SessionOpts.factory})
+     * and submits it to configured {@link SessionOpts.store}, Returns session
+     * if successful, otherwise returns `undefined`.
+     *
+     * @param ctx
+     */
     newSession(ctx: CTX): Promise<SESSION | undefined>;
     /**
      * Calls {@link SessionInterceptor.newSession} to create a new session and,
@@ -50,11 +79,12 @@ export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SES
     validateSession(cookie: string): string | undefined;
 }
 /**
- * Factory function to create a new {@link SessionInterceptor} instance.
+ * Factory function to create a new {@link SessionInterceptor} instance
+ * configured with given options.
  *
  * @param opts
  */
-export declare const serverSession: <CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession>(opts: SessionOpts<CTX, SESSION>) => SessionInterceptor<CTX, SESSION>;
+export declare const sessionInterceptor: <CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession>(opts: SessionOpts<CTX, SESSION>) => SessionInterceptor<CTX, SESSION>;
 /**
  * Creates a new basic {@link ServerSession}, using a UUID v4 for
  * {@link ServerSession.id}.

package/session/session.js

@@ -41,6 +41,17 @@ class SessionInterceptor {
     this.withSession(ctx.res, session.id);
     return true;
   }
+  /**
+   * Attempts to delete session for given ID and if successful also sets
+   * force-expired cookie in response.
+   *
+   * @remarks
+   * Intended for logout handlers and/or switching sessions when a user has
+   * successfully authenticated (to avoid session fixation).
+   *
+   * @param ctx
+   * @param sessionID
+   */
   async deleteSession(ctx, sessionID) {
     if (await this.store.delete(sessionID)) {
       ctx.logger.info("delete session:", sessionID);
@@ -51,6 +62,13 @@ class SessionInterceptor {
       );
     }
   }
+  /**
+   * Creates a new session object (via configured {@link SessionOpts.factory})
+   * and submits it to configured {@link SessionOpts.store}, Returns session
+   * if successful, otherwise returns `undefined`.
+   *
+   * @param ctx
+   */
   async newSession(ctx) {
     const session = this.factory(ctx);
     ctx.logger.info("new session:", session.id);
@@ -96,7 +114,7 @@ class SessionInterceptor {
     return timingSafeEqual(sameLength ? actual : expected, expected) && sameLength ? parts[0] : void 0;
   }
 }
-const serverSession = (opts) => new SessionInterceptor(opts);
+const sessionInterceptor = (opts) => new SessionInterceptor(opts);
 const createSession = (ctx) => ({
   id: uuid(),
   ip: ctx.req.socket.remoteAddress
@@ -104,5 +122,5 @@ const createSession = (ctx) => ({
 export {
   SessionInterceptor,
   createSession,
-  serverSession
+  sessionInterceptor
 };