@gusnips/server 0.1.0

package/src/responses.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { AppError, createAppError } from "./errors.ts";
+import { created, createErrorResponse, noContent, ok, paginated } from "./responses.ts";
+
+type Code =
+  | "VALIDATION_ERROR"
+  | "UNAUTHORIZED"
+  | "NOT_FOUND"
+  | "RATE_LIMIT_EXCEEDED"
+  | "INTERNAL_ERROR"
+  | "SERVICE_UNAVAILABLE"
+  | "GATEWAY_ERROR";
+
+const ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  RATE_LIMIT_EXCEEDED: 429,
+  INTERNAL_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_ERROR: 502,
+} as const satisfies Record<Code, number>;
+
+const appError = createAppError<typeof ERROR_STATUS>(ERROR_STATUS);
+
+const errorResponse = createErrorResponse<Code>({
+  internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+  validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+});
+
+describe("success helpers", () => {
+  it("wraps every 2xx body in { data }", () => {
+    expect(ok({ id: 1 })).toEqual({ status: 200, body: { data: { id: 1 } } });
+    expect(created({ id: 1 })).toEqual({ status: 201, body: { data: { id: 1 } } });
+    expect(noContent()).toEqual({ status: 204, body: null });
+  });
+
+  it("omits meta when there is none", () => {
+    expect(ok({ id: 1 }).body).not.toHaveProperty("meta");
+  });
+
+  it("computes hasMore from the page it actually returned", () => {
+    expect(paginated([1, 2], { total: 10, limit: 2, offset: 0 }).body.meta).toEqual({
+      total: 10,
+      limit: 2,
+      offset: 0,
+      hasMore: true,
+    });
+    expect(paginated([9, 10], { total: 10, limit: 2, offset: 8 }).body.meta?.hasMore).toBe(false);
+    expect(paginated([], { total: 0, limit: 20, offset: 0 }).body.meta?.hasMore).toBe(false);
+  });
+});
+
+describe("the error envelope", () => {
+  it("omits every optional field that was not set", () => {
+    expect(errorResponse(appError("NOT_FOUND", "Workspace not found")).body).toEqual({
+      error: { code: "NOT_FOUND", message: "Workspace not found" },
+    });
+  });
+
+  it("carries messageKey, params and details when they are set", () => {
+    const body = errorResponse(
+      appError("NOT_FOUND", "No such plan", {
+        messageKey: "serverErrors.notFound",
+        params: { id: "pro" },
+        details: { id: "pro", upgradeTo: "starter" },
+      }),
+    ).body;
+    expect(body.error.messageKey).toBe("serverErrors.notFound");
+    expect(body.error.params).toEqual({ id: "pro" });
+    expect(body.error.details).toEqual({ id: "pro", upgradeTo: "starter" });
+  });
+
+  it("folds a stated wait into an object details", () => {
+    const err = appError("RATE_LIMIT_EXCEEDED", "Too many requests", {
+      details: { limit: 60 },
+      retryAfterSecs: 30,
+    });
+    expect(errorResponse(err).body.error.details).toEqual({ limit: 60, retryAfterSecs: 30 });
+  });
+
+  it("folds it into an absent details", () => {
+    const err = appError("RATE_LIMIT_EXCEEDED", "Too many requests", { retryAfterSecs: 30 });
+    expect(errorResponse(err).body.error.details).toEqual({ retryAfterSecs: 30 });
+  });
+
+  it("hands an ARRAY details back untouched", () => {
+    const issues = [{ path: ["url"], code: "invalid_string" }];
+    const err = appError("RATE_LIMIT_EXCEEDED", "Too many requests", {
+      details: issues,
+      retryAfterSecs: 5,
+    });
+    const details = errorResponse(err).body.error.details;
+    expect(details).toEqual(issues);
+    expect(Array.isArray(details)).toBe(true);
+  });
+
+  it("hands a STRING details back untouched", () => {
+    const err = appError("RATE_LIMIT_EXCEEDED", "Spent", {
+      details: "month",
+      retryAfterSecs: 5,
+    });
+    expect(errorResponse(err).body.error.details).toBe("month");
+  });
+});
+
+describe("a validation failure is a 400 that reflects nothing back", () => {
+  const schema = z
+    .object({ days: z.enum(["7", "30"]), timeoutMs: z.number().max(30_000) })
+    .strict();
+
+  it("answers 400 with the path and the rule", () => {
+    const parsed = schema.safeParse({ days: "90", timeoutMs: 1 });
+    const answer = errorResponse(parsed.error);
+    expect(answer.status).toBe(400);
+    expect(answer.kind).toBe("client");
+    expect(answer.body.error.code).toBe("VALIDATION_ERROR");
+    expect(answer.body.error.details).toEqual([{ path: ["days"], code: "invalid_value" }]);
+  });
+
+  it("carries the BOUND a range failed against, because the bound is our published contract", () => {
+    const parsed = schema.safeParse({ days: "7", timeoutMs: 999_999 });
+    expect(errorResponse(parsed.error).body.error.details).toEqual([
+      { path: ["timeoutMs"], code: "too_big", maximum: 30_000 },
+    ]);
+  });
+
+  it("never reflects the rejected value or the keys the caller sent", () => {
+    const parsed = schema.safeParse({ days: "90", timeoutMs: 1, secretGuess: "admin" });
+    const details = JSON.stringify(errorResponse(parsed.error).body.error.details);
+    expect(details).not.toContain("90");
+    expect(details).not.toContain("secretGuess");
+    expect(details).not.toContain("admin");
+  });
+
+  it("recognizes a ZodError structurally, with no zod import of its own", () => {
+    const hand = {
+      name: "ZodError",
+      issues: [{ path: ["a"], code: "custom", received: "sekrit" }],
+    };
+    const answer = errorResponse(hand);
+    expect(answer.status).toBe(400);
+    expect(JSON.stringify(answer.body.error.details)).not.toContain("sekrit");
+  });
+});
+
+describe("an AppError under 500 is answered as itself", () => {
+  it("keeps the status, the code and the message", () => {
+    const answer = errorResponse(appError("NOT_FOUND", "Workspace not found"));
+    expect(answer).toMatchObject({
+      status: 404,
+      kind: "client",
+      body: { error: { code: "NOT_FOUND", message: "Workspace not found" } },
+    });
+  });
+
+  it("names the scheme it wants on a 401", () => {
+    expect(errorResponse(appError("UNAUTHORIZED", "Sign in")).headers).toEqual({
+      "WWW-Authenticate": "Bearer",
+    });
+  });
+
+  it("says a refusal does NOT clear by waiting, and sends no Retry-After for it", () => {
+    // A concurrency slot frees when another job finishes, and a cap on live objects clears by
+    // archiving one. Neither is a wait a server can state, and both are 429s in the fleet.
+    const answer = errorResponse(
+      appError("RATE_LIMIT_EXCEEDED", "Three jobs already running — wait for one to finish", {
+        retryAfterSecs: null,
+      }),
+    );
+    expect(answer.headers).not.toHaveProperty("Retry-After");
+    expect(answer.body.error.details).toEqual({ retryAfterSecs: null });
+  });
+
+  it("states a wait in the header as well as in details", () => {
+    const answer = errorResponse(
+      appError("RATE_LIMIT_EXCEEDED", "Slow down", { retryAfterSecs: 45 }),
+    );
+    expect(answer.headers["Retry-After"]).toBe("45");
+    expect(answer.body.error.details).toEqual({ retryAfterSecs: 45 });
+  });
+});
+
+describe("the 5xx mask", () => {
+  it("replaces the message of the one code that may carry internals", () => {
+    const answer = errorResponse(
+      appError("INTERNAL_ERROR", 'duplicate key value violates "users_email_key"'),
+    );
+    expect(answer.status).toBe(500);
+    expect(answer.kind).toBe("server");
+    expect(answer.body.error.message).toBe("Something on our side failed");
+    expect(JSON.stringify(answer.body)).not.toContain("users_email_key");
+  });
+
+  it("drops a masked 5xx's details entirely, whatever was put in them", () => {
+    // The trap this closes: a driver error handed straight to `details`. Postgres writes the
+    // ENTIRE failing row into its `detail` field on a CHECK or NOT NULL violation — every
+    // column, values included — so a caught driver object in `details` is a row on the wire.
+    const err = appError("INTERNAL_ERROR", "insert failed", {
+      details: { detail: "Failing row contains (someone@example.com, 4242424242424242)." },
+    });
+    const answer = errorResponse(err);
+    expect(answer.body.error).not.toHaveProperty("details");
+    expect(JSON.stringify(answer)).not.toContain("4242");
+  });
+
+  it("lets an authored 5xx through, because it is what says whether to retry", () => {
+    const answer = errorResponse(appError("SERVICE_UNAVAILABLE", "Metering is unavailable"));
+    expect(answer.status).toBe(503);
+    expect(answer.body.error.message).toBe("Metering is unavailable");
+  });
+
+  it("keeps the STATUS when it masks the message", () => {
+    const all = createErrorResponse<Code>({
+      internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+      validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+      maskAll: true,
+    });
+    const answer = all(appError("GATEWAY_ERROR", "upstream said: connection reset by peer"));
+    expect(answer.status).toBe(502);
+    expect(answer.body.error.message).toBe("Something on our side failed");
+    expect(answer.body.error.code).toBe("INTERNAL_ERROR");
+  });
+
+  it("lets `expose` opt an authored sentence back through maskAll", () => {
+    const all = createErrorResponse<Code>({
+      internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+      validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+      maskAll: true,
+    });
+    const err = appError("SERVICE_UNAVAILABLE", "Payments are not set up here", { expose: true });
+    expect(all(err).body.error.message).toBe("Payments are not set up here");
+  });
+
+  it("drops a 5xx's details on its own knob, exposed or not", () => {
+    const quiet = createErrorResponse<Code>({
+      internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+      validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+      maskDetails: true,
+    });
+    const err = appError("SERVICE_UNAVAILABLE", "A dependency is down", {
+      details: { pg: "connection refused at 10.0.0.4:5432" },
+    });
+    expect(quiet(err).body.error.message).toBe("A dependency is down");
+    expect(quiet(err).body.error).not.toHaveProperty("details");
+    expect(JSON.stringify(quiet(err))).not.toContain("10.0.0.4");
+  });
+
+  it("keeps a 5xx's details by default, because they name which dependency is down", () => {
+    const err = appError("SERVICE_UNAVAILABLE", "Not ready", {
+      details: { pg: "down", redis: "ok" },
+    });
+    expect(errorResponse(err).body.error.details).toEqual({ pg: "down", redis: "ok" });
+  });
+
+  it("leaves a 4xx's details alone whatever the mask says", () => {
+    const quiet = createErrorResponse<Code>({
+      internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+      validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+      maskAll: true,
+      maskDetails: true,
+    });
+    const err = appError("NOT_FOUND", "No such plan", { details: { id: "pro" } });
+    expect(quiet(err).body.error.details).toEqual({ id: "pro" });
+    expect(quiet(err).body.error.message).toBe("No such plan");
+  });
+});
+
+describe("a throw nobody raised on purpose", () => {
+  it("answers a generic 500 and never repeats what it caught", () => {
+    const answer = errorResponse(new Error("ECONNREFUSED redis://10.0.0.4:6379"));
+    expect(answer.status).toBe(500);
+    expect(answer.kind).toBe("unexpected");
+    expect(answer.body.error.code).toBe("INTERNAL_ERROR");
+    expect(JSON.stringify(answer)).not.toContain("10.0.0.4");
+  });
+
+  it("does the same for a plain object a driver rejected with", () => {
+    const answer = errorResponse({ code: "PGRST205", message: 'Could not find table "app.jobs"' });
+    expect(answer.status).toBe(500);
+    expect(answer.kind).toBe("unexpected");
+    expect(JSON.stringify(answer)).not.toContain("app.jobs");
+  });
+
+  it("separates a 5xx we raised from one that escaped", () => {
+    expect(errorResponse(appError("INTERNAL_ERROR", "we broke it")).kind).toBe("server");
+    expect(errorResponse(new AppError(500, "INTERNAL_ERROR", "we broke it")).kind).toBe("server");
+    expect(errorResponse("a string nobody expected").kind).toBe("unexpected");
+  });
+});

