@gusnips/server 0.1.0

package/src/hono/errors.test.ts

@@ -0,0 +1,215 @@
+import { Hono } from "hono";
+import { describe, expect, it, vi } from "vitest";
+import { AppError, createAppError, createErrorResponse, createLogger } from "../index.ts";
+import { errorBoundary, errorHandler, notFoundHandler } from "./errors.ts";
+import { requestLogger, type RequestVariables } from "./request-logger.ts";
+
+type ErrorCode = "NOT_FOUND" | "RATE_LIMIT_EXCEEDED" | "UNAVAILABLE" | "INTERNAL_ERROR" | "ODD";
+
+const appError = createAppError({
+  NOT_FOUND: 404,
+  RATE_LIMIT_EXCEEDED: 429,
+  UNAVAILABLE: 503,
+  INTERNAL_ERROR: 500,
+} as const);
+
+const errorResponse = createErrorResponse<ErrorCode, string>({
+  internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+  validation: { code: "INTERNAL_ERROR", message: "unused here" },
+});
+
+function setup({ boundary = true } = {}) {
+  const lines: Array<Record<string, unknown>> = [];
+  const logger = createLogger({
+    level: "debug",
+    write: (line) => lines.push(JSON.parse(line) as Record<string, unknown>),
+  });
+  const onUnexpected = vi.fn();
+  const app = new Hono<{ Variables: RequestVariables<ErrorCode> }>();
+  app.use(requestLogger({ logger }));
+  if (boundary) app.use(errorBoundary);
+  app.onError(errorHandler({ errorResponse, logger, onUnexpected }));
+  app.notFound(notFoundHandler(errorResponse(appError("NOT_FOUND", "Route not found"))));
+  return { app, lines, onUnexpected };
+}
+
+describe("errorBoundary", () => {
+  const rejection = { code: "PGRST116", message: "no rows returned" };
+
+  it("turns a thrown plain object into an answer, where Hono alone answers nothing", async () => {
+    const bare = setup({ boundary: false });
+    bare.app.get("/rows", () => {
+      throw rejection;
+    });
+    await expect(bare.app.request("/rows")).rejects.toBe(rejection);
+
+    const { app } = setup();
+    app.get("/rows", () => {
+      throw rejection;
+    });
+    const res = await app.request("/rows");
+
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({
+      error: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+    });
+  });
+
+  it("keeps the original as the cause, and its message as the message", async () => {
+    const { app, lines } = setup();
+    app.get("/rows", () => {
+      throw rejection;
+    });
+
+    await app.request("/rows");
+
+    const failed = lines.find((line) => line.message === "request failed");
+    expect(failed?.error).toMatchObject({ message: "no rows returned", cause: rejection });
+  });
+
+  it("hands a real Error through as the same instance", async () => {
+    const thrown = new TypeError("x is undefined");
+    const { app, onUnexpected } = setup();
+    app.get("/", () => {
+      throw thrown;
+    });
+
+    await app.request("/");
+
+    expect(onUnexpected.mock.calls[0]![0]).toBe(thrown);
+  });
+});
+
+describe("errorHandler", () => {
+  it("answers a refusal with its status, body and headers, and names it on the request line", async () => {
+    const { app, lines, onUnexpected } = setup();
+    app.get("/send", () => {
+      throw appError("RATE_LIMIT_EXCEEDED", "Too many requests", { retryAfterSecs: 30 });
+    });
+
+    const res = await app.request("/send");
+
+    expect(res.status).toBe(429);
+    expect(res.headers.get("Retry-After")).toBe("30");
+    expect(await res.json()).toMatchObject({ error: { code: "RATE_LIMIT_EXCEEDED" } });
+    expect(lines).toEqual([
+      expect.objectContaining({
+        message: "request",
+        status: 429,
+        errorCode: "RATE_LIMIT_EXCEEDED",
+      }),
+    ]);
+    expect(onUnexpected).not.toHaveBeenCalled();
+  });
+
+  it("logs a 5xx it was handed on purpose, without calling it unexpected", async () => {
+    const { app, lines, onUnexpected } = setup();
+    app.get("/", () => {
+      throw appError("UNAVAILABLE", "The database is unreachable");
+    });
+
+    const res = await app.request("/");
+
+    expect(res.status).toBe(503);
+    expect(lines[0]).toMatchObject({ level: "error", message: "request failed", kind: "server" });
+    expect(onUnexpected).not.toHaveBeenCalled();
+  });
+
+  it("logs an escaped throw with its stack, alerts on it, and answers the generic 500", async () => {
+    const { app, lines, onUnexpected } = setup();
+    app.get("/", () => {
+      throw new TypeError("x is undefined");
+    });
+
+    const res = await app.request("/");
+
+    expect(res.status).toBe(500);
+    expect(await res.json()).toMatchObject({ error: { code: "INTERNAL_ERROR" } });
+    expect(lines[0]).toMatchObject({ level: "error", kind: "unexpected" });
+    expect(lines[0]!.error).toMatchObject({ name: "TypeError", message: "x is undefined" });
+    expect(String((lines[0]!.error as { stack: string }).stack)).toContain("TypeError");
+    expect(lines[1]).toMatchObject({
+      message: "request",
+      status: 500,
+      errorCode: "INTERNAL_ERROR",
+    });
+    expect(onUnexpected).toHaveBeenCalledOnce();
+  });
+
+  it("carries the request id on the error answer, the same one the lines carry", async () => {
+    // The browser client reads the id off this header into the error it raises, which is what
+    // lets an error screen show a reference someone can quote.
+    const { app, lines } = setup();
+    app.get("/", () => {
+      throw new TypeError("x is undefined");
+    });
+
+    const res = await app.request("/", { headers: { "X-Request-ID": "trace-1" } });
+
+    expect(res.headers.get("X-Request-ID")).toBe("trace-1");
+    expect(lines.map((line) => line.requestId)).toEqual(["trace-1", "trace-1"]);
+  });
+
+  it.each([
+    ["a success", 200],
+    ["one that cannot carry a body", 204],
+    ["one outside HTTP", 700],
+  ])("treats an error raised with %s status as the bug it is", async (_, status) => {
+    // Hono hands an Error thrown out of onError back to onError, one level up. So refusing the
+    // status is enough to land it in the unexpected arm, where somebody is told.
+    const { app, lines, onUnexpected } = setup();
+    app.get("/", () => {
+      throw new AppError(status, "ODD", "a status nobody should raise");
+    });
+
+    const res = await app.request("/");
+
+    expect(res.status).toBe(500);
+    expect(await res.json()).toMatchObject({ error: { code: "INTERNAL_ERROR" } });
+    expect(onUnexpected).toHaveBeenCalledOnce();
+    expect(lines.find((line) => line.kind === "unexpected")?.error).toMatchObject({
+      name: "RangeError",
+      message: `An error answered ${status}.`,
+    });
+  });
+});
+
+describe("notFoundHandler", () => {
+  it("answers the refusal it was given, with the request id, and names it on the request line", async () => {
+    const { app, lines } = setup();
+
+    const res = await app.request("/nothing/here");
+
+    expect(res.status).toBe(404);
+    expect(res.headers.get("X-Request-ID")).toBeTruthy();
+    expect(await res.json()).toEqual({ error: { code: "NOT_FOUND", message: "Route not found" } });
+    expect(lines[0]).toMatchObject({ status: 404, errorCode: "NOT_FOUND" });
+  });
+});
+
+describe("an app's own env", () => {
+  it("takes all four pieces without a cast", async () => {
+    // The shape an adopter writes: bindings, variables of its own, and `errorCode` typed to its
+    // own code union rather than to `string`.
+    type AppEnv = {
+      Bindings: { DATABASE_URL: string };
+      Variables: { requestId: string; errorCode: ErrorCode | null; userId: string };
+    };
+    const logger = createLogger({ level: "silent" });
+    const app = new Hono<AppEnv>();
+    app.use(requestLogger({ logger }));
+    app.use(errorBoundary);
+    app.onError(errorHandler({ errorResponse, logger, onUnexpected: (_err, c) => c.req.method }));
+    app.notFound(notFoundHandler(errorResponse(appError("NOT_FOUND", "Route not found"))));
+    app.get("/", (c) => c.text(c.get("requestId")));
+
+    expect((await app.request("/")).status).toBe(200);
+  });
+
+  it("refuses an errorResponse that answers codes the app's errorCode cannot hold", () => {
+    const logger = createLogger({ level: "silent" });
+    const narrow = new Hono<{ Variables: RequestVariables<"NOT_FOUND"> }>();
+    // @ts-expect-error — this errorResponse also answers INTERNAL_ERROR, among others.
+    narrow.onError(errorHandler({ errorResponse, logger }));
+  });
+});

