@thi.ng/server 0.1.0

package/interceptors/cache-control.d.ts

@@ -0,0 +1,25 @@
+import type { Interceptor } from "../api";
+export interface CacheControlOpts {
+    maxAge: number;
+    sMaxAge: number;
+    noCache: boolean;
+    noStore: boolean;
+    noTransform: boolean;
+    mustRevalidate: boolean;
+    proxyRevalidate: boolean;
+    mustUnderstand: boolean;
+    private: boolean;
+    public: boolean;
+    immutable: boolean;
+    staleWhileRevalidate: boolean;
+    staleIfError: boolean;
+}
+/**
+ * @remarks
+ * Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+ *
+ * @param opts
+ */
+export declare const cacheControl: (opts?: Partial<CacheControlOpts>) => Interceptor;
+//# sourceMappingURL=cache-control.d.ts.map

package/interceptors/cache-control.js

@@ -0,0 +1,23 @@
+import { kebab } from "@thi.ng/strings";
+const cacheControl = (opts = {}) => {
+  const acc = [];
+  for (let [k, v] of Object.entries(opts)) {
+    switch (k) {
+      case "maxAge":
+        acc.push("max-age=" + v);
+        break;
+      case "sMaxAge":
+        acc.push("s-maxage=" + v);
+        break;
+      default:
+        acc.push(kebab(k));
+    }
+  }
+  const value = acc.join(", ");
+  return {
+    pre: (ctx) => (value && ctx.res.setHeader("cache-control", value), true)
+  };
+};
+export {
+  cacheControl
+};

package/interceptors/inject-headers.d.ts

@@ -0,0 +1,8 @@
+import type { Interceptor } from "../api.js";
+/**
+ * Pre-interceptor to inject given headers into the response.
+ *
+ * @param headers
+ */
+export declare const injectHeaders: (headers: Record<string, string | string[]>) => Interceptor;
+//# sourceMappingURL=inject-headers.d.ts.map

package/interceptors/inject-headers.js

@@ -0,0 +1,11 @@
+const injectHeaders = (headers) => ({
+  pre: (ctx) => {
+    for (let header of Object.entries(headers)) {
+      ctx.res.appendHeader(...header);
+    }
+    return true;
+  }
+});
+export {
+  injectHeaders
+};

package/interceptors/logging.d.ts

@@ -0,0 +1,19 @@
+import { LogLevel, type LogLevelName } from "@thi.ng/logger";
+import type { Interceptor } from "../api.js";
+/**
+ * Pre-interceptor to log request details (route, headers, query string args)
+ * using the server's {@link ServerOpts.logger}. The `level` arg can be used to
+ * customize which log level to use.
+ *
+ * @param level
+ */
+export declare const logRequest: (level?: LogLevel | LogLevelName) => Interceptor;
+/**
+ * Pre-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.
+ *
+ * @param level
+ */
+export declare const logResponse: (level?: LogLevel | LogLevelName) => Interceptor;
+//# sourceMappingURL=logging.d.ts.map

package/interceptors/logging.js

@@ -0,0 +1,30 @@
+import { isString } from "@thi.ng/checks";
+import { LogLevel } from "@thi.ng/logger";
+const __method = (level) => (isString(level) ? level : LogLevel[level]).toLowerCase();
+const logRequest = (level = "INFO") => {
+  const method = __method(level);
+  return {
+    pre: ({ logger, req, match, query }) => {
+      logger[method]("request route", req.method, match);
+      logger[method]("request headers", req.headers);
+      if (Object.keys(query).length) {
+        logger[method]("request query", query);
+      }
+      return true;
+    }
+  };
+};
+const logResponse = (level = "INFO") => {
+  const method = __method(level);
+  return {
+    post: ({ logger, match, res }) => {
+      logger[method]("response status", res.statusCode, match);
+      logger[method]("response headers", res.getHeaders());
+      return true;
+    }
+  };
+};
+export {
+  logRequest,
+  logResponse
+};

package/interceptors/referrer-policy.d.ts

@@ -0,0 +1,11 @@
+import type { Interceptor } from "../api.js";
+export type ReferrerPolicy = "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url";
+/**
+ * @remarks
+ * Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
+ *
+ * @param policy
+ */
+export declare const referrerPolicy: (policy?: ReferrerPolicy) => Interceptor;
+//# sourceMappingURL=referrer-policy.d.ts.map

package/interceptors/referrer-policy.js

@@ -0,0 +1,6 @@
+const referrerPolicy = (policy = "no-referrer") => ({
+  pre: (ctx) => (ctx.res.setHeader("referrer-policy", policy), true)
+});
+export {
+  referrerPolicy
+};

package/interceptors/session.d.ts

@@ -0,0 +1,51 @@
+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

@@ -0,0 +1,38 @@
+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
+};

package/interceptors/strict-transport.d.ts

@@ -0,0 +1,11 @@
+import type { Interceptor } from "../api.js";
+/**
+ * @remarks
+ * Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
+ *
+ * @param maxAge
+ * @param includeSubDomains
+ */
+export declare const strictTransportSecurity: (maxAge?: number, includeSubDomains?: boolean) => Interceptor;
+//# sourceMappingURL=strict-transport.d.ts.map

package/interceptors/strict-transport.js

@@ -0,0 +1,9 @@
+const strictTransportSecurity = (maxAge = 63072e3, includeSubDomains = true) => {
+  const value = `max-age=${maxAge}${includeSubDomains ? "; includeSubDomains" : ""}`;
+  return {
+    pre: (ctx) => (ctx.res.setHeader("strict-transport-security", value), true)
+  };
+};
+export {
+  strictTransportSecurity
+};

