@thi.ng/server 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-29T16:25:48Z
+- **Last updated**: 2025-02-02T22:46:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,29 @@ 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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.3.0) (2025-02-02)
+
+#### 🚀 Features
+
+- add more HTTP error response methods ([5731ff3](https://github.com/thi-ng/umbrella/commit/5731ff3))
+- add ServerResponse, IPv6 support ([22f64c5](https://github.com/thi-ng/umbrella/commit/22f64c5))
+
+## [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

@@ -1,10 +1,10 @@
 import type { Fn, Maybe, MaybePromise } from "@thi.ng/api";
 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 {
+import type { IncomingMessage } from "node:http";
+import type { ServerResponse, Server } from "./server.js";
+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,12 +6,14 @@ 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/host.js";
 export * from "./utils/formdata.js";
 export * from "./utils/multipart.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -6,11 +6,13 @@ 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/host.js";
 export * from "./utils/formdata.js";
 export * from "./utils/multipart.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/auth-route.js

@@ -1,7 +1,7 @@
 const authenticateWith = (pred) => ({
   pre: (ctx) => {
     if (ctx.route.auth && !pred(ctx)) {
-      ctx.server.unauthorized(ctx.res);
+      ctx.res.unauthorized();
       return false;
     }
     return true;

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.3.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"
     },
@@ -141,6 +145,9 @@
     "./utils/formdata": {
       "default": "./utils/formdata.js"
     },
+    "./utils/host": {
+      "default": "./utils/host.js"
+    },
     "./utils/multipart": {
       "default": "./utils/multipart.js"
     }
@@ -149,5 +156,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "fc1d498e8d4b690db873c30cc594352a804e7a65\n"
+  "gitHead": "fa1407b41ef907a5523d30bcb28691a5aed6e85c\n"
 }

package/server.d.ts

@@ -1,25 +1,39 @@
+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;
-    server: http.Server;
-    constructor(opts?: Partial<ServerOpts>);
+    router: Router<CompiledServerRoute<CTX>>;
+    server: http.Server<typeof http.IncomingMessage, typeof ServerResponse>;
+    host: string;
+    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;
-    addRoutes(routes: ServerRoute[]): void;
+    protected listener(req: http.IncomingMessage, res: ServerResponse): Promise<void>;
+    protected runHandler({ fn, pre, post }: CompiledHandler, ctx: CTX): Promise<void>;
+    protected compileRoute(route: ServerRoute<CTX>): CompiledServerRoute<CTX>;
+    addRoutes(routes: ServerRoute<CTX>[]): void;
     sendFile({ req, res }: RequestCtx, path: string, headers?: http.OutgoingHttpHeaders, compress?: boolean): Promise<void>;
-    unauthorized(res: http.ServerResponse): void;
-    unmodified(res: http.ServerResponse): void;
-    missing(res: http.ServerResponse): void;
-    redirectTo(res: http.ServerResponse, location: string): void;
-    redirectToRoute(res: http.ServerResponse, route: RouteMatch): void;
+    redirectToRoute(res: ServerResponse, route: RouteMatch): void;
+}
+export declare const server: <CTX extends RequestCtx>(opts?: Partial<ServerOpts<CTX>>) => Server<CTX>;
+/**
+ * Extended version of the default NodeJS ServerResponse with additional methods
+ * for various commonly used HTTP statuses/errors.
+ */
+export declare class ServerResponse extends http.ServerResponse<http.IncomingMessage> {
+    noContent(headers?: http.OutgoingHttpHeaders): void;
+    redirectTo(location: string, headers?: http.OutgoingHttpHeaders): void;
+    seeOther(location: string, headers?: http.OutgoingHttpHeaders): void;
+    unmodified(headers?: http.OutgoingHttpHeaders): void;
+    unauthorized(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    forbidden(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    missing(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    notAllowed(headers?: http.OutgoingHttpHeaders, body?: any): void;
+    notAcceptable(headers?: http.OutgoingHttpHeaders, body?: any): void;
 }
-export declare const server: (opts?: Partial<ServerOpts>) => Server;
 //# sourceMappingURL=server.d.ts.map

package/server.js

@@ -1,26 +1,33 @@
+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";
 import { preferredTypeForPath } from "@thi.ng/mime";
 import { Router } from "@thi.ng/router";
+import { upper } from "@thi.ng/strings";
 import { createReadStream } from "node:fs";
 import * as http from "node:http";
 import * as https from "node:https";
+import { isIPv6 } from "node:net";
 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 { isMatchingHost, normalizeIPv6Address } from "./utils/host.js";
 const MISSING = "__missing";
 class Server {
   constructor(opts = {}) {
     this.opts = opts;
     this.logger = opts.logger ?? new ConsoleLogger("server");
+    this.host = opts.host ?? "localhost";
+    if (isIPv6(this.host)) this.host = normalizeIPv6Address(this.host);
+    this.augmentCtx = opts.context ?? identity;
     const routes = [
       {
         id: MISSING,
         match: ["__404__"],
         handlers: {
-          get: async ({ res }) => this.missing(res)
+          get: async ({ res }) => res.missing()
         }
       },
       ...this.opts.routes ?? []
@@ -35,18 +42,22 @@ class Server {
   logger;
   router;
   server;
+  host;
+  augmentCtx;
   async start() {
-    const ssl = this.opts.ssl;
-    const port = this.opts.port ?? (ssl ? 443 : 8080);
-    const host = this.opts.host ?? "localhost";
+    const { ssl, host = "localhost", port = ssl ? 443 : 8080 } = this.opts;
     try {
       this.server = ssl ? https.createServer(
         {
           key: readText(ssl.key, this.logger),
-          cert: readText(ssl.cert, this.logger)
+          cert: readText(ssl.cert, this.logger),
+          ServerResponse
         },
         this.listener.bind(this)
-      ) : http.createServer({}, this.listener.bind(this));
+      ) : http.createServer(
+        { ServerResponse },
+        this.listener.bind(this)
+      );
       this.server.listen(port, host, void 0, () => {
         this.logger.info(
           `starting server: http${ssl ? "s" : ""}://${host}:${port}`
@@ -66,19 +77,20 @@ class Server {
     return true;
   }
   async listener(req, res) {
-    const url = new URL(req.url, `http://${req.headers.host}`);
-    if (this.opts.host && this.opts.host !== url.host) {
-      res.writeHead(503).end();
-      return;
-    }
-    const path = decodeURIComponent(url.pathname);
     try {
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      if (this.opts.host && !isMatchingHost(url.hostname, this.opts.host)) {
+        res.writeHead(503).end();
+        return;
+      }
+      const path = decodeURIComponent(url.pathname);
       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 +100,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";
       }
@@ -101,7 +119,7 @@ class Server {
       if (handler) {
         this.runHandler(handler, ctx);
       } else {
-        res.writeHead(405).end();
+        res.notAllowed();
       }
     } catch (e) {
       this.logger.warn("error:", e.message);
@@ -185,29 +203,47 @@ class Server {
         encoding ? pipeline(src, encoding.tx(), res, finalize) : pipeline(src, res, finalize);
       } catch (e) {
         this.logger.warn(e.message);
-        this.missing(res);
+        res.missing();
         resolve();
       }
     });
   }
-  unauthorized(res) {
-    res.writeHead(403, "Forbidden").end();
+  redirectToRoute(res, route) {
+    res.redirectTo(this.router.format(route));
+  }
+}
+const server = (opts) => new Server(opts);
+class ServerResponse extends http.ServerResponse {
+  noContent(headers) {
+    this.writeHead(204, headers).end();
   }
-  unmodified(res) {
-    res.writeHead(304, "Not modified").end();
+  redirectTo(location, headers) {
+    this.writeHead(302, { ...headers, location }).end();
   }
-  missing(res) {
-    res.writeHead(404, "Not found").end();
+  seeOther(location, headers) {
+    this.writeHead(303, { ...headers, location }).end();
   }
-  redirectTo(res, location) {
-    res.writeHead(302, { location }).end();
+  unmodified(headers) {
+    this.writeHead(304, headers).end();
   }
-  redirectToRoute(res, route) {
-    this.redirectTo(res, this.router.format(route));
+  unauthorized(headers, body) {
+    this.writeHead(401, headers).end(body);
+  }
+  forbidden(headers, body) {
+    this.writeHead(403, headers).end(body);
+  }
+  missing(headers, body) {
+    this.writeHead(404, headers).end(body);
+  }
+  notAllowed(headers, body) {
+    this.writeHead(405, headers).end(body);
+  }
+  notAcceptable(headers, body) {
+    this.writeHead(406, headers).end(body);
   }
 }
-const server = (opts) => new Server(opts);
 export {
   Server,
+  ServerResponse,
   server
 };

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,44 @@
+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>;
+    newSession(ctx: CTX): Promise<SESSION | undefined>;
+    withSession(res: ServerResponse, sessionID: string): ServerResponse<import("http").IncomingMessage>;
+}
+/**
+ * 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,61 @@
+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 id = ctx.cookies?.[this.cookieName];
+    let session = id ? await this.store.get(id) : void 0;
+    if (!session) {
+      session = await this.newSession(ctx);
+      if (!session) return false;
+    }
+    ctx.session = session;
+    this.withSession(ctx.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}`
+      );
+    }
+  }
+  async newSession(ctx) {
+    const session = this.factory(ctx);
+    ctx.logger.info("new session:", session.id);
+    if (!await this.store.set(session)) {
+      ctx.logger.warn("could not store session...");
+      return;
+    }
+    return session;
+  }
+  withSession(res, sessionID) {
+    return 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) => {
@@ -52,11 +54,11 @@ const staticFiles = ({
 });
 const __fileHeaders = async (path, ctx, filter, etag, headers) => {
   if (!(existsSync(path) && filter(path))) {
-    return ctx.server.missing(ctx.res);
+    return ctx.res.missing();
   }
   if (etag) {
     const etagValue = await etag(path);
-    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.server.unmodified(ctx.res) : { ...headers, etag: etagValue };
+    return isUnmodified(etagValue, ctx.req.headers["if-none-match"]) ? ctx.res.unmodified() : { ...headers, etag: etagValue };
   }
   return { ...headers };
 };

package/utils/host.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Takes a hostname or IPv6 address `test` and compares it against `expected`,
+ * returns true if matching.
+ *
+ * @remarks
+ * If `test` is an IPv6 address in the format `[...]`, it will be compared
+ * without surrounding square brackets. If `expected` is an IPv6 address it MUST
+ * have been pre-normalized using {@link normalizeIPv6Address}. For performance
+ * reasons only `test` will be automatically normalized, i.e. `::1` will be
+ * normalized as `0:0:0:0:0:0:0:1`.
+ *
+ * @param test
+ * @param expected
+ *
+ * @internal
+ */
+export declare const isMatchingHost: (test: string, expected: string) => boolean;
+/**
+ * Parses given IPv6 address into an 8-tuple of 16bit uints. Throws error if
+ * address is invalid.
+ *
+ * @remarks
+ * https://en.wikipedia.org/wiki/IPv6_address
+ *
+ * @param addr
+ */
+export declare const parseIPv6Address: (addr: string) => number[];
+/**
+ * Returns normalized version of given IPv6 address, i.e. expanding `::`
+ * sections, removing leading zeroes and performing other syntactic validations.
+ * The returned address always has 8 parts. Throws error if address is invalid.
+ *
+ * @remarks
+ * Internally uses {@link parseIPv6Address}.
+ *
+ * Reference:
+ * https://en.wikipedia.org/wiki/IPv6_address
+ *
+ * @param addr
+ */
+export declare const normalizeIPv6Address: (addr: string) => string;
+//# sourceMappingURL=host.d.ts.map

package/utils/host.js

@@ -0,0 +1,40 @@
+import { illegalArgs } from "@thi.ng/errors";
+import { HEX } from "@thi.ng/strings";
+const isMatchingHost = (test, expected) => /^\[[0-9a-f:]+\]$/.test(test) ? normalizeIPv6Address(test.substring(1, test.length - 1)) === expected : test === expected;
+const parseIPv6Address = (addr) => {
+  if (addr == "::") return [0, 0, 0, 0, 0, 0, 0, 0];
+  if (addr == "::1") return [0, 0, 0, 0, 0, 0, 0, 1];
+  const n = addr.length - 1;
+  if (n > 38) invalidIPv6(addr);
+  const parts = [];
+  let curr = 0;
+  let zeroes = -1;
+  for (let i = 0; i <= n; i++) {
+    const ch = addr[i];
+    if (i === n && ch == ":") illegalArgs(addr);
+    if (i === n || ch === ":") {
+      if (parts.length >= (zeroes >= 0 ? 6 : 8)) invalidIPv6(addr);
+      const end = i === n ? n + 1 : i > curr ? i : invalidIPv6(addr);
+      if (end - curr > 4) invalidIPv6(addr);
+      parts.push(parseInt(addr.substring(curr, end), 16));
+      if (addr[i + 1] === ":") {
+        if (zeroes >= 0) invalidIPv6(addr);
+        zeroes = parts.length;
+        i++;
+      }
+      curr = i + 1;
+    } else if (!HEX[ch]) invalidIPv6(addr);
+  }
+  if (zeroes >= 0) {
+    parts.splice(zeroes, 0, ...new Array(8 - parts.length).fill(0));
+  }
+  if (parts.length !== 8) invalidIPv6(addr);
+  return parts;
+};
+const normalizeIPv6Address = (addr) => parseIPv6Address(addr).map((x) => x.toString(16)).join(":");
+const invalidIPv6 = (addr) => illegalArgs("invalid IPv6 address: " + addr);
+export {
+  isMatchingHost,
+  normalizeIPv6Address,
+  parseIPv6Address
+};

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
-};