@gusnips/server 0.1.0

package/src/hono/request-logger.test.ts

@@ -0,0 +1,200 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import { createLogger } from "../logger/index.ts";
+import {
+  requestLogger,
+  type RequestLoggerOptions,
+  type RequestVariables,
+} from "./request-logger.ts";
+
+function setup(options: Omit<RequestLoggerOptions, "logger"> = {}) {
+  const lines: Array<Record<string, unknown>> = [];
+  const logger = createLogger({
+    level: "debug",
+    write: (line) => lines.push(JSON.parse(line) as Record<string, unknown>),
+  });
+  const app = new Hono<{ Variables: RequestVariables }>();
+  app.use(requestLogger({ logger, ...options }));
+  return { app, lines };
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+describe("the request line", () => {
+  it("names the route template, never the path", async () => {
+    // A path carries whatever the caller put in it. In one backend that was a customer's national
+    // id number, and the request line carried it into the log and on into an analytics event.
+    const { app, lines } = setup();
+    app.get("/people/:taxId/export", (c) => c.text("ok"));
+
+    await app.request("/people/12345678900/export");
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatchObject({ method: "GET", route: "/people/:taxId/export", status: 200 });
+    expect(JSON.stringify(lines)).not.toContain("12345678900");
+  });
+
+  it("names the route a refused request was headed for, not the middleware that refused it", async () => {
+    // The last matched route, not the deepest one that ran: a 401 from an auth middleware is
+    // filed under the endpoint it protected, which is the thing anyone reading the log asks about.
+    const { app, lines } = setup();
+    app.use("/admin/*", (c) => Promise.resolve(c.json({}, 401)));
+    app.get("/admin/users/:id", (c) => c.text("ok"));
+
+    await app.request("/admin/users/7");
+
+    expect(lines[0]).toMatchObject({ route: "/admin/users/:id", status: 401 });
+  });
+
+  it("does not write an unmatched path either", async () => {
+    const { app, lines } = setup();
+
+    await app.request("/wp-admin/12345678900.php");
+
+    expect(lines[0]).toMatchObject({ status: 404 });
+    expect(JSON.stringify(lines)).not.toContain("12345678900");
+  });
+
+  it("carries the refusal's code, rather than a second line of its own", async () => {
+    // A wrong code, a spent quota and a scanner's junk key are all routine. One warn per event
+    // would bury the failures that need a human, so the code rides on the line that exists anyway.
+    const { app, lines } = setup();
+    app.get("/verify", (c) => {
+      c.set("errorCode", "CODE_MISMATCH");
+      return c.json({}, 400);
+    });
+    app.get("/fine", (c) => c.text("ok"));
+
+    await app.request("/verify");
+    await app.request("/fine");
+
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toMatchObject({ level: "info", status: 400, errorCode: "CODE_MISMATCH" });
+    expect(lines[1]).not.toHaveProperty("errorCode");
+  });
+
+  it("starts errorCode at null, as its type says, rather than undefined", async () => {
+    const { app } = setup();
+    app.get("/", (c) => c.json({ errorCode: c.get("errorCode") }));
+
+    expect(await (await app.request("/")).json()).toEqual({ errorCode: null });
+  });
+
+  it("is still written for a request whose throw escaped every handler", async () => {
+    // Hono hands onError only an `Error`. A plain object — which is what a PostgREST client
+    // rejects with — is rethrown past every layer, and without a catch here the request that
+    // most needed a line is the one that never gets one.
+    const { app, lines } = setup();
+    app.get("/rows", () => {
+      throw { code: "PGRST116", message: "no rows" };
+    });
+
+    await expect(app.request("/rows")).rejects.toMatchObject({ code: "PGRST116" });
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatchObject({ level: "error", route: "/rows", status: 500 });
+    expect(lines[0]!.error).toMatchObject({ code: "PGRST116" });
+  });
+});
+
+describe("what is not logged", () => {
+  it("skips /health and anything under it, but not a path that only starts with the word", async () => {
+    const { app, lines } = setup();
+    for (const path of ["/health", "/health/db", "/healthz"]) app.get(path, (c) => c.text("ok"));
+
+    for (const path of ["/health", "/health/db", "/healthz"]) await app.request(path);
+
+    expect(lines.map((line) => line.route)).toEqual(["/healthz"]);
+  });
+
+  it("skips a preflight", async () => {
+    const { app, lines } = setup();
+    app.options("/items", (c) => c.body(null, 204));
+
+    await app.request("/items", { method: "OPTIONS" });
+
+    expect(lines).toEqual([]);
+  });
+
+  it("takes your own list in place of /health", async () => {
+    const { app, lines } = setup({ skipPaths: ["/ready"] });
+    app.get("/ready", (c) => c.text("ok"));
+    app.get("/health", (c) => c.text("ok"));
+
+    await app.request("/ready");
+    await app.request("/health");
+
+    expect(lines.map((line) => line.route)).toEqual(["/health"]);
+  });
+
+  it("still logs a skipped path that threw", async () => {
+    // Skipping is about volume. A health check that throws is not routine.
+    const { app, lines } = setup();
+    app.get("/health", () => {
+      throw { message: "pool exhausted" };
+    });
+
+    await expect(app.request("/health")).rejects.toMatchObject({ message: "pool exhausted" });
+
+    expect(lines[0]).toMatchObject({ level: "error", status: 500 });
+  });
+});
+
+describe("the request id", () => {
+  it("echoes a well-formed id the caller sent, and logs it", async () => {
+    const { app, lines } = setup();
+    app.get("/", (c) => c.text(c.get("requestId")));
+
+    const res = await app.request("/", { headers: { "X-Request-ID": "trace-2f9A_b.7" } });
+
+    expect(res.headers.get("X-Request-ID")).toBe("trace-2f9A_b.7");
+    expect(await res.text()).toBe("trace-2f9A_b.7");
+    expect(lines[0]).toMatchObject({ requestId: "trace-2f9A_b.7" });
+  });
+
+  it.each([
+    ["longer than 64 characters", "a".repeat(65)],
+    ["eight kilobytes long", "a".repeat(8192)],
+    ["carrying a space", "trace 1"],
+    ["carrying JSON", '{"admin":true}'],
+    ["carrying a character outside ASCII", "trace-ï"],
+  ])("replaces one %s with a fresh id, rather than echoing it", async (_, supplied) => {
+    const { app, lines } = setup();
+    app.get("/", (c) => c.text("ok"));
+
+    const res = await app.request("/", { headers: { "X-Request-ID": supplied } });
+
+    expect(res.headers.get("X-Request-ID")).toMatch(UUID);
+    expect(lines[0]!.requestId).toBe(res.headers.get("X-Request-ID"));
+    expect(JSON.stringify(lines)).not.toContain(supplied);
+  });
+
+  it("mints one when the caller sent none", async () => {
+    const { app } = setup();
+    app.get("/", (c) => c.text("ok"));
+
+    const res = await app.request("/");
+
+    expect(res.headers.get("X-Request-ID")).toMatch(UUID);
+  });
+
+  it("is on the answer even when the handler built its own Response", async () => {
+    // A header set before `next()` lives on a draft that Hono drops when a handler returns a
+    // Response it built itself, unless something else happened to materialize the draft first.
+    const { app } = setup();
+    app.get("/raw", () => new Response("ok"));
+
+    const res = await app.request("/raw");
+
+    expect(res.headers.get("X-Request-ID")).toMatch(UUID);
+  });
+
+  it("is on a skipped path's answer too", async () => {
+    const { app } = setup();
+    app.get("/health", (c) => c.text("ok"));
+
+    const res = await app.request("/health");
+
+    expect(res.headers.get("X-Request-ID")).toMatch(UUID);
+  });
+});

package/src/hono/request-logger.ts

@@ -0,0 +1,77 @@
+import type { MiddlewareHandler } from "hono";
+import { routePath } from "hono/route";
+import type { Logger } from "../logger/index.ts";
+
+/** The two variables this adapter writes. Put them in your app's `Variables`. */
+export interface RequestVariables<Code extends string = string> {
+  requestId: string;
+  /** The code of the refusal this request got, for the request line. `null` until one happens. */
+  errorCode: Code | null;
+}
+
+export interface RequestLoggerOptions {
+  logger: Logger;
+  /**
+   * Paths answered but never logged, each with everything under it: `/health` covers
+   * `/health/db` and not `/healthz`. Defaults to `["/health"]`. A throw is logged anyway.
+   */
+  skipPaths?: readonly string[];
+}
+
+/**
+ * A caller's id is echoed back and written into every line, so it is kept only in a shape that
+ * cannot carry anything else: 64 characters of `A-Z a-z 0-9 . _ -`. Anything else is replaced, not
+ * trimmed, so the id in the log is always either the caller's or ours.
+ */
+const REQUEST_ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+/**
+ * One line per request, and the request id.
+ *
+ * Mount it first, so it times and sees everything under it:
+ *
+ *     app.use(requestLogger({ logger }));
+ *
+ * The id goes back on `X-Request-ID`, which is where the browser client reads it from, on every
+ * answer including `onError`'s and `notFound`'s. Cross-origin, list that header in your CORS
+ * `exposeHeaders` or the browser hides it from the page.
+ */
+export function requestLogger({
+  logger,
+  skipPaths = ["/health"],
+}: RequestLoggerOptions): MiddlewareHandler<{ Variables: RequestVariables }> {
+  return async (c, next) => {
+    const supplied = c.req.header("X-Request-ID");
+    const requestId = supplied && REQUEST_ID.test(supplied) ? supplied : crypto.randomUUID();
+    c.set("requestId", requestId);
+    c.set("errorCode", null);
+    const { method, path } = c.req;
+    const start = Date.now();
+    // The route TEMPLATE, never the path: a path carries whatever the caller put in it, and in one
+    // backend that was a national id number, which the request line carried into an analytics
+    // event. The last matched route rather than the deepest one that ran, so a 401 from an auth
+    // middleware is filed under the endpoint it protected.
+    const line = (status: number) => ({
+      requestId,
+      method,
+      route: routePath(c, -1),
+      status,
+      ms: Date.now() - start,
+      errorCode: c.get("errorCode") ?? undefined,
+    });
+    try {
+      await next();
+    } catch (err) {
+      // Only what Hono would not hand to onError gets here: a non-`Error` with no `errorBoundary`
+      // above it, or a throw from onError itself. Nothing answered it, so the runtime will, and
+      // the request that most needs a line is the one that would otherwise never get one.
+      logger.error("request", { ...line(500), error: err });
+      throw err;
+    }
+    // After `next()`, not before: a header set earlier lives on a draft Hono drops when a handler
+    // returns a Response it built itself.
+    c.header("X-Request-ID", requestId);
+    const skipped = skipPaths.some((skip) => path === skip || path.startsWith(`${skip}/`));
+    if (method !== "OPTIONS" && !skipped) logger.info("request", line(c.res.status));
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { AppError, createAppError, toMessage } from "./errors.ts";
+export type { AppErrorOptions } from "./errors.ts";
+export { created, createErrorResponse, noContent, ok, paginated } from "./responses.ts";
+export type { CannedError, ErrorAnswer, ErrorResponseOptions } from "./responses.ts";
+export { createLogger, errorReplacer, keptErrorFields } from "./logger/index.ts";
+export type { Logger, LoggerOptions, LogLevel, LogThreshold } from "./logger/index.ts";

package/src/logger/index.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createLogger, type LogLevel } from "./index.ts";
+
+function capture() {
+  const lines: Array<{ level: LogLevel; entry: Record<string, unknown> }> = [];
+  const write = (line: string, level: LogLevel) =>
+    lines.push({ level, entry: JSON.parse(line) as Record<string, unknown> });
+  return { lines, write };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("the log line", () => {
+  it("is one JSON object with level, time and message on it", () => {
+    const { lines, write } = capture();
+    createLogger({ write }).info("server started", { port: 3000 });
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0]!.entry).toMatchObject({ level: "info", message: "server started", port: 3000 });
+    expect(new Date(String(lines[0]!.entry.time)).toISOString()).toBe(lines[0]!.entry.time);
+  });
+
+  it("lets the canonical fields win over a meta key of the same name", () => {
+    // A `meta.message` must never become the line's label. One backend re-implemented this
+    // logger inline with the spread the other way round, and a meta `message` silently replaced
+    // the line it was attached to.
+    const { lines, write } = capture();
+    createLogger({ write }).warn("quota check failed", {
+      message: "the caller's own text",
+      level: "debug",
+      time: "not a time",
+    });
+
+    expect(lines[0]!.entry).toMatchObject({
+      level: "warn",
+      message: "quota check failed",
+    });
+    expect(lines[0]!.entry.time).not.toBe("not a time");
+  });
+});
+
+describe("a logger that cannot serialize a line", () => {
+  it("writes a flagged line instead of throwing", () => {
+    // A logger must never take down the process it was called to report on. Reachable through a
+    // throwing getter or a throwing `toJSON()` on anything in `meta` — and the flag is there so
+    // a reader knows a line was lost rather than never written.
+    const hostile = {
+      toJSON() {
+        throw new Error("no");
+      },
+    };
+
+    const { lines, write } = capture();
+    createLogger({ write }).error("charge failed", { hostile });
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0]!.entry).toMatchObject({
+      level: "error",
+      message: "charge failed",
+      logSerializationFailed: true,
+    });
+  });
+});
+
+describe("the level", () => {
+  it("defaults to info, so debug is dropped and warn is kept", () => {
+    const { lines, write } = capture();
+    const logger = createLogger({ write });
+    logger.debug("noise");
+    logger.info("kept");
+    logger.warn("kept");
+    logger.error("kept");
+
+    expect(lines.map((l) => l.level)).toEqual(["info", "warn", "error"]);
+  });
+
+  it("comes from the caller, never from the environment", () => {
+    // The whole reason this is an argument: `.` has to import cleanly inside a Cloudflare
+    // Worker, which has no `process` at all. A module-scope `process.env.LOG_LEVEL` read makes
+    // the package Node-only by accident, and nothing in a type or a test would say so.
+    const { lines, write } = capture();
+    createLogger({ level: "debug", write }).debug("now visible");
+
+    expect(lines).toHaveLength(1);
+  });
+
+  it("writes nothing at all when it is silent", () => {
+    // What a test suite sets, so an injected failure does not print a real-looking error line
+    // and bury the one real failure. It is a threshold, not a level: nothing logs AT silent.
+    const { lines, write } = capture();
+    const logger = createLogger({ level: "silent", write });
+    logger.debug("x");
+    logger.error("x");
+
+    expect(lines).toHaveLength(0);
+  });
+
+  it("treats an unset or empty level as info", () => {
+    // `process.env.LOG_LEVEL` is `undefined` when unset and "" when set to nothing, and both
+    // mean the same thing to the person who typed them.
+    const { lines, write } = capture();
+    createLogger({ level: undefined, write }).info("a");
+    createLogger({ level: "", write }).info("b");
+
+    expect(lines).toHaveLength(2);
+  });
+
+  it("refuses an unknown level at boot, and names the ones that work", () => {
+    // Loud here rather than a silent fall back to info: a box running at the wrong level is
+    // discovered during the incident it was supposed to explain. This runs once, at boot, so a
+    // typo fails the deploy instead of the 3am read.
+    expect(() => createLogger({ level: "verbose" })).toThrow(/verbose/);
+    expect(() => createLogger({ level: "verbose" })).toThrow(/debug, info, warn, error, silent/);
+  });
+});
+
+describe("where a line goes", () => {
+  it("sends error and warn to stderr and the rest to stdout", () => {
+    // The process manager reading these keeps stdout and stderr apart, and a crash that only
+    // reaches stderr is the thing the structured log exists to replace.
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const logger = createLogger({ level: "debug" });
+    logger.debug("a");
+    logger.info("b");
+    logger.warn("c");
+    logger.error("d");
+
+    expect(log).toHaveBeenCalledTimes(2);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalledTimes(1);
+  });
+});

