src/manual-steps.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/secret-presence.ts. Imported by src/inbox.ts, src/stale-jobs.ts, src/watcher-gather.ts.

Source

1import type { Env } from "./env";
2import { ghFetch, resolveRepo } from "./github/client";
3import { readStoredSecrets, type StoredSecrets } from "./secret-presence";
4
5// DUSTIN'S MANUAL STEPS, DONE ONLY WHEN CAPSID CAN SEE THEM (improvement list item 14).
6// A session that needs a person to click something (approve an npm publish, add an Access
7// app, set a secret, fill a repo's About box) blocks its job as for any gate
8// (src/jobs-holder.ts): the reason carries the click steps, and a line of the form
9// "check: <form>" in the reason or the command names the result Capsid looks for. The
10// forms (docs/work-queue.md):
11//   check: secret NAME on <namespace>     the site's Worker has the secret NAME, from the
12//                                         names the watcher stored (src/secret-presence.ts)
13//   check: npm <package>@<version>        npm lists that version (registry.npmjs.org)
14//   check: access app <name>              Cloudflare Access has an application of that name
15//   check: github about <owner/repo> [homepage <url>]
16//                                         the repo has a description and a homepage (that
17//                                         homepage, when one is named), read through the App
18// A check line in any other form is a result Capsid cannot see, so it never counts as seen.
19//
20// The watcher's pass reads them (src/watcher.ts) and writes the counts per job to one APP_KV
21// value, as the merge-resume step does for pull requests (src/stale-jobs.ts): the inbox and
22// the stale view read the counts and never call out. A job whose every named step is seen
23// after it last changed is settled exactly as a merged pull request settles one: the inbox
24// stops showing it as waiting on Dustin, and the stale view lists it as steps-seen so it is
25// closed or resumed. Nothing here moves a job. A failed read is "unread", never "seen".
26
27export const STALE_STEPS_KEY = "stale:steps";
28const MAX_JOBS = 25;
29const MAX_STEPS = 5;
30
31export type ManualStep =
32  | { kind: "secret"; name: string; namespace: string; text: string }
33  | { kind: "npm"; name: string; version: string; text: string }
34  | { kind: "access-app"; name: string; text: string }
35  | { kind: "github-about"; repo: string; homepage: string | null; text: string }
36  | { kind: "unknown"; text: string };
37
38const CHECK_LINE = /^[ \t]*check:[ \t]*(.+?)[ \t]*$/gim;
39const SECRET = /^secret\s+([A-Za-z_][A-Za-z0-9_]*)\s+on\s+([a-z0-9][a-z0-9_-]*)$/i;
40const NPM = /^npm\s+((?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*)@(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?)$/;
41const ACCESS_APP = /^access\s+app\s+(.+)$/i;
42const GITHUB_ABOUT = /^github\s+about\s+([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)(?:\s+homepage\s+(https?:\/\/\S+))?$/i;
43
44/** One check line's form, or kind "unknown" for a line Capsid has no read for. */
45export function parseStep(text: string): ManualStep {
46  let m: RegExpMatchArray | null;
47  if ((m = text.match(SECRET))) return { kind: "secret", name: m[1]!, namespace: m[2]!.toLowerCase(), text };
48  if ((m = text.match(NPM))) return { kind: "npm", name: m[1]!, version: m[2]!, text };
49  if ((m = text.match(GITHUB_ABOUT))) return { kind: "github-about", repo: m[1]!, homepage: m[2] ?? null, text };
50  if ((m = text.match(ACCESS_APP))) return { kind: "access-app", name: m[1]!.trim(), text };
51  return { kind: "unknown", text };
52}
53
54/** The manual steps a blocked job's summary names, one per distinct check line. */
55export function stepsNamed(summary: string): ManualStep[] {
56  const lines = [...new Set([...summary.matchAll(CHECK_LINE)].map((m) => m[1]!))];
57  return lines.map(parseStep);
58}
59
60export type StepState = "seen" | "unseen" | "unread";
61
62export interface StaleStepEntry {
63  seen: number;
64  unseen: number;
65  unread: number;
66  // ISO time of the read.
67  at: string;
68}
69
70export type StaleStepCache = Record<string, StaleStepEntry>;
71
72export function tallySteps(states: readonly StepState[], at: string): StaleStepEntry {
73  const entry: StaleStepEntry = { seen: 0, unseen: 0, unread: 0, at };
74  for (const state of states) entry[state] += 1;
75  return entry;
76}
77
78/** Every step the job names was seen, and it named at least one. */
79export function stepsSeen(entry: StaleStepEntry | undefined): boolean {
80  return entry !== undefined && entry.unseen === 0 && entry.unread === 0 && entry.seen > 0;
81}
82
83const isCount = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 0;
84
85/** The stored cache, keeping only entries of the right shape. Never written is empty;
86 *  anything unreadable is reported, not thrown. */
87export function parseStepCache(text: string | null): { cache: StaleStepCache; problem: string | null } {
88  if (text === null) return { cache: {}, problem: null };
89  let raw: unknown;
90  try {
91    raw = JSON.parse(text);
92  } catch {
93    return { cache: {}, problem: `${STALE_STEPS_KEY} is not JSON` };
94  }
95  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { cache: {}, problem: `${STALE_STEPS_KEY} is not a JSON object` };
96  const cache: StaleStepCache = {};
97  let dropped = 0;
98  for (const [id, e] of Object.entries(raw as Record<string, unknown>)) {
99    const v = (e ?? {}) as Record<string, unknown>;
100    if (isCount(v.seen) && isCount(v.unseen) && isCount(v.unread) && typeof v.at === "string") cache[id] = { seen: v.seen, unseen: v.unseen, unread: v.unread, at: v.at };
101    else dropped++;
102  }
103  return { cache, problem: dropped > 0 ? `${STALE_STEPS_KEY} held ${dropped} entr${dropped === 1 ? "y" : "ies"} of the wrong shape, left out` : null };
104}
105
106export async function readStepCache(kv: KVNamespace): Promise<{ cache: StaleStepCache; problem: string | null }> {
107  return parseStepCache(await kv.get(STALE_STEPS_KEY));
108}
109
110// What the pass can read. Each reader throws on a failed read.
111export interface StepReaders {
112  secrets(namespace: string): Promise<StoredSecrets | null>;
113  // null: npm has no such package.
114  npmVersions(name: string): Promise<string[] | null>;
115  accessAppNames(): Promise<string[]>;
116  githubAbout(namespace: string, repo: string): Promise<{ description: string | null; homepage: string | null }>;
117}
118
119const trimSlash = (url: string) => url.replace(/\/+$/, "");
120
121/** One step as the readers see it now. A read that throws is unread. A secret read before
122 *  the job last changed says nothing about the step, so it is unread too. */
123export async function stepState(step: ManualStep, job: { namespace: string; updated_at: string }, readers: StepReaders): Promise<StepState> {
124  try {
125    switch (step.kind) {
126      case "secret": {
127        const stored = await readers.secrets(step.namespace);
128        if (!stored || stored.state !== "ok" || stored.read_at < job.updated_at) return "unread";
129        return stored.rows.some((r) => r.name === step.name && r.set) ? "seen" : "unseen";
130      }
131      case "npm": {
132        const versions = await readers.npmVersions(step.name);
133        return versions !== null && versions.includes(step.version) ? "seen" : "unseen";
134      }
135      case "access-app": {
136        const want = step.name.toLowerCase();
137        return (await readers.accessAppNames()).some((n) => n.trim().toLowerCase() === want) ? "seen" : "unseen";
138      }
139      case "github-about": {
140        const about = await readers.githubAbout(job.namespace, step.repo);
141        if (!about.description?.trim() || !about.homepage?.trim()) return "unseen";
142        return step.homepage === null || trimSlash(about.homepage.trim()) === trimSlash(step.homepage) ? "seen" : "unseen";
143      }
144      case "unknown":
145        return "unread";
146    }
147  } catch {
148    return "unread";
149  }
150}
151
152/** The live readers, each remembered for the pass so a name read twice is fetched once. */
153export function liveStepReaders(
154  env: Env,
155  reads: { npmVersions: (name: string) => Promise<string[] | null>; accessAppNames: () => Promise<string[]> }
156): StepReaders {
157  const once = <T>(memo: Map<string, Promise<T>>, key: string, read: () => Promise<T>): Promise<T> => {
158    let p = memo.get(key);
159    if (!p) memo.set(key, (p = read()));
160    return p;
161  };
162  const secrets = new Map<string, Promise<StoredSecrets | null>>();
163  const npm = new Map<string, Promise<string[] | null>>();
164  const access = new Map<string, Promise<string[]>>();
165  const about = new Map<string, Promise<{ description: string | null; homepage: string | null }>>();
166  return {
167    secrets: (namespace) => once(secrets, namespace, () => readStoredSecrets(env, namespace)),
168    npmVersions: (name) => once(npm, name, () => reads.npmVersions(name)),
169    accessAppNames: () => once(access, "", reads.accessAppNames),
170    githubAbout: (namespace, selector) =>
171      once(about, `${namespace} ${selector}`, async () => {
172        // The repo must be one the job's namespace maps, as for the pull requests merge-resume reads.
173        const { owner, repo } = await resolveRepo(env, namespace, selector);
174        const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}`);
175        if (!resp.ok) throw new Error(`GitHub answered ${resp.status} for ${owner}/${repo}`);
176        const r = (await resp.json()) as { description?: unknown; homepage?: unknown };
177        return { description: typeof r.description === "string" ? r.description : null, homepage: typeof r.homepage === "string" ? r.homepage : null };
178      }),
179  };
180}
181
182export interface ManualStepsReport {
183  looked: number;
184  seen: string[];
185  note: string;
186}
187
188/**
189 * The watcher's step: read the steps every blocked job names (the oldest MAX_JOBS, up to
190 * MAX_STEPS each; a job naming more is left unread) and rewrite STALE_STEPS_KEY whole, so a
191 * job no longer blocked or no longer naming a step drops out.
192 */
193export async function checkManualSteps(env: Pick<Env, "DB" | "APP_KV">, now: Date, readers: StepReaders): Promise<ManualStepsReport> {
194  const { results } = await env.DB.prepare(
195    "SELECT id, namespace, result_summary, updated_at FROM jobs WHERE status = 'blocked' AND result_summary LIKE '%check:%' ORDER BY updated_at LIMIT ?1"
196  )
197    .bind(MAX_JOBS)
198    .all<{ id: string; namespace: string; result_summary: string | null; updated_at: string }>();
199  const at = now.toISOString();
200  const cache: StaleStepCache = {};
201  const seen: string[] = [];
202  for (const job of results ?? []) {
203    const steps = stepsNamed(job.result_summary ?? "");
204    if (steps.length === 0) continue;
205    const states = steps.length > MAX_STEPS ? steps.map((): StepState => "unread") : await Promise.all(steps.map((s) => stepState(s, job, readers)));
206    cache[job.id] = tallySteps(states, at);
207    if (stepsSeen(cache[job.id])) seen.push(job.id);
208  }
209  await env.APP_KV.put(STALE_STEPS_KEY, JSON.stringify(cache));
210  const looked = Object.keys(cache).length;
211  return { looked, seen, note: `read the manual steps of ${looked} blocked job(s), every step seen on ${seen.length}${seen.length ? `: ${seen.join(", ")}` : ""}` };
212}