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

An admin sends a webhook a test `ping` delivery through the API and MCP, and sees it among the deliveries #7943

Closed opened this
Closed without merging

mason/forge:mason/7872-an-admin-sends-a-webhook-a-test-ping-del → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +242 −7
docs/MCP.md +1 −1
@@ -96,7 +96,7 @@ for a tunnel and a forge that sleeps.
9696 | `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents | |
9797 | `here` | `{ url }`: on a forge page, what you may do there as who you are, each action with its route and tool; on the link of one of this forge's app hosts, what its `/__forge/` door shows: `{ app, repo, environment, pull: { number, title } or null, working: [names], links: { home, repo, report } }`; a foreign host, or a private app you may not enter, is refused like a missing page | |
9898 | `hold` | `{ app, pull | path, why?, until?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; or with `path` (no `pull`) hold new work on a file so the picker starts no build whose issue names it, or list the holds and who set each; an admin of the app; plans unless `dryRun: false` | yes |
99 | `hooks` | `{ repo, action, url, secret, kinds, id }`: `list` (pages: `limit` 1–200, `cursor`; `{ items, next_cursor }`), `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; `deliveries` with `id` answers that hook's last 20, newest first (`{ items: [{ id, state, attempts, lastStatus, lastError, kind }] }`); an admin-scope token on a repository you administer, and a secret is never shown | yes |
99 | `hooks` | `{ repo, action, url, secret, kinds, id }`: `list` (pages: `limit` 1–200, `cursor`; `{ items, next_cursor }`), `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; `deliveries` with `id` answers that hook's last 20, newest first (`{ items: [{ id, state, attempts, lastStatus, lastError, kind }] }`); `ping` with `id` queues one `ping` delivery (`{ id }`), at most 3 a minute per hook; an admin-scope token on a repository you administer, and a secret is never shown | yes |
100100 | `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes |
101101 | `issue` | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, the newest 50 comments (author, authorIsAgent, body, at), `commentsTotal` and `commentsNext` (older ones: `GET …/comments?cursor=`), and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found; draws the `ui://forge/issue` card: title, state, assignee, labels and what it waits for, never the body or comments | |
102102 | `issue_teams` | `{ repo, number, teams? }`: the crew teams an issue names; with `teams` (at most two slugs, `[]` clears) names them, and each reviews the closing pull | yes |
src/contract/openapi/routes/index.ts +1
@@ -224,6 +224,7 @@ export { route as postApiV1ReposOwnerNameFollowingSever } from "./postApiV1Repos
224224 export { route as postApiV1ReposOwnerNameFollowingTake } from "./postApiV1ReposOwnerNameFollowingTake.ts";
225225 export { route as postApiV1ReposOwnerNameForks } from "./postApiV1ReposOwnerNameForks.ts";
226226 export { route as postApiV1ReposOwnerNameHooks } from "./postApiV1ReposOwnerNameHooks.ts";
227 export { route as postApiV1ReposOwnerNameHooksIdPing } from "./postApiV1ReposOwnerNameHooksIdPing.ts";
227228 export { route as postApiV1ReposOwnerNameIssues } from "./postApiV1ReposOwnerNameIssues.ts";
228229 export { route as postApiV1ReposOwnerNameIssuesNumberComments } from "./postApiV1ReposOwnerNameIssuesNumberComments.ts";
229230 export { route as postApiV1ReposOwnerNameIssuesNumberDependencies } from "./postApiV1ReposOwnerNameIssuesNumberDependencies.ts";
src/contract/openapi/routes/postApiV1ReposOwnerNameHooksIdPing.ts added +9
@@ -0,0 +1,9 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: `${REPO}/hooks/{id}/ping`,
6 summary:
7 "Queue one signed `ping` delivery { kind, repo, hook, at } to this webhook only (admin scope); answers 202 { id } of the delivery, 429 past 3 a minute per hook",
8 auth: true,
9 };
src/core/webhooks.ts +51 −1
@@ -170,6 +170,55 @@ export function enqueueForEvent(db: Database, event: ForgeEvent): number {
170170 return queued;
171171 }
172172
173 /** Pings one hook may be sent in a minute. */
174 export const PING_LIMIT = 3;
175 const PING_WINDOW_MS = 60_000;
176
177 /**
178 * Queue one `ping` delivery for one hook, whatever kinds it subscribes to.
179 * The event row is written directly, not through the bus, so no other hook
180 * hears of it; the request is made later by `deliverDue`, which keeps the
181 * egress refusal. `retryAfter` is in seconds when the hook was pinged too
182 * often.
183 */
184 export function pingWebhook(
185 db: Database,
186 repoSlug: string,
187 hook: Webhook,
188 now = new Date(),
189 ): Result<{ id: string }, { retryAfter: number }> {
190 const since = new Date(now.getTime() - PING_WINDOW_MS).toISOString();
191 const recent = db
192 .query<{ n: number; first: string | null }, [string, string]>(
193 `SELECT COUNT(*) AS n, MIN(e.created_at) AS first
194 FROM webhook_delivery d JOIN event e ON e.id = d.event_id
195 WHERE d.webhook_id = ?1 AND e.kind = 'ping' AND e.created_at > ?2`,
196 )
197 .get(hook.id, since)!;
198 if (recent.n >= PING_LIMIT) {
199 const first = recent.first ? Date.parse(recent.first) : now.getTime();
200 const wait = Math.ceil((first + PING_WINDOW_MS - now.getTime()) / 1000);
201 return err({ retryAfter: Math.max(1, wait) });
202 }
203 const at = now.toISOString();
204 const eventId = id();
205 const deliveryId = id();
206 db.transaction(() => {
207 db.query(
208 "INSERT INTO event (id, kind, repo_id, actor_id, payload, created_at) VALUES (?1, 'ping', ?2, NULL, ?3, ?4)",
209 ).run(
210 eventId,
211 hook.repoId,
212 JSON.stringify({ kind: "ping", repo: repoSlug, hook: hook.id, at }),
213 at,
214 );
215 db.query(
216 "INSERT INTO webhook_delivery (id, webhook_id, event_id) VALUES (?1, ?2, ?3)",
217 ).run(deliveryId, hook.id, eventId);
218 })();
219 return ok({ id: deliveryId });
220 }
221
173222 // ---- the worker ----
174223
175224 interface DueRow {
@@ -261,7 +310,8 @@ async function deliverOne(
261310 now: Date,
262311 outbound: OutboundOptions,
263312 ): Promise<void> {
264 const body = JSON.stringify({
313 // A ping's body is its payload as it stands: { kind, repo, hook, at }.
314 const body = row.kind === "ping" ? row.payload : JSON.stringify({
265315 id: row.event_id,
266316 kind: row.kind,
267317 repo_id: row.repo_id,
src/http/api/hooks.ts +18 −1
@@ -9,7 +9,7 @@
99 import { createWebhook, deleteWebhook } from "../../actions/repos.ts";
1010 import { canAdmin } from "../../core/repos.ts";
1111 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
12 import { getWebhook, listWebhooks, recentDeliveries } from "../../core/webhooks.ts";
12 import { getWebhook, listWebhooks, pingWebhook, recentDeliveries } from "../../core/webhooks.ts";
1313 import { loadRepo, pageOf, pageParams } from "../api.ts";
1414 import type { Handler } from "../context.ts";
1515 import { body, json, notFound, requireScope, respondAccess, str } from "../respond.ts";
@@ -38,6 +38,23 @@ export function hookRoutes(router: Router<Handler>): void {
3838 return json({ items: recentDeliveries(ctx.app.db, ctx.params.id!, 20) });
3939 });
4040
41 router.add("POST", "/api/v1/repos/:owner/:name/hooks/:id/ping", (ctx) => {
42 const denied = requireScope(ctx, "admin");
43 if (denied) return denied.status === 403 ? notFound() : denied;
44 const repo = loadRepo(ctx);
45 if (!repo || !canAdmin(ctx.app.db, repo, ctx.auth.user)) return notFound();
46 const hook = getWebhook(ctx.app.db, repo.id, ctx.params.id!);
47 if (!hook) return notFound();
48 const pinged = pingWebhook(ctx.app.db, `${ctx.params.owner}/${ctx.params.name}`, hook);
49 if (!pinged.ok)
50 return json(
51 { error: "rate_limited", message: `too many pings: try again in ${pinged.error.retryAfter} s` },
52 429,
53 { "retry-after": String(pinged.error.retryAfter) },
54 );
55 return json({ id: pinged.value.id }, 202);
56 });
57
4158 router.add("POST", "/api/v1/repos/:owner/:name/hooks", async (ctx) => {
4259 const denied = requireScope(ctx, "admin");
4360 if (denied) return denied;
src/http/mcp/tools/hooks.ts +13 −4
@@ -1,5 +1,5 @@
11 import { canAdmin } from "../../../core/repos.ts";
2 import { getWebhook, listWebhooks, recentDeliveries } from "../../../core/webhooks.ts";
2 import { getWebhook, listWebhooks, pingWebhook, recentDeliveries } from "../../../core/webhooks.ts";
33 import { createWebhook, deleteWebhook } from "../../../actions/repos.ts";
44 import { pageRows } from "../page.ts";
55 import { good, bad, type Answer, type Args, type Tool, REPO_ARG, repoArg, isAnswer, str } from "../shared.ts";
@@ -20,13 +20,13 @@ const notAdmin = (): Answer => bad("not_found", "no such app or repository, or y
2020
2121 export const tool: Tool = {
2222 name: "hooks",
23 doc: "`{ repo, action, url, secret, kinds, id }`: `list` (pages: `limit` 1–200, `cursor`; `{ items, next_cursor }`), `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; `deliveries` with `id` answers that hook's last 20, newest first (`{ items: [{ id, state, attempts, lastStatus, lastError, kind }] }`); an admin-scope token on a repository you administer, and a secret is never shown",
23 doc: "`{ repo, action, url, secret, kinds, id }`: `list` (pages: `limit` 1–200, `cursor`; `{ items, next_cursor }`), `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; `deliveries` with `id` answers that hook's last 20, newest first (`{ items: [{ id, state, attempts, lastStatus, lastError, kind }] }`); `ping` with `id` queues one `ping` delivery (`{ id }`), at most 3 a minute per hook; an admin-scope token on a repository you administer, and a secret is never shown",
2424 description: "List, add (`url`, `secret`, `kinds`) or remove (`id`) webhooks; admins.",
2525 inputSchema: {
2626 type: "object",
2727 properties: {
2828 repo: REPO_ARG,
29 action: { type: "string", enum: ["list", "add", "remove", "deliveries"] },
29 action: { type: "string", enum: ["list", "add", "remove", "deliveries", "ping"] },
3030 url: { type: "string", maxLength: 2048 },
3131 kinds: { type: "string", maxLength: 200 },
3232 secret: { type: "string", maxLength: 200 },
@@ -54,6 +54,15 @@ export const tool: Tool = {
5454 if (hook === undefined) return bad("not_found", "no such webhook here");
5555 return good({ items: recentDeliveries(ctx.app.db, hook.id, 20) });
5656 }
57 if (action === "ping") {
58 const long = hookTooLong(args);
59 if (long !== undefined) return long;
60 if (!canAdmin(ctx.app.db, repo, user)) return notAdmin();
61 const hook = getWebhook(ctx.app.db, repo.id, str(args["id"]));
62 if (hook === undefined) return bad("not_found", "no such webhook here");
63 const pinged = pingWebhook(ctx.app.db, `${repo.ownerName}/${repo.name}`, hook);
64 return pinged.ok ? good({ id: pinged.value.id }) : bad("rate_limited", `too many pings: try again in ${pinged.error.retryAfter} s`);
65 }
5766 if (action === "add") {
5867 const long = hookTooLong(args);
5968 if (long !== undefined) return long;
@@ -78,6 +87,6 @@ export const tool: Tool = {
7887 const removed = deleteWebhook(ctx.app, user, repo, str(args["id"]));
7988 return removed.ok ? good({}) : bad("not_found", "no such webhook here");
8089 }
81 return bad("invalid", "action is list, add, remove or deliveries");
90 return bad("invalid", "action is list, add, remove, deliveries or ping");
8291 },
8392 };
test/hook-ping.test.ts added +149
@@ -0,0 +1,149 @@
1 /** POST …/hooks/:id/ping and MCP `hooks` action `ping` (#7872). */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { createRepo } from "../src/actions/repos.ts";
8 import { createToken } from "../src/core/tokens.ts";
9 import { createUser } from "../src/core/users.ts";
10 import { createWebhook, deliverDue, recentDeliveries, verifySignature } from "../src/core/webhooks.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { LOOPBACK } from "./helpers/loopback-hook.ts";
13 import { quietLogs } from "./helpers/globals.ts";
14
15 quietLogs();
16
17 let dataDir: string;
18 let app: App;
19 let servers: Servers;
20 let adminTok = "";
21 let otherTok = "";
22 let hookA = "";
23 let hookB = "";
24 let secretA = "";
25 let received: { body: string; sig: string; kind: string }[] = [];
26 let receiver: ReturnType<typeof Bun.serve>;
27 const cells = process.env["FORGE_CELLS"];
28
29 beforeAll(async () => {
30 process.env["FORGE_CELLS"] = "off";
31 receiver = Bun.serve({
32 port: 0,
33 hostname: "127.0.0.1",
34 async fetch(req) {
35 received.push({
36 body: await req.text(),
37 sig: req.headers.get("x-forge-signature-256") ?? "",
38 kind: req.headers.get("x-forge-event") ?? "",
39 });
40 return new Response("ok");
41 },
42 });
43 dataDir = await mkdtemp(join(tmpdir(), "forge-hook-ping-"));
44 app = createApp({ dataDir, port: 0 });
45 servers = await serve(app);
46 const mk = async (username: string, first: boolean) => {
47 const made = await createUser(app.db, {
48 origin: "seed",
49 trusted: true,
50 username,
51 email: `${username}@forge.local`,
52 password: "a-good-passphrase",
53 adminIfFirst: first,
54 });
55 if (!made.ok) throw new Error(String(made.error));
56 return made.value;
57 };
58 const alice = await mk("alice", true);
59 const bob = await mk("bob", false);
60 const ra = await createRepo(app, alice, { name: "a", visibility: "public" });
61 if (!ra.ok) throw new Error("repo");
62 // Subscribes to issues only: a ping must reach it anyway. The other hook hears nothing.
63 const a = createWebhook(app.db, { repoId: ra.value.id, url: "https://a.example/h", kinds: "issue.opened" });
64 const b = createWebhook(app.db, { repoId: ra.value.id, url: "https://b.example/h" });
65 if (!a.ok || !b.ok) throw new Error("hook");
66 hookA = a.value.webhook.id;
67 hookB = b.value.webhook.id;
68 secretA = a.value.secret;
69 adminTok = createToken(app.db, alice.id, "t", "admin").token;
70 otherTok = createToken(app.db, bob.id, "o", "admin").token;
71 });
72 afterAll(async () => {
73 receiver.stop(true);
74 await servers.stop();
75 app.close();
76 if (cells === undefined) delete process.env["FORGE_CELLS"];
77 else process.env["FORGE_CELLS"] = cells;
78 await rm(dataDir, { recursive: true, force: true });
79 });
80
81 const ping = (hook: string, tok: string) =>
82 fetch(`${servers.url}/api/v1/repos/alice/a/hooks/${hook}/ping`, { method: "POST", headers: { authorization: `Bearer ${tok}` } });
83 const mcp = async (args: unknown) => {
84 const res = await fetch(`${servers.url}/mcp`, {
85 method: "POST",
86 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${adminTok}` },
87 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "hooks", arguments: args } }),
88 });
89 const body = (await res.json()) as any;
90 const text: string = body.result.content[0].text;
91 return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
92 };
93 const resetWindow = () => app.db.run("UPDATE event SET created_at = '2020-01-01T00:00:00.000Z' WHERE kind = 'ping'");
94
95 test("a ping answers 202, shows among the deliveries and reaches only that hook", async () => {
96 const res = await ping(hookA, adminTok);
97 expect(res.status).toBe(202);
98 const { id } = (await res.json()) as { id: string };
99 const api = await fetch(`${servers.url}/api/v1/repos/alice/a/hooks/${hookA}/deliveries`, { headers: { authorization: `Bearer ${adminTok}` } });
100 const items = ((await api.json()) as any).items;
101 expect(items[0]).toMatchObject({ id, kind: "ping", state: "pending" });
102 const viaMcp = await mcp({ repo: "alice/a", action: "deliveries", id: hookA });
103 expect(viaMcp.value.items[0]).toMatchObject({ id, kind: "ping" });
104 expect(recentDeliveries(app.db, hookB)).toHaveLength(0);
105 });
106
107 test("the ping is signed and goes through deliverDue, body { kind, repo, hook, at }", async () => {
108 received = [];
109 app.db.run("UPDATE webhook SET url = ?2 WHERE id = ?1", [hookA, `http://127.0.0.1:${receiver.port}/h`]);
110 await deliverDue(app.db, app.log, new Date(), LOOPBACK);
111 expect(received).toHaveLength(1);
112 const hit = received[0]!;
113 expect(hit.kind).toBe("ping");
114 const body = JSON.parse(hit.body);
115 expect(Object.keys(body).sort()).toEqual(["at", "hook", "kind", "repo"]);
116 expect(body).toMatchObject({ kind: "ping", repo: "alice/a", hook: hookA });
117 expect(await verifySignature(secretA, hit.body, hit.sig)).toBe(true);
118 });
119
120 test("a private address is refused as a failed delivery with its reason, never fetched inline", async () => {
121 resetWindow();
122 const res = await ping(hookB, adminTok);
123 expect(res.status).toBe(202);
124 expect(recentDeliveries(app.db, hookB)[0]).toMatchObject({ kind: "ping", state: "pending", attempts: 0 });
125 app.db.run("UPDATE webhook SET url = 'https://127.0.0.1/h' WHERE id = ?1", [hookB]);
126 await deliverDue(app.db, app.log);
127 expect(recentDeliveries(app.db, hookB)[0]).toMatchObject({ kind: "ping", state: "failed" });
128 expect(recentDeliveries(app.db, hookB)[0]!.lastError).toBeTruthy();
129 });
130
131 test("a non-admin, a missing hook and no credentials are refused", async () => {
132 expect((await ping(hookA, otherTok)).status).toBe(404);
133 expect((await ping("nope", adminTok)).status).toBe(404);
134 const anon = await fetch(`${servers.url}/api/v1/repos/alice/a/hooks/${hookA}/ping`, { method: "POST" });
135 expect(anon.status).toBe(401);
136 });
137
138 test("past three a minute it is 429 with retry-after, over the API and MCP", async () => {
139 resetWindow();
140 for (let i = 0; i < 3; i++) expect((await ping(hookA, adminTok)).status).toBe(202);
141 const over = await ping(hookA, adminTok);
142 expect(over.status).toBe(429);
143 expect(Number(over.headers.get("retry-after"))).toBeGreaterThan(0);
144 const m = await mcp({ repo: "alice/a", action: "ping", id: hookA });
145 expect(m.error).toContain("too many pings");
146 resetWindow();
147 const ok = await mcp({ repo: "alice/a", action: "ping", id: hookA });
148 expect(typeof ok.value.id).toBe("string");
149 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs