908957e · 24b41bf · 7f7d30d · f5160fa · 399d11a · b292736
@@ -97,7 +97,7 @@
for a tunnel and a forge that sleeps.
| `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents |  |
| `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 |  |
| `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 |
| `hooks` | (admin scope) `{ 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 |
| `hooks` | (admin scope) `{ 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 |
| `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 |
| `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 |  |
| `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 |
@@ -0,0 +1,11 @@
# Send a webhook a test ping
A repository admin can check that a webhook's receiver answers without waiting for a real event: a `ping` is one signed delivery to that hook only, whatever kinds it follows.
- **Page.** Settings › Webhooks has a **Send ping** button on each hook, a same-origin POST to `/:owner/:name/settings/hooks/:id/ping`. The ping appears at once among that hook's deliveries; a refused one says how long to wait.
- **API.** `POST /api/v1/repos/:owner/:name/hooks/:id/ping` with an admin-scope token answers 202 `{ id }`. Below admin, or for a hook not in the repository, it is 404.
- **MCP.** `hooks` with `action: ping` and `id`, admin scope; it answers `{ id }`.
- **Terminal.** Open a hook's Deliveries screen and press `p`. The screen and the key are a repository admin's; the new row shows at the top as `ping · pending`.
- **Body.** `{ kind: "ping", repo, hook, at }`, signed with the hook's secret like any delivery. The worker sends it on its next pass, with the same egress refusal and retries; a paused hook holds it pending until it is resumed.
- **Rate limit.** At most 3 a minute per hook. Past that the API answers 429 with `retry-after`, MCP says the same, and the page and the terminal say how many seconds to wait.
- **Not an event.** The ping lives on its own delivery row (`webhook_ping`), never in the event log, so no feed, stream or other hook hears of it. A failed ping is not redelivered with `r`: send another.
@@ -242,6 +242,7 @@
export { route as postApiV1ReposOwnerNameFollowingSever } from "./postApiV1Repos
export { route as postApiV1ReposOwnerNameFollowingTake } from "./postApiV1ReposOwnerNameFollowingTake.ts";
export { route as postApiV1ReposOwnerNameForks } from "./postApiV1ReposOwnerNameForks.ts";
export { route as postApiV1ReposOwnerNameHooks } from "./postApiV1ReposOwnerNameHooks.ts";
export { route as postApiV1ReposOwnerNameHooksIdPing } from "./postApiV1ReposOwnerNameHooksIdPing.ts";
export { route as postApiV1ReposOwnerNameIssues } from "./postApiV1ReposOwnerNameIssues.ts";
export { route as postApiV1ReposOwnerNameIssuesNumberComments } from "./postApiV1ReposOwnerNameIssuesNumberComments.ts";
export { route as postApiV1ReposOwnerNameIssuesNumberDependencies } from "./postApiV1ReposOwnerNameIssuesNumberDependencies.ts";
@@ -0,0 +1,9 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: `${REPO}/hooks/{id}/ping`,
  summary:
    "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",
  auth: true,
};
@@ -0,0 +1,1 @@
9ec6439b3eb7d11764ea98a509a4978937e9c1f11ee06a53c0d943ec3dde3ca0
@@ -0,0 +1,19 @@
// A test `ping` belongs to its own row, not to the repository's event log
// (#8006). A delivery must name an event, and a roll keeps the old release
// reading `webhook_delivery`, so the ping gets a table of its own beside it
// rather than a rebuilt delivery table: nothing the old release reads changes.
export default `
  CREATE TABLE IF NOT EXISTS webhook_ping (
    id          TEXT PRIMARY KEY,
    webhook_id  TEXT NOT NULL REFERENCES webhook(id) ON DELETE CASCADE,
    state       TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending','ok','failed')),
    attempts    INTEGER NOT NULL DEFAULT 0,
    next_try_at TEXT,
    last_status INTEGER,
    last_error  TEXT,
    payload     TEXT NOT NULL,
    created_at  TEXT NOT NULL
  );
  CREATE INDEX IF NOT EXISTS ping_due ON webhook_ping(state, next_try_at);
  CREATE INDEX IF NOT EXISTS ping_hook ON webhook_ping(webhook_id, created_at);
  `;
@@ -187,6 +187,49 @@
export function enqueueForEvent(db: Database, event: ForgeEvent): number {
  return queued;
}
/** Pings one hook may be sent in a minute. */
export const PING_LIMIT = 3;
const PING_WINDOW_MS = 60_000;
/**
 * Queue one `ping` delivery for one hook, whatever kinds it subscribes to.
 * The payload lives on the delivery row, never in the event log, so no feed,
 * stream or other hook hears of it; the request is made later by `deliverDue`, which keeps the
 * egress refusal. `retryAfter` is in seconds when the hook was pinged too
 * often.
 */
export function pingWebhook(
  db: Database,
  repoSlug: string,
  hook: Webhook,
  now = new Date(),
): Result<{ id: string }, { retryAfter: number }> {
  const since = new Date(now.getTime() - PING_WINDOW_MS).toISOString();
  const recent = db
    .query<{ n: number; first: string | null }, [string, string]>(
      `SELECT COUNT(*) AS n, MIN(created_at) AS first
       FROM webhook_ping
       WHERE webhook_id = ?1 AND created_at > ?2`,
    )
    .get(hook.id, since)!;
  if (recent.n >= PING_LIMIT) {
    const first = recent.first ? Date.parse(recent.first) : now.getTime();
    const wait = Math.ceil((first + PING_WINDOW_MS - now.getTime()) / 1000);
    return err({ retryAfter: Math.max(1, wait) });
  }
  const at = now.toISOString();
  const deliveryId = id();
  db.query(
    "INSERT INTO webhook_ping (id, webhook_id, payload, created_at) VALUES (?1, ?2, ?3, ?4)",
  ).run(
    deliveryId,
    hook.id,
    JSON.stringify({ kind: "ping", repo: repoSlug, hook: hook.id, at }),
    at,
  );
  return ok({ id: deliveryId });
}
export type RedeliverError = "not_found" | "not_failed" | "sealed";
/**
@@ -244,7 +287,9 @@
function redeliverIn(db: Database, deliveryId: string, webhookId: string): Resul
interface DueRow {
  id: string;
  webhook_id: string;
  event_id: string;
  event_id: string | null;
  /** True when the row is in `webhook_ping`, not `webhook_delivery`. */
  ping: boolean;
  attempts: number;
  url: string;
  secret: string;
