@thi.ng/server 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-29T16:25:48Z
+- **Last updated**: 2025-01-30T15:45:22Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,22 @@ 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.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.2.0) (2025-01-30)
+
+#### 🚀 Features
+
+- add generics, various other updates ([a340f65](https://github.com/thi-ng/umbrella/commit/a340f65))
+  - add generics to most main types/interfaces
+  - refactor `SessionInterceptor` as class w/ pluggable storage
+  - add `ISessionStore` and `InMemorySessionStore` impl
+  - update ServerOpts to allow augmenting request context object
+  - add default HTTP OPTIONS handler
+  - update Server cookie parsing
+  - add StaticOpts.auth flag
+  - update logRequest() interceptor
+  - update pkg exports
+  - update tests
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.1.0) (2025-01-29)
 
 #### 🚀 Features

package/README.md

@@ -39,38 +39,47 @@ implementations.
 ### Main features
 
 - Declarative & parametric routing (incl. validation and coercion of route
-params)
+  params)
+    - Uses [@thi.ng/router](https://github.com/thi-ng/umbrella/tree/develop/packages/router) as implementation
 - Multiple HTTP methods per route
-- Composable & customizable interceptors (global for all routes and/or for
-  indidual routes & HTTP methods)
+    - Built-in HTTP OPTIONS handler for listing available route methods
+    - Fallback HTTP HEAD to GET method (if available)
 - Asynchronous route handler processing
+    - Composable & customizable interceptor chains
+    - 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
+  detection and support for Etags, as well as Brotli, Gzip and Deflate
+  compression
 - Utilities for parsing form-encoded multipart request bodies
 
 ### Interceptors
 
-Interceptors are additionally injected handlers (aka middleware) which are
+Interceptors are additionally injected route handlers (aka middleware) which are
 pre/post-processed before/after a route's main handler and can be used for
 validation, cancellation or other side effects. Each single interceptor can have
-a `pre` and/or `post` phase function. Post-phase interceptors are processed in
-reverse order. See
+a `pre` and/or `post` phase function. Each route handler can define its own
+interceptor chains, which will be appended to the globally defined interceptors
+(applied to all routes). Post-phase interceptors are processed in reverse order.
+See
 [`Interceptor`](https://docs.thi.ng/umbrella/server/interfaces/Interceptor.html)
 for more details.
 
+![Diagram illustrating interceptor processing order](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/server/server-interceptors.png)
+
 #### Available interceptors
 
-- [`authenticateWith()`](https://docs.thi.ng/umbrella/server/functions/authenticateWith.html)
-- [`cacheControl()`](https://docs.thi.ng/umbrella/server/functions/cacheControl.html)
-- [`crossOriginOpenerPolicy()`](https://docs.thi.ng/umbrella/server/functions/crossOriginOpenerPolicy.html)
-- [`crossOriginResourcePolicy()`](https://docs.thi.ng/umbrella/server/functions/crossOriginResourcePolicy.html)
-- [`injectHeaders()`](https://docs.thi.ng/umbrella/server/functions/injectHeaders.html)
-- [`logRequest()`](https://docs.thi.ng/umbrella/server/functions/logRequest.html)
-- [`logResponse()`](https://docs.thi.ng/umbrella/server/functions/logResponse.html)
-- [`referrerPolicy()`](https://docs.thi.ng/umbrella/server/functions/referrerPolicy.html)
-- [`serverSession()`](https://docs.thi.ng/umbrella/server/functions/serverSession.html)
-- [`strictTransportSecurity()`](https://docs.thi.ng/umbrella/server/functions/strictTransportSecurity.html)
+- [`authenticateWith()`](https://docs.thi.ng/umbrella/server/functions/authenticateWith.html): Predicate function based authentication
+- [`cacheControl()`](https://docs.thi.ng/umbrella/server/functions/cacheControl.html): Cache control header injection
+- [`crossOriginOpenerPolicy()`](https://docs.thi.ng/umbrella/server/functions/crossOriginOpenerPolicy-1.html): Policy header injection
+- [`crossOriginResourcePolicy()`](https://docs.thi.ng/umbrella/server/functions/crossOriginResourcePolicy-1.html): Policy header injection
+- [`injectHeaders()`](https://docs.thi.ng/umbrella/server/functions/injectHeaders.html): Arbitrary header injection
+- [`logRequest()`](https://docs.thi.ng/umbrella/server/functions/logRequest.html): Request detail logging
+- [`logResponse()`](https://docs.thi.ng/umbrella/server/functions/logResponse.html): Response logging
+- [`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
+- [`strictTransportSecurity()`](https://docs.thi.ng/umbrella/server/functions/strictTransportSecurity.html): Policy header injection
 
 #### Custom interceptors
 
@@ -138,7 +147,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.75 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.02 KB
 
 ## Dependencies
 
@@ -164,34 +173,96 @@ Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 ### Usage example
 
 ```ts tangle:export/readme-hello.ts
-import {
-    server, staticFiles, cacheControl, etagFileHash, logRequest
-} from "@thi.ng/server";
+import * as srv from "@thi.ng/server";
+
+// all route handlers & interceptors receive a request context object
+// here we define an extended/customized version
+interface AppCtx extends srv.RequestCtx {
+    session?: AppSession;
+}
+
+// customized version of the default server session type
+interface AppSession extends srv.ServerSession {
+    user?: string;
+    locale?: string;
+}
+
+// interceptor for injecting/managing sessions
+// by default uses in-memory storage/cache
+const session = srv.serverSession<AppCtx, AppSession>();
 
-const app = server({
+// create server with given config
+const app = srv.server<AppCtx>({
+    // global interceptors (used for all routes)
+    intercept: [
+        // log all requests (using server's configured logger)
+        srv.logRequest(),
+        // lookup/create sessions (using above interceptor)
+        session,
+        // ensure routes with `auth` flag have a logged-in user
+        srv.authenticateWith<AppCtx>((ctx) => !!ctx.session?.user),
+    ],
+    // route definitions (more can be added dynamically later)
     routes: [
-        // define a route for static files
-        staticFiles({
+        // define a route for serving static assets
+        srv.staticFiles({
+            // ensure only logged-in users can access
+            auth: true,
+            // use compression (if client supports it)
             compress: true,
-            etag: etagFileHash(),
+            // route prefix
+            prefix: "assets",
+            // map to current CWD
+            rootDir: ".",
+            // strategy for computing etags (optional)
+            etag: srv.etagFileHash(),
             // route specific interceptors
-            intercept: [
-                cacheControl({ maxAge: 3600 })
-            ]
+            intercept: [srv.cacheControl({ maxAge: 3600 })],
         }),
-        // parametric route
+        // define a dummy login route
+        {
+            id: "login",
+            match: "/login",
+            handlers: {
+                // each route can specify handlers for various HTTP methods
+                post: async (ctx) => {
+                    const { user, pass } = await srv.parseRequestFormData(ctx.req);
+                    ctx.logger.info("login details", user, pass);
+                    if (user === "thi.ng" && pass === "1234") {
+                        ctx.session!.user = user;
+                        ctx.res.writeHead(200).end("logged in as " + user);
+                    } else {
+                        ctx.res.writeHead(403).end("login failed");
+                    }
+                },
+            },
+        },
+        // dummy logout route
+        {
+            id: "logout",
+            match: "/logout",
+            // use auth flag here to ensure route is only accessible if valid session
+            auth: true,
+            handlers: {
+                get: async (ctx) => {
+                    // remove session & force expire session cookie
+                    await session.delete(ctx, ctx.session!.id);
+                    ctx.res.writeHead(200).end("logged out");
+                },
+            },
+        },
+        // parametric route (w/ optional validator)
         {
             id: "hello",
             match: "/hello/?name",
-            // optional validator(s)
             validate: {
                 name: { check: (x) => /^[a-z]+$/i.test(x) },
             },
-            // each route can specify handlers for various HTTP methods
             handlers: {
-                get: async ({ match, res }) =>
-                    res.writeHead(200, { "content-type": "text/plain"})
-                       .end(`hello, ${match.params!.name.toLowerCase()}!`)
+                get: async ({ match, res }) => {
+                    res.writeHead(200, { "content-type": "text/plain" })
+                       .end(`hello, ${match.params!.name}!`);
+                },
             },
         },
         // another route to demonstrate role/usage of route IDs
@@ -201,14 +272,13 @@ const app = server({
             match: "/alias/?name",
             handlers: {
                 get: ({ server, match, res }) =>
-                    server.redirectToRoute(res, { id: "hello", params: match.params })
-            }
-        }
+                    server.redirectToRoute(res, {
+                        id: "hello",
+                        params: match.params,
+                    }),
+            },
+        },
     ],
-    // global interceptors (used for all routes)
-    intercept: [
-        logRequest(),
-    ]
 });
 
 await app.start();

package/api.d.ts

@@ -3,8 +3,8 @@ import type { ILogger } from "@thi.ng/logger";
 import type { Route, RouteMatch } from "@thi.ng/router";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Server } from "./server.js";
-import type { ServerSession } from "./interceptors/session.js";
-export interface ServerOpts {
+export type Method = "get" | "put" | "post" | "delete" | "head" | "options" | "patch";
+export interface ServerOpts<CTX extends RequestCtx = RequestCtx> {
     logger: ILogger;
     /**
      * SSL configuration
@@ -29,7 +29,7 @@ export interface ServerOpts {
      * Initial list of routes (more can be added dynamically via
      * {@link Server.addRoutes}).
      */
-    routes: ServerRoute[];
+    routes: ServerRoute<CTX>[];
     /**
      * Route prefix. Default: `/`. All routes are assumed to have this prefix
      * prepended. If given, the prefix MUST end with `/`.
@@ -44,13 +44,22 @@ export interface ServerOpts {
      * Interceptors (aka pre/post middlewares) which are to be applied to all
      * route handlers (in the given order).
      */
-    intercept: Interceptor[];
+    intercept: Interceptor<CTX>[];
+    /**
+     * User defined function to augment the {@link RequestCtx} object for each
+     * request before processing its handler & interceptors.
+     */
+    context: Fn<RequestCtx, CTX>;
 }
-export interface ServerRoute extends Route {
-    handlers: Partial<Record<Method, RequestHandler>>;
+export interface ServerRoute<CTX extends RequestCtx = RequestCtx> extends Route {
+    handlers: Partial<Record<Method, RequestHandler<CTX>>>;
 }
-export interface CompiledServerRoute extends Route {
-    handlers: Partial<Record<Method, CompiledHandler>>;
+/**
+ * Version of {@link ServerRoute} whose handlers/interceptors already have been
+ * pre-processed.
+ */
+export interface CompiledServerRoute<CTX extends RequestCtx = RequestCtx> extends Route {
+    handlers: Partial<Record<Method, CompiledHandler<CTX>>>;
 }
 export interface RequestCtx {
     server: Server;
@@ -63,12 +72,12 @@ export interface RequestCtx {
     query: Record<string, any>;
     cookies?: Record<string, string>;
     session?: ServerSession;
-    [id: string]: any;
 }
-export type HandlerResult = MaybePromise<Maybe<RequestCtx> | void>;
-export type RequestHandler = Fn<RequestCtx, HandlerResult> | InterceptedRequestHandler;
-export interface InterceptedRequestHandler {
-    fn: Fn<RequestCtx, HandlerResult>;
+export type HandlerResult = MaybePromise<void>;
+export type InterceptorResult = MaybePromise<boolean>;
+export type RequestHandler<CTX extends RequestCtx = RequestCtx> = Fn<CTX, HandlerResult> | InterceptedRequestHandler<CTX>;
+export interface InterceptedRequestHandler<CTX extends RequestCtx = RequestCtx> {
+    fn: Fn<CTX, HandlerResult>;
     /**
      * List of interceptors which will be executed when processing the main
      * handler {@link InterceptedRequestHandler.fn}.
@@ -85,14 +94,14 @@ export interface InterceptedRequestHandler {
      * If an interceptor function returns false, further processing stops and
      * response will be closed.
      */
-    intercept: Interceptor[];
+    intercept: Interceptor<CTX>[];
 }
-export interface CompiledHandler {
-    fn: Fn<RequestCtx, HandlerResult>;
-    pre?: Fn<RequestCtx, InterceptorResult>[];
-    post?: Fn<RequestCtx, InterceptorResult>[];
+export interface CompiledHandler<CTX extends RequestCtx = RequestCtx> {
+    fn: Fn<CTX, HandlerResult>;
+    pre?: Fn<CTX, InterceptorResult>[];
+    post?: Fn<CTX, InterceptorResult>[];
 }
-export interface Interceptor {
+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
@@ -100,15 +109,47 @@ export interface Interceptor {
      * pre-interceptors, the main handler and all post-interceptors will be
      * skipped.
      */
-    pre?: Fn<RequestCtx, InterceptorResult>;
+    pre?: Fn<CTX, InterceptorResult>;
     /**
      * 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.
      */
-    post?: Fn<RequestCtx, InterceptorResult>;
+    post?: Fn<CTX, InterceptorResult>;
+}
+export interface ServerSession {
+    id: string;
+    flash?: FlashMsg;
+}
+export interface FlashMsg {
+    type: "success" | "info" | "warn" | "error";
+    body: any;
+}
+export interface ISessionStore<T extends ServerSession = ServerSession> {
+    /**
+     * Attempts to retrieve the session for given `id`.
+     *
+     * @param id
+     */
+    get(id: string): MaybePromise<Maybe<T>>;
+    /**
+     * Adds given `session` to underlying storage.
+     *
+     * @param session
+     */
+    set(session: T): MaybePromise<boolean>;
+    /**
+     * Attempts to delete the session for given `id` from storage. Returns true
+     * if successful.
+     *
+     * @param id
+     */
+    delete(id: string): MaybePromise<boolean>;
+    /**
+     * Configured Time-To-Live for stored sessions. Will also be used to
+     * configure the `max-age` attribute of the session ID cookie.
+     */
+    readonly ttl: number;
 }
-export type InterceptorResult = MaybePromise<boolean>;
-export type Method = "get" | "put" | "post" | "delete" | "head" | "options" | "patch";
 //# sourceMappingURL=api.d.ts.map

package/index.d.ts

@@ -6,10 +6,11 @@ export * from "./interceptors/cache-control.js";
 export * from "./interceptors/inject-headers.js";
 export * from "./interceptors/logging.js";
 export * from "./interceptors/referrer-policy.js";
-export * from "./interceptors/session.js";
 export * from "./interceptors/strict-transport.js";
 export * from "./interceptors/x-origin-opener.js";
 export * from "./interceptors/x-origin-resource.js";
+export * from "./session/session.js";
+export * from "./session/memory.js";
 export * from "./utils/cookies.js";
 export * from "./utils/cache.js";
 export * from "./utils/formdata.js";

package/index.js

@@ -6,10 +6,11 @@ export * from "./interceptors/cache-control.js";
 export * from "./interceptors/inject-headers.js";
 export * from "./interceptors/logging.js";
 export * from "./interceptors/referrer-policy.js";
-export * from "./interceptors/session.js";
 export * from "./interceptors/strict-transport.js";
 export * from "./interceptors/x-origin-opener.js";
 export * from "./interceptors/x-origin-resource.js";
+export * from "./session/session.js";
+export * from "./session/memory.js";
 export * from "./utils/cookies.js";
 export * from "./utils/cache.js";
 export * from "./utils/formdata.js";

package/interceptors/auth-route.d.ts

@@ -14,5 +14,5 @@ import type { Interceptor, RequestCtx } from "../api.js";
  *
  * @param pred
  */
-export declare const authenticateWith: (pred: Predicate<RequestCtx>) => Interceptor;
+export declare const authenticateWith: <CTX extends RequestCtx>(pred: Predicate<CTX>) => Interceptor<CTX>;
 //# sourceMappingURL=auth-route.d.ts.map

package/interceptors/logging.js

@@ -4,12 +4,11 @@ const __method = (level) => (isString(level) ? level : LogLevel[level]).toLowerC
 const logRequest = (level = "INFO") => {
   const method = __method(level);
   return {
-    pre: ({ logger, req, match, query }) => {
+    pre: ({ logger, req, match, query, cookies }) => {
       logger[method]("request route", req.method, match);
       logger[method]("request headers", req.headers);
-      if (Object.keys(query).length) {
-        logger[method]("request query", query);
-      }
+      logger[method]("request cookies", cookies);
+      logger[method]("request query", query);
       return true;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -90,6 +90,7 @@
     "./*.js",
     "./*.d.ts",
     "interceptors",
+    "session",
     "utils"
   ],
   "exports": {
@@ -114,9 +115,6 @@
     "./interceptors/referrer-policy": {
       "default": "./interceptors/referrer-policy.js"
     },
-    "./interceptors/session": {
-      "default": "./interceptors/session.js"
-    },
     "./interceptors/strict-transport": {
       "default": "./interceptors/strict-transport.js"
     },
@@ -129,6 +127,12 @@
     "./server": {
       "default": "./server.js"
     },
+    "./session/memory": {
+      "default": "./session/memory.js"
+    },
+    "./session/session": {
+      "default": "./session/session.js"
+    },
     "./static": {
       "default": "./static.js"
     },
@@ -149,5 +153,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "fc1d498e8d4b690db873c30cc594352a804e7a65\n"
+  "gitHead": "078de98f4365f0d472c87198bcd6a112e732d9ef\n"
 }

package/server.d.ts

@@ -1,18 +1,20 @@
+import { type Fn } from "@thi.ng/api";
 import { type ILogger } from "@thi.ng/logger";
 import { Router, type RouteMatch } from "@thi.ng/router";
 import * as http from "node:http";
 import type { CompiledHandler, CompiledServerRoute, RequestCtx, ServerOpts, ServerRoute } from "./api.js";
-export declare class Server {
-    opts: Partial<ServerOpts>;
+export declare class Server<CTX extends RequestCtx = RequestCtx> {
+    opts: Partial<ServerOpts<CTX>>;
     logger: ILogger;
-    router: Router;
+    router: Router<CompiledServerRoute<CTX>>;
     server: http.Server;
-    constructor(opts?: Partial<ServerOpts>);
+    protected augmentCtx: Fn<RequestCtx, CTX>;
+    constructor(opts?: Partial<ServerOpts<CTX>>);
     start(): Promise<boolean>;
     stop(): Promise<boolean>;
-    listener(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
-    runHandler({ fn, pre, post }: CompiledHandler, ctx: RequestCtx): Promise<void>;
-    protected compileRoute(route: ServerRoute): CompiledServerRoute;
+    protected listener(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
+    protected runHandler({ fn, pre, post }: CompiledHandler, ctx: CTX): Promise<void>;
+    protected compileRoute(route: ServerRoute<CTX>): CompiledServerRoute<CTX>;
     addRoutes(routes: ServerRoute[]): void;
     sendFile({ req, res }: RequestCtx, path: string, headers?: http.OutgoingHttpHeaders, compress?: boolean): Promise<void>;
     unauthorized(res: http.ServerResponse): void;
@@ -21,5 +23,5 @@ export declare class Server {
     redirectTo(res: http.ServerResponse, location: string): void;
     redirectToRoute(res: http.ServerResponse, route: RouteMatch): void;
 }
-export declare const server: (opts?: Partial<ServerOpts>) => Server;
+export declare const server: <CTX extends RequestCtx>(opts?: Partial<ServerOpts<CTX>>) => Server<CTX>;
 //# sourceMappingURL=server.d.ts.map

package/server.js

@@ -1,3 +1,4 @@
+import { identity } from "@thi.ng/api";
 import { isFunction } from "@thi.ng/checks";
 import { readText } from "@thi.ng/file-io";
 import { ConsoleLogger } from "@thi.ng/logger";
@@ -10,11 +11,13 @@ import { pipeline, Transform } from "node:stream";
 import { createBrotliCompress, createDeflate, createGzip } from "node:zlib";
 import { parseCoookies } from "./utils/cookies.js";
 import { parseSearchParams } from "./utils/formdata.js";
+import { upper } from "@thi.ng/strings";
 const MISSING = "__missing";
 class Server {
   constructor(opts = {}) {
     this.opts = opts;
     this.logger = opts.logger ?? new ConsoleLogger("server");
+    this.augmentCtx = opts.context ?? identity;
     const routes = [
       {
         id: MISSING,
@@ -35,6 +38,7 @@ class Server {
   logger;
   router;
   server;
+  augmentCtx;
   async start() {
     const ssl = this.opts.ssl;
     const port = this.opts.port ?? (ssl ? 443 : 8080);
@@ -76,9 +80,10 @@ class Server {
       const query = parseSearchParams(url.searchParams);
       const match = this.router.route(path);
       const route = this.router.routeForID(match.id).spec;
-      const rawCookies = req.headers["set-cookie"]?.join(";");
+      const rawCookies = req.headers["cookie"] || req.headers["set-cookie"]?.join(";");
       const cookies = rawCookies ? parseCoookies(rawCookies) : {};
-      const ctx = {
+      const ctx = this.augmentCtx({
+        // @ts-ignore
         server: this,
         logger: this.logger,
         req,
@@ -88,12 +93,18 @@ class Server {
         cookies,
         route,
         match
-      };
+      });
       if (match.id === MISSING) {
         this.runHandler(route.handlers.get, ctx);
         return;
       }
       let method = ctx.query?.__method || req.method.toLowerCase();
+      if (method === "options" && !route.handlers.options) {
+        res.writeHead(204, {
+          allow: Object.keys(route.handlers).map(upper).join(", ")
+        }).end();
+        return;
+      }
       if (method === "head" && !route.handlers.head && route.handlers.get) {
         method = "get";
       }

package/session/memory.d.ts

@@ -0,0 +1,41 @@
+import { TLRUCache } from "@thi.ng/cache";
+import type { ISessionStore, ServerSession } from "../api.js";
+export interface InMemorySessionOpts<T extends ServerSession = ServerSession> {
+    /**
+     * Session timeout in seconds.
+     *
+     * @defaultValue 3600
+     */
+    ttl: number;
+    /**
+     * If true (default), a session's cache span automatically extends by
+     * {@link InMemorySessionOpts.ttl} with each request. If false, the session
+     * auto-expires after TTL since session creation.
+     *
+     * @defaultValue true
+     */
+    autoExtend: boolean;
+    /**
+     * Initial record of active sessions (none by default).
+     */
+    initial: Record<string, T>;
+}
+/**
+ * Session storage implementation for use with {@link serverSession}, using an
+ * in-memory TLRU Cache with configurable TTL.
+ */
+export declare class InMemorySessionStore<T extends ServerSession = ServerSession> implements ISessionStore<T> {
+    readonly ttl: number;
+    protected sessions: TLRUCache<string, T>;
+    constructor({ ttl, autoExtend, initial, }?: Partial<InMemorySessionOpts<T>>);
+    get(id: string): T | undefined;
+    set(session: T): boolean;
+    delete(id: string): boolean;
+}
+/**
+ * Factory function for creating a new {@link InMemorySessionStore}.
+ *
+ * @param opts
+ */
+export declare const inMemorySessionStore: <T extends ServerSession = ServerSession>(opts?: Partial<InMemorySessionOpts<T>>) => InMemorySessionStore<T>;
+//# sourceMappingURL=memory.d.ts.map

package/session/memory.js

@@ -0,0 +1,34 @@
+import { TLRUCache } from "@thi.ng/cache";
+class InMemorySessionStore {
+  ttl;
+  sessions;
+  constructor({
+    ttl = 3600,
+    autoExtend = true,
+    initial
+  } = {}) {
+    this.ttl = ttl;
+    this.sessions = new TLRUCache(
+      initial ? Object.entries(initial) : null,
+      {
+        ttl: ttl * 1e3,
+        autoExtend
+      }
+    );
+  }
+  get(id) {
+    return this.sessions.get(id);
+  }
+  set(session) {
+    this.sessions.set(session.id, session);
+    return true;
+  }
+  delete(id) {
+    return this.sessions.delete(id);
+  }
+}
+const inMemorySessionStore = (opts) => new InMemorySessionStore(opts);
+export {
+  InMemorySessionStore,
+  inMemorySessionStore
+};

package/session/session.d.ts

@@ -0,0 +1,43 @@
+import type { Fn } from "@thi.ng/api";
+import { ServerResponse } from "node:http";
+import type { Interceptor, ISessionStore, RequestCtx, ServerSession } from "../api.js";
+export interface SessionOpts<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> {
+    /**
+     * Session storage implementation. Default: {@link InMemorySessionStore}.
+     */
+    store: ISessionStore<SESSION>;
+    /**
+     * Factory function to create a new session object. By default the object
+     * only contains a {@link ServerSession.id} (UUID v4).
+     */
+    factory: Fn<CTX, SESSION>;
+    /**
+     * Session cookie name
+     *
+     * @defaultValue "__sid"
+     */
+    cookieName?: string;
+    /**
+     * Additional session cookie config options.
+     *
+     * @defaultValue "Secure;HttpOnly;SameSite=Strict;Path=/"
+     */
+    cookieOpts?: string;
+}
+export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession> implements Interceptor<CTX> {
+    store: ISessionStore<SESSION>;
+    factory: Fn<CTX, SESSION>;
+    cookieName: string;
+    cookieOpts: string;
+    constructor({ store, factory, cookieName, cookieOpts, }?: Partial<SessionOpts<CTX, SESSION>>);
+    pre(ctx: CTX): Promise<boolean>;
+    delete(ctx: CTX, sessionID: string): Promise<void>;
+    withSession(res: ServerResponse, sessionID: string): void;
+}
+/**
+ * Factory function to create a new {@link SessionInterceptor} instance.
+ *
+ * @param opts
+ */
+export declare const serverSession: <CTX extends RequestCtx = RequestCtx, SESSION extends ServerSession = ServerSession>(opts?: Partial<SessionOpts<CTX, SESSION>>) => SessionInterceptor<CTX, SESSION>;
+//# sourceMappingURL=session.d.ts.map

package/session/session.js

@@ -0,0 +1,54 @@
+import { uuid } from "@thi.ng/uuid";
+import { ServerResponse } from "node:http";
+import { inMemorySessionStore } from "./memory.js";
+class SessionInterceptor {
+  store;
+  factory;
+  cookieName;
+  cookieOpts;
+  constructor({
+    store = inMemorySessionStore(),
+    factory = () => ({ id: uuid() }),
+    cookieName = "__sid",
+    cookieOpts = "Secure;HttpOnly;SameSite=Strict;Path=/"
+  } = {}) {
+    this.store = store;
+    this.factory = factory;
+    this.cookieName = cookieName;
+    this.cookieOpts = cookieOpts;
+  }
+  async pre(ctx) {
+    const { res, logger, cookies } = ctx;
+    const id = cookies?.[this.cookieName];
+    let session = id ? await this.store.get(id) : void 0;
+    if (!session) {
+      session = this.factory(ctx);
+      logger.info("new session:", session.id);
+      this.store.set(session);
+    }
+    ctx.session = session;
+    this.withSession(res, session.id);
+    return true;
+  }
+  async delete(ctx, sessionID) {
+    if (await this.store.delete(sessionID)) {
+      ctx.logger.info("delete session:", sessionID);
+      ctx.session = void 0;
+      ctx.res.appendHeader(
+        "set-cookie",
+        `${this.cookieName}=;Expires=Thu, 01 Jan 1970 00:00:00 GMT;${this.cookieOpts}`
+      );
+    }
+  }
+  withSession(res, sessionID) {
+    res.appendHeader(
+      "set-cookie",
+      `${this.cookieName}=${sessionID};Max-Age=${this.store.ttl};${this.cookieOpts}`
+    );
+  }
+}
+const serverSession = (opts) => new SessionInterceptor(opts);
+export {
+  SessionInterceptor,
+  serverSession
+};

package/static.d.ts

@@ -1,11 +1,11 @@
 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, ServerRoute } from "./api.js";
+import type { Interceptor, RequestCtx, ServerRoute } from "./api.js";
 /**
  * Static file configuration options.
  */
-export interface StaticOpts {
+export interface StaticOpts<CTX extends RequestCtx = RequestCtx> {
     /**
      * Path to local root directory for static assets. Also see
      * {@link StaticOpts.prefix}
@@ -29,7 +29,7 @@ export interface StaticOpts {
     /**
      * Additional route specific interceptors.
      */
-    intercept: Interceptor[];
+    intercept: Interceptor<CTX>[];
     /**
      * Additional common headers (e.g. cache control) for all static files
      */
@@ -46,6 +46,13 @@ export interface StaticOpts {
      * 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
@@ -54,7 +61,7 @@ export interface StaticOpts {
  *
  * @param opts
  */
-export declare const staticFiles: ({ prefix, rootDir, intercept, filter, compress, etag, headers, }?: Partial<StaticOpts>) => ServerRoute;
+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.

package/static.js

@@ -9,11 +9,13 @@ const staticFiles = ({
   intercept = [],
   filter = () => true,
   compress = false,
+  auth = false,
   etag,
   headers
 } = {}) => ({
   id: "__static",
   match: [prefix, "+"],
+  auth,
   handlers: {
     head: {
       fn: async (ctx) => {

package/interceptors/session.d.ts

@@ -1,51 +0,0 @@
-import type { Fn } from "@thi.ng/api";
-import * as http from "node:http";
-import type { Interceptor, RequestCtx } from "../api.js";
-export interface SessionOpts<T extends ServerSession> {
-    /**
-     * Factory function to create a new session object. By default the object
-     * only contains a {@link ServerSession.id} (UUID v4).
-     */
-    factory: Fn<RequestCtx, T>;
-    /**
-     * Initial record of active sessions (none by default).
-     */
-    initial: Record<string, T>;
-    /**
-     * Session cookie name
-     *
-     * @defaultValue "__sid"
-     */
-    cookieName?: string;
-    /**
-     * Additional session cookie config options.
-     *
-     * @defaultValue "Secure;HttpOnly;SameSite=Strict;Path=/"
-     */
-    cookieOpts?: string;
-    /**
-     * Session timeout in seconds.
-     *
-     * @defaultValue 3600
-     */
-    ttl?: number;
-}
-export interface ServerSession {
-    id: string;
-    flash?: FlashMsg;
-}
-export interface FlashMsg {
-    type: "success" | "info" | "warn" | "error";
-    body: any;
-}
-export interface SessionInterceptor extends Interceptor {
-    /**
-     * Adds configured session cookie to response.
-     *
-     * @param res
-     * @param sessionID
-     */
-    withSession(res: http.ServerResponse, sessionID: string): http.ServerResponse;
-}
-export declare const serverSession: <T extends ServerSession>(opts?: Partial<SessionOpts<T>>) => SessionInterceptor;
-//# sourceMappingURL=session.d.ts.map

package/interceptors/session.js

@@ -1,38 +0,0 @@
-import { TLRUCache } from "@thi.ng/cache";
-import { uuid } from "@thi.ng/uuid";
-import * as http from "node:http";
-const serverSession = (opts = {}) => {
-  const factory = opts.factory ?? (() => ({ id: uuid() }));
-  const ttl = opts.ttl ?? 3600;
-  const cookieName = opts.cookieName ?? "__sid";
-  const cookieOpts = `Max-Age=${ttl};` + (opts.cookieOpts ?? "Secure;HttpOnly;SameSite=Strict;Path=/");
-  const sessions = new TLRUCache(
-    opts.initial ? Object.entries(opts.initial) : null,
-    {
-      ttl: ttl * 1e3,
-      autoExtend: true
-    }
-  );
-  return {
-    pre(ctx) {
-      const { res, logger, cookies } = ctx;
-      let id = cookies?.[cookieName];
-      let session = id ? sessions.get(id) : void 0;
-      if (!session) {
-        session = factory(ctx);
-        logger.info("new session", session);
-        sessions.set(session.id, session);
-      }
-      ctx.session = session;
-      this.withSession(res, session.id);
-      return true;
-    },
-    withSession: (res, sessionID) => res.appendHeader(
-      "set-cookie",
-      `${cookieName}=${sessionID};${cookieOpts}`
-    )
-  };
-};
-export {
-  serverSession
-};