package/src/hono/errors.ts

@@ -0,0 +1,86 @@
+import type { Context, ErrorHandler, MiddlewareHandler, NotFoundHandler } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { toMessage } from "../errors.ts";
+import type { Logger } from "../logger/index.ts";
+import type { ErrorAnswer } from "../responses.ts";
+import type { RequestVariables } from "./request-logger.ts";
+
+/**
+ * The app's own env, taken from the `onError` / `notFound` call it is passed to, so its bindings
+ * and variables fit as they are. The code type comes from its `errorCode`, which is what stops
+ * `errorResponse` from answering a code that slot cannot hold.
+ */
+type ErrorEnv = { Variables: RequestVariables };
+type CodeOf<E extends ErrorEnv> = NonNullable<E["Variables"]["errorCode"]>;
+
+/**
+ * Turns a thrown non-`Error` into an `Error`, so it reaches `onError`.
+ *
+ * Hono hands `onError` only what is `instanceof Error`. Anything else is rethrown past every
+ * layer and escapes as an unhandled rejection: no answer, a dropped connection, and a browser that
+ * reports it as a CORS failure — which sends whoever reads it to the wrong layer. A PostgREST
+ * client rejects with plain objects, so this is not hypothetical. The original rides as `cause`.
+ *
+ * Mount it right after `requestLogger`.
+ */
+export const errorBoundary: MiddlewareHandler = async (_c, next) => {
+  try {
+    await next();
+  } catch (err) {
+    if (err instanceof Error) throw err;
+    throw new Error(toMessage(err), { cause: err });
+  }
+};
+
+export interface ErrorHandlerOptions<E extends ErrorEnv> {
+  /** Your bound `createErrorResponse(...)`. */
+  errorResponse: (err: unknown) => ErrorAnswer<CodeOf<E>>;
+  logger: Logger;
+  /**
+   * Called for a throw nobody raised on purpose, which is where an alert belongs. It runs inside
+   * `onError`, so it must not throw, and anything slow should be sent without being awaited.
+   */
+  onUnexpected?: (err: unknown, c: Context<E>) => void;
+}
+
+/**
+ * `app.onError(errorHandler({ errorResponse, logger }))`.
+ *
+ * A refusal under 500 writes no line of its own: its code rides on the request line, because one
+ * line per wrong password buries the failures that need a human. A 5xx and an escaped throw are
+ * logged with the raw error, stack and cause included.
+ */
+export function errorHandler<E extends ErrorEnv>({
+  errorResponse,
+  logger,
+  onUnexpected,
+}: ErrorHandlerOptions<E>): ErrorHandler<E> {
+  return (err, c) => {
+    const answer = errorResponse(err);
+    if (answer.kind !== "client")
+      logger.error("request failed", {
+        requestId: c.get("requestId"),
+        kind: answer.kind,
+        error: err,
+      });
+    if (answer.kind === "unexpected") onUnexpected?.(err, c);
+    return respond(c, answer);
+  };
+}
+
+/** `app.notFound(notFoundHandler(errorResponse(errors.notFound("Route"))))`. */
+export const notFoundHandler =
+  <E extends ErrorEnv>(answer: ErrorAnswer<CodeOf<E>>): NotFoundHandler<E> =>
+  (c) =>
+    respond(c, answer);
+
+function respond<E extends ErrorEnv>(c: Context<E>, answer: ErrorAnswer<CodeOf<E>>) {
+  // An error answered as a 2xx reads as success to every client. Thrown instead, it comes back
+  // through onError as the unexpected throw it is: the generic 500, logged, and alerted on.
+  if (!isErrorStatus(answer.status)) throw new RangeError(`An error answered ${answer.status}.`);
+  c.set("errorCode", answer.body.error.code);
+  return c.json(answer.body, answer.status, answer.headers);
+}
+
+const isErrorStatus = (status: number): status is ContentfulStatusCode =>
+  status >= 400 && status <= 599;