package/src/responses.ts

@@ -0,0 +1,277 @@
+/**
+ * How a backend answers: the success envelope, and the one function that turns a thrown thing
+ * into an HTTP answer.
+ *
+ * Nothing here knows about a framework, and that is a measurement rather than a preference.
+ * Five backends put this logic inside one `app.onError`, and then **three of them re-derived
+ * the same two arms inside an MCP tool wrapper** so an agent would get a real refusal instead
+ * of "an unexpected error occurred". A fourth re-derived the error body inside a background
+ * worker's health handler and got it wrong, answering a caught Redis message on a 503 — the
+ * API next door masks exactly that. A `Context`-shaped function would serve one of those four
+ * callers. The framework adapter is eight lines and lives in `/hono`.
+ */
+import type { ApiError, ApiSuccess, PaginationMeta } from "@gusnips/http";
+import { AppError } from "./errors.ts";
+
+/** Every 2xx body is `{ data }`, or `{ data, meta }` where a route has counts to report. */
+export function ok<T, M = PaginationMeta>(data: T, meta?: M) {
+  const body: ApiSuccess<T, M> = meta === undefined ? { data } : { data, meta };
+  return { status: 200 as const, body };
+}
+
+export function created<T>(data: T) {
+  const body: ApiSuccess<T> = { data };
+  return { status: 201 as const, body };
+}
+
+/**
+ * `hasMore` is computed from the page that was actually returned, not from `limit`: a page cut
+ * short by a filter still has to answer the question honestly. Identical, to the field, in five
+ * donors.
+ */
+export function paginated<T>(rows: T[], meta: Omit<PaginationMeta, "hasMore">) {
+  const body: ApiSuccess<T[]> = {
+    data: rows,
+    meta: { ...meta, hasMore: meta.offset + rows.length < meta.total },
+  };
+  return { status: 200 as const, body };
+}
+
+export function noContent() {
+  return { status: 204 as const, body: null };
+}
+
+export interface ErrorAnswer<Code extends string = string> {
+  status: number;
+  body: ApiError<Code>;
+  /** `Retry-After` when the refusal states a wait; `WWW-Authenticate` on a 401. */
+  headers: Record<string, string>;
+  /**
+   * What kind of failure this was, which is the one thing a caller cannot work out from the
+   * status. A 500 raised on purpose and a `TypeError` that escaped are both 500s, and only the
+   * second one means nobody is watching a log for it — every donor fires its admin alert on
+   * exactly that branch.
+   */
+  kind: "client" | "server" | "unexpected";
+}
+
+/** The envelope a masked 5xx, an unexpected throw, or a refused body is answered with. */
+export interface CannedError<Code extends string, Key extends string> {
+  code: Code;
+  /** English, for logs, `curl` and agents. A client localizes from `messageKey`. */
+  message: string;
+  messageKey?: Key;
+}
+
+export interface ErrorResponseOptions<Code extends string, Key extends string> {
+  /** Answers a masked 5xx and anything that escaped. */
+  internal: CannedError<Code, Key>;
+  /** Answers a validation failure. */
+  validation: CannedError<Code, Key>;
+  /**
+   * The 5xx codes whose message is replaced. Defaults to `["INTERNAL_ERROR"]`, which is what
+   * four of the five newest donors do, and their reason is worth keeping: flattening a
+   * `GATEWAY_ERROR` or a `SERVICE_UNAVAILABLE` into a generic 500 "would take away the one
+   * thing that tells a developer whether to retry."
+   *
+   * **That default is safe because of your call sites, not because of this code.** It holds
+   * only while every non-masked 5xx is handed a message somebody wrote for the client. A repo
+   * whose repository layer interpolates the driver's error into the message it raises — one
+   * donor's does, deliberately, so that duplicate-key heuristics keep working — wants
+   * `maskAll` instead.
+   */
+  maskedCodes?: readonly Code[];
+  /** Replace every 5xx message, and let `expose` be what opts an authored sentence back in. */
+  maskAll?: boolean;
+  /**
+   * Drop `details` from a 5xx whose message you did NOT mask — a separate knob because it is a
+   * separate decision. The newest donors put a readiness report in a 503's details, naming
+   * which dependency is down so a deploy gate and a human at 3am can both read it; another
+   * donor's details are where caught error text is recorded, and must never go out. Both are
+   * right about their own repo, which is why this is not folded into the mask above. (A masked
+   * 5xx drops its details on its own: the body is built fresh from `internal`.)
+   *
+   * The sharpest reason to turn it on is a caught driver error handed straight to `details`.
+   * On a CHECK or NOT NULL violation Postgres writes the ENTIRE failing row into its `detail`
+   * field — `Failing row contains (someone@example.com, 4242…)`, every column, values
+   * included. Measured against a real server, not assumed.
+   */
+  maskDetails?: boolean;
+}
+
+/**
+ * `retryAfterSecs` also rides inside `details`, because that is where clients already look —
+ * an explicit `null` included, since "waiting cannot fix this" is an answer a client needs and
+ * the only alternative is the hand-written code list this replaces.
+ *
+ * Only an object `details` can carry it. Spreading an ARRAY — a list of validation issues —
+ * turns it into `{"0": …}` and breaks every client that parses it; spreading a STRING turns it
+ * into one key per character. Anything that is not a plain object is handed back untouched, and
+ * the header still tells that caller when to come back.
+ */
+function detailsWithRetry(err: AppError): unknown {
+  if (err.retryAfterSecs === undefined) return err.details;
+  const carries =
+    err.details === undefined ||
+    (typeof err.details === "object" && err.details !== null && !Array.isArray(err.details));
+  if (!carries) return err.details;
+  return { ...err.details, retryAfterSecs: err.retryAfterSecs };
+}
+
+/**
+ * The wire body for an error somebody raised on purpose.
+ *
+ * It is a function rather than a method on `AppError`, and that is a fix rather than a style
+ * choice — see the note on the class. It also keeps the envelope in one file with the mask,
+ * instead of in two.
+ */
+function appErrorBody<Code extends string>(err: AppError<Code>): ApiError<Code> {
+  const details = detailsWithRetry(err);
+  return {
+    error: {
+      code: err.code,
+      message: err.message,
+      ...(err.messageKey !== undefined && { messageKey: err.messageKey }),
+      ...(err.params !== undefined && { params: err.params }),
+      ...(details !== undefined && { details }),
+    },
+  };
+}
+
+function envelope<Code extends string, Key extends string>(
+  canned: CannedError<Code, Key>,
+  details?: unknown,
+): ApiError<Code> {
+  return {
+    error: {
+      code: canned.code,
+      message: canned.message,
+      ...(canned.messageKey !== undefined && { messageKey: canned.messageKey }),
+      ...(details !== undefined && { details }),
+    },
+  };
+}
+
+interface RawIssue {
+  path?: unknown;
+  code?: unknown;
+  maximum?: unknown;
+  minimum?: unknown;
+}
+
+/**
+ * Recognize a validation failure without importing the validator.
+ *
+ * `name === "ZodError"` plus an `issues` array holds for zod 3.25, 4.4 and 4.5 — measured, all
+ * three, because this package must not make an adopter's validator its own dependency. It also
+ * accepts an issue list that arrived some other way, which is what a second door (an MCP tool,
+ * a queue consumer) needs.
+ */
+function zodIssues(err: unknown): RawIssue[] | null {
+  if (typeof err !== "object" || err === null) return null;
+  const { name, issues } = err as { name?: unknown; issues?: unknown };
+  if (name !== "ZodError" || !Array.isArray(issues)) return null;
+  return issues as RawIssue[];
+}
+
+/**
+ * The field path, the rule it failed, and — for a range — the BOUND it failed against.
+ *
+ * Never the rejected value, and never the schema's internals. All six donors carry a version of
+ * that comment; what none of them carries is the proof, so here it is: handing the validator's
+ * issues straight to the client ships back the caller's own key names (`keys`), the enum's
+ * allowed values (`values`), the validator's English sentence and the expected type
+ * (`origin`) — four disclosures from one convenience, and two repos in the fleet do it today.
+ * An audit note written against an older validator looks for `received`, which the current one
+ * no longer emits; the projection is an allow-list precisely so a rename cannot reopen this.
+ *
+ * The bound is the exception, and it belongs to the caller: it is the published contract, and
+ * a `too_big` without it costs somebody a bisect to rediscover a number our own docs state.
+ */
+function safeIssues(issues: RawIssue[]): unknown[] {
+  return issues.map((issue) => ({
+    path: issue.path,
+    code: issue.code,
+    ...(typeof issue.maximum === "number" && { maximum: issue.maximum }),
+    ...(typeof issue.minimum === "number" && { minimum: issue.minimum }),
+  }));
+}
+
+/**
+ * `AppError` is generic over the product's own code union, and no runtime check can verify
+ * membership. The predicate asserts what `createAppError` guarantees: every `AppError` in this
+ * app was built from the map whose keys are `Code`.
+ */
+function isAppError<Code extends string>(err: unknown): err is AppError<Code> {
+  return err instanceof AppError;
+}
+
+const DEFAULT_MASKED = ["INTERNAL_ERROR"];
+
+/**
+ * Binds the mask policy and the two canned bodies, and returns the function that answers.
+ *
+ * Bound once, at the app's edge, because the alternative is what the reading found: four places
+ * in one fleet deciding the mask separately, and the one furthest from the API getting it
+ * wrong. Every other door — a tool wrapper, a worker's health port — imports the same bound
+ * function and cannot disagree with the API about what a refusal looks like.
+ *
+ * ```ts
+ * export const errorResponse = createErrorResponse<ErrorCode, MessageKey>({
+ *   internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+ *   validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+ * });
+ * ```
+ */
+export function createErrorResponse<Code extends string = string, Key extends string = string>(
+  opts: ErrorResponseOptions<Code, Key>,
+) {
+  const maskedCodes: readonly string[] = opts.maskedCodes ?? DEFAULT_MASKED;
+
+  return function errorResponse(err: unknown): ErrorAnswer<Code> {
+    const issues = zodIssues(err);
+    if (issues !== null) {
+      return {
+        status: 400,
+        body: envelope(opts.validation, safeIssues(issues)),
+        headers: {},
+        kind: "client",
+      };
+    }
+
+    if (isAppError<Code>(err)) {
+      const headers: Record<string, string> = {};
+      // The standard header, not just our envelope: every HTTP client, proxy and SDK already
+      // knows how to wait on `Retry-After`, and none of them knows `details.retryAfterSecs`.
+      // A number only — a refusal that waiting cannot fix says so in the body, because
+      // `Retry-After: null` is a header that states a wait and names no time.
+      if (typeof err.retryAfterSecs === "number") {
+        headers["Retry-After"] = String(err.retryAfterSecs);
+      }
+      // RFC 6750 §3: a 401 names the scheme it wants. Without it a 401 is a closed door with no
+      // handle — which is what an agent, with no human to ask, is left holding.
+      if (err.statusCode === 401) headers["WWW-Authenticate"] = "Bearer";
+
+      if (err.statusCode < 500)
+        return { status: err.statusCode, body: appErrorBody(err), headers, kind: "client" };
+
+      const hide = !err.expose && (opts.maskAll === true || maskedCodes.includes(err.code));
+      if (hide) {
+        // The message is replaced; the STATUS is not. A status is chosen by our own map and
+        // discloses nothing, while it is the only thing left telling a client whether waiting
+        // can help — collapsing a masked 502 into a 500 throws that away for no gain. One
+        // donor does collapse it, and never noticed because it masks only the code that is
+        // already a 500.
+        return { status: err.statusCode, body: envelope(opts.internal), headers, kind: "server" };
+      }
+      const body = appErrorBody(err);
+      if (opts.maskDetails === true) delete body.error.details;
+      return { status: err.statusCode, body, headers, kind: "server" };
+    }
+
+    // Nothing raised this on purpose, so nothing in it was written for a reader. Whatever it
+    // says stays in the log: a background worker in the fleet answers `toMessage(err)` on its
+    // health port today, which is a driver's sentence on the wire.
+    return { status: 500, body: envelope(opts.internal), headers: {}, kind: "unexpected" };
+  };
+}