package/interceptors/x-origin-opener.d.ts

@@ -0,0 +1,11 @@
+import type { Interceptor } from "../api.js";
+export type CrossOriginOpenerPolicy = "unsafe-none" | "same-origin-allow-popups" | "same-origin" | "noopener-allow-popups";
+/**
+ * @remarks
+ * Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy
+ *
+ * @param policy
+ */
+export declare const crossOriginOpenerPolicy: (policy?: CrossOriginOpenerPolicy) => Interceptor;
+//# sourceMappingURL=x-origin-opener.d.ts.map

package/interceptors/x-origin-opener.js

@@ -0,0 +1,6 @@
+const crossOriginOpenerPolicy = (policy = "same-origin") => ({
+  pre: (ctx) => (ctx.res.setHeader("cross-origin-opener-policy", policy), true)
+});
+export {
+  crossOriginOpenerPolicy
+};

package/interceptors/x-origin-resource.d.ts

@@ -0,0 +1,11 @@
+import type { Interceptor } from "../api.js";
+export type CrossOriginResourcePolicy = "same-origin" | "same-site" | "cross-origin";
+/**
+ * @remarks
+ * Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy
+ *
+ * @param policy
+ */
+export declare const crossOriginResourcePolicy: (policy?: CrossOriginResourcePolicy) => Interceptor;
+//# sourceMappingURL=x-origin-resource.d.ts.map

package/interceptors/x-origin-resource.js

@@ -0,0 +1,6 @@
+const crossOriginResourcePolicy = (policy = "same-origin") => ({
+  pre: (ctx) => (ctx.res.setHeader("cross-origin-resource-policy", policy), true)
+});
+export {
+  crossOriginResourcePolicy
+};

package/package.json

@@ -0,0 +1,153 @@
+{
+  "name": "@thi.ng/server",
+  "version": "0.1.0",
+  "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://thi.ng/server",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    },
+    {
+      "type": "liberapay",
+      "url": "https://liberapay.com/thi.ng"
+    }
+  ],
+  "author": "Karsten Schmidt (https://thi.ng)",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn build:esbuild && yarn build:decl",
+    "build:decl": "tsc --declaration --emitDeclarationOnly",
+    "build:esbuild": "esbuild --format=esm --platform=neutral --target=es2022 --tsconfig=tsconfig.json --outdir=. src/**/*.ts",
+    "clean": "bun ../../tools/src/clean-package.ts",
+    "doc": "typedoc --options ../../typedoc.json --out doc src/index.ts",
+    "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
+    "pub": "yarn npm publish --access public",
+    "test": "bun test",
+    "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.25",
+    "@thi.ng/logger": "^3.0.30",
+    "@thi.ng/mime": "^2.7.0",
+    "@thi.ng/paths": "^5.2.0",
+    "@thi.ng/router": "^4.1.17",
+    "@thi.ng/strings": "^3.9.4",
+    "@thi.ng/uuid": "^1.1.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.10",
+    "esbuild": "^0.24.2",
+    "typedoc": "^0.27.6",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "cookie",
+    "compression",
+    "file",
+    "formdata",
+    "headers",
+    "http",
+    "https",
+    "interceptors",
+    "logger",
+    "multipart",
+    "nodejs",
+    "querystring",
+    "security",
+    "server",
+    "session",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts",
+    "interceptors",
+    "utils"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./interceptors/auth-route": {
+      "default": "./interceptors/auth-route.js"
+    },
+    "./interceptors/cache-control": {
+      "default": "./interceptors/cache-control.js"
+    },
+    "./interceptors/inject-headers": {
+      "default": "./interceptors/inject-headers.js"
+    },
+    "./interceptors/logging": {
+      "default": "./interceptors/logging.js"
+    },
+    "./interceptors/referrer-policy": {
+      "default": "./interceptors/referrer-policy.js"
+    },
+    "./interceptors/session": {
+      "default": "./interceptors/session.js"
+    },
+    "./interceptors/strict-transport": {
+      "default": "./interceptors/strict-transport.js"
+    },
+    "./interceptors/x-origin-opener": {
+      "default": "./interceptors/x-origin-opener.js"
+    },
+    "./interceptors/x-origin-resource": {
+      "default": "./interceptors/x-origin-resource.js"
+    },
+    "./server": {
+      "default": "./server.js"
+    },
+    "./static": {
+      "default": "./static.js"
+    },
+    "./utils/cache": {
+      "default": "./utils/cache.js"
+    },
+    "./utils/cookies": {
+      "default": "./utils/cookies.js"
+    },
+    "./utils/formdata": {
+      "default": "./utils/formdata.js"
+    },
+    "./utils/multipart": {
+      "default": "./utils/multipart.js"
+    }
+  },
+  "thi.ng": {
+    "status": "alpha",
+    "year": 2024
+  },
+  "gitHead": "fc1d498e8d4b690db873c30cc594352a804e7a65\n"
+}

package/server.d.ts

@@ -0,0 +1,25 @@
+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>;
+    logger: ILogger;
+    router: Router;
+    server: http.Server;
+    constructor(opts?: Partial<ServerOpts>);
+    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;
+    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;
+}
+export declare const server: (opts?: Partial<ServerOpts>) => Server;
+//# sourceMappingURL=server.d.ts.map