package/src/hono/guards.test.ts

@@ -0,0 +1,234 @@
+import { Hono, type MiddlewareHandler } from "hono";
+import { describe, expect, it } from "vitest";
+import { assertEveryRouteGuarded, guard, underAny } from "./guards.ts";
+
+const requireAdmin = guard(async (c, next) => {
+  if (c.req.header("Authorization") !== "Bearer admin") return c.json({}, 401);
+  return next();
+});
+
+const logRequest: MiddlewareHandler = async (_c, next) => {
+  await next();
+};
+
+const ok = (c: { text: (body: string) => Response }) => c.text("ok");
+
+function check(app: Hono, isPublic: (path: string) => boolean = () => false) {
+  return () => assertEveryRouteGuarded(app, { isPublic });
+}
+
+describe("assertEveryRouteGuarded", () => {
+  it("passes an app whose guard is mounted before its routes", () => {
+    const app = new Hono();
+    app.use(logRequest);
+    app.use("/admin/*", requireAdmin);
+    app.get("/admin/users", ok);
+    app.post("/admin/users/:id/ban", ok);
+
+    expect(check(app)).not.toThrow();
+  });
+
+  it("fails a guard registered after its route, which matches it and never runs", async () => {
+    // Compare pattern lists and this app is guarded: `/admin/*` covers `/admin/users`. Ask the
+    // matcher and the handler comes first, answers, and the guard never runs.
+    const app = new Hono();
+    app.get("/admin/users", ok);
+    app.use("/admin/*", requireAdmin);
+
+    expect((await app.request("/admin/users")).status).toBe(200);
+    expect(check(app)).toThrow(/endpoint\(s\) answer with no guard[^]*\n {2}GET \/admin\/users\n/);
+  });
+
+  it("fails a router mounted above the guard loop", async () => {
+    // One backend's gate test built a second app from its guard list plus a catch-all, so it never
+    // saw the real mount order, and passed while the real app's router, mounted above the loop,
+    // answered with no token at all. Only the real app, asked, has the order.
+    const patterns = ["/feedback", "/admin/*"];
+    const feedback = new Hono();
+    feedback.get("/", ok);
+    feedback.post("/", ok);
+    feedback.get("/mine", ok);
+    const app = new Hono();
+    app.route("/feedback", feedback);
+    for (const pattern of patterns) app.use(pattern, requireAdmin);
+    app.get("/admin/users", ok);
+
+    expect((await app.request("/feedback/mine")).status).toBe(200);
+    expect(check(app)).toThrow(
+      /3 endpoint\(s\)[^]*\n {2}GET \/feedback\n {2}GET \/feedback\/mine\n {2}POST \/feedback\n/,
+    );
+  });
+
+  it("fails the route under an exact guard pattern, which only ever covered itself", () => {
+    // Hono reads `use("/feedback")` as that one path. The sub-route under it is what shipped public.
+    const feedback = new Hono();
+    feedback.get("/", ok);
+    feedback.get("/mine", ok);
+    const app = new Hono();
+    app.use("/feedback", requireAdmin);
+    app.route("/feedback", feedback);
+
+    expect(check(app)).toThrow(/1 endpoint\(s\)[^]*\n {2}GET \/feedback\/mine\n/);
+  });
+
+  it("fails a guard that runs in front of no endpoint, which is what a router that mounted nothing leaves", () => {
+    // A stand-in dependency's router registers nothing, so its routes drop out of the check, and
+    // the check passes by having nothing to ask. The guard mounted over it is the trace left.
+    const app = new Hono();
+    app.use("/admin/*", requireAdmin);
+    app.route("/admin", new Hono());
+    app.get("/health", ok);
+
+    expect(check(app, (path) => path === "/health")).toThrow(
+      /1 guard\(s\) run in front of no endpoint:\n {2}ALL \/admin\/\*\n/,
+    );
+  });
+
+  it("counts a guard in front of a route the app calls public, which the guard itself lets by", () => {
+    // A guard that waves one public read through is still a guard with a route behind it.
+    const app = new Hono();
+    app.use("/sources/*", requireAdmin);
+    app.get("/sources/catalog", ok);
+
+    expect(check(app, (path) => path === "/sources/catalog")).not.toThrow();
+  });
+
+  it("fails an app with no endpoints at all, rather than passing it", () => {
+    expect(check(new Hono())).toThrow(/no endpoints/);
+  });
+
+  it("fails a route with nothing in front of it but middleware that is not a guard", () => {
+    const app = new Hono();
+    app.use(logRequest);
+    app.use("/admin/*", requireAdmin);
+    app.get("/admin/users", ok);
+    app.delete("/users/:id", ok);
+
+    expect(check(app)).toThrow(/\n {2}DELETE \/users\/:id\n/);
+    expect(check(app)).not.toThrow(/\/admin\/users/);
+  });
+
+  it("names every unguarded endpoint once, sorted", () => {
+    const app = new Hono();
+    app.post("/b", ok);
+    app.get("/a", ok);
+    app.get("/a", ok);
+
+    expect(check(app)).toThrow(/2 endpoint\(s\)[^]*\n {2}GET \/a\n {2}POST \/b\n/);
+  });
+
+  it("skips what the app's own rule calls public, asked with the path a request would carry", () => {
+    const app = new Hono();
+    app.post("/webhooks/pay", ok);
+    app.get("/docs/:page", ok);
+    app.get("/reports/:id{[0-9]+}", ok);
+    const asked: string[] = [];
+    const isPublic = (path: string) => {
+      asked.push(path);
+      return path.startsWith("/webhooks/") || path.startsWith("/docs/");
+    };
+
+    expect(check(app, isPublic)).toThrow(/1 endpoint\(s\)[^]*\n {2}GET \/reports\/:id/);
+    expect(asked).toEqual(["/webhooks/pay", "/docs/probe", "/reports/1"]);
+  });
+
+  it("counts a guard passed inline, ahead of the handler", () => {
+    const app = new Hono();
+    app.get("/me", requireAdmin, ok);
+
+    expect(check(app)).not.toThrow();
+  });
+
+  it("checks an all() endpoint under every method, since every method reaches it", () => {
+    // A protocol endpoint taking any method is written `app.all("/mcp", handle)`. A guard mounted
+    // for POST alone leaves every other method reaching the handler bare.
+    const guardedForAll = new Hono();
+    guardedForAll.use("/mcp", requireAdmin);
+    guardedForAll.all("/mcp", ok);
+
+    const guardedForPost = new Hono();
+    guardedForPost.post("/mcp", requireAdmin);
+    guardedForPost.all("/mcp", ok);
+
+    expect(check(guardedForAll)).not.toThrow();
+    expect(check(guardedForPost)).toThrow(/\n {2}ALL \/mcp\n/);
+  });
+
+  it("sees through a sub-app, including one with its own onError", () => {
+    // A sub-app with its own onError has every handler wrapped in a two-argument function, so an
+    // endpoint in it reads as middleware unless the wrapper is looked through.
+    const admin = new Hono();
+    admin.onError((_err, c) => c.text("admin failed", 500));
+    admin.get("/users", ok);
+
+    const bare = new Hono();
+    bare.route("/admin", admin);
+    expect(check(bare)).toThrow(/\n {2}GET \/admin\/users\n/);
+
+    const guardedInside = new Hono();
+    guardedInside.use(requireAdmin);
+    guardedInside.onError((_err, c) => c.text("admin failed", 500));
+    guardedInside.get("/users", ok);
+    const app = new Hono();
+    app.route("/admin", guardedInside);
+    expect(check(app)).not.toThrow();
+  });
+
+  it("fails a guard mounted in the parent after the sub-app it was meant for", () => {
+    const admin = new Hono();
+    admin.get("/users", ok);
+    const app = new Hono();
+    app.route("/admin", admin);
+    app.use("/admin/*", requireAdmin);
+
+    expect(check(app)).toThrow(/\n {2}GET \/admin\/users\n/);
+  });
+
+  it("probes a numeric parameter pattern with a number", () => {
+    const app = new Hono();
+    app.use("/forecasts/*", requireAdmin);
+    app.get("/forecasts/:id{[0-9]+}/watch", ok);
+
+    expect(check(app)).not.toThrow();
+  });
+
+  it("reports a path it cannot build a request for, rather than passing it", () => {
+    const app = new Hono();
+    app.use("/tags/*", requireAdmin);
+    app.get("/tags/:name{[a-z]+}", ok);
+
+    expect(check(app)).toThrow(
+      /GET \/tags\/:name\{\[a-z\]\+\} \(could not be probed at \/tags\/1\)/,
+    );
+  });
+
+  it("probes a wildcard endpoint", () => {
+    const app = new Hono();
+    app.get("/static/*", ok);
+    app.get("*", ok);
+
+    expect(check(app, underAny(["/static"]))).toThrow(/\n {2}GET \/\*\n/);
+    expect(check(app, underAny(["/static"]))).not.toThrow(/static/);
+  });
+});
+
+describe("underAny", () => {
+  it("reads every entry as a prefix, whichever pattern form it is written in", () => {
+    const under = underAny(["/feedback", "/admin/*"]);
+
+    for (const path of ["/feedback", "/feedback/mine", "/admin", "/admin/users/1"])
+      expect(under(path), path).toBe(true);
+    for (const path of ["/feedbacks", "/adminx", "/", "/other/feedback"])
+      expect(under(path), path).toBe(false);
+  });
+});
+
+describe("guard", () => {
+  it("returns the same function, so it can wrap one where it is defined", () => {
+    const middleware: MiddlewareHandler = async (_c, next) => {
+      await next();
+    };
+
+    expect(guard(middleware)).toBe(middleware);
+  });
+});