package/src/logger/index.ts

@@ -0,0 +1,112 @@
+/**
+ * One JSON line per event, on stdout, and nothing else.
+ *
+ * Twelve backends were read for this and none of them installs a logging library. The measured
+ * gap between 60 lines of `console.log(JSON.stringify(...))` and a real one is not levels,
+ * transports or child loggers — it is the error serializer, and the standard one ships the same
+ * copy-loop this package exists to remove. So the package ships no logging library, no transports,
+ * no file rotation and no extra levels. Every backend here runs under a process manager or a
+ * container that already owns stdout; nothing in twelve repos writes a log file.
+ */
+import { errorReplacer } from "./serialize.ts";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/** A threshold, which is a level or "silent". "silent" is not a level: nothing logs AT it. */
+export type LogThreshold = LogLevel | "silent";
+
+export interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface LoggerOptions {
+  /**
+   * The lowest level that gets written. Defaults to "info".
+   *
+   * It is an argument rather than a `process.env.LOG_LEVEL` read, and that is the boundary this
+   * package is built on: a Cloudflare Worker has no `process` at all, so a module-scope read makes
+   * the package Node-only by accident. The adopter writes the read:
+   *
+   *     export const logger = createLogger({ level: process.env.LOG_LEVEL });
+   *
+   * and a Worker writes `createLogger({ level: env.LOG_LEVEL })` from its handler argument.
+   *
+   * Typed `string` on purpose, so passing `process.env.LOG_LEVEL` needs no cast. An unrecognized
+   * value throws — see `resolveThreshold`.
+   */
+  level?: string | undefined;
+  /**
+   * Where a finished line goes. Defaults to the console, `error`/`warn` to stderr.
+   *
+   * This is a seam, not a transport — the package ships none. It exists because one backend in
+   * the fleet needs the line twice (stdout and a batched exporter it flushes on SIGTERM), and
+   * because without it every test of anything that logs has to monkey-patch a global.
+   */
+  write?: (line: string, level: LogLevel) => void;
+}
+
+const LEVELS: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+const SILENT = Number.POSITIVE_INFINITY;
+
+function resolveThreshold(level: string | undefined): number {
+  if (level === undefined || level === "") return LEVELS.info;
+  if (level === "silent") return SILENT;
+  const known = LEVELS[level as LogLevel];
+  if (known !== undefined) return known;
+  // Loud, at construction, rather than silently falling back to "info": a box running at the
+  // wrong level is discovered during the incident it was meant to explain. This is called once
+  // at boot, so a typo fails the deploy instead of the 3am read.
+  throw new Error(
+    `Unknown log level ${JSON.stringify(level)}. ` +
+      `Use one of: debug, info, warn, error, silent — or leave it unset for info.`,
+  );
+}
+
+function consoleWrite(line: string, level: LogLevel): void {
+  if (level === "error") console.error(line);
+  else if (level === "warn") console.warn(line);
+  else console.log(line);
+}
+
+/**
+ * Build a logger. Call it once, at boot, and pass the result to everything that logs.
+ *
+ *     const logger = createLogger({ level: process.env.LOG_LEVEL });
+ *     logger.info("server started", { port: 3000 });
+ *     logger.error("charge failed", { orderId, error: err });   // the RAW error, never String(err)
+ */
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const threshold = resolveThreshold(options.level);
+  const write = options.write ?? consoleWrite;
+
+  function emit(level: LogLevel, message: string, meta?: Record<string, unknown>): void {
+    if (LEVELS[level] < threshold) return;
+    // Canonical fields last, so they win: a meta `message`, `level` or `time` must never replace
+    // the line's own label, severity or timestamp. One backend re-implemented this logger inline
+    // with the order inverted, and a `meta.message` silently became the line.
+    const time = new Date().toISOString();
+    const entry = { ...meta, level, time, message };
+    let line: string;
+    try {
+      line = JSON.stringify(entry, errorReplacer());
+    } catch {
+      // A logger must never take down the process it is reporting on. Reachable through a
+      // throwing getter or a throwing `toJSON()` on something in `meta` — and the flag is there
+      // so a reader knows a line was lost rather than never written.
+      line = JSON.stringify({ level, time, message, logSerializationFailed: true });
+    }
+    write(line, level);
+  }
+
+  return {
+    debug: (message, meta) => emit("debug", message, meta),
+    info: (message, meta) => emit("info", message, meta),
+    warn: (message, meta) => emit("warn", message, meta),
+    error: (message, meta) => emit("error", message, meta),
+  };
+}
+
+export { errorReplacer, keptErrorFields } from "./serialize.ts";