@@ -271,9 +316,9 @@
export async function deliverDue(
  outbound: OutboundOptions = {},
): Promise<number> {
  const nowIso = now.toISOString();
  const due = db
  const events = db
    .query<DueRow, [string]>(
      `SELECT d.id, d.webhook_id, d.event_id, d.attempts,
      `SELECT d.id, d.webhook_id, d.event_id, 0 AS ping, d.attempts,
              w.url, w.secret,
              e.kind, e.repo_id, e.actor_id, e.payload, e.created_at
       FROM webhook_delivery d
@@ -284,6 +329,20 @@
export async function deliverDue(
       ORDER BY d.id LIMIT 50`,
    )
    .all(nowIso);
  const pings = db
    .query<DueRow, [string]>(
      `SELECT d.id, d.webhook_id, NULL AS event_id, 1 AS ping, d.attempts,
              w.url, w.secret,
              'ping' AS kind, NULL AS repo_id, NULL AS actor_id,
              d.payload, d.created_at
       FROM webhook_ping d
       JOIN webhook w ON w.id = d.webhook_id
       WHERE d.state = 'pending' AND w.active = 1
         AND (d.next_try_at IS NULL OR d.next_try_at <= ?1)
       ORDER BY d.id LIMIT 50`,
    )
    .all(nowIso);
  const due = [...events, ...pings].map((r) => ({ ...r, ping: !!r.ping }));
  for (const row of due) {
    // Claimed before it is sent: two forge processes over one database (a
@@ -295,7 +354,7 @@
export async function deliverDue(
    const claimAt = Date.now();
    const claimed = db
      .query(
        `UPDATE webhook_delivery SET next_try_at = ?2
        `UPDATE ${tableOf(row)} SET next_try_at = ?2
          WHERE id = ?1 AND state = 'pending'
            AND (next_try_at IS NULL OR next_try_at <= ?3)`,
      )
@@ -324,6 +383,11 @@
export async function deliverDue(
  return due.length;
}
/** Where a due row lives: a ping has its own table, never the event log's. */
function tableOf(row: DueRow): "webhook_ping" | "webhook_delivery" {
  return row.ping ? "webhook_ping" : "webhook_delivery";
}
async function deliverOne(
  db: Database,
  log: Log,
@@ -331,14 +395,18 @@
async function deliverOne(
  now: Date,
  outbound: OutboundOptions,
): Promise<void> {
  const body = JSON.stringify({
    id: row.event_id,
    kind: row.kind,
    repo_id: row.repo_id,
    actor_id: row.actor_id,
    payload: JSON.parse(row.payload),
    created_at: row.created_at,
  });
  // A ping's body is its payload as it stands: { kind, repo, hook, at }.
  const body =
    row.ping
      ? row.payload
      : JSON.stringify({
          id: row.event_id,
          kind: row.kind,
          repo_id: row.repo_id,
          actor_id: row.actor_id,
          payload: JSON.parse(row.payload),
          created_at: row.created_at,
        });
  const signature = await sign(row.secret, body);
  const attempt = row.attempts + 1;
@@ -370,7 +438,7 @@
async function deliverOne(
      // seconds, so there is nothing to retry: fail it now, with the reason.
      log.warn("webhook delivery refused", { delivery: row.id });
      db.query(
        "UPDATE webhook_delivery SET state = 'failed', attempts = ?1, last_status = NULL, last_error = ?2 WHERE id = ?3",
        `UPDATE ${tableOf(row)} SET state = 'failed', attempts = ?1, last_status = NULL, last_error = ?2 WHERE id = ?3`,
      ).run(attempt, error.message, row.id);
      return;
    }
@@ -383,7 +451,7 @@
async function deliverOne(
  const ok2xx = status >= 200 && status < 300;
  if (ok2xx) {
    db.query(
      "UPDATE webhook_delivery SET state = 'ok', attempts = ?1, last_status = ?2, last_error = NULL WHERE id = ?3",
      `UPDATE ${tableOf(row)} SET state = 'ok', attempts = ?1, last_status = ?2, last_error = NULL WHERE id = ?3`,
    ).run(attempt, status, row.id);
    return;
  }
@@ -401,7 +469,7 @@
function backOff(
  const attempt = row.attempts + 1;
  if (attempt >= MAX_ATTEMPTS) {
    db.query(
      "UPDATE webhook_delivery SET state = 'failed', attempts = ?1, last_status = ?2 WHERE id = ?3",
      `UPDATE ${tableOf(row)} SET state = 'failed', attempts = ?1, last_status = ?2 WHERE id = ?3`,
    ).run(attempt, status, row.id);
    log.warn("webhook delivery gave up", {
      delivery: row.id,
@@ -414,7 +482,7 @@
function backOff(
  const delayMs = attempt * attempt * 10_000;
  const nextTry = new Date(now.getTime() + delayMs).toISOString();
  db.query(
    "UPDATE webhook_delivery SET attempts = ?1, last_status = ?2, next_try_at = ?3 WHERE id = ?4",
    `UPDATE ${tableOf(row)} SET attempts = ?1, last_status = ?2, next_try_at = ?3 WHERE id = ?4`,
  ).run(attempt, status, nextTry, row.id);
}
@@ -484,9 +552,14 @@
export function recentDeliveries(
      },
      [string, number]
    >(
      `SELECT d.id, d.state, d.attempts, d.last_status, d.last_error, e.kind
       FROM webhook_delivery d JOIN event e ON e.id = d.event_id
       WHERE d.webhook_id = ?1 ORDER BY d.id DESC LIMIT ?2`,
      `SELECT id, state, attempts, last_status, last_error, kind FROM (
         SELECT d.id, d.state, d.attempts, d.last_status, d.last_error, e.kind
         FROM webhook_delivery d JOIN event e ON e.id = d.event_id
         WHERE d.webhook_id = ?1
         UNION ALL
         SELECT id, state, attempts, last_status, last_error, 'ping' AS kind
         FROM webhook_ping WHERE webhook_id = ?1
       ) ORDER BY id DESC LIMIT ?2`,
    )
    .all(webhookId, limit);
  return rows.map((r) => ({
@@ -9,7 +9,7 @@
import { createWebhook, deleteWebhook } from "../../actions/repos.ts";
import { canAdmin } from "../../core/repos.ts";
import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
import { getWebhook, listWebhooks, recentDeliveries } from "../../core/webhooks.ts";
import { getWebhook, listWebhooks, pingWebhook, recentDeliveries } from "../../core/webhooks.ts";
import { loadRepo, pageOf, pageParams } from "../api.ts";
import type { Handler } from "../context.ts";
import { body, json, notFound, requireScope, respondAccess, str } from "../respond.ts";
@@ -38,6 +38,23 @@
export function hookRoutes(router: Router<Handler>): void {
    return json({ items: recentDeliveries(ctx.app.db, ctx.params.id!, 20) });
  });
  router.add("POST", "/api/v1/repos/:owner/:name/hooks/:id/ping", (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied.status === 403 ? notFound() : denied;
    const repo = loadRepo(ctx);
    if (!repo || !canAdmin(ctx.app.db, repo, ctx.auth.user)) return notFound();
    const hook = getWebhook(ctx.app.db, repo.id, ctx.params.id!);
    if (!hook) return notFound();
    const pinged = pingWebhook(ctx.app.db, `${ctx.params.owner}/${ctx.params.name}`, hook);
    if (!pinged.ok)
      return json(
        { error: "rate_limited", message: `too many pings: try again in ${pinged.error.retryAfter} s` },
        429,
        { "retry-after": String(pinged.error.retryAfter) },
      );
    return json({ id: pinged.value.id }, 202);
  });
  router.add("POST", "/api/v1/repos/:owner/:name/hooks", async (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
@@ -1,5 +1,5 @@
import { canAdmin } from "../../../core/repos.ts";
import { getWebhook, listWebhooks, recentDeliveries } from "../../../core/webhooks.ts";
import { getWebhook, listWebhooks, pingWebhook, recentDeliveries } from "../../../core/webhooks.ts";
import { createWebhook, deleteWebhook } from "../../../actions/repos.ts";
import { pageRows } from "../page.ts";
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
export const tool: Tool = {
  name: "hooks",
  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",
  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",
  description: "List, add (`url`, `secret`, `kinds`) or remove (`id`) webhooks; admins.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      action: { type: "string", enum: ["list", "add", "remove", "deliveries"] },
      action: { type: "string", enum: ["list", "add", "remove", "deliveries", "ping"] },
      url: { type: "string", maxLength: 2048 },
      kinds: { type: "string", maxLength: 200 },
      secret: { type: "string", maxLength: 200 },
@@ -54,6 +54,15 @@
export const tool: Tool = {
      if (hook === undefined) return bad("not_found", "no such webhook here");
      return good({ items: recentDeliveries(ctx.app.db, hook.id, 20) });
    }
    if (action === "ping") {
      const long = hookTooLong(args);
      if (long !== undefined) return long;
      if (!canAdmin(ctx.app.db, repo, user)) return notAdmin();
      const hook = getWebhook(ctx.app.db, repo.id, str(args["id"]));
      if (hook === undefined) return bad("not_found", "no such webhook here");
      const pinged = pingWebhook(ctx.app.db, `${repo.ownerName}/${repo.name}`, hook);
      return pinged.ok ? good({ id: pinged.value.id }) : bad("rate_limited", `too many pings: try again in ${pinged.error.retryAfter} s`);
    }
    if (action === "add") {
      const long = hookTooLong(args);
      if (long !== undefined) return long;
@@ -78,6 +87,6 @@
export const tool: Tool = {
      const removed = deleteWebhook(ctx.app, user, repo, str(args["id"]));
      return removed.ok ? good({}) : bad("not_found", "no such webhook here");
    }
    return bad("invalid", "action is list, add, remove or deliveries");
    return bad("invalid", "action is list, add, remove, deliveries or ping");
  },
};
@@ -411,7 +411,7 @@
import {
} from "../web/pages/settings.ts";
import { dangerPage, repoDelete } from "../web/pages/danger.ts";
import { detachSubmit } from "../web/pages/detach.ts";
import { hooksPage, webhookCreate, webhookDelete } from "../web/pages/hooks.ts";
import { hooksPage, webhookCreate, webhookDelete, webhookPing } from "../web/pages/hooks.ts";
import {
  crewAdd,
  crewRemove,
@@ -1545,6 +1545,7 @@
export function buildRouter(): Router<Handler> {
  router.add("GET", "/:owner/:name/settings/hooks", hooksPage);
  router.add("POST", "/:owner/:name/settings/hooks", webhookCreate);
  router.add("POST", "/:owner/:name/settings/hooks/:id/delete", webhookDelete);
  router.add("POST", "/:owner/:name/settings/hooks/:id/ping", webhookPing);
  router.add("GET", "/:owner/:name/settings/danger", dangerPage);
  router.add("POST", "/:owner/:name/settings/delete", repoDelete);
  router.add("POST", "/:owner/:name/settings/detach", detachSubmit);
@@ -1,7 +1,9 @@
/**
 * A repository's webhooks in the terminal, an admin's: each hook's url,
 * kinds and last delivery, never its secret. `enter` opens its last 20
 * deliveries; `r` there sends a failed one again through `redeliver`.
 * deliveries; `r` there sends a failed one again through `redeliver`, and
 * `p` sends the hook a `ping` through `pingWebhook` (a refusal past the rate
 * limit says how long to wait).
 * `a` asks for url, kinds and a secret (typed masked, 16–200 characters)
 * and adds it through `createWebhook`; `p` pauses or resumes the selected
 * one through `pauseWebhook` (a paused row reads `paused` and gets no
@@ -15,7 +17,14 @@
import {
  pauseWebhook,
} from "../../actions/repos.ts";
import { canAdmin, type Repo } from "../../core/repos.ts";
import { listWebhooks, recentDeliveries, redeliver, type DeliveryInfo, type Webhook } from "../../core/webhooks.ts";
import {
  listWebhooks,
  pingWebhook,
  recentDeliveries,
  redeliver,
  type DeliveryInfo,
  type Webhook,
} from "../../core/webhooks.ts";
import type { Ctx, Screen } from "../app/app.ts";
import type { Command } from "../app/palette.ts";
import { binding } from "../app/keys.ts";
@@ -53,7 +62,7 @@
function lastDelivery(f: Session, hook: Webhook): string {
}
/** One hook's last 20 deliveries, newest first: kind · state · status or reason · attempts. */
function deliveriesScreen(f: Session, ctx: Ctx, hook: Webhook, allowed: () => boolean): Screen {
function deliveriesScreen(f: Session, ctx: Ctx, repo: Repo, hook: Webhook, allowed: () => boolean): Screen {
  const state = new ListState();
  let all: DeliveryInfo[] = [];
  return {
@@ -63,6 +72,7 @@
function deliveriesScreen(f: Session, ctx: Ctx, hook: Webhook, allowed: () => bo
      return [
        binding(["j", "k"], "move"),
        binding(["r"], "redeliver", { disabled: !failed }),
        binding(["p"], "send a ping"),
        binding(["esc", "q"], "back"),
      ];
    },
@@ -100,6 +110,14 @@
function deliveriesScreen(f: Session, ctx: Ctx, hook: Webhook, allowed: () => bo
        ctx.invalidate();
        return true;
      }
      if (e.key === "p") {
        const sent = pingWebhook(f.db, `${repo.ownerName}/${repo.name}`, hook);
        if (sent.ok) ctx.toast("ping queued", "success");
        else ctx.toast(`too many pings: try again in ${sent.error.retryAfter} s`, "danger");
        state.index = 0;
        ctx.invalidate();
        return true;
      }
      return state.key(e, all.length);
    },
  };
@@ -203,7 +221,7 @@
export function hooksScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
      else if (e.key === "enter") {
        const hook = hooks()[state.index];
        if (hook === undefined) return false;
        ctx.push(deliveriesScreen(f, ctx, hook, allowed));
        ctx.push(deliveriesScreen(f, ctx, repo, hook, allowed));
      } else if (e.key === "p") {
        const hook = hooks()[state.index];
        if (hook === undefined) return false;
@@ -7,7 +7,7 @@
import { createWebhook, deleteWebhook } from "../../actions/repos.ts";
import { notePhase, timePhase } from "../../core/route_timing.ts";
import { listWebhooks, recentDeliveries } from "../../core/webhooks.ts";
import { getWebhook, listWebhooks, pingWebhook, recentDeliveries } from "../../core/webhooks.ts";
import type { Ctx } from "../../http/context.ts";
import { repoBase, repoNotFound } from "../chrome.ts";
import { field } from "../form.ts";
@@ -85,6 +85,9 @@
export function hooksPage(ctx: Ctx): Response {
              head: html`<span class="grow truncate mono" title="${hook.url}"
                  >${hook.url}</span
                >
                <form method="post" action="${base}/settings/hooks/${hook.id}/ping">
                  ${btn("Send ping", { size: "sm" })}
                </form>
                <span class="badge" data-variant="secondary"
                  >${hook.kinds}</span
                >
@@ -188,3 +191,20 @@
export async function webhookDelete(ctx: Ctx): Promise<Response> {
      : { tone: "danger", message: "That webhook no longer exists." },
  );
}
export async function webhookPing(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo } = gate;
  const to = `${repoBase(repo)}/settings/hooks`;
  const hook = getWebhook(ctx.app.db, repo.id, ctx.params.id ?? "");
  if (!hook) return flashTo(ctx, to, { tone: "danger", message: "That webhook no longer exists." });
  const pinged = pingWebhook(ctx.app.db, `${repo.ownerName}/${repo.name}`, hook);
  return flashTo(
    ctx,
    to,
    pinged.ok
      ? { message: "Ping queued: it shows among this webhook's deliveries." }
      : { tone: "danger", message: `Too many pings: try again in ${pinged.error.retryAfter} s.` },
  );
}
@@ -0,0 +1,203 @@
/** POST …/hooks/:id/ping, MCP `hooks` action `ping` and the settings page's Send ping (#8006). */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { createRepo } from "../src/actions/repos.ts";
import { createSession } from "../src/core/sessions.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser } from "../src/core/users.ts";
import { createWebhook, deliverDue, recentDeliveries, verifySignature } from "../src/core/webhooks.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { LOOPBACK } from "./helpers/loopback-hook.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
let dataDir: string;
let app: App;
let servers: Servers;
let adminTok = "";
let otherTok = "";
let cookie = "";
let hookA = "";
let hookB = "";
let secretA = "";
let received: { body: string; sig: string; kind: string }[] = [];
let receiver: ReturnType<typeof Bun.serve>;
const cells = process.env["FORGE_CELLS"];
beforeAll(async () => {
  process.env["FORGE_CELLS"] = "off";
  receiver = Bun.serve({
    port: 0,
    hostname: "127.0.0.1",
    async fetch(req) {
      received.push({
        body: await req.text(),
        sig: req.headers.get("x-forge-signature-256") ?? "",
        kind: req.headers.get("x-forge-event") ?? "",
      });
      return new Response("ok");
    },
  });
  dataDir = await mkdtemp(join(tmpdir(), "forge-hook-ping-"));
  app = createApp({ dataDir, port: 0 });
  servers = await serve(app);
  const mk = async (username: string, first: boolean) => {
    const made = await createUser(app.db, {
      origin: "seed",
      trusted: true,
      username,
      email: `${username}@forge.local`,
      password: "a-good-passphrase",
      adminIfFirst: first,
    });
    if (!made.ok) throw new Error(String(made.error));
    return made.value;
  };
  const alice = await mk("alice", true);
  const bob = await mk("bob", false);
  const ra = await createRepo(app, alice, { name: "a", visibility: "public" });
  if (!ra.ok) throw new Error("repo");
  // Subscribes to issues only: a ping must reach it anyway. The other hook hears nothing.
  const a = createWebhook(app.db, { repoId: ra.value.id, url: "https://a.example/h", kinds: "issue.opened" });
  const b = createWebhook(app.db, { repoId: ra.value.id, url: "https://b.example/h" });
  if (!a.ok || !b.ok) throw new Error("hook");
  hookA = a.value.webhook.id;
  hookB = b.value.webhook.id;
  secretA = a.value.secret;
  adminTok = createToken(app.db, alice.id, "t", "admin").token;
  cookie = `forge_session=${createSession(app.db, alice.id).token}`;
  otherTok = createToken(app.db, bob.id, "o", "admin").token;
});
afterAll(async () => {
  receiver.stop(true);
  await servers.stop();
  app.close();
  if (cells === undefined) delete process.env["FORGE_CELLS"];
  else process.env["FORGE_CELLS"] = cells;
  await rm(dataDir, { recursive: true, force: true });
});
const ping = (hook: string, tok: string) =>
  fetch(`${servers.url}/api/v1/repos/alice/a/hooks/${hook}/ping`, { method: "POST", headers: { authorization: `Bearer ${tok}` } });
const mcp = async (args: unknown) => {
  const res = await fetch(`${servers.url}/mcp`, {
    method: "POST",
    headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${adminTok}` },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "hooks", arguments: args } }),
  });
  const body = (await res.json()) as any;
  const text: string = body.result.content[0].text;
  return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
};
const resetWindow = () => app.db.run("UPDATE webhook_ping SET created_at = '2020-01-01T00:00:00.000Z'");
test("a ping answers 202, shows among the deliveries and reaches only that hook", async () => {
  const res = await ping(hookA, adminTok);
  expect(res.status).toBe(202);
  const { id } = (await res.json()) as { id: string };
  const api = await fetch(`${servers.url}/api/v1/repos/alice/a/hooks/${hookA}/deliveries`, { headers: { authorization: `Bearer ${adminTok}` } });
  const items = ((await api.json()) as any).items;
  expect(items[0]).toMatchObject({ id, kind: "ping", state: "pending" });
  const viaMcp = await mcp({ repo: "alice/a", action: "deliveries", id: hookA });
  expect(viaMcp.value.items[0]).toMatchObject({ id, kind: "ping" });
  expect(recentDeliveries(app.db, hookB)).toHaveLength(0);
});
test("the ping is signed and goes through deliverDue, body { kind, repo, hook, at }", async () => {
  received = [];
  app.db.run("UPDATE webhook SET url = ?2 WHERE id = ?1", [hookA, `http://127.0.0.1:${receiver.port}/h`]);
  await deliverDue(app.db, app.log, new Date(), LOOPBACK);
  expect(received).toHaveLength(1);
  const hit = received[0]!;
  expect(hit.kind).toBe("ping");
  const body = JSON.parse(hit.body);
  expect(Object.keys(body).sort()).toEqual(["at", "hook", "kind", "repo"]);
  expect(body).toMatchObject({ kind: "ping", repo: "alice/a", hook: hookA });
  expect(await verifySignature(secretA, hit.body, hit.sig)).toBe(true);
});
test("a private address is refused as a failed delivery with its reason, never fetched inline", async () => {
  resetWindow();
  const res = await ping(hookB, adminTok);
  expect(res.status).toBe(202);
  expect(recentDeliveries(app.db, hookB)[0]).toMatchObject({ kind: "ping", state: "pending", attempts: 0 });
  app.db.run("UPDATE webhook SET url = 'https://127.0.0.1/h' WHERE id = ?1", [hookB]);
  await deliverDue(app.db, app.log);
  expect(recentDeliveries(app.db, hookB)[0]).toMatchObject({ kind: "ping", state: "failed" });
  expect(recentDeliveries(app.db, hookB)[0]!.lastError).toBeTruthy();
});
test("a non-admin, a missing hook and no credentials are refused", async () => {
  expect((await ping(hookA, otherTok)).status).toBe(404);
  expect((await ping("nope", adminTok)).status).toBe(404);
  const anon = await fetch(`${servers.url}/api/v1/repos/alice/a/hooks/${hookA}/ping`, { method: "POST" });
  expect(anon.status).toBe(401);
});
test("past three a minute it is 429 with retry-after, over the API and MCP", async () => {
  resetWindow();
  for (let i = 0; i < 3; i++) expect((await ping(hookA, adminTok)).status).toBe(202);
  const over = await ping(hookA, adminTok);
  expect(over.status).toBe(429);
  expect(Number(over.headers.get("retry-after"))).toBeGreaterThan(0);
  const m = await mcp({ repo: "alice/a", action: "ping", id: hookA });
  expect(m.error).toContain("too many pings");
  resetWindow();
  const ok = await mcp({ repo: "alice/a", action: "ping", id: hookA });
  expect(typeof ok.value.id).toBe("string");
});
test("a ping is not an event: the repository's event log, feed and stream never hear of it", async () => {
  resetWindow();
  const before = app.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM event").get()!.n;
  expect((await ping(hookA, adminTok)).status).toBe(202);
  expect(app.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM event").get()!.n).toBe(before);
  expect(app.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM event WHERE kind = 'ping'").get()!.n).toBe(0);
  const events = await fetch(`${servers.url}/api/v1/repos/alice/a/events?kind=ping`);
  expect(((await events.json()) as any).items).toHaveLength(0);
  const all = await fetch(`${servers.url}/api/v1/repos/alice/a/events`);
  expect(JSON.stringify(await all.json())).not.toContain("ping");
});
test("the limit counts deliveries, so it holds with nothing in the event log", async () => {
  resetWindow();
  for (let i = 0; i < 3; i++) expect((await ping(hookB, adminTok)).status).toBe(202);
  expect((await ping(hookB, adminTok)).status).toBe(429);
  expect(app.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM event WHERE kind = 'ping'").get()!.n).toBe(0);
});
const send = (hook: string, headers: Record<string, string>) =>
  fetch(`${servers.url}/alice/a/settings/hooks/${hook}/ping`, { method: "POST", redirect: "manual", headers: { cookie, ...headers } });
test("the hooks page has a Send ping form; posting it queues a delivery, a cross-site post does not", async () => {
  resetWindow();
  const page = await (await fetch(`${servers.url}/alice/a/settings/hooks`, { headers: { cookie } })).text();
  expect(page).toContain(`action="/alice/a/settings/hooks/${hookA}/ping"`);
  expect(page).toContain("Send ping");
  const n = () => recentDeliveries(app.db, hookA, 50).length;
  const before = n();
  expect((await send(hookA, { origin: "https://evil.example" })).status).toBe(403);
  expect(n()).toBe(before);
  const ok = await send(hookA, { origin: servers.url });
  expect(ok.status).toBe(303);
  expect(n()).toBe(before + 1);
  expect(recentDeliveries(app.db, hookA, 1)[0]).toMatchObject({ kind: "ping", state: "pending" });
});
test("the page post past the limit is a message, not a delivery; a stranger gets nothing", async () => {
  resetWindow();
  for (let i = 0; i < 3; i++) await send(hookA, { origin: servers.url });
  const before = recentDeliveries(app.db, hookA, 50).length;
  const over = await send(hookA, { origin: servers.url });
  expect(over.status).toBe(303);
  expect(recentDeliveries(app.db, hookA, 50)).toHaveLength(before);
  const shown = await (await fetch(`${servers.url}/alice/a/settings/hooks`, { headers: { cookie: over.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ") + "; " + cookie } })).text();
  expect(shown).toContain("Too many pings");
  const anon = await fetch(`${servers.url}/alice/a/settings/hooks/${hookA}/ping`, { method: "POST", redirect: "manual", headers: { origin: servers.url } });
  expect(anon.status).toBe(404);
  expect(recentDeliveries(app.db, hookA, 50)).toHaveLength(before);
});
@@ -1,7 +1,8 @@
/**
 * Enter on a webhook in the terminal's Hooks screen opens its last 20
 * deliveries (#7873): state, status and why it failed, never a secret;
 * esc or q returns to the same row; losing admin closes it.
 * esc or q returns to the same row; losing admin closes it. `r` redelivers
 * a failed row (#8075); `p` sends the hook a ping (#7872).
 */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
@@ -11,7 +12,7 @@
import { createRepo } from "../src/actions/repos.ts";
import { createApp, type App } from "../src/app.ts";
import type { Repo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import { createWebhook, enqueueForEvent, listWebhooks } from "../src/core/webhooks.ts";
import { createWebhook, enqueueForEvent, listWebhooks, PING_LIMIT } from "../src/core/webhooks.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { hooksScreen } from "../src/tui/screens/hooks.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
@@ -174,3 +175,32 @@
test("a person who lost admin cannot redeliver with r: the row stays failed", as
  expect(app.db.query("SELECT 1 FROM webhook_delivery WHERE state = 'pending'").get()).toBeNull();
  h.stop();
});
test("p sends the hook a ping that shows at once among its deliveries; past the limit it says how long to wait", async () => {
  const h = open();
  await h.feed("j", "j", "enter");
  expect(h.text()).toContain("No deliveries yet.");
  for (let i = 0; i < PING_LIMIT; i++) {
    await h.feed("p");
    expect(h.text()).toContain("ping queued");
  }
  expect(h.text()).toMatch(/ping · pending · — · 0/);
  await h.feed("p");
  expect(h.text()).toMatch(/too many pings: try again in \d+ s/);
  const hook = listWebhooks(app.db, repo.id)[2]!;
  expect(app.db.query("SELECT COUNT(*) AS n FROM webhook_ping WHERE webhook_id = ?1").get(hook.id)).toEqual({
    n: PING_LIMIT,
  });
  h.stop();
});
test("a person who lost admin cannot ping with p", async () => {
  const before = (app.db.query("SELECT COUNT(*) AS n FROM webhook_ping").get() as { n: number }).n;
  const h = open();
  await h.feed("enter");
  (h.session as { user: User }).user = bob;
  await h.feed("p");
  expect(h.text()).not.toContain("ping queued");
  expect((app.db.query("SELECT COUNT(*) AS n FROM webhook_ping").get() as { n: number }).n).toBe(before);
  h.stop();
});
		@@ -97,7 +97,7 @@ for a tunnel and a forge that sleeps.
97	97	\| `health` \| how this forge is: the version and commit it runs, draining or not, the rollout and its incidents \| \|
98	98	\| `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 \| \|
99	99	\| `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 \|
100		\| `hooks` \| (admin scope) `{ 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 \|
	100	\| `hooks` \| (admin scope) `{ 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 \|
101	101	\| `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 \|
102	102	\| `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 \| \|
103	103	\| `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 \|
		@@ -0,0 +1,11 @@
	1	# Send a webhook a test ping
	2
	3	A repository admin can check that a webhook's receiver answers without waiting for a real event: a `ping` is one signed delivery to that hook only, whatever kinds it follows.
	4
	5	- Page. Settings › Webhooks has a Send ping button on each hook, a same-origin POST to `/:owner/:name/settings/hooks/:id/ping`. The ping appears at once among that hook's deliveries; a refused one says how long to wait.
	6	- API. `POST /api/v1/repos/:owner/:name/hooks/:id/ping` with an admin-scope token answers 202 `{ id }`. Below admin, or for a hook not in the repository, it is 404.
	7	- MCP. `hooks` with `action: ping` and `id`, admin scope; it answers `{ id }`.
	8	- Terminal. Open a hook's Deliveries screen and press `p`. The screen and the key are a repository admin's; the new row shows at the top as `ping · pending`.
	9	- Body. `{ kind: "ping", repo, hook, at }`, signed with the hook's secret like any delivery. The worker sends it on its next pass, with the same egress refusal and retries; a paused hook holds it pending until it is resumed.
	10	- Rate limit. At most 3 a minute per hook. Past that the API answers 429 with `retry-after`, MCP says the same, and the page and the terminal say how many seconds to wait.
	11	- Not an event. The ping lives on its own delivery row (`webhook_ping`), never in the event log, so no feed, stream or other hook hears of it. A failed ping is not redelivered with `r`: send another.
		@@ -242,6 +242,7 @@ export { route as postApiV1ReposOwnerNameFollowingSever } from "./postApiV1Repos
242	242	export { route as postApiV1ReposOwnerNameFollowingTake } from "./postApiV1ReposOwnerNameFollowingTake.ts";
243	243	export { route as postApiV1ReposOwnerNameForks } from "./postApiV1ReposOwnerNameForks.ts";
244	244	export { route as postApiV1ReposOwnerNameHooks } from "./postApiV1ReposOwnerNameHooks.ts";
	245	export { route as postApiV1ReposOwnerNameHooksIdPing } from "./postApiV1ReposOwnerNameHooksIdPing.ts";
245	246	export { route as postApiV1ReposOwnerNameIssues } from "./postApiV1ReposOwnerNameIssues.ts";
246	247	export { route as postApiV1ReposOwnerNameIssuesNumberComments } from "./postApiV1ReposOwnerNameIssuesNumberComments.ts";
247	248	export { route as postApiV1ReposOwnerNameIssuesNumberDependencies } from "./postApiV1ReposOwnerNameIssuesNumberDependencies.ts";
		@@ -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	};
		@@ -0,0 +1,1 @@
	1	9ec6439b3eb7d11764ea98a509a4978937e9c1f11ee06a53c0d943ec3dde3ca0
		@@ -0,0 +1,19 @@
	1	// A test `ping` belongs to its own row, not to the repository's event log
	2	// (#8006). A delivery must name an event, and a roll keeps the old release
	3	// reading `webhook_delivery`, so the ping gets a table of its own beside it
	4	// rather than a rebuilt delivery table: nothing the old release reads changes.
	5	export default `
	6	CREATE TABLE IF NOT EXISTS webhook_ping (
	7	id TEXT PRIMARY KEY,
	8	webhook_id TEXT NOT NULL REFERENCES webhook(id) ON DELETE CASCADE,
	9	state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending','ok','failed')),
	10	attempts INTEGER NOT NULL DEFAULT 0,
	11	next_try_at TEXT,
	12	last_status INTEGER,
	13	last_error TEXT,
	14	payload TEXT NOT NULL,
	15	created_at TEXT NOT NULL
	16	);
	17	CREATE INDEX IF NOT EXISTS ping_due ON webhook_ping(state, next_try_at);
	18	CREATE INDEX IF NOT EXISTS ping_hook ON webhook_ping(webhook_id, created_at);
	19	`;
		@@ -187,6 +187,49 @@ export function enqueueForEvent(db: Database, event: ForgeEvent): number {
187	187	return queued;
188	188	}
189	189
	190	/** Pings one hook may be sent in a minute. */
	191	export const PING_LIMIT = 3;
	192	const PING_WINDOW_MS = 60_000;
	193
	194	/**
	195	* Queue one `ping` delivery for one hook, whatever kinds it subscribes to.
	196	* The payload lives on the delivery row, never in the event log, so no feed,
	197	* stream or other hook hears of it; the request is made later by `deliverDue`, which keeps the
	198	* egress refusal. `retryAfter` is in seconds when the hook was pinged too
	199	* often.
	200	*/
	201	export function pingWebhook(
	202	db: Database,
	203	repoSlug: string,
	204	hook: Webhook,
	205	now = new Date(),
	206	): Result<{ id: string }, { retryAfter: number }> {
	207	const since = new Date(now.getTime() - PING_WINDOW_MS).toISOString();
	208	const recent = db
	209	.query<{ n: number; first: string \| null }, [string, string]>(
	210	`SELECT COUNT(*) AS n, MIN(created_at) AS first
	211	FROM webhook_ping
	212	WHERE webhook_id = ?1 AND created_at > ?2`,
	213	)
	214	.get(hook.id, since)!;
	215	if (recent.n >= PING_LIMIT) {
	216	const first = recent.first ? Date.parse(recent.first) : now.getTime();
	217	const wait = Math.ceil((first + PING_WINDOW_MS - now.getTime()) / 1000);
	218	return err({ retryAfter: Math.max(1, wait) });
	219	}
	220	const at = now.toISOString();
	221	const deliveryId = id();
	222	db.query(
	223	"INSERT INTO webhook_ping (id, webhook_id, payload, created_at) VALUES (?1, ?2, ?3, ?4)",
	224	).run(
	225	deliveryId,
	226	hook.id,
	227	JSON.stringify({ kind: "ping", repo: repoSlug, hook: hook.id, at }),
	228	at,
	229	);
	230	return ok({ id: deliveryId });
	231	}
	232
190	233	export type RedeliverError = "not_found" \| "not_failed" \| "sealed";
191	234
192	235	/**
		@@ -244,7 +287,9 @@ function redeliverIn(db: Database, deliveryId: string, webhookId: string): Resul
244	287	interface DueRow {
245	288	id: string;
246	289	webhook_id: string;
247		event_id: string;
	290	event_id: string \| null;
	291	/** True when the row is in `webhook_ping`, not `webhook_delivery`. */
	292	ping: boolean;
248	293	attempts: number;
249	294	url: string;
250	295	secret: string;
		@@ -271,9 +316,9 @@ export async function deliverDue(
271	316	outbound: OutboundOptions = {},
272	317	): Promise<number> {
273	318	const nowIso = now.toISOString();
274		const due = db
	319	const events = db
275	320	.query<DueRow, [string]>(
276		`SELECT d.id, d.webhook_id, d.event_id, d.attempts,
	321	`SELECT d.id, d.webhook_id, d.event_id, 0 AS ping, d.attempts,
277	322	w.url, w.secret,
278	323	e.kind, e.repo_id, e.actor_id, e.payload, e.created_at
279	324	FROM webhook_delivery d
		@@ -284,6 +329,20 @@ export async function deliverDue(
284	329	ORDER BY d.id LIMIT 50`,
285	330	)
286	331	.all(nowIso);
	332	const pings = db
	333	.query<DueRow, [string]>(
	334	`SELECT d.id, d.webhook_id, NULL AS event_id, 1 AS ping, d.attempts,
	335	w.url, w.secret,
	336	'ping' AS kind, NULL AS repo_id, NULL AS actor_id,
	337	d.payload, d.created_at
	338	FROM webhook_ping d
	339	JOIN webhook w ON w.id = d.webhook_id
	340	WHERE d.state = 'pending' AND w.active = 1
	341	AND (d.next_try_at IS NULL OR d.next_try_at <= ?1)
	342	ORDER BY d.id LIMIT 50`,
	343	)
	344	.all(nowIso);
	345	const due = [...events, ...pings].map((r) => ({ ...r, ping: !!r.ping }));
287	346
288	347	for (const row of due) {
289	348	// Claimed before it is sent: two forge processes over one database (a
		@@ -295,7 +354,7 @@ export async function deliverDue(
295	354	const claimAt = Date.now();
296	355	const claimed = db
297	356	.query(
298		`UPDATE webhook_delivery SET next_try_at = ?2
	357	`UPDATE ${tableOf(row)} SET next_try_at = ?2
299	358	WHERE id = ?1 AND state = 'pending'
300	359	AND (next_try_at IS NULL OR next_try_at <= ?3)`,
301	360	)
		@@ -324,6 +383,11 @@ export async function deliverDue(
324	383	return due.length;
325	384	}
326	385
	386	/** Where a due row lives: a ping has its own table, never the event log's. */
	387	function tableOf(row: DueRow): "webhook_ping" \| "webhook_delivery" {
	388	return row.ping ? "webhook_ping" : "webhook_delivery";
	389	}
	390
327	391	async function deliverOne(
328	392	db: Database,
329	393	log: Log,
		@@ -331,14 +395,18 @@ async function deliverOne(
331	395	now: Date,
332	396	outbound: OutboundOptions,
333	397	): Promise<void> {
334		const body = JSON.stringify({
335		id: row.event_id,
336		kind: row.kind,
337		repo_id: row.repo_id,
338		actor_id: row.actor_id,
339		payload: JSON.parse(row.payload),
340		created_at: row.created_at,
341		});
	398	// A ping's body is its payload as it stands: { kind, repo, hook, at }.
	399	const body =
	400	row.ping
	401	? row.payload
	402	: JSON.stringify({
	403	id: row.event_id,
	404	kind: row.kind,
	405	repo_id: row.repo_id,
	406	actor_id: row.actor_id,
	407	payload: JSON.parse(row.payload),
	408	created_at: row.created_at,
	409	});
342	410	const signature = await sign(row.secret, body);
343	411	const attempt = row.attempts + 1;
344	412
		@@ -370,7 +438,7 @@ async function deliverOne(
370	438	// seconds, so there is nothing to retry: fail it now, with the reason.
371	439	log.warn("webhook delivery refused", { delivery: row.id });
372	440	db.query(
373		"UPDATE webhook_delivery SET state = 'failed', attempts = ?1, last_status = NULL, last_error = ?2 WHERE id = ?3",
	441	`UPDATE ${tableOf(row)} SET state = 'failed', attempts = ?1, last_status = NULL, last_error = ?2 WHERE id = ?3`,
374	442	).run(attempt, error.message, row.id);
375	443	return;
376	444	}
		@@ -383,7 +451,7 @@ async function deliverOne(
383	451	const ok2xx = status >= 200 && status < 300;
384	452	if (ok2xx) {
385	453	db.query(
386		"UPDATE webhook_delivery SET state = 'ok', attempts = ?1, last_status = ?2, last_error = NULL WHERE id = ?3",
	454	`UPDATE ${tableOf(row)} SET state = 'ok', attempts = ?1, last_status = ?2, last_error = NULL WHERE id = ?3`,
387	455	).run(attempt, status, row.id);
388	456	return;
389	457	}
		@@ -401,7 +469,7 @@ function backOff(
401	469	const attempt = row.attempts + 1;
402	470	if (attempt >= MAX_ATTEMPTS) {
403	471	db.query(
404		"UPDATE webhook_delivery SET state = 'failed', attempts = ?1, last_status = ?2 WHERE id = ?3",
	472	`UPDATE ${tableOf(row)} SET state = 'failed', attempts = ?1, last_status = ?2 WHERE id = ?3`,
405	473	).run(attempt, status, row.id);
406	474	log.warn("webhook delivery gave up", {
407	475	delivery: row.id,
		@@ -414,7 +482,7 @@ function backOff(
414	482	const delayMs = attempt * attempt * 10_000;
415	483	const nextTry = new Date(now.getTime() + delayMs).toISOString();
416	484	db.query(
417		"UPDATE webhook_delivery SET attempts = ?1, last_status = ?2, next_try_at = ?3 WHERE id = ?4",
	485	`UPDATE ${tableOf(row)} SET attempts = ?1, last_status = ?2, next_try_at = ?3 WHERE id = ?4`,
418	486	).run(attempt, status, nextTry, row.id);
419	487	}
420	488
		@@ -484,9 +552,14 @@ export function recentDeliveries(
484	552	},
485	553	[string, number]
486	554	>(
487		`SELECT d.id, d.state, d.attempts, d.last_status, d.last_error, e.kind
488		FROM webhook_delivery d JOIN event e ON e.id = d.event_id
489		WHERE d.webhook_id = ?1 ORDER BY d.id DESC LIMIT ?2`,
	555	`SELECT id, state, attempts, last_status, last_error, kind FROM (
	556	SELECT d.id, d.state, d.attempts, d.last_status, d.last_error, e.kind
	557	FROM webhook_delivery d JOIN event e ON e.id = d.event_id
	558	WHERE d.webhook_id = ?1
	559	UNION ALL
	560	SELECT id, state, attempts, last_status, last_error, 'ping' AS kind
	561	FROM webhook_ping WHERE webhook_id = ?1
	562	) ORDER BY id DESC LIMIT ?2`,
490	563	)
491	564	.all(webhookId, limit);
492	565	return rows.map((r) => ({
		@@ -9,7 +9,7 @@
9	9	import { createWebhook, deleteWebhook } from "../../actions/repos.ts";
10	10	import { canAdmin } from "../../core/repos.ts";
11	11	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";
13	13	import { loadRepo, pageOf, pageParams } from "../api.ts";
14	14	import type { Handler } from "../context.ts";
15	15	import { body, json, notFound, requireScope, respondAccess, str } from "../respond.ts";
		@@ -38,6 +38,23 @@ export function hookRoutes(router: Router<Handler>): void {
38	38	return json({ items: recentDeliveries(ctx.app.db, ctx.params.id!, 20) });
39	39	});
40	40
	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
41	58	router.add("POST", "/api/v1/repos/:owner/:name/hooks", async (ctx) => {
42	59	const denied = requireScope(ctx, "admin");
43	60	if (denied) return denied;
		@@ -1,5 +1,5 @@
1	1	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";
3	3	import { createWebhook, deleteWebhook } from "../../../actions/repos.ts";
4	4	import { pageRows } from "../page.ts";
5	5	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
20	20
21	21	export const tool: Tool = {
22	22	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",
24	24	description: "List, add (`url`, `secret`, `kinds`) or remove (`id`) webhooks; admins.",
25	25	inputSchema: {
26	26	type: "object",
27	27	properties: {
28	28	repo: REPO_ARG,
29		action: { type: "string", enum: ["list", "add", "remove", "deliveries"] },
	29	action: { type: "string", enum: ["list", "add", "remove", "deliveries", "ping"] },
30	30	url: { type: "string", maxLength: 2048 },
31	31	kinds: { type: "string", maxLength: 200 },
32	32	secret: { type: "string", maxLength: 200 },
		@@ -54,6 +54,15 @@ export const tool: Tool = {
54	54	if (hook === undefined) return bad("not_found", "no such webhook here");
55	55	return good({ items: recentDeliveries(ctx.app.db, hook.id, 20) });
56	56	}
	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	}
57	66	if (action === "add") {
58	67	const long = hookTooLong(args);
59	68	if (long !== undefined) return long;
		@@ -78,6 +87,6 @@ export const tool: Tool = {
78	87	const removed = deleteWebhook(ctx.app, user, repo, str(args["id"]));
79	88	return removed.ok ? good({}) : bad("not_found", "no such webhook here");
80	89	}
81		return bad("invalid", "action is list, add, remove or deliveries");
	90	return bad("invalid", "action is list, add, remove, deliveries or ping");
82	91	},
83	92	};
		@@ -411,7 +411,7 @@ import {
411	411	} from "../web/pages/settings.ts";
412	412	import { dangerPage, repoDelete } from "../web/pages/danger.ts";
413	413	import { detachSubmit } from "../web/pages/detach.ts";
414		import { hooksPage, webhookCreate, webhookDelete } from "../web/pages/hooks.ts";
	414	import { hooksPage, webhookCreate, webhookDelete, webhookPing } from "../web/pages/hooks.ts";
415	415	import {
416	416	crewAdd,
417	417	crewRemove,
		@@ -1545,6 +1545,7 @@ export function buildRouter(): Router<Handler> {
1545	1545	router.add("GET", "/:owner/:name/settings/hooks", hooksPage);
1546	1546	router.add("POST", "/:owner/:name/settings/hooks", webhookCreate);
1547	1547	router.add("POST", "/:owner/:name/settings/hooks/:id/delete", webhookDelete);
	1548	router.add("POST", "/:owner/:name/settings/hooks/:id/ping", webhookPing);
1548	1549	router.add("GET", "/:owner/:name/settings/danger", dangerPage);
1549	1550	router.add("POST", "/:owner/:name/settings/delete", repoDelete);
1550	1551	router.add("POST", "/:owner/:name/settings/detach", detachSubmit);