package/src/hono/guards.ts

@@ -0,0 +1,107 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import { METHODS } from "hono/router";
+import type { RouterRoute } from "hono/types";
+import { findTargetHandler, isMiddleware } from "hono/utils/handler";
+
+const GUARD = Symbol.for("@gusnips/server/hono:guard");
+
+/**
+ * Marks a middleware as one that decides who may pass, for `assertEveryRouteGuarded`. Returns the
+ * same function. Mark it where it is defined, so every place it is mounted counts.
+ *
+ *     export const requireAdmin = guard(async (c, next) => { … });
+ */
+export function guard<H extends MiddlewareHandler>(middleware: H): H {
+  Object.defineProperty(middleware, GUARD, { value: true });
+  return middleware;
+}
+
+export interface GuardCheckOptions {
+  /**
+   * The app's own rule for what anyone may call, asked with the path a request would carry:
+   * `/people/:id` is asked as `/people/probe`, `/reports/:id{[0-9]+}` as `/reports/1`. Pass the
+   * predicate or the list the app itself uses, never a second one kept for the test: an exemption
+   * list nothing else reads is the next thing to drift. `underAny(list)` reads a list as prefixes.
+   */
+  isPublic: (path: string) => boolean;
+}
+
+/**
+ * "Under one of these", reading each entry as a prefix whichever pattern form it holds:
+ * `/feedback` and `/feedback/*` both cover `/feedback` and `/feedback/mine`, and neither covers
+ * `/feedbacks`. Hono reads `use("/feedback")` as that one path, which is how the route under it
+ * once shipped public while the list said it was guarded.
+ */
+export function underAny(prefixes: readonly string[]): (path: string) => boolean {
+  const bases = prefixes.map((prefix) => prefix.replace(/\/\*$/, ""));
+  return (path) => bases.some((base) => path === base || path.startsWith(`${base}/`));
+}
+
+const isGuard = (handler: RouterRoute["handler"]) => GUARD in findTargetHandler(handler);
+
+/**
+ * Throws, naming every endpoint no guard runs in front of, and every guard that runs in front of
+ * nothing. Build the real app, and call it in a test once every route is registered: the first
+ * match freezes Hono's router.
+ *
+ * It asks Hono's own router what would run for each of the app's real routes, and in what order,
+ * rather than comparing patterns. A pattern list cannot see order, and order is the whole bug: a
+ * `use()` registered after its route matches that route and never runs for it, because the
+ * handler answers first. Only the matcher tells a guard that never fires from one that does.
+ *
+ * A guard in front of nothing is the trace a router leaves when it mounted no routes, which is
+ * what a stand-in dependency's router does in a test: its routes drop out of the check, and the
+ * check would pass by having nothing to ask. A guard inside that router drops out with it, so a
+ * stand-in that yields a router should throw when Hono reads its `routes`.
+ *
+ * An endpoint is what Hono's own route inspector calls one, a handler taking fewer than two
+ * arguments. So a `(c, next)` handler that answers is not checked, and a path whose parameter
+ * pattern rejects the probe is reported as unprobeable rather than passed.
+ */
+export function assertEveryRouteGuarded(
+  app: Pick<Hono, "routes" | "router">,
+  { isPublic }: GuardCheckOptions,
+): void {
+  const endpoints = app.routes.filter((route) => !isMiddleware(findTargetHandler(route.handler)));
+  if (endpoints.length === 0)
+    throw new Error(
+      "The app has no endpoints to check, so the check would pass by asking nothing.",
+    );
+  const idle = new Set(app.routes.filter((route) => isGuard(route.handler)));
+  const unguarded = new Set<string>();
+  for (const route of endpoints) {
+    const { method, path } = route;
+    const probe = path.replace(/:\w+\{[^}]*\}\??/g, "1").replace(/:\w+\??|\*/g, "probe");
+    const open = isPublic(probe);
+    for (const each of method === "ALL" ? METHODS.map((m) => m.toUpperCase()) : [method]) {
+      const [matched] = app.router.match(each, probe);
+      const at = matched.findIndex(([[, candidate]]) => candidate === route);
+      const ahead = matched.slice(0, Math.max(at, 0)).filter(([[handler]]) => isGuard(handler));
+      for (const [[, guardRoute]] of ahead) idle.delete(guardRoute);
+      if (open) continue;
+      if (at === -1) unguarded.add(`${method} ${path} (could not be probed at ${probe})`);
+      else if (ahead.length === 0) unguarded.add(`${method} ${path}`);
+    }
+  }
+  if (unguarded.size === 0 && idle.size === 0) return;
+  const list = (lines: Iterable<string>) =>
+    [...new Set(lines)]
+      .sort()
+      .map((line) => `  ${line}\n`)
+      .join("");
+  const idleLines = [...idle].map((route) => `${route.method} ${route.path}`);
+  throw new Error(
+    (unguarded.size > 0
+      ? `${String(unguarded.size)} endpoint(s) answer with no guard running in front of them:\n` +
+        list(unguarded)
+      : "") +
+      (idle.size > 0
+        ? `${String(new Set(idleLines).size)} guard(s) run in front of no endpoint:\n` +
+          list(idleLines)
+        : "") +
+      "A guard counts when it is wrapped in guard() and registered BEFORE its routes: a use() " +
+      "added after them never runs for them. A guard in front of nothing sits after its routes, " +
+      "or over a router that mounted none. Move it up, build that router for real, or have " +
+      "isPublic say so if anyone may call the path.",
+  );
+}

package/src/hono/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@gusnips/server/hono`: the package mounted on a Hono app.
+ *
+ *     app.use(requestLogger({ logger }));
+ *     app.use(errorBoundary);
+ *     app.onError(errorHandler({ errorResponse, logger }));
+ *     app.notFound(notFoundHandler(errorResponse(errors.notFound("Route"))));
+ *
+ * and, in a test of the real app, `assertEveryRouteGuarded(app, { isPublic })`, with the rule the
+ * app itself uses for what anyone may call.
+ */
+export { errorBoundary, errorHandler, notFoundHandler } from "./errors.ts";
+export type { ErrorHandlerOptions } from "./errors.ts";
+export { assertEveryRouteGuarded, guard, underAny } from "./guards.ts";
+export type { GuardCheckOptions } from "./guards.ts";
+export { requestLogger } from "./request-logger.ts";
+export type { RequestLoggerOptions, RequestVariables } from "./request-logger.ts";