@thi.ng/server 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-30T15:45:22Z
+- **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,13 @@ 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

package/api.d.ts

@@ -1,8 +1,8 @@
 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 { 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;

package/index.d.ts

@@ -13,6 +13,7 @@ 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

@@ -13,5 +13,6 @@ 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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.2.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",
@@ -145,6 +145,9 @@
     "./utils/formdata": {
       "default": "./utils/formdata.js"
     },
+    "./utils/host": {
+      "default": "./utils/host.js"
+    },
     "./utils/multipart": {
       "default": "./utils/multipart.js"
     }
@@ -153,5 +156,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "078de98f4365f0d472c87198bcd6a112e732d9ef\n"
+  "gitHead": "fa1407b41ef907a5523d30bcb28691a5aed6e85c\n"
 }

package/server.d.ts

@@ -7,21 +7,33 @@ export declare class Server<CTX extends RequestCtx = RequestCtx> {
     opts: Partial<ServerOpts<CTX>>;
     logger: ILogger;
     router: Router<CompiledServerRoute<CTX>>;
-    server: http.Server;
+    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>;
-    protected listener(req: http.IncomingMessage, res: http.ServerResponse): Promise<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[]): void;
+    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;
+}
 //# sourceMappingURL=server.d.ts.map

package/server.js

@@ -4,26 +4,30 @@ 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 { upper } from "@thi.ng/strings";
+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 ?? []
@@ -38,19 +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}`
@@ -70,13 +77,13 @@ 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;
@@ -112,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);
@@ -196,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/session.d.ts

@@ -32,7 +32,8 @@ export declare class SessionInterceptor<CTX extends RequestCtx = RequestCtx, SES
     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;
+    newSession(ctx: CTX): Promise<SESSION | undefined>;
+    withSession(res: ServerResponse, sessionID: string): ServerResponse<import("http").IncomingMessage>;
 }
 /**
  * Factory function to create a new {@link SessionInterceptor} instance.

package/session/session.js

@@ -18,16 +18,14 @@ class SessionInterceptor {
     this.cookieOpts = cookieOpts;
   }
   async pre(ctx) {
-    const { res, logger, cookies } = ctx;
-    const id = cookies?.[this.cookieName];
+    const id = ctx.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);
+      session = await this.newSession(ctx);
+      if (!session) return false;
     }
     ctx.session = session;
-    this.withSession(res, session.id);
+    this.withSession(ctx.res, session.id);
     return true;
   }
   async delete(ctx, sessionID) {
@@ -40,8 +38,17 @@ class SessionInterceptor {
       );
     }
   }
+  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) {
-    res.appendHeader(
+    return res.appendHeader(
       "set-cookie",
       `${this.cookieName}=${sessionID};Max-Age=${this.store.ttl};${this.cookieOpts}`
     );

package/static.js

@@ -54,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
+};