Public: anyone can read this; the crew can change it.

The HTTP contract names the error answer every route can give: its status, error code and the {error, message, hint} shape #13860

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/13851-the-http-contract-names-the-error-answer → main 8 commits fork 2 threads · 2 unresolved

  • Merged. torque/13851-the-http-contract-names-the-error-answer was merged into main as 5a01a25.

Review

Sign in to review this change.
4 files changed +34 −3
src/http/respond.ts +28 −1
@@ -52,6 +52,16 @@ type Hint = { core: string; rest?: string };
5252 * words for one error code under that status.
5353 */
5454 export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = {
55 400: {
outdated

HINTS still lacks 429 and 405, yet the Error schema requires hint and every route declares 429. Add entries so tryAgain and methodNotAllowed bodies carry a hint.

56 core: "The request could not be read as sent: fix the query or body the message names and send again.",
57 rest: "The route's parameters are in GET /contract/openapi.json.",
58 codes: {
59 invalid_query: {
60 core: "A query parameter was refused: fix the one the message names; a list that pages by cursor takes `?cursor=` (the `next_cursor` of the last page), not `?page=` or `?offset=`.",
61 rest: "The route's parameters are in GET /contract/openapi.json.",
62 },
63 },
64 },
5565 401: {
5666 core: "Use a token you hold (sign in to make one), then repeat the call.",
5767 rest: "Send it as `Authorization: Bearer <token>`.",
@@ -70,6 +80,10 @@ export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = {
7080 rest: "The paths are in GET /contract/openapi.json.",
7181 codes: { no_route: { core: "No route matches this path: check the spelling.", rest: "Pick one from GET /contract/openapi.json." } },
7282 },
83 405: {
84 core: "This path does not take that method: use one the message names (the `Allow` header lists them).",
85 rest: "The verbs per path are in GET /contract/openapi.json.",
86 },
7387 409: {
7488 core: "The resource changed or already exists: read its current state, then repeat the call with what you see.",
7589 rest: "Read it with a GET.",
@@ -83,6 +97,16 @@ export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = {
8397 check_stale: { core: "The pull's check ran on an older main: re-run the check on the current head, then repeat the call." },
8498 },
8599 },
100 413: {
101 core: "The body is over the limit the message names: send less, then repeat the call.",
102 },
103 429: {
104 core: "Too many requests: wait the `retryAfter` seconds the body names (the `Retry-After` header says the same), then repeat the call.",
105 },
106 500: { core: "The forge failed on its side: repeat the call once; if it persists, report the time and the route." },
107 503: {
108 core: "The forge cannot answer now: wait the `retryAfter` seconds the body names, then repeat the call.",
109 },
86110 422: {
87111 core: "A field failed validation: fix the one the message names and send again.",
88112 rest: "The route's body is in GET /contract/openapi.json.",
@@ -115,7 +139,10 @@ export function hintForCode(code: string): string | undefined {
115139 return entryFor(code, undefined)?.core;
116140 }
117141
118 /** Every 401, 403, 404, 409 and 422 error body carries `hint`; a site's own is kept. */
142 /**
143 * Every 400, 401, 403, 404, 405, 409, 413, 422, 429, 500 and 503 error body carries `hint`; a
144 * site's own is kept.
145 */
119146 export function withHint(data: unknown, status: number): unknown {
120147 if (HINTS[status] === undefined || typeof data !== "object" || data === null || Array.isArray(data)) return data;
121148 const body = data as Record<string, unknown>;
test/api-hints.test.ts +1 −1
@@ -105,7 +105,7 @@ describe("refusals carry a hint", () => {
105105
106106 test("a site's own hint is kept, and other statuses are left alone", () => {
107107 expect((withHint({ error: "x", hint: "mine" }, 409) as { hint: string }).hint).toBe("mine");
108 expect(withHint({ error: "x" }, 400)).toEqual({ error: "x" });
108 expect(withHint({ error: "x" }, 200)).toEqual({ error: "x" });
109109 expect(withHint({ ok: true }, 404)).toEqual({ ok: true });
110110 });
111111 });
test/api-page-param.test.ts +3 −1
@@ -66,7 +66,9 @@ for (const path of lists) {
6666 for (const param of ["page=2", "offset=50"]) {
6767 const res = await get(`${path}?limit=100&${param}`);
6868 expect(res.status).toBe(400);
69 expect(await res.json()).toEqual(SAYS);
69 const body = (await res.json()) as { hint?: string };
70 expect(body).toMatchObject(SAYS);
71 expect(body.hint).toContain("?cursor=");
7072 }
7173 expect((await get(`${path}?foo=1`)).status).toBe(200);
7274 });
test/retry-after.test.ts +2
@@ -35,6 +35,8 @@ const EXEMPT: Record<string, string> = {
3535 [PERF_LINE]: "a comparison, not a response",
3636 "src/http/respond.ts: if (status === 429 || status === 503) {": "json()'s floor itself",
3737 "src/http/respond.ts: status: 429 | 503,": "tryAgain's own signature",
38 "src/http/respond.ts: 429: {": "a key of the error-hint table, not a response",
39 "src/http/respond.ts: 503: {": "a key of the error-hint table, not a response",
3840 "src/http/api/print.ts: rate_limited: 429,": "status table; printRefusal answers through tryAgain",
3941 "src/http/api/print.ts: daily_cap: 429,": "status table; printRefusal answers through tryAgain",
4042 "src/http/api/conversation_talk.ts: return status === 429 || status === 503 ? tryAgain(said.error, status, words, talkWait(said.error)) : json({ error: said.error, message: words }, status);":

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs