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

JSON request bodies for issues are validated by one small schema helper #15099

Merged opened this

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

Merged

torque/forge:torque/15064-json-request-bodies-for-issues-are-valid → main 4 commits fork 3 threads · 3 unresolved

  • Merged. torque/15064-json-request-bodies-for-issues-are-valid was merged into main as 337e9c0.

Review

Sign in to review this change.
4 files changed +315 −2
src/actions/issues.ts +19 −2
@@ -93,11 +93,17 @@ import {
9393 /** A repo whose truth lives on an origin cannot take a local-only write. */
9494 export type MirrorError = "mirrored";
9595
96 /**
97 * A check the caller's schema runs once access, mirror and planner-pause have
98 * answered: a refusal is the error, so the order of answers never changes.
99 */
100 export type Refuse<E extends string> = () => E | undefined;
101
96102 export function openIssue(
97103 app: App,
98104 actor: User | undefined,
99105 repo: Repo,
100 input: { title: string; body?: string; sealed?: boolean },
106 input: { title: string; body?: string; sealed?: boolean; refuse?: Refuse<TitleError | "body_too_long"> },
101107 ): Result<
102108 Issue,
103109 "not_found" | "unauthorized" | "planner_paused" | "planner_ceiling" | TitleError | "body_too_long" | MirrorError
@@ -121,6 +127,8 @@ export function openIssue(
121127 !splitPending(app, repo)
122128 )
123129 return err("planner_ceiling");
130 const refused = input.refuse?.();
131 if (refused !== undefined) return err(refused);
124132 // Anyone who may open an issue may seal it: a reader reporting a hole
125133 // seals it too, and from then on only writers and the crew see it
126134 // (`core/sealed.ts`).
@@ -387,12 +395,15 @@ export function addComment(
387395 repo: Repo,
388396 issue: Issue,
389397 body: string,
398 refuse?: Refuse<BodyError>,
390399 ): Result<Comment, "not_found" | "unauthorized" | BodyError | MirrorError> {
391400 // The engine speaks on a pull only (`crew/approved_week.ts`), never on an issue.
392401 const user = isEngine(actor) && issue.kind === "pull" ? ok(actor!) : requireParticipant(app, actor, repo);
393402 if (!user.ok) return user;
394403 if (issue.repoId !== repo.id) return err("not_found");
395404 if (isMirror(app, repo)) return err("mirrored");
405 const refused = refuse?.();
406 if (refused !== undefined) return err(refused);
396407 const added = insertComment(app.db, {
397408 issueId: issue.id,
398409 authorId: user.value.id,
@@ -881,6 +892,7 @@ export async function openIssueThrough(
881892 body?: string;
882893 labels?: readonly string[];
883894 sealed?: boolean;
895 refuse?: Refuse<TitleError | "body_too_long">;
884896 },
885897 ): Promise<
886898 Result<
@@ -896,6 +908,8 @@ export async function openIssueThrough(
896908 // A mirror's issues are written on its origin, in the open: a sealed
897909 // report has no place there.
898910 if (input.sealed === true) return err("mirrored");
911 const refused = input.refuse?.();
912 if (refused !== undefined) return err(refused);
899913
900914 const title = input.title.trim();
901915 if (title === "") return err("empty_title");
@@ -928,6 +942,7 @@ export async function addCommentThrough(
928942 repo: Repo,
929943 issue: Issue,
930944 body: string,
945 refuse?: Refuse<BodyError>,
931946 ): Promise<
932947 Result<Comment, ThroughError<"not_found" | "unauthorized" | BodyError>>
933948 > {
@@ -937,7 +952,9 @@ export async function addCommentThrough(
937952 const through = writeThroughFor(app, user.value, repo);
938953 if (!through.ok) return through;
939954 if (through.value === undefined)
940 return addComment(app, actor, repo, issue, body);
955 return addComment(app, actor, repo, issue, body, refuse);
956 const refused = refuse?.();
957 if (refused !== undefined) return err(refused);
941958
942959 const trimmed = body.trim();
943960 if (trimmed === "") return err("empty_body");
src/http/api/issues.ts +20
@@ -36,7 +36,11 @@ import {
3636 getIssue,
3737 listComments,
3838 listIssues,
39 MAX_BODY,
40 MAX_TITLE,
41 type BodyError,
3942 type Issue,
43 type TitleError,
4044 } from "../../core/issues.ts";
4145 import { canRead, type Repo } from "../../core/repos.ts";
4246 import { pillarsOf, structuralIds } from "../../core/pillars.ts";
@@ -62,6 +66,7 @@ import {
6266 import type { Ctx, Handler } from "../context.ts";
6367 import { apiError, body, json, notFound, paged, requireScope, respondAccess, str } from "../respond.ts";
6468 import type { Router } from "../router.ts";
69 import { parse, string } from "../schema.ts";
6570
outdated

The doc comment for briefIssue (/** An issue for a listing...) is now stranded above the new NEW_ISSUE block, and briefIssue lost its doc. Put the new constants and invalidInput below briefIssue or restore the comment to it.

6671 /** An issue for a listing: what to pick from, without bodies. */
6772 function briefIssue(i: ReturnType<typeof withLabelsMany>[number]) {
@@ -82,6 +87,17 @@ function briefIssue(i: ReturnType<typeof withLabelsMany>[number]) {
8287 };
8388 }
8489
90 // The words a new issue and a new comment are checked against, with the codes
91 // clients already read (`core/issues.ts` holds the caps). Anything that is not
92 // a string reads as empty, as it always did.
93 const NEW_ISSUE = {
94 title: string({ max: MAX_TITLE, empty: "empty_title", long: "title_too_long", coerce: true }),
95 body: string({ max: MAX_BODY, long: "body_too_long", trim: false, coerce: true }),
96 };
97 const NEW_COMMENT = {
98 body: string({ max: MAX_BODY, empty: "empty_body", long: "body_too_long", coerce: true }),
99 };
100
85101 function loadIssue(ctx: Ctx): Found<{ issue: Issue }> {
86102 const found = loadConversation(ctx);
87103 if ("error" in found) return found;
@@ -215,9 +231,11 @@ export function issueRoutes(router: Router<Handler>): void {
215231 const repo = loadRepo(ctx);
216232 if (!repo) return notFound();
217233 const input = await body(ctx.request);
234 const got = parse(NEW_ISSUE, input);
218235 const created = await openIssueThrough(ctx.app, ctx.auth.user, repo, {
219236 title: str(input.title),
220237 body: str(input.body),
238 refuse: () => (got.ok ? undefined : (got.error as TitleError | "body_too_long")),
221239 ...(input.sealed === true ? { sealed: true } : {}),
222240 });
223241 if (!created.ok) return originAware(created.error);
@@ -591,12 +609,14 @@ export function issueRoutes(router: Router<Handler>): void {
591609 : { repo: issueFound.repo, thread: issueFound.issue };
592610 if ("error" in found) return found.error;
593611 const input = await body(ctx.request);
612 const got = parse(NEW_COMMENT, input);
594613 const added = await addCommentThrough(
595614 ctx.app,
596615 ctx.auth.user,
597616 found.repo,
598617 "thread" in found ? found.thread : found.pull,
599618 str(input.body),
619 () => (got.ok ? undefined : (got.error as BodyError)),
600620 );
601621 if (!added.ok) return originAware(added.error);
602622 return json(added.value, 201);
src/http/schema.ts added +83
@@ -0,0 +1,83 @@
1 /**
2 * Schema at the boundary: a request body is plain data, a shape is a record
3 * of small checks, and the answer is either the typed value or the first
4 * error, named by field. No dependency, no class, no throwing.
5 *
6 * const shape = { title: string({ max: 256, empty: "empty_title", long: "title_too_long" }) };
7 * const got = parse(shape, await body(request));
8 * if (!got.ok) return json({ error: got.error }, 422); // got.field names the field
9 *
10 * Fields are checked in the order the shape lists them; the first failure
11 * is the answer. Each check carries its own error code, so a route keeps
12 * the codes its clients already read.
13 */
14
15 export type Checked<T> = { ok: true; value: T } | { ok: false; error: string };
16 export type Check<T> = (value: unknown) => Checked<T>;
17
18 export type Shape = Record<string, Check<unknown>>;
19 export type Parsed<S extends Shape> = { [K in keyof S]: S[K] extends Check<infer T> ? T : never };
20 export type Outcome<S extends Shape> =
21 | { ok: true; value: Parsed<S> }
22 | { ok: false; field: string; error: string };
23
24 const good = <T>(value: T): Checked<T> => ({ ok: true, value });
25 const bad = (error: string): Checked<never> => ({ ok: false, error });
26
27 /**
28 * Text. `empty` is the code for nothing after trimming, `long` for more than
29 * `max` characters (counted after trimming when `trim` is on, the default).
30 * `coerce` reads anything that is not a string as "" — what a route that
31 * used to say `str(input.x)` did; without it, a non-string is `wrong`
32 * (or `empty` when no `wrong` is named).
33 */
34 export function string(opts: {
35 max: number;
36 empty?: string;
37 long: string;
38 wrong?: string;
39 trim?: boolean;
40 coerce?: boolean;
41 }): Check<string> {
42 return (v) => {
43 if (typeof v !== "string" && opts.coerce !== true) return bad(opts.wrong ?? opts.empty ?? opts.long);
44 const text = typeof v === "string" ? ((opts.trim ?? true) ? v.trim() : v) : "";
45 if (opts.empty !== undefined && text === "") return bad(opts.empty);
46 if (text.length > opts.max) return bad(opts.long);
47 return good(text);
48 };
49 }
50
51 /** A whole number within `min`..`max`, as a number or as digits in a string. */
52 export function int(opts: { min: number; max: number; error: string }): Check<number> {
53 return (v) => {
54 const n = typeof v === "string" && /^-?\d+$/.test(v.trim()) ? Number(v) : v;
55 if (typeof n !== "number" || !Number.isSafeInteger(n) || n < opts.min || n > opts.max)
56 return bad(opts.error);
57 return good(n);
58 };
59 }
60
61 /** One of a closed list of strings. */
62 export function oneOf<const T extends string>(values: readonly T[], error: string): Check<T> {
63 return (v) => (typeof v === "string" && (values as readonly string[]).includes(v) ? good(v as T) : bad(error));
64 }
65
66 /**
67 * A field that may be left out (undefined or null): `fallback` stands in. A value that is given
68 * must pass `check`.
69 */
70 export function optional<T, D = undefined>(check: Check<T>, fallback?: D): Check<T | D> {
71 return (v) => (v === undefined || v === null ? good(fallback as D) : check(v));
72 }
73
74 /** Run every check in the shape's order; the first failure is the answer. */
75 export function parse<S extends Shape>(shape: S, input: Record<string, unknown>): Outcome<S> {
76 const value: Record<string, unknown> = {};
77 for (const [field, check] of Object.entries(shape)) {
78 const got = check(input[field]);
79 if (!got.ok) return { ok: false, field, error: got.error };
80 value[field] = got.value;
81 }
82 return { ok: true, value: value as Parsed<S> };
83 }
test/schema.test.ts added +193
@@ -0,0 +1,193 @@
1 /**
2 * The schema helper (`src/http/schema.ts`), each check on its own, and the
3 * issue create and comment routes' answers, unchanged by moving onto it.
4 */
5 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createRepo } from "../src/actions/repos.ts";
10 import { createApp, type App } from "../src/app.ts";
11 import { setPlannerSwitch } from "../src/actions/planner_switch.ts";
12 import { addCrew, createAgentRow } from "../src/core/agents.ts";
13 import { getRepo } from "../src/core/repos.ts";
14 import { createToken } from "../src/core/tokens.ts";
15 import { createUser, type User } from "../src/core/users.ts";
16 import { int, oneOf, optional, parse, string } from "../src/http/schema.ts";
17 import { serve, type Servers } from "../src/http/server.ts";
18 import { quietLogs } from "./helpers/globals.ts";
19
20 quietLogs();
21
22 describe("schema checks", () => {
23 const text = string({ max: 5, empty: "empty", long: "long" });
24
25 test("string trims, then refuses empty and too long, by its own codes", () => {
26 expect(text(" abc ")).toEqual({ ok: true, value: "abc" });
27 expect(text(" ")).toEqual({ ok: false, error: "empty" });
28 expect(text("abcdef")).toEqual({ ok: false, error: "long" });
29 expect(text(" abcde ")).toEqual({ ok: true, value: "abcde" });
30 });
31
32 test("a non-string is refused, or read as empty when coerced", () => {
33 expect(text(7)).toEqual({ ok: false, error: "empty" });
34 expect(string({ max: 5, long: "long", wrong: "wrong" })(7)).toEqual({ ok: false, error: "wrong" });
35 expect(string({ max: 5, long: "long", coerce: true })(7)).toEqual({ ok: true, value: "" });
36 expect(string({ max: 5, empty: "empty", long: "long", coerce: true })(null)).toEqual({ ok: false, error: "empty" });
37 });
38
39 test("string without trim measures what was sent", () => {
40 const raw = string({ max: 3, long: "long", trim: false });
41 expect(raw(" ab ")).toEqual({ ok: false, error: "long" });
42 expect(raw(" ")).toEqual({ ok: true, value: " " });
43 });
44
45 test("int takes whole numbers in range, as numbers or digit strings", () => {
46 const n = int({ min: 1, max: 10, error: "bad" });
47 expect(n(3)).toEqual({ ok: true, value: 3 });
48 expect(n(" 4 ")).toEqual({ ok: true, value: 4 });
49 for (const v of [0, 11, 1.5, "1.5", "x", NaN, null, undefined, {}]) expect(n(v)).toEqual({ ok: false, error: "bad" });
50 });
51
52 test("oneOf takes only the listed strings", () => {
53 const s = oneOf(["open", "closed"], "state");
54 expect(s("open")).toEqual({ ok: true, value: "open" });
55 expect(s("done")).toEqual({ ok: false, error: "state" });
56 expect(s(1)).toEqual({ ok: false, error: "state" });
57 });
58
59 test("optional lets a missing field through with its fallback, and checks one that is given", () => {
60 const n = optional(int({ min: 1, max: 9, error: "bad" }), 5);
61 expect(n(undefined)).toEqual({ ok: true, value: 5 });
62 expect(n(null)).toEqual({ ok: true, value: 5 });
63 expect(n(2)).toEqual({ ok: true, value: 2 });
64 expect(n(20)).toEqual({ ok: false, error: "bad" });
65 });
66
67 test("parse answers the first error, by field, in the shape's order", () => {
68 const shape = { a: text, b: int({ min: 1, max: 2, error: "b_bad" }), c: optional(text) };
69 expect(parse(shape, { a: "", b: 9 })).toEqual({ ok: false, field: "a", error: "empty" });
70 expect(parse(shape, { a: "x", b: 9 })).toEqual({ ok: false, field: "b", error: "b_bad" });
71 expect(parse(shape, { a: " x ", b: "2" })).toEqual({ ok: true, value: { a: "x", b: 2, c: undefined } });
72 });
73 });
74
75 describe("issue create and comment keep their answers", () => {
76 let dataDir = "";
77 let app: App;
78 let servers: Servers;
79 let alice: User;
80 let bob: User;
81 const call = (u: User | undefined, path: string, body: unknown, scope: "ro" | "rw" = "rw") =>
82 fetch(`${servers.url}/api/v1/repos/alice/garden${path}`, {
83 method: "POST",
84 headers: {
85 "content-type": "application/json",
86 ...(u ? { authorization: `Bearer ${createToken(app.db, u.id, "t", scope).token}` } : {}),
87 },
88 body: JSON.stringify(body),
89 });
90
91 beforeAll(async () => {
92 dataDir = await mkdtemp(join(tmpdir(), "forge-schema-"));
93 app = createApp({ dataDir, port: 0 });
94 servers = await serve(app);
95 for (const username of ["alice", "bob"]) {
96 const made = await createUser(app.db, {
97 origin: "seed",
98 trusted: true,
99 username,
100 email: `${username}@forge.local`,
101 password: "a-good-passphrase",
102 adminIfFirst: username === "alice",
103 });
104 if (!made.ok) throw new Error(made.error);
105 if (username === "alice") alice = made.value;
106 else bob = made.value;
107 }
108 const r = await createRepo(app, alice, { name: "garden", visibility: "private" });
109 if (!r.ok) throw new Error(String(r.error));
110 }, 30_000);
111
112 afterAll(async () => {
113 await servers.stop();
114 app.close();
115 await rm(dataDir, { recursive: true, force: true });
116 });
117
118 // The server adds a `hint` to every validation answer; the code and status are the contract here.
119 const refused = async (res: Response) => ({ status: res.status, body: { error: ((await res.json()) as { error: string }).error } });
120
121 test("a new issue: empty, wrong-typed and too-long titles answer as before", async () => {
122 for (const title of [undefined, "", " ", 42, null])
123 expect(await refused(await call(alice, "/issues", { title, body: "x" }))).toEqual({
124 status: 422,
125 body: { error: "empty_title" },
126 });
127 expect(await refused(await call(alice, "/issues", { title: "t".repeat(257) }))).toEqual({
128 status: 422,
129 body: { error: "title_too_long" },
130 });
131 expect(await refused(await call(alice, "/issues", { title: "t", body: "b".repeat(65_537) }))).toEqual({
132 status: 422,
133 body: { error: "body_too_long" },
134 });
135 });
136
137 test("a new issue that is whole is created, title trimmed, a non-string body read as empty", async () => {
138 const res = await call(alice, "/issues", { title: " A chart ", body: 5 });
139 expect(res.status).toBe(201);
140 const made = (await res.json()) as { title: string; body: string };
141 expect(made.title).toBe("A chart");
142 expect(made.body).toBe("");
143 });
144
145 test("a comment: empty and too-long answer as before; a whole one is created", async () => {
146 const issue = (await (await call(alice, "/issues", { title: "Talk" })).json()) as { number: number };
147 const path = `/issues/${issue.number}/comments`;
148 for (const body of [undefined, "", " ", 3])
149 expect(await refused(await call(alice, path, { body }))).toEqual({ status: 422, body: { error: "empty_body" } });
150 expect(await refused(await call(alice, path, { body: "b".repeat(65_537) }))).toEqual({
151 status: 422,
152 body: { error: "body_too_long" },
153 });
154 expect((await call(alice, path, { body: " hi " })).status).toBe(201);
155 });
156
157 test("someone who may not write is told so before any field error", async () => {
158 // bob cannot see alice's private repository: not found, not a 422.
159 expect((await call(bob, "/issues", { title: "" })).status).toBe(404);
160 expect((await call(undefined, "/issues", { title: "" })).status).toBe(401);
161 });
162
163 // The field check runs after access, mirror and planner-pause have answered, so a client reads
164 // the state of the repository before it reads a mistake in its form.
165 test("a paused planner and a mirror owned by someone else are told so before any field error", async () => {
166 const made = await createUser(app.db, { username: "plan", email: "[email protected]", agent: true, origin: "agent" });
167 if (!made.ok) throw new Error(String(made.error));
168 createAgentRow(app.db, { userId: made.value.id, roles: ["planner"] });
169 const garden = getRepo(app.db, "alice", "garden")!;
170 addCrew(app.db, garden.id, made.value.id, alice.id, "planner");
171 expect(setPlannerSwitch(app, alice, garden, { mode: "owner" }).ok).toBe(true);
172 expect(await refused(await call(made.value, "/issues", { title: "" }))).toEqual({
173 status: 409,
174 body: { error: "planner_paused" },
175 });
176
177 const mirror = await createRepo(app, alice, { name: "copy", visibility: "private" });
178 if (!mirror.ok) throw new Error(String(mirror.error));
179 const copy = getRepo(app.db, "alice", "copy")!;
180 // A mirror whose origin belongs to bob: alice is told the write is not hers before any field
181 // error.
182 app.db
183 .query("INSERT INTO origin (id, user_id, kind, api_url, web_url, login, token_enc) VALUES ('o1', ?1, 'github', 'https://api.github.com', 'https://github.com', 'octo', 'x')")
184 .run(bob.id);
185 app.db.query("UPDATE repo SET origin_id = 'o1', origin_full_name = 'octo/copy' WHERE id = ?1").run(copy.id);
186 const asked = await fetch(`${servers.url}/api/v1/repos/alice/copy/issues`, {
187 method: "POST",
188 headers: { "content-type": "application/json", authorization: `Bearer ${createToken(app.db, alice.id, "m", "rw").token}` },
189 body: JSON.stringify({ title: "" }),
190 });
191 expect(await refused(asked)).toEqual({ status: 403, body: { error: "origin_owner_only" } });
192 });
193 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs