@darthcav/ts-http-server 0.0.1

package/src/__tests__/launcher.test.ts

@@ -0,0 +1,136 @@
+import { equal, ok } from "node:assert/strict"
+import { after, before, describe, it } from "node:test"
+import { setTimeout } from "node:timers/promises"
+import FastifyAccepts from "@fastify/accepts"
+import type { Logger } from "@logtape/logtape"
+import type { RouteOptions } from "fastify"
+import launcher from "../launcher.ts"
+import type { FSTPlugin } from "../types.ts"
+
+// ---------------------------------------------------------------------------
+// Minimal test logger (no real I/O)
+// ---------------------------------------------------------------------------
+
+const noop = (): void => {}
+const testLogger = {
+    category: ["test"],
+    info: noop,
+    error: noop,
+    warn: noop,
+    debug: noop,
+    getChild: () => testLogger,
+} as unknown as Logger
+
+// ---------------------------------------------------------------------------
+// Minimal plugins and routes (no EJS/static required)
+// ---------------------------------------------------------------------------
+
+const plugins = new Map<string, FSTPlugin>([
+    ["@fastify/accepts", { plugin: FastifyAccepts }],
+])
+
+const routes = new Map<string, RouteOptions>([
+    [
+        "JSON_OK",
+        {
+            method: "GET",
+            url: "/",
+            handler: async (_request, reply) => reply.send({ ok: true }),
+        },
+    ],
+    [
+        "JSON_405",
+        {
+            method: ["POST", "PUT", "DELETE", "PATCH"],
+            url: "/",
+            handler: async (_request, reply) => {
+                reply.header("allow", "GET, HEAD")
+                return reply.status(405).send({ statusCode: 405 })
+            },
+        },
+    ],
+    [
+        "ERROR_ROUTE",
+        {
+            method: "GET",
+            url: "/error",
+            handler: async () => {
+                throw new Error("test server error")
+            },
+        },
+    ],
+])
+
+// ---------------------------------------------------------------------------
+// HTTP server suite
+// ---------------------------------------------------------------------------
+
+describe("launcher [HTTP]", () => {
+    const port = 19001
+    const base = `http://localhost:${port}`
+    let server: import("fastify").FastifyInstance
+
+    before(async () => {
+        server = launcher({
+            logger: testLogger,
+            locals: { port },
+            plugins,
+            routes,
+            opts: { disableRequestLogging: true },
+        })
+        await setTimeout(500)
+    })
+
+    after(async () => {
+        await setTimeout(200)
+        await server.close()
+    })
+
+    it("GET / → 200 JSON", async () => {
+        const res = await fetch(`${base}/`)
+        equal(res.status, 200)
+        const body = (await res.json()) as { ok: boolean }
+        equal(body.ok, true)
+    })
+
+    it("POST / → 405", async () => {
+        const res = await fetch(`${base}/`, { method: "POST" })
+        equal(res.status, 405)
+        equal(res.headers.get("allow"), "GET, HEAD")
+    })
+
+    it("GET /missing → 404 JSON", async () => {
+        const res = await fetch(`${base}/missing`, {
+            headers: { accept: "application/json" },
+        })
+        equal(res.status, 404)
+        equal(
+            res.headers.get("content-type"),
+            "application/json; charset=utf-8",
+        )
+        const body = (await res.json()) as { statusCode: number }
+        ok(body.statusCode)
+        equal(body.statusCode, 404)
+    })
+
+    it("GET /missing → 404 plain text", async () => {
+        const res = await fetch(`${base}/missing`, {
+            headers: { accept: "text/plain" },
+        })
+        equal(res.status, 404)
+    })
+
+    it("GET /error → 500 JSON", async () => {
+        const res = await fetch(`${base}/error`, {
+            headers: { accept: "application/json" },
+        })
+        equal(res.status, 500)
+    })
+
+    it("GET /error → 500 plain text", async () => {
+        const res = await fetch(`${base}/error`, {
+            headers: { accept: "text/plain" },
+        })
+        equal(res.status, 500)
+    })
+})

package/src/defaults/defaultErrorHandler.ts

