Something went wrong. Try again.
Tangled Spindle built on Cloudflare Workers
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530import { runDurableObjectAlarm, runInDurableObject } from "cloudflare:test";import { env, exports } from "cloudflare:workers";import { beforeEach, describe, expect, it, vi } from "vitest";import { assertOutput, didDoc, getRecordRoute, keypair, knot, knotService, offline, pds, pdsService, record, repoDid as repo, routeFetch, serviceToken, spindle,} from "./helpers";import type { Route } from "./helpers";
const host = "treadle.example.com";const owner = env.OWNER_DID;const stranger = "did:plc:ssssssssssssssssssssssss";const ownerKey = keypair("p256");const strangerKey = keypair();const repoKey = keypair();const target = "https://hooks.example.com/tangled";const hooks = exports.Webhooks.getByName(repo);const pushBody = { ref: "refs/heads/main", repository: { full_name: `${owner}/my.repo` } };let manifestSpindle: string;let routes: Record<string, Route>;let sent: { headers: Headers; body: string; redirect: string }[];
beforeEach(async () => { manifestSpindle = spindle; sent = []; await runInDurableObject(exports.Store.getByName("main"), (_instance, state) => state.storage.deleteAlarm(), ); await runInDurableObject(hooks, async (_instance, state) => { state.storage.sql.exec( "DELETE FROM hooks; DELETE FROM jobs; DELETE FROM deliveries; DELETE FROM pushes", ); await state.storage.deleteAlarm(); }); routes = { [`GET https://plc.directory/${owner}`]: () => Response.json(didDoc(owner, ownerKey, [pdsService])), [`GET https://plc.directory/${stranger}`]: () => Response.json(didDoc(stranger, strangerKey)), [`GET https://plc.directory/${repo}`]: () => Response.json(didDoc(repo, repoKey, [knotService])), [getRecordRoute(knot, repo, "org.tangled.repo.manifest", "self")]: () => record({ declaration: { owner, name: "My.Repo" }, spindle: manifestSpindle }), [getRecordRoute(pds, owner, "org.tangled.repo.declaration", "my.repo")]: () => record({ repo }), [`POST ${target}`]: () => new Response("thanks"), }; routeFetch(routes, async (request) => { if (request.url.startsWith(target)) { sent.push({ headers: request.headers, body: await request.clone().text(), redirect: request.redirect, }); } });});
function call( method: string, params: Record<string, unknown> = {}, { key = ownerKey, iss = owner, jti = crypto.randomUUID(), }: { key?: typeof ownerKey; iss?: string; jti?: string } = {},): Promise<Response> { const nsid = `org.tangled.webhook.${method}`; const headers = { Authorization: `Bearer ${serviceToken(key, { iss, lxm: nsid, jti })}`, "Content-Type": "application/json", }; const url = `https://${host}/xrpc/${nsid}`; if (method.startsWith("list")) { const query = new URLSearchParams({ repo }); for (const [name, value] of Object.entries(params)) { for (const item of [value].flat()) { query.append(name, String(item)); } } query.sort(); return exports.default.fetch(`${url}?${query.toString()}`, { headers }); } return exports.default.fetch(url, { method: "POST", headers, body: JSON.stringify({ repo, ...params }), });}
async function create(input: object = {}): Promise<string> { const res = await call("createWebhook", { url: target, events: ["push"], ...input }); expect(res.status).toBe(200); const body: { id: string } = await res.json(); assertOutput("org.tangled.webhook.createWebhook", body); return body.id;}
async function list(): Promise<Record<string, unknown>[]> { const res = await call("listWebhooks"); expect(res.status).toBe(200); const body: { webhooks: Record<string, unknown>[] } = await res.json(); assertOutput("org.tangled.webhook.listWebhooks", body); return body.webhooks;}
interface Delivery { id: string; webhook: string; event: string; url: string; success: boolean; responseCode?: number; requestBody?: { $bytes: string }; responseBody?: { $bytes: string };}
async function deliveries(ids: string[], limit?: number): Promise<Delivery[]> { const res = await call("listWebhookDeliveries", { webhooks: ids, ...(limit === undefined ? {} : { limit }), }); expect(res.status).toBe(200); const body: { deliveries: Delivery[] } = await res.json(); assertOutput("org.tangled.webhook.listWebhookDeliveries", body); return body.deliveries;}
function text(bytes: { $bytes: string } | undefined): string { return new TextDecoder().decode(Uint8Array.fromBase64(bytes?.$bytes ?? ""));}
function dueJobs(): Promise<number> { return runInDurableObject( hooks, (_instance, state) => state.storage.sql .exec<{ n: number }>("SELECT count(*) AS n FROM jobs WHERE due <= ?", Date.now()) .one().n, );}
async function drain(): Promise<void> { await runDurableObjectAlarm(hooks); await vi.waitFor(async () => expect(await dueJobs()).toBe(0));}
// Makes the retries that wait for their backoff due now.async function retryNow(): Promise<void> { await runInDurableObject(hooks, (_instance, state) => { state.storage.sql.exec("UPDATE jobs SET due = 0"); }); await drain();}
async function firePush(key = "push-1"): Promise<void> { await hooks.firePush(key, pushBody, "Tangled-Hook/abcdef0"); await drain();}
async function hmac(secret: string, body: string): Promise<string> { const key = await crypto.subtle.importKey( "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"], ); const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body)); return `sha256=${new Uint8Array(mac).toHex()}`;}
describe("org.tangled.webhook methods", () => { it("creates, lists, updates and deletes a webhook without returning its secret", async () => { const id = await create({ secret: " s3cret ", events: ["push", "push"] }); expect(id).toMatch(/^\d+$/); const [hook, ...rest] = await list(); expect(rest).toEqual([]); expect(hook).toMatchObject({ id, url: target, active: true, events: ["push"] }); expect(JSON.stringify(hook)).not.toContain("s3cret");
const update = await call("updateWebhook", { webhook: id, url: `${target}/v2`, active: false, events: ["pull_request:merged"], }); expect(update.status).toBe(200); expect(await list()).toMatchObject([ { id, url: `${target}/v2`, active: false, events: ["pull_request:merged"] }, ]);
expect((await call("deleteWebhook", { webhook: id })).status).toBe(200); expect(await list()).toEqual([]); const missing = await call("deleteWebhook", { webhook: id }); expect(missing.status).toBe(404); expect(await missing.json()).toMatchObject({ error: "WebhookNotFound" }); });
it("keeps the fields that an update omits", async () => { const id = await create({ events: ["push", "pull_request:created"], active: false }); await call("updateWebhook", { webhook: id, url: " ", events: [] }); expect(await list()).toMatchObject([ { url: target, active: false, events: ["push", "pull_request:created"] }, ]); });
it("accepts every upstream event name", async () => { const events = [ "push", "repository:renamed", "pull_request:created", "pull_request:resubmitted", "pull_request:merged", "pull_request:closed", "pull_request:reopened", ]; await create({ events }); expect(await list()).toMatchObject([{ events }]); });
it.each([ ["no events", { events: [] }, "NoEventsSelected"], ["an unknown event", { events: ["org.tangled.event.pullRequest"] }, "InvalidEvent"], ["events that are not a list", { events: "push" }, "InvalidRequest"], ["no URL", { url: undefined }, "InvalidRequest"], ["an ftp URL", { url: "ftp://hooks.example.com/" }, "InvalidRequest"], ["a URL that does not parse", { url: "not a url" }, "InvalidRequest"], ["a private IPv4 address", { url: "http://10.1.2.3/hook" }, "InvalidRequest"], ["a loopback address", { url: "http://127.0.0.1:8080/hook" }, "InvalidRequest"], ["a hex loopback address", { url: "http://0x7f.1/hook" }, "InvalidRequest"], ["a link-local address", { url: "http://169.254.169.254/" }, "InvalidRequest"], ["an IPv6 loopback address", { url: "http://[::1]/hook" }, "InvalidRequest"], ["a mapped IPv4 address", { url: "http://[::ffff:10.0.0.1]/" }, "InvalidRequest"], ["a unique local IPv6 address", { url: "http://[fd00::1]/" }, "InvalidRequest"], ["a 6to4 address", { url: "http://[2002:a00:1::]/" }, "InvalidRequest"], ["a Teredo address", { url: "http://[2001::1]/" }, "InvalidRequest"], ["localhost", { url: "http://localhost:8080/" }, "InvalidRequest"], ["localhost with a trailing dot", { url: "http://app.localhost./" }, "InvalidRequest"], ["a secret that is not a string", { secret: 1 }, "InvalidRequest"], ["an active flag that is not a boolean", { active: "yes" }, "InvalidRequest"], ])("refuses a webhook with %s", async (_, input, error) => { const res = await call("createWebhook", { url: target, events: ["push"], ...input }); expect(res.status).toBe(400); expect(await res.json()).toMatchObject({ error }); });
it.each([ ["a public IPv4 address", "http://93.184.216.34/hook"], ["a public IPv6 address", "https://[2606:4700::1111]/hook"], ])("accepts %s", async (_, url) => { await create({ url }); expect(await list()).toMatchObject([{ url }]); });
it.each([ ["updateWebhook", { webhook: "abc" }, 400, "InvalidRequest"], ["updateWebhook", { webhook: "99" }, 404, "WebhookNotFound"], ["deleteWebhook", { webhook: "99" }, 404, "WebhookNotFound"], ["retryWebhookDelivery", { webhook: "99", delivery: "x" }, 404, "WebhookNotFound"], ["listWebhookDeliveries", {}, 400, "InvalidRequest"], ["listWebhookDeliveries", { webhooks: "abc" }, 400, "InvalidRequest"], ["listWebhookDeliveries", { webhooks: "1", limit: 0 }, 400, "InvalidRequest"], ["listWebhookDeliveries", { webhooks: "1", limit: 101 }, 400, "InvalidRequest"], [ "listWebhookDeliveries", { webhooks: Array.from({ length: 51 }, (_, i) => i) }, 400, "InvalidRequest", ], ])("%s answers %j with %i", async (method, input, status, error) => { const res = await call(method, input); expect(res.status).toBe(status); expect(await res.json()).toMatchObject({ error }); });
it("refuses an update with an invalid URL or event", async () => { const id = await create(); for (const input of [{ url: "http://10.0.0.1/" }, { events: ["nope"] }]) { // oxlint-disable-next-line no-await-in-loop const res = await call("updateWebhook", { webhook: id, ...input }); expect(res.status).toBe(400); } expect(await list()).toMatchObject([{ url: target, events: ["push"] }]); });
it.each([ ["createWebhook", { url: target, events: ["push"] }], ["updateWebhook", { webhook: "1" }], ["deleteWebhook", { webhook: "1" }], ["listWebhooks", {}], ["listWebhookDeliveries", { webhooks: "1" }], ["retryWebhookDelivery", { webhook: "1", delivery: "x" }], ])("guards %s", async (method, input) => { const denied = await call(method, input, { key: strangerKey, iss: stranger }); expect(denied.status).toBe(403); const unauthenticated = await exports.default.fetch( `https://${host}/xrpc/org.tangled.webhook.${method}?repo=${repo}`, { method: method.startsWith("list") ? "GET" : "POST" }, ); expect(unauthenticated.status).toBe(401); const byRepo = await call(method, input, { key: repoKey, iss: repo }); expect([200, 404]).toContain(byRepo.status); manifestSpindle = "did:web:other.example.com"; const unserved = await call(method, input); expect(unserved.status).toBe(404); expect(await unserved.json()).toMatchObject({ error: "RepoNotFound" }); });});
describe("delivery", () => { it("posts the event with its headers and signature, and records the delivery", async () => { const id = await create({ secret: " s3cret " }); await firePush(); const [request, ...more] = sent; expect(more).toEqual([]); expect(request?.redirect).toBe("manual"); const body = request?.body ?? ""; expect(JSON.parse(body)).toEqual(pushBody); const headers = Object.fromEntries(request?.headers ?? []); expect(headers).toMatchObject({ "content-type": "application/json", "user-agent": "Tangled-Hook/abcdef0", "x-tangled-event": "push", "x-tangled-hook-id": id, "x-tangled-repo": `${owner}/my.repo`, "x-tangled-signature-256": await hmac("s3cret", body), }); expect(headers["x-tangled-delivery"]).toMatch( /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/, ); const [delivery] = await deliveries([id]); expect(delivery).toMatchObject({ id: headers["x-tangled-delivery"], webhook: id, event: "push", url: target, success: true, responseCode: 200, }); expect(text(delivery?.requestBody)).toBe(body); expect(text(delivery?.responseBody)).toBe("thanks"); });
it("sends no signature without a secret, and after the secret is cleared", async () => { await create(); const signed = await create({ secret: "s3cret" }); await call("updateWebhook", { webhook: signed, secret: "" }); await firePush(); expect(sent).toHaveLength(2); for (const request of sent) { expect(request.headers.has("x-tangled-signature-256")).toBe(false); } });
it("keeps the secret when an update omits it, and trims a new secret", async () => { const kept = await create({ secret: "s3cret" }); await call("updateWebhook", { webhook: kept, active: true }); const changed = await create({ secret: "s3cret" }); await call("updateWebhook", { webhook: changed, secret: " n3w " }); await firePush(); const signature = (hook: string): string | null | undefined => sent .find((request) => request.headers.get("x-tangled-hook-id") === hook) ?.headers.get("x-tangled-signature-256"); const body = sent[0]?.body ?? ""; expect(signature(kept)).toBe(await hmac("s3cret", body)); expect(signature(changed)).toBe(await hmac("n3w", body)); });
it("sends only to active webhooks of the event, once for each push", async () => { await create({ active: false }); await create({ events: ["pull_request:created"] }); const id = await create(); expect(await hooks.subscribed(["push"])).toBe(true); expect(await hooks.subscribed(["pull_request:merged"])).toBe(false); await firePush(); await firePush(); expect(sent).toHaveLength(1); expect(sent[0]?.headers.get("x-tangled-hook-id")).toBe(id); await firePush("push-2"); expect(sent).toHaveLength(2); });
it("tries a server error three times and records one failed delivery", async () => { const id = await create(); routes[`POST ${target}`] = () => new Response("down", { status: 503 }); await firePush(); await retryNow(); await retryNow(); await retryNow(); expect(sent).toHaveLength(3); expect(new Set(sent.map((r) => r.headers.get("x-tangled-delivery"))).size).toBe(1); const [delivery, ...rest] = await deliveries([id]); expect(rest).toEqual([]); expect(delivery).toMatchObject({ success: false, responseCode: 503 }); expect(text(delivery?.responseBody)).toBe("server error: 503"); });
it("tries a network error again and records the later success", async () => { const id = await create(); let calls = 0; routes[`POST ${target}`] = () => (++calls === 1 ? offline() : new Response("ok")); await firePush(); expect(await deliveries([id])).toEqual([]); await retryNow(); expect(calls).toBe(2); expect(await deliveries([id])).toMatchObject([{ success: true, responseCode: 200 }]); });
it("records a network error after three attempts", async () => { const id = await create(); routes[`POST ${target}`] = offline; await firePush(); await retryNow(); await retryNow(); const [delivery] = await deliveries([id]); expect(delivery).toMatchObject({ success: false }); expect(delivery).not.toHaveProperty("responseCode"); expect(text(delivery?.responseBody)).toBe("offline"); });
it.each([ ["a client error", () => new Response("no", { status: 404 }), 404], [ "a redirect", () => new Response(null, { status: 302, headers: { Location: "https://x.example.com/" }, }), 302, ], ])("does not try %s again", async (_, response, code) => { const id = await create(); routes[`POST ${target}`] = response; await firePush(); await retryNow(); expect(sent).toHaveLength(1); expect(await deliveries([id])).toMatchObject([{ success: false, responseCode: code }]); });
it("keeps the first 10 KiB of the response bytes", async () => { const id = await create(); const data = Uint8Array.from({ length: 20_000 }, (_, i) => i % 256); routes[`POST ${target}`] = () => new Response(data); await firePush(); const [delivery] = await deliveries([id]); expect(Uint8Array.fromBase64(delivery?.responseBody?.$bytes ?? "")).toEqual( data.subarray(0, 10_240), ); });
it("keeps the last 50 deliveries of each webhook and lists the newest first", async () => { const id = await create(); const other = await create(); for (let i = 0; i < 52; i++) { // oxlint-disable-next-line no-await-in-loop await hooks.firePush(`push-${i}`, { ...pushBody, n: i }, "Tangled-Hook/abcdef0"); } await drain(); const all = await deliveries([id], 100); expect(all).toHaveLength(50); expect(JSON.parse(text(all[0]?.requestBody))).toMatchObject({ n: 51 }); expect(await deliveries([id])).toHaveLength(50); expect(await deliveries([id], 5)).toHaveLength(5); const both = await deliveries([id, other], 2); expect(both.map((d) => d.webhook)).toEqual([id, id, other, other]); });
it("sends a delivery again with a new id and the stored body", async () => { const id = await create({ secret: "s3cret" }); await firePush(); const [first] = await deliveries([id]); const res = await call("retryWebhookDelivery", { webhook: id, delivery: first?.id }); expect(res.status).toBe(200); await drain(); expect(sent).toHaveLength(2); const retried = sent[1]; expect(retried?.headers.get("user-agent")).toBe("Tangled-Hook/retry"); expect(retried?.headers.get("x-tangled-repo")).toBe(`${owner}/my.repo`); expect(retried?.headers.get("x-tangled-delivery")).not.toBe(first?.id); const body = retried?.body ?? ""; expect(body).toBe(text(first?.requestBody)); expect(retried?.headers.get("x-tangled-signature-256")).toBe(await hmac("s3cret", body)); expect(await deliveries([id])).toHaveLength(2);
const other = await create(); const wrong = await call("retryWebhookDelivery", { webhook: other, delivery: first?.id }); expect(wrong.status).toBe(404); expect(await wrong.json()).toMatchObject({ error: "DeliveryNotFound" }); });
it.each(["createWebhook", "updateWebhook", "deleteWebhook", "retryWebhookDelivery"])( "refuses a replayed %s token", async (method) => { const id = await create(); await firePush(); const [first] = await deliveries([id]); const input = { webhook: id, delivery: first?.id, url: target, events: ["push"] }; const jti = `once-${method}`; expect((await call(method, input, { jti })).status).toBe(200); const replay = await call(method, input, { jti }); expect(replay.status).toBe(403); expect(await replay.json()).toMatchObject({ error: "Auth" }); }, );
it("drops the queued deliveries of a deleted webhook", async () => { const id = await create(); routes[`POST ${target}`] = () => new Response("down", { status: 500 }); await firePush(); await call("deleteWebhook", { webhook: id }); await retryNow(); expect(sent).toHaveLength(1); });});