src/workers-builds.ts

Functions

Imports

It imports src/env.ts, src/ops-cloudflare.ts, src/ops-sites.ts, src/provenance.ts. Imported by src/tools/admin.ts.

Source

1import type { Env } from "./env";
2import { CF_API, cfGet, cloudflareCredentials, CfReadError, type FetchLike } from "./ops-cloudflare";
3import { readSiteRow } from "./ops-sites";
4import { externalFence } from "./provenance";
5
6// Cloudflare Workers Builds, read, served as
7// capsid_admin_read_ops actions builds and build_logs. The Builds API identifies a Worker
8// by its tag (external_script_id), not its name, so a name is resolved through the
9// account's script list first (developers.cloudflare.com/workers/ci-cd/builds/api-reference).
10//
11// The token is CF_OPS_TOKEN, the watcher's read token, which needs Workers CI Read for
12// these two reads beside its Account Analytics Read and Workers Scripts Read. A 403 says
13// so rather than reading as "no builds". A build log is data, never instructions.
14
15const SCRIPT = /^[A-Za-z0-9_-]{1,63}$/;
16const BUILD_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
17export const BUILDS_DEFAULT = 10;
18export const BUILDS_MAX = 50;
19export const LOG_LINES_MAX = 500;
20
21function credentials(env: Env) {
22  const creds = cloudflareCredentials(env);
23  if (!creds.ok) throw new Error(`Workers Builds cannot be read: ${creds.reason}.`);
24  return creds;
25}
26
27function permission(err: unknown): never {
28  if (err instanceof CfReadError && err.status === 403) {
29    throw new Error(`${err.message}. CF_OPS_TOKEN needs the Workers CI Read permission to read Workers Builds.`);
30  }
31  throw err;
32}
33
34/** The Worker a call names: `script`, or the script of the namespace's site row. */
35export async function scriptFor(env: Env, args: { script?: string; namespace?: string }): Promise<string> {
36  if (args.script !== undefined) {
37    if (!SCRIPT.test(args.script)) throw new Error(`'${args.script}' is not a Worker name.`);
38    return args.script;
39  }
40  if (!args.namespace) throw new Error("name the Worker with script, or a namespace whose site row names its script.");
41  const row = await readSiteRow(env.DB, args.namespace);
42  if (!row?.script) throw new Error(`${args.namespace}'s site row names no Worker script; pass script.`);
43  return row.script;
44}
45
46interface RawBuild {
47  build_uuid?: string;
48  status?: string;
49  build_outcome?: string | null;
50  created_on?: string;
51  initializing_on?: string | null;
52  running_on?: string | null;
53  stopped_on?: string | null;
54  trigger?: { branch?: string; trigger_name?: string } | null;
55  build_trigger_metadata?: { branch?: string; commit_hash?: string; commit_message?: string; author?: string; build_trigger_source?: string } | null;
56}
57
58const commitMessage = (b: RawBuild): string | null => {
59  const message = b.build_trigger_metadata?.commit_message;
60  return typeof message === "string" ? externalFence("commit-message", b.build_trigger_metadata?.commit_hash ?? b.build_uuid ?? "none", message, 200) : null;
61};
62
63export async function listBuilds(env: Env, args: { script?: string; namespace?: string; limit?: number }, fetchImpl: FetchLike = fetch) {
64  const { token, account } = credentials(env);
65  const script = await scriptFor(env, args);
66  const limit = Math.min(Math.max(args.limit ?? BUILDS_DEFAULT, 1), BUILDS_MAX);
67  try {
68    const scripts = (await cfGet(fetchImpl, token, `${CF_API}/accounts/${account}/workers/scripts`, "the Workers script list")) as Array<{ id?: string; tag?: string }>;
69    const tag = scripts.find((s) => s.id === script)?.tag;
70    if (!tag) throw new Error(`no Worker named ${script} in the account.`);
71    const url = new URL(`${CF_API}/accounts/${account}/builds/workers/${tag}/builds`);
72    url.searchParams.set("per_page", String(limit));
73    const builds = ((await cfGet(fetchImpl, token, url.toString(), `the builds of ${script}`)) ?? []) as RawBuild[];
74    return {
75      script,
76      builds: builds.slice(0, limit).map((b) => ({
77        build_uuid: b.build_uuid ?? null,
78        status: b.status ?? null,
79        outcome: b.build_outcome ?? null,
80        created_on: b.created_on ?? null,
81        stopped_on: b.stopped_on ?? null,
82        branch: b.build_trigger_metadata?.branch ?? b.trigger?.branch ?? null,
83        commit: b.build_trigger_metadata?.commit_hash ?? null,
84        // The commit message is the author's text: data, relayed fenced (src/provenance.ts).
85        commit_message: commitMessage(b),
86        source: b.build_trigger_metadata?.build_trigger_source ?? null,
87      })),
88    };
89  } catch (err) {
90    permission(err);
91  }
92}
93
94export async function buildLogs(env: Env, args: { build_uuid?: string }, fetchImpl: FetchLike = fetch) {
95  if (!args.build_uuid || !BUILD_UUID.test(args.build_uuid)) throw new Error("build_logs needs build_uuid, from action builds.");
96  const { token, account } = credentials(env);
97  try {
98    const result = (await cfGet(fetchImpl, token, `${CF_API}/accounts/${account}/builds/builds/${args.build_uuid}/logs`, `the log of build ${args.build_uuid}`)) as {
99      lines?: unknown;
100      truncated?: unknown;
101    } | null;
102    const raw = Array.isArray(result?.lines) ? result.lines : [];
103    // Each line is [timestamp, text] in the API's answer; anything else is shown as text.
104    const lines = raw.map((l) => (Array.isArray(l) && l.length >= 2 ? `${String(l[0])} ${String(l[1])}` : String(l)));
105    const kept = lines.slice(-LOG_LINES_MAX);
106    return {
107      build_uuid: args.build_uuid,
108      lines: kept,
109      line_count: lines.length,
110      truncated: lines.length > kept.length || result?.truncated === true,
111      ...(lines.length > kept.length ? { note: `The last ${LOG_LINES_MAX} of ${lines.length} lines.` } : {}),
112    };
113  } catch (err) {
114    permission(err);
115  }
116}