@@ -0,0 +1,69 @@
+import type { Boom } from "@hapi/boom"
+import type { FastifyError, FastifyReply, FastifyRequest } from "fastify"
+
+/**
+ * Fastify error handler supporting Boom errors and generic errors.
+ *
+ * Negotiates the response format via `@fastify/accepts`:
+ * - `text/html` — renders `_error.ejs` (requires `@fastify/view`).
+ * - `application/json` — JSON payload.
+ * - Otherwise — plain-text.
+ *
+ * For Boom errors the HTTP status code and payload come from `error.output`.
+ * For generic errors a 500 is used unless the reply already has a 4xx/5xx status.
+ */
+export default async function defaultErrorHandler(
+    error: FastifyError,
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<void> {
+    const accept = request.accepts()
+    const boom = error as unknown as Boom
+
+    if (boom.isBoom) {
+        const payload = boom.output.payload
+        payload.message = boom.message
+
+        reply.status(payload.statusCode)
+
+        switch (accept.type(["html", "json"])) {
+            case "html":
+                return reply.type("text/html").view("_error", {
+                    menu_name: "",
+                    header: `HTTP error ${payload.statusCode} (${payload.message})`,
+                    uri: request.url,
+                    status: payload.statusCode,
+                    message: payload.message,
+                })
+            case "json":
+                return reply.type("application/json").send(payload)
+            default:
+                return reply
+                    .type("text/plain")
+                    .send(`${payload.error} :: ${payload.message}`)
+        }
+    } else {
+        if (
+            !reply.statusCode ||
+            reply.statusCode < 400 ||
+            reply.statusCode > 599
+        ) {
+            reply.status(500)
+        }
+
+        switch (accept.type(["html", "json"])) {
+            case "html":
+                return reply.type("text/html").view("_error", {
+                    menu_name: "",
+                    header: `HTTP error ${reply.statusCode} (${error.message})`,
+                    uri: request.url,
+                    status: reply.statusCode,
+                    message: error.message,
+                })
+            case "json":
+                return reply.type("application/json").send(error)
+            default:
+                return reply.type("text/plain").send(JSON.stringify(error))
+        }
+    }
+}

package/src/defaults/defaultFastifyOptions.ts

@@ -0,0 +1,29 @@
+import { randomUUID } from "node:crypto"
+import type { Logger } from "@logtape/logtape"
+import type { FastifyServerOptions } from "fastify"
+import getConsoleFastifyLogger from "./getConsoleFastifyLogger.ts"
+
+/**
+ * Returns base `FastifyServerOptions` used as defaults in {@link launcher}.
+ *
+ * Uses `getConsoleFastifyLogger` as `loggerInstance` so that all Fastify
+ * internal logs are routed through LogTape under `logger.category`.
+ * Built-in per-request logging is disabled in favor of the {@link preHandler}
+ * and {@link onResponse} hooks, which emit structured access log lines.
+ *
+ * Generates request IDs via `crypto.randomUUID()` and enables proxy trust.
+ * Callers may override any field by spreading their own options on top.
+ *
+ * @param logger - The application LogTape logger; its category is used as the
+ *   base category for Fastify's own logger.
+ */
+export default function defaultFastifyOptions(
+    logger: Logger,
+): FastifyServerOptions {
+    return {
+        genReqId: () => randomUUID(),
+        trustProxy: true,
+        disableRequestLogging: true,
+        loggerInstance: getConsoleFastifyLogger([...logger.category]),
+    }
+}

package/src/defaults/defaultPlugins.ts

@@ -0,0 +1,90 @@
+import { join } from "node:path"
+import FastifyAccepts from "@fastify/accepts"
+import FastifyCompress from "@fastify/compress"
+import FastifyCors from "@fastify/cors"
+import FastifyEtag from "@fastify/etag"
+import FastifyHelmet from "@fastify/helmet"
+import FastifyStatic from "@fastify/static"
+import FastifyView from "@fastify/view"
+import Ejs from "ejs"
+import type { FSTPlugin, LauncherLocals } from "../types.ts"
+
+/**
+ * Builds the default plugin map for use with `launcher`.
+ *
+ * Registers: `@fastify/accepts`, `@fastify/compress`,
+ * `@fastify/cors`, `@fastify/etag`, `@fastify/helmet`,
+ * `@fastify/view` (EJS), and `@fastify/static`.
+ *
+ * @param opts.locals - Application locals; `locals.pkg` is exposed as the
+ *   default context for every EJS view.
+ * @param opts.baseDir - Optional base directory for resolving the `src/` folder; defaults to the parent of `import.meta.dirname`.
+ * @returns A `Map` of plugin names to plugin entries, suitable for passing as
+ *   the `plugins` field of `LauncherOptions`.
+ */
+export default function defaultPlugins(opts: {
+    locals: LauncherLocals
+    baseDir?: string | null
+}): Map<string, FSTPlugin> {
+    const { locals, baseDir = null } = opts
+    const plugins = new Map<string, FSTPlugin>()
+    const srcDir = baseDir
+        ? join(baseDir, "src")
+        : join(import.meta.dirname, "..")
+
+    plugins.set("@fastify/accepts", {
+        plugin: FastifyAccepts,
+    })
+    plugins.set("@fastify/compress", {
+        plugin: FastifyCompress,
+    })
+    plugins.set("@fastify/cors", {
+        plugin: FastifyCors,
+        opts: { origin: true },
+    })
+    plugins.set("@fastify/etag", {
+        plugin: FastifyEtag,
+        opts: { algorithm: "sha1" },
+    })
+    plugins.set("@fastify/helmet", {
+        plugin: FastifyHelmet,
+        opts: {
+            global: true,
+            contentSecurityPolicy: {
+                directives: {
+                    fontSrc: [
+                        "'self'",
+                        "https://fonts.googleapis.com/",
+                        "https://fonts.gstatic.com/",
+                    ],
+                    scriptSrc: [
+                        "'self'",
+                        "'unsafe-inline'",
+                        "https://cdn.jsdelivr.net/",
+                    ],
+                },
+            },
+            hsts: {
+                maxAge: 31536000,
+                includeSubDomains: true,
+            },
+        },
+    })
+    plugins.set("@fastify/view", {
+        plugin: FastifyView,
+        opts: {
+            engine: { ejs: Ejs },
+            root: join(srcDir, "views"),
+            defaultContext: { pkg: locals.pkg },
+        },
+    })
+    plugins.set("@fastify/static", {
+        plugin: FastifyStatic,
+        opts: {
+            root: join(srcDir, "public"),
+            prefix: "/",
+        },
+    })
+
+    return plugins
+}

package/src/defaults/defaultRoutes.ts

@@ -0,0 +1,42 @@
+import { methodNotAllowed, notAcceptable } from "@hapi/boom"
+import type { RouteOptions } from "fastify"
+
+/**
+ * Returns the default route map used in {@link launcher}.
+ *
+ * Registers:
+ * - `GET /` — renders `index.ejs` for `text/html`, throws 406 otherwise.
+ * - `DELETE|PATCH|POST|PUT|OPTIONS /` — responds with 405 Method Not Allowed.
+ */
+export default function defaultRoutes(): Map<string, RouteOptions> {
+    const routes = new Map<string, RouteOptions>()
+
+    routes.set("INDEX", {
+        method: "GET",
+        url: "/",
+        exposeHeadRoute: true,
+        handler: async (request, reply) => {
+            const accept = request.accepts()
+            switch (accept.type(["html"])) {
+                case "html":
+                    return reply.type("text/html").view("index.ejs", {
+                        menu_name: "index",
+                        header: "Welcome page",
+                    })
+                default:
+                    throw notAcceptable()
+            }
+        },
+    })
+
+    routes.set("INDEX_405", {
+        method: ["DELETE", "PATCH", "POST", "PUT", "OPTIONS"],
+        url: "/",
+        handler: async (_request, reply) => {
+            reply.header("allow", "GET, HEAD")
+            throw methodNotAllowed()
+        },
+    })
+
+    return routes
+}

package/src/defaults/getConsoleFastifyLogger.ts

@@ -0,0 +1,27 @@
+import {
+    getLogTapeFastifyLogger,
+    type PinoLevel,
+    type PinoLikeLogger,
+} from "@logtape/fastify"
+
+/**
+ * Returns a `PinoLikeLogger` for Fastify scoped to the given category.
+ *
+ * Assumes LogTape has already been configured by the caller (e.g. via
+ * `getConsoleLogger`). All records at or above `level` are forwarded
+ * by Fastify to the active LogTape sinks.
+ *
+ * @param name - Logger category array passed to `getLogTapeFastifyLogger`
+ *   (e.g. `["my-app", "fastify"]`).
+ * @param level - Minimum Pino log level to pass through. Defaults to `"info"`.
+ * @returns A Pino-compatible logger backed by LogTape.
+ */
+export default function getConsoleFastifyLogger(
+    name: string[],
+    level: PinoLevel = "info",
+): PinoLikeLogger {
+    return getLogTapeFastifyLogger({
+        category: name,
+        level,
+    })
+}

package/src/hooks/onResponse.ts

@@ -0,0 +1,34 @@
+import type { FastifyReply, FastifyRequest } from "fastify"
+
+/**
+ * Fastify `onResponse` hook that logs completed request details:
+ *
+ * ```
+ * {ip} -- {method} {url} HTTP/{httpVersion} {status} {size} {elapsed}ms "{referrer}" "{userAgent}"
+ * ```
+ *
+ * Intended to be registered via:
+ * ```ts
+ * fastify.addHook("onResponse", onResponse)
+ * ```
+ *
+ * Uses `reply.log.info` so each log record is automatically correlated with
+ * the request ID assigned by Fastify.
+ */
+export default async function onResponse(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<void> {
+    const contentLength = reply.getHeader("content-length")
+    const size = contentLength != null ? Number(contentLength) : "-"
+
+    if (reply.statusCode < 400) {
+        reply.log.info(
+            `${request.ip} -- ${request.method} ${request.url} HTTP/${request.raw.httpVersion} ${reply.statusCode} ${size} ${Math.round(reply.elapsedTime)}ms "${request.headers["referer"] ?? "-"}" "${request.headers["user-agent"] ?? "-"}"`,
+        )
+    } else {
+        reply.log.error(
+            `${request.ip} -- ${request.method} ${request.url} HTTP/${request.raw.httpVersion} ${reply.statusCode} ${size} ${Math.round(reply.elapsedTime)}ms "${request.headers["referer"] ?? "-"}" "${request.headers["user-agent"] ?? "-"}"`,
+        )
+    }
+}

package/src/hooks/preHandler.ts

@@ -0,0 +1,25 @@
+import type { FastifyReply, FastifyRequest } from "fastify"
+
+/**
+ * Fastify `preHandler` hook that logs incoming request details:
+ *
+ * ```
+ * Incoming request: {method} {url} HTTP/{httpVersion} from {ip}
+ * ```
+ *
+ * Intended to be registered via:
+ * ```ts
+ * fastify.addHook("preHandler", preHandler)
+ * ```
+ *
+ * Uses `request.log.info` so each log record is automatically correlated with
+ * the request ID assigned by Fastify.
+ */
+export default async function preHandler(
+    request: FastifyRequest,
+    _reply: FastifyReply,
+): Promise<void> {
+    request.log.debug(
+        `Incoming request [${request.id}]: ${request.method} ${request.url} HTTP/${request.raw.httpVersion} from ${request.ip}`,
+    )
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * A TypeScript HTTP server library built on Fastify for Node.js >= 25.
+ *
+ * @packageDocumentation
+ */
+
+import defaultErrorHandler from "./defaults/defaultErrorHandler.ts"
+import defaultFastifyOptions from "./defaults/defaultFastifyOptions.ts"
+import defaultPlugins from "./defaults/defaultPlugins.ts"
+import defaultRoutes from "./defaults/defaultRoutes.ts"
+import onResponse from "./hooks/onResponse.ts"
+import preHandler from "./hooks/preHandler.ts"
+import launcher from "./launcher.ts"
+
+export type {
+    FSTPlugin,
+    LauncherLocals,
+    LauncherOptions,
+} from "./types.ts"
+export {
+    defaultErrorHandler,
+    defaultFastifyOptions,
+    defaultPlugins,
+    defaultRoutes,
+    launcher,
+    preHandler,
+    onResponse,
+}

package/src/launcher.ts

@@ -0,0 +1,74 @@
+import process, { env } from "node:process"
+import { notFound } from "@hapi/boom"
+import Fastify, { type FastifyInstance } from "fastify"
+import defaultErrorHandler from "./defaults/defaultErrorHandler.ts"
+import defaultFastifyOptions from "./defaults/defaultFastifyOptions.ts"
+import { onResponse, preHandler } from "./index.ts"
+import type { LauncherOptions } from "./types.ts"
+
+/**
+ * Creates and starts a Fastify HTTP server with the given configuration.
+ *
+ * Steps performed:
+ * 1. Creates a `FastifyInstance` merging {@link defaultFastifyOptions} with `opts`.
+ * 2. Decorates the instance with `locals` and any extra `decorators`.
+ * 3. Registers all `plugins` and `routes`.
+ * 4. Sets a `notFound` handler (throws Boom 404) and {@link defaultErrorHandler}.
+ * 5. Registers {@link preHandler} and {@link onResponse} hooks.
+ * 6. Calls `fastify.listen()` and invokes the optional `done` callback.
+ *
+ * @returns The `FastifyInstance` (e.g. for use with `fastify.close()`).
+ */
+export default function launcher({
+    logger,
+    locals,
+    plugins,
+    routes,
+    decorators,
+    opts,
+    done,
+}: LauncherOptions): FastifyInstance {
+    const host = locals?.host ?? "localhost"
+    const port = locals?.port ?? Number(env["CONTAINER_EXPOSE_PORT"] ?? 8888)
+
+    const fastify = Fastify({
+        ...defaultFastifyOptions(logger),
+        ...opts,
+    })
+
+    fastify.decorate("locals", locals)
+
+    if (decorators instanceof Map) {
+        for (const [key, value] of decorators) {
+            fastify.decorate(key, value)
+        }
+    }
+
+    for (const value of plugins.values()) {
+        void fastify.register(value.plugin, value.opts ?? {})
+    }
+
+    for (const value of routes.values()) {
+        fastify.route(value)
+    }
+
+    fastify.setNotFoundHandler(async (_request, _reply) => {
+        throw notFound()
+    })
+
+    fastify.setErrorHandler(defaultErrorHandler)
+
+    // TODO: Add hook for `onRequestAbort`
+    fastify.addHook("preHandler", preHandler)
+    fastify.addHook("onResponse", onResponse)
+
+    fastify.listen({ host, port }, (error) => {
+        if (error) {
+            logger.error(`${error.message}`)
+            process.exit(1)
+        }
+        done?.()
+    })
+
+    return fastify
+}

package/src/public/README.md

@@ -0,0 +1,3 @@
+# Public directory
+
+Placeholder directory for static files.

package/src/start.ts

@@ -0,0 +1,30 @@
+import process from "node:process"
+import { getConsoleLogger, main } from "@darthcav/ts-utils"
+import pkg from "../package.json" with { type: "json" }
+import { defaultPlugins, defaultRoutes, launcher } from "./index.ts"
+
+const logger = await getConsoleLogger(pkg.name, "info")
+
+main(pkg.name, logger, false, () => {
+    const locals = { pkg }
+    const plugins = defaultPlugins({ locals })
+    const routes = defaultRoutes()
+
+    const fastify = launcher({ logger, locals, plugins, routes })
+    for (const signal of ["SIGINT", "SIGTERM"] as const) {
+        process.on(signal, async (signal) =>
+            fastify
+                .close()
+                .then(() => {
+                    logger.error(
+                        `Process interrupted and server closed. Received signal: ${signal}`,
+                    )
+                    process.exit(0)
+                })
+                .catch((error) => {
+                    logger.error(`Server shutdown error: ${error}`)
+                    process.exit(1)
+                }),
+        )
+    }
+})

package/src/types.ts

@@ -0,0 +1,55 @@
+import type { Logger } from "@logtape/logtape"
+import type {
+    FastifyPluginAsync,
+    FastifyPluginCallback,
+    FastifyPluginOptions,
+    FastifyServerOptions,
+    RouteOptions,
+} from "fastify"
+
+/**
+ * A plugin entry combining a Fastify plugin function with its options,
+ * stored in the plugins `Map` passed to {@link launcher}.
+ */
+export type FSTPlugin = {
+    /** The Fastify plugin function to register. */
+    // biome-ignore lint/suspicious/noExplicitAny: third-party plugins use varied option types
+    plugin: FastifyPluginCallback<any> | FastifyPluginAsync<any>
+    /** Optional options forwarded to the plugin on registration. */
+    opts?: FastifyPluginOptions
+}
+
+/**
+ * Application locals decorated onto the Fastify instance and available
+ * throughout the request lifecycle.
+ */
+export type LauncherLocals = {
+    /** Package metadata (e.g. contents of `package.json`). */
+    pkg?: object
+    /** Hostname the server will bind to. */
+    host?: string
+    /** Port the server will listen on. */
+    port?: number
+    /** Any additional application-specific locals. */
+    [key: string]: unknown
+}
+
+/**
+ * Options passed to the {@link launcher} function.
+ */
+export type LauncherOptions = {
+    /** Logger instance used for error and info output. */
+    logger: Logger
+    /** Application locals decorated onto the Fastify instance. */
+    locals: LauncherLocals
+    /** Map of named plugins to register. */
+    plugins: Map<string, FSTPlugin>
+    /** Map of named routes to register. */
+    routes: Map<string, RouteOptions>
+    /** Map of named decorators to add to the Fastify instance. */
+    decorators?: Map<string, unknown>
+    /** Optional Fastify server options (merged over {@link defaultFastifyOptions}). */
+    opts?: FastifyServerOptions
+    /** Optional callback invoked once the server is listening. */
+    done?: () => void
+}

package/src/views/README.md

@@ -0,0 +1,3 @@
+# Views directory
+
+Placeholder directory for views files.