src/server/http.ts

Functions

Imports

It imports src/adapter.ts, src/contract.ts. Imported by src/server.ts, src/server/content.ts, src/server/media.ts, src/server/mentions.ts.

Source

1// What every route shares: the JSON answers, the body and query readers, the check on what an adapter
2// answers, and the contract's name and words for a failure.
3
4import type { z } from "zod";
5import { MediaInUseError, NotFoundError, RefusedError, VersionConflictError } from "../adapter.js";
6import type { ErrorBody, ErrorCode, MediaUse } from "../contract.js";
7import { readCapped } from "@dustinedwards/site-runtime/body";
8
9/** Four million bytes: two million characters of source can take that much as UTF-8 JSON. */
10const MAX_BODY_BYTES = 4_000_000;
11
12const STATUS: Record<ErrorCode, number> = {
13  unauthorized: 401,
14  "rate-limited": 429,
15  "not-configured": 503,
16  unavailable: 503,
17  "not-found": 404,
18  "method-not-allowed": 405,
19  invalid: 400,
20  "too-large": 413,
21  "version-conflict": 409,
22  refused: 422,
23  "not-implemented": 501,
24  internal: 500,
25};
26
27export const BASE_HEADERS = {
28  "cache-control": "no-store",
29  "x-content-type-options": "nosniff",
30};
31
32export function json(status: number, body: unknown): Response {
33  return new Response(JSON.stringify(body), {
34    status,
35    headers: { ...BASE_HEADERS, "content-type": "application/json; charset=utf-8" },
36  });
37}
38
39export function fail(code: ErrorCode, message: string, extra: Partial<ErrorBody> = {}): Response {
40  return json(STATUS[code], { error: code, message, ...extra });
41}
42
43export class BadRequest extends Error {
44  constructor(readonly code: ErrorCode, message: string) {
45    super(message);
46  }
47}
48
49export async function readBody<T extends z.ZodType>(request: Request, schema: T): Promise<z.infer<T>> {
50  const declared = Number(request.headers.get("content-length") ?? "0");
51  if (declared > MAX_BODY_BYTES) throw new BadRequest("too-large", "The body is too large.");
52  // Counted as it arrives (site-runtime's one reader), so an understated or missing Content-Length cannot make the
53  // Worker hold more than the limit; request.text() read the whole body first.
54  const text = await readCapped(request, MAX_BODY_BYTES);
55  if (text === null) throw new BadRequest("too-large", "The body is too large.");
56  let raw: unknown;
57  try {
58    raw = JSON.parse(text);
59  } catch {
60    throw new BadRequest("invalid", "The body is not JSON.");
61  }
62  const parsed = schema.safeParse(raw);
63  if (!parsed.success) throw new BadRequest("invalid", describe(parsed.error));
64  return parsed.data;
65}
66
67export function readQuery<T extends z.ZodType>(url: URL, schema: T): z.infer<T> {
68  const parsed = schema.safeParse(Object.fromEntries(url.searchParams));
69  if (!parsed.success) throw new BadRequest("invalid", describe(parsed.error));
70  return parsed.data;
71}
72
73function describe(error: z.ZodError): string {
74  return error.issues
75    .slice(0, 5)
76    .map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`)
77    .join("; ");
78}
79
80/** An adapter that answers outside the contract is a site bug, reported as one and never passed on. */
81export class ContractBreach extends Error {}
82
83export function checked<T extends z.ZodType>(schema: T, value: unknown, what: string): z.infer<T> {
84  const parsed = schema.safeParse(value);
85  if (!parsed.success) throw new ContractBreach(`${what}: ${describe(parsed.error)}`);
86  return parsed.data;
87}
88
89export type Route = { method: string; pattern: RegExp; run: (m: RegExpMatchArray, url: URL, request: Request) => Promise<Response> };
90
91export const ID = "([^/]+)";
92
93/** A path segment decoded and checked against its shape; what is refused names the thing it should have been. */
94export function pathParam(raw: string | undefined, shape: z.ZodType, what: string): string {
95  let value: string;
96  try {
97    value = decodeURIComponent(raw!);
98  } catch {
99    throw new BadRequest("invalid", `The ${what} is not valid.`);
100  }
101  if (!shape.safeParse(value).success) throw new BadRequest("invalid", `The ${what} is not valid.`);
102  return value;
103}
104
105export type Log = (entry: Record<string, unknown>) => void;
106
107export interface Failure {
108  code: ErrorCode;
109  message: string;
110  currentVersion?: string | null;
111  usedBy?: MediaUse[];
112}
113
114/** The contract's name and words for a failure, for the single routes and for one file of a bulk. */
115export function describeFailure(error: unknown, log: Log): Failure {
116  if (error instanceof BadRequest) return { code: error.code, message: error.message };
117  if (error instanceof VersionConflictError) return { code: "version-conflict", message: error.message, currentVersion: error.currentVersion };
118  if (error instanceof NotFoundError) return { code: "not-found", message: error.message };
119  if (error instanceof MediaInUseError) return { code: "refused", message: error.message, usedBy: error.usedBy };
120  if (error instanceof RefusedError) return { code: "refused", message: error.message };
121  if (error instanceof ContractBreach) {
122    log({ siteApi: "contract-breach", detail: error.message });
123    return { code: "internal", message: "The site answered outside the contract." };
124  }
125  log({ siteApi: "adapter-failed", error: error instanceof Error ? error.message : String(error) });
126  return { code: "internal", message: "The site failed to answer." };
127}