From 9168f629780101790f125c2b62e5f16088b17ba9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:08:21 -0800 Subject: [PATCH 1/4] chore(quest): claim quest/m0/github-quota/installation-token.md Quest-Claim: b64d41df3c92d367 From be2c722e2c2b982412737b992e7fd00695ee61ba Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:17:12 -0800 Subject: [PATCH 2/4] feat(github)!: read on an installation token from Kixel Quest Co-Authored-By: Claude Sonnet 5.5 --- README.md | 14 ++ quest/m0/github-quota/README.md | 47 ++-- quest/m0/github-quota/installation-token.md | 58 ----- src/cli/claims.ts | 9 +- src/cli/forge.ts | 103 +++++++- src/cli/installation.ts | 74 ++++++ src/cli/main.ts | 20 +- src/cli/review-record.ts | 2 +- src/cli/start.ts | 4 +- src/github/claims.ts | 10 +- src/github/client.ts | 100 ++++++-- src/github/duplicates.ts | 4 +- src/github/files.ts | 6 +- src/github/forge.ts | 18 +- src/github/hold.ts | 16 +- src/github/index.ts | 10 +- src/github/online-review.ts | 6 +- src/github/signals.ts | 6 +- src/github/status.ts | 20 +- src/github/view.ts | 4 +- src/github/wait.ts | 12 +- test/forge-writes.test.ts | 1 + test/forge.test.ts | 29 ++- test/installation.test.ts | 253 ++++++++++++++++++++ test/pull-files.test.ts | 2 + test/start.test.ts | 8 +- test/status-fakes.ts | 6 +- test/status.test.ts | 4 +- test/usage.test.ts | 1 + test/wait-fakes.ts | 8 +- 30 files changed, 657 insertions(+), 198 deletions(-) delete mode 100644 quest/m0/github-quota/installation-token.md create mode 100644 src/cli/installation.ts create mode 100644 test/installation.test.ts diff --git a/README.md b/README.md index cef4502f..17a735f7 100644 --- a/README.md +++ b/README.md @@ -636,6 +636,20 @@ command fails too, naming `QUEST_FORGE=github`, which reads GitHub instead. `QUEST_KIXEL_URL` names another Kixel Quest, such as one running locally, whose token the same file pairs with its URL. +A read that must come from GitHub itself, such as `quest pr view` or the +open-PR checks of `quest start`, uses a read-only App installation token Kixel +Quest mints for that repository, so it draws on the installation's rate limit, +not the person's. `POST /installation-token` takes `{"repository": +"owner/repo"}` and answers `{token, expiresAt, repository, login}`; a 404 means +Kixel Quest does not serve the repository, and `quest` reads it with the +person's own token. `quest` keeps each token in +`$XDG_CACHE_HOME/quest/installation` (else `~/.cache/quest/installation`) until +five minutes before it expires, since a person may mint only so many an hour, +and a 429 or any other failure fails the command, naming `QUEST_FORGE=github`. +Writes, such as comments, pushes, and merges, always use the person's own token, +so they are made in their name; `quest wait` takes the person from the mint's +`login`, because on an installation token GitHub names the App as the viewer. + Its read API lives under `/forge`, with the token as a bearer token: `GET /forge` answers `{"login", "repositories"}`, the person the token names and the lowercase `owner/repo` of each repository served to them, and diff --git a/quest/m0/github-quota/README.md b/quest/m0/github-quota/README.md index 5c49b25a..f69ae39d 100644 --- a/quest/m0/github-quota/README.md +++ b/quest/m0/github-quota/README.md @@ -1,12 +1,14 @@ -# Spend less of a person's GitHub quota +# [S] Record a day of GitHub quota use under the new reads ## Goal -Agents polling `quest status`, `quest wait`, and `quest unblocked` stop -draining the GitHub quota of the person running them. Three changes, each -useful alone: every REST GET revalidates with an ETag, reads use an App -installation token from Kixel Quest instead of the person's, and a forge -interface lets quest read pull request state from Kixel Quest's index. +Agents polling `quest status`, `quest wait`, and `quest unblocked` no longer +drain the GitHub quota of the person running them: every REST GET revalidates +with an ETag, reads use an App installation token from Kixel Quest, and a forge +interface reads pull request state from Kixel Quest's index. All three have +landed; what remains is the evidence. Record the person's REST `core` and +GraphQL use over a day of the maintainer's agents, from `gh api rate_limit`, +beside the outage day's, in this quest's PR, then delete this quest. Non-goals: emulating GitHub's API in Kixel Quest, and anything new for outside contributors, who keep reading GitHub with their own token. @@ -15,27 +17,12 @@ outside contributors, who keep reading GitHub with their own token. Decided 2026-11-15 (maintainer, `/quest-plan` in kixel-ai/kixel.quest, [kixel-ai/kixel.quest#48](https://github.com/kixel-ai/kixel.quest/pull/48), -"we're rate limited by github"): ✅ all three of reads from Kixel Quest, -ETags on every GET, and reads on an installation token (rejected: any one -alone). That day REST `core` sat at 0 of 5,000 on the maintainer's token -while about 20 agents checked PR status. - -Decided 2026-11-15 (maintainer, `/quest-plan` here): - -- ✅ quest has Kixel Quest's URL built in, overridable by an environment - variable for development, and names a repository by `owner/repo` from its - remote (rejected: a committed `.quest.json` naming the endpoint, which no - repository had committed yet and which could drift from what Kixel Quest - indexes). Kixel Quest says which repositories it serves; the rest use - GitHub. Session records route the same way. -- ✅ Kixel Quest is used only by a person holding a Kixel Quest token, which - its admin-managed allow-list gives out; outside contributors stay a - non-goal for now (rejected: a self-serve contributor role, picked and then - withdrawn in the same interview). -- ✅ A chosen Kixel Quest backend that errors fails the command and names the - setting that forces GitHub (rejected: falling back to GitHub, which hides - a broken index and spends the quota this saves). - -The epic's closing PR records the person's REST `core` and GraphQL use over a -day of the maintainer's agents, from `gh api rate_limit`, beside the outage -day's. +"we're rate limited by github"): all three of reads from Kixel Quest, ETags on +every GET, and reads on an installation token. That day REST `core` sat at 0 of +5,000 on the maintainer's token while about 20 agents checked PR status. + +An installation token serves only reads that go to GitHub itself, such as `quest +pr view` and the verifying reads of `quest start`; where Kixel Quest serves the +repository, its index answers the rest. Compare the person's own `core` and +GraphQL `used` per hour, from `gh api rate_limit`, on a day the maintainer's +agents ran as usual. diff --git a/quest/m0/github-quota/installation-token.md b/quest/m0/github-quota/installation-token.md deleted file mode 100644 index f161eeec..00000000 --- a/quest/m0/github-quota/installation-token.md +++ /dev/null @@ -1,58 +0,0 @@ -# [S] Read on an installation token from Kixel Quest - -## Goal - -A person signed in to Kixel Quest reads GitHub on a short-lived, read-only -App installation token that Kixel Quest mints, so their reads draw on the -installation's own rate-limit bucket, not their personal 5,000 an hour. -Writes, such as comments, pushes, and merges, stay on the person's token, -so they are made in that person's name. - -## Plan - -Decided 2026-11-15 (maintainer, `/quest-plan`): ✅ Kixel Quest mints the token -(rejected: the App's private key on every host, which would put a key that -writes to every installation on every agent host). - -- quest trades the person's Kixel Quest token for an installation token - scoped to one repository with read permissions, and caches it on disk - until shortly before it expires. -- The endpoint, from - [kixel-ai/kixel.quest#51](https://github.com/kixel-ai/kixel.quest/pull/51): - `POST /installation-token` with the person's Kixel Quest token as a bearer - token and `{"repository": "owner/repo"}`. A 200 answers - `{token, expiresAt, repository, login}`. A 404 means the repository is not - indexed or the person cannot read it; 429, with `Retry-After`, means the - person hit the per-person hourly cap; 502 and 503 mean GitHub or the App - refused the mint. -- Cache each token by repository until shortly before `expiresAt`: a host - then mints about once per repository an hour, and minting per command - would hit the cap within a minute. -- Without a Kixel Quest token, or on a 404, reads use the person's token as - today, since the answer says the repository is not served. Any other - error fails the command naming the setting that forces the person's - token, as the [epic](/quest/m0/github-quota/README.md) decided for the - Kixel Quest backend; a 429 never quietly spends the person's quota. -- Split the client's dependencies so a read and a write each say which token - they use; a write on the installation token must not compile. -- Keep the caller's identity apart from the read credential. `quest wait` - reads `viewer { login }` in the same query as the PR's activity - (`src/cli/wait.ts`) to ignore the person's own replies, reactions, labels, - and edits; on an installation token `viewer` is the App, so the person's - own activity would wake the waiter. Take the person from the mint - response's `login` and pass it in. - -Tests: with a fake Kixel Quest and a fake GitHub, a read goes out on the -minted token and a write on the person's; the token is minted once and -reused until near expiry; a 404 reads on the person's token and a 429 -fails naming the override; the person's own reply, reaction, label, and -edit still do not wake `quest wait` when its reads use the minted token; -and a repository Kixel Quest does not serve reads on the person's token. - -## Waiting - -- kixel-ai/kixel.quest: the endpoint above, in - [kixel-ai/kixel.quest#51](https://github.com/kixel-ai/kixel.quest/pull/51), - merged and deployed. Check that #51 merged and that `curl -X POST - https://kixel.quest/installation-token` without a token answers 401, not - 404. diff --git a/src/cli/claims.ts b/src/cli/claims.ts index a84fe294..322f1c51 100644 --- a/src/cli/claims.ts +++ b/src/cli/claims.ts @@ -6,7 +6,6 @@ import { type Remote, readRemote, remoteHost, remoteRepository, requireRemote } import { type GitHubDependencies, GitHub, object, repositoryPath, string } from "../github/client"; import type { Claim, Forge, ForgeWrites, Holdings, OpenPull, Repository } from "../core"; import { questBranches } from "../github/claims"; -import { GitHubForge } from "../github/forge"; import { landingCheck } from "./landed"; import { GitHubWrites } from "./writes"; import { type Snapshot, snapshot } from "./tree"; @@ -16,6 +15,8 @@ export interface ClaimDependencies { github(): GitHubDependencies; /** The forge answering reads of a repository on GitHub, such as its claims and open PRs. */ forge(repository: Repository): Promise; + /** The forge answering a read of a repository on GitHub from GitHub itself, never an index that may lag. */ + live(repository: Repository): Promise; /** Kixel Quest, for remotes on it; without it, no remote is. */ kixel?: { /** The repository `url` on Kixel Quest names, or null for none. */ @@ -38,7 +39,7 @@ export interface Hosting { /** The forge answering reads of `repository`, chosen on first use. */ forge(): Promise; /** The forge's own answers, never an index that may lag, for a read that verifies or rewrites what it read. */ - live(): Forge; + live(): Promise; /** The forge taking writes to `repository`, created on first use. */ writes(): ForgeWrites; /** A link to `path` on the default branch, where the forge shows files. */ @@ -91,7 +92,7 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen defaultBranch: defaultBranch(root, remote.name), prefix: git(root, ["rev-parse", "--show-prefix"]), forge: async () => forge(), - live: forge, + live: async () => forge(), writes: forge, link: () => null, }, @@ -121,7 +122,7 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen defaultBranch: up.defaultBranch, prefix, forge: () => (forge ??= deps.forge(up.repository)), - live: () => new GitHubForge(deps.github()), + live: () => deps.live(up.repository), writes: () => (writes ??= new GitHubWrites(deps.github(), landingCheck(root))), link: (path: string) => `https://github.com/${owner}/${repo}/blob/${up.defaultBranch}/${encodeURI(prefix + path)}`, diff --git a/src/cli/forge.ts b/src/cli/forge.ts index dc62b203..791d3a20 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -1,7 +1,9 @@ // Which forge answers a repository's reads and takes its writes. A repository Kixel Quest hosts, named by a remote or // PR URL on Kixel Quest, is read and written there alone. For one on GitHub, reads go to Kixel Quest's index for a // person holding its token when it serves the repository, else GitHub, and writes go to GitHub. A Kixel Quest failure -// fails the command, naming the setting that reads GitHub instead where that would help. +// fails the command, naming the setting that reads GitHub instead where that would help. A read that goes to GitHub +// anyway, to verify what an index said or because Kixel Quest does not serve the repository, runs on a read-only +// installation token Kixel Quest mints, so it draws on the installation's rate limit rather than the person's. import { type Answer, type ClaimSources, @@ -29,9 +31,10 @@ import { parseForgeInfo, Refusal, } from "../core"; -import type { GitHubDependencies } from "../github/client"; +import { type GitHubDependencies, reading } from "../github/client"; import { GitHubForge } from "../github/forge"; import { pullRequest, readRemote, remoteHost } from "./github"; +import { type Installation, REUSE_MARGIN, installationDirectory, keep, kept } from "./installation"; import { kixelUrl, tokenFor, tokensPath } from "./tokens"; /** The variable that, set to `github`, reads GitHub even where Kixel Quest serves the repository. */ @@ -84,7 +87,25 @@ export async function forgeFor( const kixel = kixelQuest(deps); return kixel !== null && (await kixel.serves(repository, deadline)) ? new KixelQuestForge(kixel) - : new GitHubForge(deps.github()); + : new GitHubForge(reading(deps.github())); +} + +/** + * The forge that answers `repository`'s reads from GitHub itself, never an index that may lag. For a person holding a + * Kixel Quest token it reads on the installation token Kixel Quest mints for the repository, and on the person's own + * where Kixel Quest does not serve it or the reads are forced onto GitHub. Minting gives up at `deadline`. + */ +export async function liveFor( + repository: Repository, + deps: ForgeDependencies, + deadline = Infinity, +): Promise { + const kixel = kixelQuest(deps); + const installation = kixel === null ? null : await kixel.installation(repository, deadline); + const person = reading(deps.github()); + return installation === null + ? new GitHubForge(person) + : new GitHubForge({ ...person, readToken: installation.token }, installation.login); } /** Kixel Quest refused the person's token, as a sender must tell from a failure that may pass. */ @@ -177,6 +198,66 @@ export class KixelQuest { ); } + /** + * A read-only token for `repository`, or null when Kixel Quest does not serve it to this person. Minted at most + * once an hour per repository: a kept token with time left is reused, so a command mints none. + */ + async installation(repository: Repository, deadline = Infinity): Promise { + const directory = installationDirectory(this.deps.env); + const instead = `set ${FORGE}=github to read GitHub with your own token`; + const keeping = (what: string, error: unknown) => + new Error( + `cannot ${what} installation tokens in ${directory}: ${error instanceof Error ? error.message : String(error)}; ${instead}`, + ); + try { + const have = kept(directory, this.url, this.token, repository, this.deps.now()); + if (have !== null) return have; + } catch (error) { + throw keeping("read", error); + } + const path = "/installation-token"; + const name = `${repository.owner}/${repository.repo}`; + const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); + if (response.status === 404) return null; + if (response.status === 429) { + const wait = Number(response.headers.get("retry-after")); + throw this.#failed( + "POST", + path, + `you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`, + ); + } + if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`); + const installation = this.#minted(text, name); + try { + keep(directory, this.url, this.token, repository, installation); + } catch (error) { + throw keeping("keep", error); + } + return installation; + } + + /** The token in a mint's answer, `{token, expiresAt, repository, login}`, for `name`. */ + #minted(text: string, name: string): Installation { + const path = "/installation-token"; + let json: unknown; + try { + json = JSON.parse(text); + } catch { + throw this.#failed("POST", path, "its answer is not JSON"); + } + const { token, expiresAt, repository, login } = (json ?? {}) as Record; + const at = typeof expiresAt === "string" ? Date.parse(expiresAt) : NaN; + if (typeof token !== "string" || token === "" || typeof login !== "string" || login === "" || Number.isNaN(at)) + throw this.#failed("POST", path, "its answer lacks a token, an expiry, or a login"); + if (typeof repository !== "string" || repository.toLowerCase() !== name.toLowerCase()) + throw this.#failed("POST", path, `it minted a token for ${String(repository)}, not ${name}`); + // A token that is already inside its reuse margin would be minted again by every command. + if (at - this.deps.now() <= REUSE_MARGIN) + throw this.#failed("POST", path, `its token expires at ${expiresAt}, too soon to reuse`); + return { token, expiresAt: at, login }; + } + /** The time now, epoch milliseconds. */ now(): number { return this.deps.now(); @@ -203,8 +284,13 @@ export class KixelQuest { return new Error(`Kixel Quest (${this.url}) failed ${method} ${path}: ${why}${instead}`); } - /** The JSON answer to a request, or an error naming the setting that reads GitHub instead. */ - async #send(method: "GET" | "POST", path: string, body: unknown, deadline: number): Promise { + /** The answer to a request, as text; Kixel Quest's refusal of the person's token and any network failure throw. */ + async #fetch( + method: "GET" | "POST", + path: string, + body: unknown, + deadline: number, + ): Promise<{ response: Response; text: string }> { const failed = (why: string) => this.#failed(method, path, why); const remaining = deadline - this.deps.now(); if (remaining <= 0) throw failed("its deadline passed"); @@ -238,6 +324,13 @@ export class KixelQuest { .message, response.status, ); + return { response, text }; + } + + /** The JSON answer to a request, or an error naming the setting that reads GitHub instead. */ + async #send(method: "GET" | "POST", path: string, body: unknown, deadline: number): Promise { + const failed = (why: string) => this.#failed(method, path, why); + const { response, text } = await this.#fetch(method, path, body, deadline); // A malformed wait point, token, thread, or body is the caller's to fix on any forge; the other reads take no // free-form argument, so their 400 means the CLI and Kixel Quest disagree on the wire, which reading GitHub // sidesteps. diff --git a/src/cli/installation.ts b/src/cli/installation.ts new file mode 100644 index 00000000..aa6923a3 --- /dev/null +++ b/src/cli/installation.ts @@ -0,0 +1,74 @@ +// The App installation tokens Kixel Quest mints for a person's reads, kept on disk until shortly before they expire: +// a person's hourly cap on minting is spent within a minute if each command mints its own. +import { createHash } from "node:crypto"; +import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; + +import type { Repository } from "../core"; + +/** A read-only token for one repository, and the person it was minted for. */ +export interface Installation { + token: string; + /** Epoch milliseconds. */ + expiresAt: number; + /** The GitHub login of the person, who is not the token's own account. */ + login: string; +} + +/** How long before expiry a token stops being reused, so a command never starts its reads on one about to lapse. */ +export const REUSE_MARGIN = 5 * 60_000; + +/** Where tokens live: `$XDG_CACHE_HOME/quest/installation`, else `~/.cache/quest/installation`. */ +export function installationDirectory(env: NodeJS.ProcessEnv = process.env): string { + return join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "quest", "installation"); +} + +/** The file for a token: a hash of the Kixel Quest, the person's token for it, and the repository, so none is named. */ +function file(directory: string, url: string, kixelToken: string, repository: Repository): string { + const name = `${repository.owner}/${repository.repo}`.toLowerCase(); + return join(directory, createHash("sha256").update(`${url}\n${kixelToken}\n${name}`).digest("hex")); +} + +/** The kept token for `repository` that still has `REUSE_MARGIN` left at `now`, or null; a damaged file is a miss. */ +export function kept( + directory: string, + url: string, + kixelToken: string, + repository: Repository, + now: number, +): Installation | null { + let text: string; + try { + text = readFileSync(file(directory, url, kixelToken, repository), "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; + throw error; + } + let value: unknown; + try { + value = JSON.parse(text); + } catch { + return null; + } + if (typeof value !== "object" || value === null) return null; + const { token, expiresAt, login } = value as Record; + if (typeof token !== "string" || token === "" || typeof login !== "string" || typeof expiresAt !== "number") + return null; + return expiresAt - now > REUSE_MARGIN ? { token, expiresAt, login } : null; +} + +/** Keep `installation`, private to the user; a finished file is renamed into place, so no reader sees half of one. */ +export function keep( + directory: string, + url: string, + kixelToken: string, + repository: Repository, + installation: Installation, +): void { + mkdirSync(directory, { recursive: true, mode: 0o700 }); + const path = file(directory, url, kixelToken, repository); + const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`; + writeFileSync(temporary, JSON.stringify(installation), { mode: 0o600 }); + renameSync(temporary, path); +} diff --git a/src/cli/main.ts b/src/cli/main.ts index 98ea3b2c..107f025b 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -45,12 +45,12 @@ import { } from "./agent"; import type { ForgeWrites, Hold, Repository } from "../core"; import { GitHubWrites } from "./writes"; -import { GitHubForge } from "../github/forge"; import { type ClaimDependencies, held, openDrafts, reach, target, upstream, upstreamRefs } from "./claims"; import { type ForgeDependencies, type Located, forgeFor, + liveFor, hostedForge, hostedRepository, locate as locatePull, @@ -153,6 +153,7 @@ export function main(argv: string[], out: Output): number | Promise { const claimDependencies = (): ClaimDependencies => ({ github: () => gitHubDependencies(warn), forge: (repository) => forgeFor(repository, forgeDependencies()), + live: (repository) => liveFor(repository, forgeDependencies()), kixel: { hosted: (url) => hostedRepository(kixelUrl(process.env), url), forge: (repository) => hostedForge(repository, forgeDependencies()), @@ -968,11 +969,16 @@ export function main(argv: string[], out: Output): number | Promise { .option("--json", "Print a deterministic JSON object") .action((value: string, options: { json?: boolean }) => { const { pull, hosted } = locatePull(value, root(), process.env); - const forge = hosted ? hostedForge(pull, forgeDependencies()) : new GitHubForge(gitHubDependencies(warn)); - settle(forge.view(pull), ({ value: view }) => { - if (options.json) print(JSON.stringify(view)); - else for (const line of viewLines(view)) print(line); - }); + settle( + (async () => + (hosted ? hostedForge(pull, forgeDependencies()) : await liveFor(pull, forgeDependencies())).view( + pull, + ))(), + ({ value: view }) => { + if (options.json) print(JSON.stringify(view)); + else for (const line of viewLines(view)) print(line); + }, + ); }); pr.command("list") .description( @@ -990,7 +996,7 @@ export function main(argv: string[], out: Output): number | Promise { if (up.hosting === null) throw new InputError("origin names neither a github.com repository nor one on Kixel Quest"); // Verifies a search, so it reads GitHub itself, never an index that may lag. - return up.hosting.live().files(up.hosting.repository); + return (await up.hosting.live()).files(up.hosting.repository); })(), ({ value: pulls }) => { if (options.json) print(JSON.stringify(pulls)); diff --git a/src/cli/review-record.ts b/src/cli/review-record.ts index 30e5bf03..7ac5f180 100644 --- a/src/cli/review-record.ts +++ b/src/cli/review-record.ts @@ -314,7 +314,7 @@ async function openPull( if (hosting === null) return { skipped: `${remote} is not on GitHub or Kixel Quest` }; const { repository, head } = hosting; const name = `${head.owner}/${head.repo}`.toLowerCase(); - const pull = pullsFrom((await hosting.live().pulls(repository)).value, branch).find( + const pull = pullsFrom((await (await hosting.live()).pulls(repository)).value, branch).find( (each) => each.base === base && each.head?.toLowerCase() === name, ); if (pull === undefined) return { skipped: `no open PR from ${head.owner}:${branch} into ${base}` }; diff --git a/src/cli/start.ts b/src/cli/start.ts index 836abf43..beec8144 100644 --- a/src/cli/start.ts +++ b/src/cli/start.ts @@ -193,7 +193,7 @@ async function openDraft( } // Two claimers on different repositories, such as forks, both push; the earliest PR wins. - const open = pullsFrom((await hosting.live().pulls(repository)).value, branch); + const open = pullsFrom((await (await hosting.live()).pulls(repository)).value, branch); const first = pullsFrom([...open.filter((pull) => pull.number !== created.number), created], branch)[0]; if (first.number !== created.number) { deleteBranch(root, remote, branch, sha); @@ -241,7 +241,7 @@ export async function releaseQuest( const hosting = up.hosting; if (hosting) { const head = `${hosting.head.owner}/${hosting.head.repo}`.toLowerCase(); - const open = (await hosting.live().pulls(hosting.repository)).value; + const open = (await (await hosting.live()).pulls(hosting.repository)).value; pulls.push(...pullsFrom(open, branch).filter((pull) => pull.head?.toLowerCase() === head)); } // Deleting first means the lease decides: a push since the check keeps both the branch and its PR. diff --git a/src/github/claims.ts b/src/github/claims.ts index 055de43c..2010e631 100644 --- a/src/github/claims.ts +++ b/src/github/claims.ts @@ -10,10 +10,10 @@ import { handedBack, landed, } from "../core"; -import { type GitHub, object, repositoryPath, string } from "./client"; +import { type GitHubReader, object, repositoryPath, string } from "./client"; /** Every open PR in `repository`, from any head repository. */ -export async function openPullRequests(github: GitHub, repository: Repository): Promise { +export async function openPullRequests(github: GitHubReader, repository: Repository): Promise { const rows = await github.all(`${repositoryPath(repository)}/pulls?state=open&per_page=100`); return rows.map((row) => { const head = object(row.head); @@ -47,7 +47,7 @@ export function questBranches(refs: Map): Map { } /** The `quest/*` branches of `repository`, with their tips. */ -export async function claimBranches(github: GitHub, repository: Repository): Promise> { +export async function claimBranches(github: GitHubReader, repository: Repository): Promise> { const rows = await github.all(`${repositoryPath(repository)}/git/matching-refs/heads/quest/`); return questBranches(new Map(rows.map((row) => [string(row.ref), string(object(row.object).sha)]))); } @@ -58,7 +58,7 @@ export async function claimBranches(github: GitHub, repository: Repository): Pro * PR's branch still holds its quest, since that work may be wanted back. A fork's own branches and PRs * count, so a claim pushed there is seen before its PR opens. Tips a source leaves out are read here. */ -export async function held(github: GitHub, sources: ClaimSources, branches: string[]): Promise { +export async function held(github: GitHubReader, sources: ClaimSources, branches: string[]): Promise { const { upstream, fork } = sources; const read = async (source: ClaimSource) => ({ repository: source.repository, @@ -92,7 +92,7 @@ export async function held(github: GitHub, sources: ClaimSources, branches: stri /** The URL of the PR from `head`'s `branch` that merged into `repository` with `tip` as its head, or `null`. */ export async function mergedPull( - github: GitHub, + github: GitHubReader, repository: Repository, head: Repository, branch: string, diff --git a/src/github/client.ts b/src/github/client.ts index 93acb14f..126bc884 100644 --- a/src/github/client.ts +++ b/src/github/client.ts @@ -7,14 +7,15 @@ const API = "https://api.github.com"; const MAX_SLEEP = 2_147_483_647; /** - * What the client needs from its host: `fetch`, a clock, a way to pause, the token, where warnings - * go, and what to do once the token's hourly quota is spent. + * What a read-only client needs from its host: `fetch`, a clock, a way to pause, the token it reads + * with, where warnings go, and what to do once the token's hourly quota is spent. The read token may + * be an App installation's, which can read but never write; a write takes {@link GitHubDependencies}. */ -export interface GitHubDependencies { +export interface GitHubReadDependencies { fetch: typeof fetch; now(): number; sleep(milliseconds: number): Promise; - token: string; + readToken: string; warn(message: string): void; /** * `wait` sleeps until a spent quota resets, up to an hour, for a daemon or a waiter whose job is to @@ -25,6 +26,20 @@ export interface GitHubDependencies { cache?: ResponseCache; } +/** + * What a client that writes needs: the same, with the person's own token, so what it writes is in their + * name. It has no `readToken`, so it never stands in for read dependencies built on another token. + */ +export interface GitHubDependencies extends Omit { + token: string; +} + +/** `deps` as read dependencies, reading on the person's own token. */ +export function reading(deps: GitHubDependencies): GitHubReadDependencies { + const { token, ...rest } = deps; + return { ...rest, readToken: token }; +} + /** A 200 answer to a GET, kept to serve when GitHub answers its ETag with a 304. */ export interface CachedResponse { etag: string; @@ -95,16 +110,22 @@ function limited(response: Response, body: string): boolean { ); } -/** Authenticated REST and GraphQL requests that wait out rate limits, bounded by an optional deadline. */ -export class GitHub { +/** How {@link GitHubReader.request} reads: a GET, so it takes neither method nor body. */ +export type ReadOptions = Pick; + +/** + * Authenticated REST GETs and GraphQL queries that wait out rate limits, bounded by an optional deadline. It + * cannot write, so it may hold an installation token; {@link GitHub} writes too, on the person's own. + */ +export class GitHubReader { /** The longest X-Poll-Interval GitHub asked for since the caller last set this, in milliseconds. */ pollInterval = 0; /** The response cache, dropped after its first failure. */ private cache: ResponseCache | undefined; constructor( - private readonly deps: GitHubDependencies, - private readonly deadline = Infinity, + protected readonly deps: GitHubReadDependencies, + protected readonly deadline = Infinity, ) { this.cache = deps.cache; } @@ -132,6 +153,11 @@ export class GitHub { if (this.deps.now() >= this.deadline) throw new GitHubDeadline(); } + /** A GET: see {@link GitHubReader.send}. */ + request(path: string, options: ReadOptions = {}): Promise { + return this.send(path, options); + } + /** * A 2xx response, its body already read; anything else fails, with GitHub's reason when it gives * one, unless `allow` lists its status. A GET revalidates the cached answer by its ETag and serves @@ -140,7 +166,7 @@ export class GitHub { * retried with bounded backoff as `repeat` allows, then fails with the last error. `body` makes * it a POST unless `method` says otherwise. */ - async request(path: string, options: RequestOptions = {}): Promise { + protected async send(path: string, options: RequestOptions = {}): Promise { // Follow only same-origin pagination links; never send a token to another host. const url = new URL(path, API); if (url.origin !== API || url.username || url.password) throw new Error("invalid GitHub pagination URL"); @@ -149,7 +175,7 @@ export class GitHub { const accept = options.accept ?? "application/vnd.github+json"; const get = options.body === undefined && options.method === undefined; const cache = get ? this.cache : undefined; - const key = cache && (await cacheKey(this.deps.token, accept, url.href)); + const key = cache && (await cacheKey(this.deps.readToken, accept, url.href)); const cached = key === undefined ? undefined : await this.cached(() => cache!.get(key)); let limits = 0; let failures = 0; @@ -165,7 +191,7 @@ export class GitHub { : { method: options.method ?? "POST", body: JSON.stringify(options.body) }), headers: { Accept: accept, - Authorization: `Bearer ${this.deps.token}`, + Authorization: `Bearer ${this.deps.readToken}`, "X-GitHub-Api-Version": "2022-11-28", "User-Agent": "quest", ...(cached ? { "If-None-Match": cached.etag } : {}), @@ -359,15 +385,19 @@ export class GitHub { } /** - * Run a GraphQL query and return its data, failing on any reported error. A query repeats after - * a 5xx or a dropped connection; a mutation only once its effect is confirmed missing, and one - * confirmed to have taken effect returns no data. GitHub can report a rate limit as a 200 whose - * errors say `RATE_LIMITED`; that is waited out like a REST one. + * Run a GraphQL query and return its data, failing on any reported error, and on a mutation, which only + * {@link GitHub} runs. A query repeats after a 5xx or a dropped connection. GitHub can report a rate limit as a + * 200 whose errors say `RATE_LIMITED`; that is waited out like a REST one. */ async graphql(query: string, variables: ObjectValue): Promise { - const repeat = this.mutationRepeat(query, variables); + if (/^\s*mutation\b/.test(query)) throw new Error("a read-only GitHub client cannot run a mutation"); + return this.operate(query, variables, true); + } + + /** Run a GraphQL operation that repeats as `repeat` says. */ + protected async operate(query: string, variables: ObjectValue, repeat: Repeat): Promise { for (let limits = 0; ; limits++) { - const response = await this.request("/graphql", { body: { query, variables }, repeat }); + const response = await this.send("/graphql", { body: { query, variables }, repeat }); const body = object(await response.json()); if (body.errors === undefined) return object(body.data); const errors = array(body.errors); @@ -380,6 +410,26 @@ export class GitHub { await this.waitOut(response.headers, limits, "GitHub GraphQL rate limit persisted"); } } +} + +/** A client that reads and writes on the person's own token, so what it writes is in their name. */ +export class GitHub extends GitHubReader { + constructor(deps: GitHubDependencies, deadline = Infinity) { + super(reading(deps), deadline); + } + + /** A request of any method, with {@link GitHubReader.send}'s retries. */ + override request(path: string, options: RequestOptions = {}): Promise { + return this.send(path, options); + } + + /** + * Run a GraphQL query, or a mutation: it repeats only once its effect is confirmed missing, and one + * confirmed to have taken effect returns no data. + */ + override graphql(query: string, variables: ObjectValue): Promise { + return this.operate(query, variables, this.mutationRepeat(query, variables)); + } /** * Repeat a query; confirm a pull request mutation `PULL_MUTATIONS` knows; never repeat another. @@ -473,7 +523,7 @@ export interface Requirements { * Every rule a branch's active rulesets apply. GitHub Free offers no rulesets on a private repository and * answers 403 with an upgrade notice, so none apply there; any other refusal fails. */ -async function branchRules(github: GitHub, path: string): Promise { +async function branchRules(github: GitHubReader, path: string): Promise { const first = await github.request(path, { allow: [403] }); if (first.status !== 403) { const next = link(first, "next"); @@ -495,7 +545,7 @@ export function workflowKey(repository: string, path: string): string { } /** The workflow files `rules` require, each keyed by {@link workflowKey} from its rule's `repository_id`. */ -async function requiredWorkflows(github: GitHub, rules: ObjectValue[]): Promise { +async function requiredWorkflows(github: GitHubReader, rules: ObjectValue[]): Promise { const names = new Map(); const keys: string[] = []; for (const row of rules @@ -513,7 +563,11 @@ async function requiredWorkflows(github: GitHub, rules: ObjectValue[]): Promise< } /** What `branch` of `repository` requires, read with read access from branch protection and rulesets. */ -export async function requirements(github: GitHub, repository: Repository, branch: string): Promise { +export async function requirements( + github: GitHubReader, + repository: Repository, + branch: string, +): Promise { const base = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}`; const ref = encodeURIComponent(branch); const protection = object(object(await (await github.request(`${base}/branches/${ref}`)).json()).protection ?? {}); @@ -550,7 +604,7 @@ export async function requirements(github: GitHub, repository: Repository, branc } /** Every GitHub Actions workflow run on `head`. Reading them needs Actions read access. */ -export async function workflowRuns(github: GitHub, repository: Repository, head: string): Promise { +export async function workflowRuns(github: GitHubReader, repository: Repository, head: string): Promise { const runs: WorkflowRun[] = []; let path: string | undefined = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/actions/runs?head_sha=${head}&per_page=100`; @@ -576,7 +630,7 @@ export async function workflowRuns(github: GitHub, repository: Repository, head: * report they can drop. */ export async function currentChecks( - github: GitHub, + github: GitHubReader, repository: Repository, head: string, contexts: T[], @@ -591,7 +645,7 @@ export async function currentChecks( * Whether a merged PR in `repository` had `commit` as its head or below it, as when `quest land` merged * the base into the head before squashing; false for a commit GitHub does not have. */ -export async function mergedHolds(github: GitHub, repository: Repository, commit: string): Promise { +export async function mergedHolds(github: GitHubReader, repository: Repository, commit: string): Promise { const data = await github.graphql( "query($owner: String!, $name: String!, $oid: GitObjectID!) { repository(owner: $owner, name: $name) { " + "object(oid: $oid) { ... on Commit { associatedPullRequests(first: 100) { nodes { merged headRefOid } } } } } }", diff --git a/src/github/duplicates.ts b/src/github/duplicates.ts index e61ebbd7..e905f06f 100644 --- a/src/github/duplicates.ts +++ b/src/github/duplicates.ts @@ -1,7 +1,7 @@ // Quests a PR adds that another open PR also adds, so a follow-up some other PR already owns is // caught before a pick round asks about it. import { type Duplicate, type PullRequest, isQuest, parse } from "../core"; -import { type GitHub, object } from "./client"; +import { type GitHubReader, object } from "./client"; import { openFiles } from "./files"; /** An open PR's added quest files, each with its title, or null when it has none. */ @@ -49,7 +49,7 @@ export function duplicates(self: number, pulls: Added[]): Duplicate[] { /** * The quests `pr` adds that another open PR in its repository also adds. Reads every open PR's files, then the titles of their quests at each PR's head, only when `pr` adds a quest. */ -export async function duplicateQuests(github: GitHub, pr: PullRequest): Promise { +export async function duplicateQuests(github: GitHubReader, pr: PullRequest): Promise { const pulls = (await openFiles(github, pr)).map(({ number, url, head, files }) => ({ number, url, diff --git a/src/github/files.ts b/src/github/files.ts index 332a9d5e..dcf0d61e 100644 --- a/src/github/files.ts +++ b/src/github/files.ts @@ -1,6 +1,6 @@ // Every open PR's changed files, as GitHub lists them: what `gh pr list --json files` gives, without its cap. import type { PullFiles, Repository } from "../core"; -import { type GitHub, array, object, repositoryPath, string } from "./client"; +import { type GitHubReader, array, object, repositoryPath, string } from "./client"; /** The most files GitHub's REST API lists for a PR. */ const REST_LIMIT = 3000; @@ -26,7 +26,7 @@ const OPEN = `query OpenFiles($owner: String!, $repo: String!, $after: String) { }`; /** Every open PR in `repository` with its changed files. */ -export async function openFiles(github: GitHub, repository: Repository): Promise { +export async function openFiles(github: GitHubReader, repository: Repository): Promise { const pulls: OpenFiles[] = []; for (let after: string | null = null, more = true; more;) { const data = await github.graphql(OPEN, { owner: repository.owner, repo: repository.repo, after }); @@ -60,7 +60,7 @@ export async function openFiles(github: GitHub, repository: Repository): Promise } /** `openFiles` as the paths each PR changes, by number. */ -export async function openPullFiles(github: GitHub, repository: Repository): Promise { +export async function openPullFiles(github: GitHubReader, repository: Repository): Promise { const pulls = await openFiles(github, repository); // Fail loud: a cut list would let the duplicate search miss a PR touching a path. const cut = pulls.find((pull) => pull.cut); diff --git a/src/github/forge.ts b/src/github/forge.ts index ce1c14da..6207bb8f 100644 --- a/src/github/forge.ts +++ b/src/github/forge.ts @@ -14,7 +14,7 @@ import type { WatchOptions, } from "../core"; import { held, openPullRequests } from "./claims"; -import { GitHub, type GitHubDependencies, object, string } from "./client"; +import { GitHubReader, type GitHubReadDependencies, object, string } from "./client"; import { openPullFiles } from "./files"; import { pullRequestStatus } from "./status"; import { pullView } from "./view"; @@ -27,18 +27,18 @@ export class GitHubForge implements Forge { /** `viewer` names the person reading when the token is not theirs, such as an App installation's. */ constructor( - private readonly deps: GitHubDependencies, + private readonly deps: GitHubReadDependencies, viewer?: string, ) { if (viewer !== undefined) this.#viewer = Promise.resolve(viewer); } viewer(): Promise { - return this.#viewerOn(new GitHub(this.deps)); + return this.#viewerOn(new GitHubReader(this.deps)); } /** The viewer, read on `github`, whose deadline then bounds the read; kept once read, and read again after a failure. */ - #viewerOn(github: GitHub): Promise { + #viewerOn(github: GitHubReader): Promise { const read = (this.#viewer ??= github .graphql("query { viewer { login } }", {}) .then((data) => string(object(data.viewer).login))); @@ -53,24 +53,24 @@ export class GitHubForge implements Forge { } async pulls(repository: Repository): Promise> { - return live(await openPullRequests(new GitHub(this.deps), repository)); + return live(await openPullRequests(new GitHubReader(this.deps), repository)); } async files(repository: Repository): Promise> { - return live(await openPullFiles(new GitHub(this.deps), repository)); + return live(await openPullFiles(new GitHubReader(this.deps), repository)); } async held(sources: ClaimSources, branches: string[]): Promise> { - return live(await held(new GitHub(this.deps), sources, branches)); + return live(await held(new GitHubReader(this.deps), sources, branches)); } watch(pull: PullRequest, options: WatchOptions): Watch { - const github = new GitHub(this.deps, options.deadline); + const github = new GitHubReader(this.deps, options.deadline); return watchPull(github, this.deps, pull, options.since, { viewer: () => this.#viewerOn(github) }); } async view(pull: PullRequest): Promise> { - return live(await pullView(new GitHub(this.deps), pull)); + return live(await pullView(new GitHubReader(this.deps), pull)); } } diff --git a/src/github/hold.ts b/src/github/hold.ts index 9d4b87f1..46a1db8d 100644 --- a/src/github/hold.ts +++ b/src/github/hold.ts @@ -1,7 +1,15 @@ // Reading who holds a PR: its `quest:*` labels, the events that added them, and a draft its starter still holds. // Taking and releasing holds stays in the CLI. import { type HoldFact, type PullRequest, type StarterHold, handedBack, isHoldLabel, latestHold } from "../core"; -import { GitHub, type GitHubDependencies, type ObjectValue, array, object, repositoryPath, string } from "./client"; +import { + GitHubReader, + type GitHubReadDependencies, + type ObjectValue, + array, + object, + repositoryPath, + string, +} from "./client"; import { lacksApproval } from "./merge"; /** The PR, its `quest:*` labels, and the timeline events that add a label. */ @@ -62,7 +70,7 @@ export interface HoldReport { } /** Read `pr` and its hold labels. */ -export async function readSnapshot(github: GitHub, pr: PullRequest): Promise { +export async function readSnapshot(github: GitHubReader, pr: PullRequest): Promise { const data = await github.graphql(READ, { owner: pr.owner, repo: pr.repo, @@ -98,8 +106,8 @@ export async function readSnapshot(github: GitHub, pr: PullRequest): Promise { - const github = new GitHub(deps); +export async function readHoldStatus(pr: PullRequest, deps: GitHubReadDependencies): Promise { + const github = new GitHubReader(deps); const snapshot = await readSnapshot(github, pr); const holds = snapshot.state !== "OPEN" diff --git a/src/github/index.ts b/src/github/index.ts index dde8a9f3..6b5e23bc 100644 --- a/src/github/index.ts +++ b/src/github/index.ts @@ -3,7 +3,15 @@ // decides them. The caller supplies `fetch` and the token through `GitHubDependencies`; the read types are // `quest/core`'s. -export { GitHub, GitHubDeadline, type GitHubDependencies, GitHubGraphQLError } from "./client"; +export { + GitHub, + GitHubDeadline, + type GitHubDependencies, + GitHubGraphQLError, + type GitHubReadDependencies, + GitHubReader, + reading, +} from "./client"; export { GitHubForge } from "./forge"; export { type BaseNeeds, type Needs, pullRequestStatus, requiredOf } from "./status"; export { type HoldReport } from "./hold"; diff --git a/src/github/online-review.ts b/src/github/online-review.ts index b1583f1e..e350600f 100644 --- a/src/github/online-review.ts +++ b/src/github/online-review.ts @@ -2,7 +2,7 @@ // thread, and any review whose // body opens with `Automated review by `, as a reviewer posting under a person's account does. A finding is a // review thread one opens, or a `[P]` line in its review body; whoever answers it says whether it was taken. -import { type GitHub, type ObjectValue, array, object } from "./client"; +import { type GitHubReader, type ObjectValue, array, object } from "./client"; import type { Repository } from "../core"; /** One online reviewer's record on one PR. */ @@ -87,7 +87,7 @@ export type Activity = Record, ObjectVal /** Each PR's reviews, review threads, and comments, and its head, read in batches and then in pages. */ export async function readActivity( - client: GitHub, + client: GitHubReader, repository: Repository, numbers: number[], extra: "userContentEdits"[] = [], @@ -302,7 +302,7 @@ export function onlineReviews(pull: Activity): OnlineReview[] { /** Each PR's online reviews, and every body its edits left, by number. */ export async function readOnlineReviews( - client: GitHub, + client: GitHubReader, repository: Repository, numbers: number[], ): Promise> { diff --git a/src/github/signals.ts b/src/github/signals.ts index 4ebbbc17..903f87e8 100644 --- a/src/github/signals.ts +++ b/src/github/signals.ts @@ -1,7 +1,7 @@ // What holds a PR's head from landing besides its checks: an online reviewer's finding on the head that no writer has // answered, and a maintainer decision recorded in a comment after the head was committed that nothing has answered. import type { Repository, Signal } from "../core"; -import { type GitHub, type ObjectValue, array, object, string } from "./client"; +import { type GitHubReader, type ObjectValue, array, object, string } from "./client"; import { type Activity, bodyFindings, isBot, login, readActivity, reviewerOf } from "./online-review"; /** The picked heads whose signals a later commit carries unread, and when the pick was made. */ @@ -143,7 +143,7 @@ export function signals(pull: Activity, writers: ReadonlySet, carried?: * read, so their permission is read; any other association cannot. */ async function writersOf( - client: GitHub, + client: GitHubReader, repository: Repository, actors: { actor: unknown; association: unknown }[], ): Promise> { @@ -168,7 +168,7 @@ async function writersOf( /** The signals on each PR's current head, by number, with the head they were read for, and those `carried` carries. */ export async function readSignals( - client: GitHub, + client: GitHubReader, repository: Repository, numbers: number[], carried?: ReadonlyMap, diff --git a/src/github/status.ts b/src/github/status.ts index 077b7323..87790ce6 100644 --- a/src/github/status.ts +++ b/src/github/status.ts @@ -3,9 +3,9 @@ import { actor, array, currentChecks, - GitHub, + GitHubReader, GitHubDeadline, - type GitHubDependencies, + type GitHubReadDependencies, link, object, type ObjectValue, @@ -91,13 +91,17 @@ export interface BaseNeeds extends Repository { * what it read of their base once, instead of each read fetching it again; it throws when the PR's repository or base * is another. */ -export async function pullRequestStatus(pr: PullRequest, deps: GitHubDependencies, base?: BaseNeeds): Promise { +export async function pullRequestStatus( + pr: PullRequest, + deps: GitHubReadDependencies, + base?: BaseNeeds, +): Promise { // GitHub's owner and repository names are case-insensitive. if (base !== undefined && `${base.owner}/${base.repo}`.toLowerCase() !== `${pr.owner}/${pr.repo}`.toLowerCase()) throw new Error( `the requirements passed for ${pr.owner}/${pr.repo}#${pr.number} were read for ${base.owner}/${base.repo}`, ); - const github = new GitHub(deps); + const github = new GitHubReader(deps); const cursors: Record<"checks" | "reviews" | "threads", string | null | undefined> = { checks: null, reviews: null, @@ -182,7 +186,7 @@ function risk(body: string, head: string, record: ReviewRecord | null): Status[" } async function reviewRecord( - github: GitHub, + github: GitHubReader, pr: PullRequest, pull: ObjectValue, warn: (message: string) => void, @@ -236,7 +240,7 @@ export const BRANCH_UPDATES = ["push", "force_push", "branch_creation", "pr_merg * `headRefName`, `headRepository { nameWithOwner }`, and `autoMergeRequest { enabledAt commitBody }`. */ export async function enabledHead( - github: GitHub, + github: GitHubReader, pull: ObjectValue, warn: (message: string) => void, ): Promise { @@ -255,7 +259,7 @@ export async function enabledHead( * `headRepository { nameWithOwner }`. */ export async function headBefore( - github: GitHub, + github: GitHubReader, pull: ObjectValue, time: number, what: string, @@ -298,7 +302,7 @@ export interface Needs { } /** What `branch` requires of a PR head. The gate's own check is never on one, so it is left out. */ -export async function requiredOf(github: GitHub, repository: Repository, branch: string): Promise { +export async function requiredOf(github: GitHubReader, repository: Repository, branch: string): Promise { const found = await requirements(github, repository, branch); return { checks: found.checks.filter((check) => check.name !== LAND_CHECK), workflows: found.workflows }; } diff --git a/src/github/view.ts b/src/github/view.ts index 40294e6d..cbdcab07 100644 --- a/src/github/view.ts +++ b/src/github/view.ts @@ -1,11 +1,11 @@ // A PR's title, body, and discussion as GitHub gives them: what `gh pr view --comments` shows, with its review // threads' comments too. import type { Comment, PullRequest, PullView } from "../core"; -import { type GitHub, type ObjectValue, actor, array, object, string } from "./client"; +import { type GitHubReader, type ObjectValue, actor, array, object, string } from "./client"; import { readActivity } from "./online-review"; /** `pull`'s title, body, comments, submitted reviews, and review threads. */ -export async function pullView(github: GitHub, pull: PullRequest): Promise { +export async function pullView(github: GitHubReader, pull: PullRequest): Promise { const data = await github.graphql( "query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) { " + "pullRequest(number: $number) { url title body state isDraft author { login } } } }", diff --git a/src/github/wait.ts b/src/github/wait.ts index dd208406..9902db62 100644 --- a/src/github/wait.ts +++ b/src/github/wait.ts @@ -4,8 +4,8 @@ import { actor, array, currentChecks, - type GitHub, - type GitHubDependencies, + type GitHubReader, + type GitHubReadDependencies, link, object, type ObjectValue, @@ -120,8 +120,8 @@ interface Viewer { * the person whose own label changes, replies, reactions, and edits never wake them. */ export function watchPull( - github: GitHub, - deps: GitHubDependencies, + github: GitHubReader, + deps: GitHubReadDependencies, pr: PullRequest, since: string | undefined, identity: Viewer, @@ -147,8 +147,8 @@ export function watchPull( /** Read the starting point, returning one poll from it. */ async function start( - github: GitHub, - deps: GitHubDependencies, + github: GitHubReader, + deps: GitHubReadDependencies, pr: PullRequest, from: string | undefined, identity: Viewer, diff --git a/test/forge-writes.test.ts b/test/forge-writes.test.ts index ac1795aa..5fa39d32 100644 --- a/test/forge-writes.test.ts +++ b/test/forge-writes.test.ts @@ -231,6 +231,7 @@ describe("where a PR lives", () => { const found = await upstream(work, remote, { github, forge: github, + live: github, kixel: { hosted: (url) => hostedRepository(KIXEL, url), forge: github }, warn: () => undefined, }); diff --git a/test/forge.test.ts b/test/forge.test.ts index 363e60e0..d9ece492 100644 --- a/test/forge.test.ts +++ b/test/forge.test.ts @@ -21,7 +21,7 @@ import { } from "../src/core"; import { type ForgeDependencies, forgeFor, KixelQuest, KixelQuestForge } from "../src/cli/forge"; import { waitForActivity, WaitTimeout } from "../src/cli/wait"; -import { type GitHubDependencies } from "../src/github/client"; +import { type GitHubReadDependencies } from "../src/github/client"; import { GitHubForge } from "../src/github/forge"; import * as status from "./status-fakes"; import * as wait from "./wait-fakes"; @@ -32,7 +32,7 @@ const repository = { owner: "example", repo: "project" }; /** A fake Kixel Quest serving `github`'s answers to the person `login`, at `asOf`. */ function kixelQuest( - github: () => GitHubDependencies, + github: () => GitHubReadDependencies, options: { login?: string; repositories?: string[]; asOf?: string | null; fail?: number; answer?: unknown } = {}, ) { const requests: { method: string; path: string; body: unknown }[] = []; @@ -94,7 +94,7 @@ afterEach(() => { /** Forge dependencies whose token file pairs `TOKEN` with Kixel Quest, unless `token` is false. */ function dependencies( fetch: ForgeDependencies["fetch"], - github: () => GitHubDependencies, + github: () => GitHubReadDependencies, env: NodeJS.ProcessEnv = {}, token = true, ): ForgeDependencies { @@ -103,11 +103,20 @@ function dependencies( mkdirSync(join(config, "quest")); writeFileSync(join(config, "quest", "records.json"), JSON.stringify({ [URL_]: TOKEN })); } - return { env: { XDG_CONFIG_HOME: config, ...env }, fetch, now: () => 0, github }; + return { + env: { XDG_CONFIG_HOME: config, XDG_CACHE_HOME: join(config, "cache"), ...env }, + fetch, + now: () => 0, + // The fake's token is the person's own here. + github: () => { + const { readToken, ...rest } = github(); + return { ...rest, token: readToken }; + }, + }; } /** Kixel Quest's backend over a fake serving `github`. */ -async function throughKixelQuest(github: () => GitHubDependencies, options?: Parameters[1]) { +async function throughKixelQuest(github: () => GitHubReadDependencies, options?: Parameters[1]) { const server = kixelQuest(github, options); // Kixel Quest's reads keep the fake GitHub's clock, which a wait's deadline is set by. const forge = await forgeFor(repository, { ...dependencies(server.fetch, github), now: () => github().now() }); @@ -236,7 +245,7 @@ describe("status", () => { }); /** A fake GitHub holding open PRs and a merged one, as the claim reads list them. */ -function claimsGitHub(): GitHubDependencies { +function claimsGitHub(): GitHubReadDependencies { const pull = (number: number, ref: string, extra: Record = {}) => ({ number, html_url: `https://github.com/example/project/pull/${number}`, @@ -251,7 +260,7 @@ function claimsGitHub(): GitHubDependencies { const open = [pull(1, "quest/m0/one"), pull(2, "quest/m0/two"), pull(3, "feature", { draft: false, body: null })]; const merged = [pull(4, "quest/m0/done", { head: { ref: "quest/m0/done", sha: "d".repeat(40) }, merged_at: "x" })]; return { - token: "test-token", + readToken: "test-token", quota: "fail", now: () => 0, sleep: async () => {}, @@ -431,7 +440,7 @@ describe("wait deadlines and arguments", () => { test("a viewer or Kixel Quest read that failed is read again, not kept", async () => { let viewers = 0; - const github: GitHubDependencies = { + const github: GitHubReadDependencies = { ...claimsGitHub(), fetch: async () => ++viewers === 1 @@ -474,12 +483,12 @@ describe("wait deadlines and arguments", () => { }); }); -const unreachableGitHub = (): GitHubDependencies => { +const unreachableGitHub = (): GitHubReadDependencies => { throw new Error("read GitHub"); }; describe("choosing the forge", () => { - const unreachable = (): GitHubDependencies => { + const unreachable = (): GitHubReadDependencies => { throw new Error("read GitHub"); }; diff --git a/test/installation.test.ts b/test/installation.test.ts new file mode 100644 index 00000000..fdd73c0a --- /dev/null +++ b/test/installation.test.ts @@ -0,0 +1,253 @@ +// Reads on the installation token Kixel Quest mints, and writes on the person's own, against a fake Kixel Quest and a +// fake GitHub that record the token each request carries. +import { existsSync, mkdirSync, mkdtempSync, readdirSync, statSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { beforeEach, describe, expect, test } from "vitest"; + +import { type ForgeDependencies, liveFor } from "../src/cli/forge"; +import { REUSE_MARGIN, installationDirectory } from "../src/cli/installation"; +import { waitForActivity } from "../src/cli/wait"; +import { GitHubWrites } from "../src/cli/writes"; +import { GitHub, type GitHubDependencies, GitHubReader, reading } from "../src/github/client"; +import * as wait from "./wait-fakes"; + +const KIXEL = "https://kixel.test"; +const KIXEL_TOKEN = "kq-token"; +const PERSON = "person-token"; +const repository = { owner: "example", repo: "project" }; +const START = Date.parse("2026-11-17T00:00:00Z"); + +let cache: string; +let config: string; +let clock: number; +beforeEach(() => { + config = mkdtempSync(join(tmpdir(), "quest-installation-config-")); + cache = mkdtempSync(join(tmpdir(), "quest-installation-cache-")); + mkdirSync(join(config, "quest")); + writeFileSync(join(config, "quest", "records.json"), JSON.stringify({ [KIXEL]: KIXEL_TOKEN })); + clock = START; +}); + +/** A fake Kixel Quest minting tokens, and the GitHub requests the person's reads and writes make, with their tokens. */ +function world(options: { mint?: (n: number, repository: string) => Response; github?: typeof fetch } = {}) { + const mints: { repository: string; authorization: string | null }[] = []; + const github: { method: string; path: string; token: string | null }[] = []; + const env = { XDG_CONFIG_HOME: config, XDG_CACHE_HOME: cache, QUEST_KIXEL_URL: KIXEL } as NodeJS.ProcessEnv; + const mint = + options.mint ?? + ((n: number, name: string) => + Response.json({ + token: `minted-${n}`, + expiresAt: new Date(clock + 3_600_000).toISOString(), + repository: name, + login: "waiter", + })); + const fetch = async (input: string | URL | Request, init?: RequestInit): Promise => { + const url = new URL(String(input)); + if (url.origin === KIXEL) { + if (url.pathname !== "/installation-token") throw new Error(`unexpected Kixel Quest ${url.pathname}`); + const { repository: name } = JSON.parse(String(init?.body)) as { repository: string }; + mints.push({ repository: name, authorization: new Headers(init?.headers).get("authorization") }); + return mint(mints.length, name); + } + const token = new Headers(init?.headers).get("authorization")?.replace(/^Bearer /, "") ?? null; + github.push({ method: init?.method ?? "GET", path: url.pathname, token }); + return options.github ? options.github(input, init) : Response.json([]); + }; + const person = (): GitHubDependencies => ({ + fetch: fetch as typeof globalThis.fetch, + now: () => clock, + sleep: async () => {}, + token: PERSON, + quota: "fail", + warn: () => {}, + }); + const deps: ForgeDependencies = { env, fetch: fetch as typeof globalThis.fetch, now: () => clock, github: person }; + return { deps, mints, github, person, env }; +} + +describe("reads on a minted installation token", () => { + test("a read goes out on the minted token and a write on the person's", async () => { + const w = world(); + const forge = await liveFor(repository, w.deps); + await forge.pulls(repository); + await new GitHubWrites(w.person(), null as never).close({ ...repository, number: 7 }); + expect(w.mints).toEqual([{ repository: "example/project", authorization: `Bearer ${KIXEL_TOKEN}` }]); + expect(w.github).toEqual([ + { method: "GET", path: "/repos/example/project/pulls", token: "minted-1" }, + { method: "PATCH", path: "/repos/example/project/pulls/7", token: PERSON }, + ]); + // The person is the mint's login, not the installation's account. + expect(await forge.viewer()).toBe("waiter"); + }); + + test("a read client cannot write: not in its types, and not at run time for a mutation", async () => { + const w = world(); + const reader = new GitHubReader({ ...reading(w.person()), readToken: "minted" }); + // @ts-expect-error a read has no method or body + const request = () => reader.request("/repos/example/project/pulls/7", { method: "PATCH", body: {} }); + void request; + // @ts-expect-error a write takes the person's token, not read dependencies + const write = () => new GitHub({ ...reading(w.person()), readToken: "minted" }); + void write; + // @ts-expect-error a client that writes is not made from a reader's dependencies + const forge = () => new GitHubWrites(reading(w.person()), null as never); + void forge; + await expect(reader.graphql("mutation { x }", {})).rejects.toThrow("cannot run a mutation"); + expect(w.github).toEqual([]); + }); + + test("the token is minted once and reused across runs until shortly before it expires", async () => { + const w = world(); + await liveFor(repository, w.deps); + clock += 30 * 60_000; + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.mints).toHaveLength(1); + expect(w.github.map((request) => request.token)).toEqual(["minted-1"]); + // Another repository has a token of its own. + await liveFor({ owner: "example", repo: "other" }, w.deps); + expect(w.mints.map((mint) => mint.repository)).toEqual(["example/project", "example/other"]); + // One that has `REUSE_MARGIN` left is not reused; the next mint replaces it. + clock = START + 3_600_000 - REUSE_MARGIN; + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.mints).toHaveLength(3); + expect(w.github.map((request) => request.token)).toEqual(["minted-1", "minted-3"]); + // The file is private to the person, and no name or token appears in its path. + const directory = installationDirectory(w.env); + for (const name of readdirSync(directory)) { + expect(name).toMatch(/^[0-9a-f]{64}$/); + expect(statSync(join(directory, name)).mode & 0o777).toBe(0o600); + } + expect(statSync(directory).mode & 0o777).toBe(0o700); + }); + + test("a person with another Kixel Quest token mints their own", async () => { + const w = world(); + await liveFor(repository, w.deps); + writeFileSync(join(config, "quest", "records.json"), JSON.stringify({ [KIXEL]: "other-token" })); + await liveFor(repository, w.deps); + expect(w.mints.map((mint) => mint.authorization)).toEqual([`Bearer ${KIXEL_TOKEN}`, "Bearer other-token"]); + }); + + test("a repository Kixel Quest does not serve reads on the person's token, minting nothing to keep", async () => { + const w = world({ mint: () => Response.json({ error: "not indexed" }, { status: 404 }) }); + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.github.map((request) => request.token)).toEqual([PERSON]); + expect(files(w.env)).toEqual([]); + }); + + test("without a Kixel Quest token, or with reads forced onto GitHub, none is minted", async () => { + const w = world(); + await (await liveFor(repository, { ...w.deps, env: { ...w.env, QUEST_FORGE: "github" } })).pulls(repository); + writeFileSync(join(config, "quest", "records.json"), "{}"); + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.mints).toEqual([]); + expect(w.github.map((request) => request.token)).toEqual([PERSON, PERSON]); + }); + + test.each([ + [ + "429", + () => new Response("{}", { status: 429, headers: { "retry-after": "1200" } }), + "try again in 1200 seconds", + ], + ["502", () => Response.json({ error: "GitHub refused" }, { status: 502 }), "HTTP 502, GitHub refused"], + ["503", () => Response.json({ error: "App down" }, { status: 503 }), "HTTP 503, App down"], + ["401", () => new Response("{}", { status: 401 }), "refused the token"], + ])("a %s fails the command, naming the setting that reads GitHub with the person's token", async (_, mint, why) => { + const w = world({ mint }); + const error = await liveFor(repository, w.deps).catch((error: Error) => error); + expect(error).toBeInstanceOf(Error); + expect((error as Error).message).toContain(why); + expect((error as Error).message).toContain("set QUEST_FORGE=github to read GitHub"); + // A refused mint never quietly spends the person's quota, and is asked again, not kept. + expect(w.github).toEqual([]); + expect(files(w.env)).toEqual([]); + }); + + test.each([ + ["names no login", { token: "t", expiresAt: "2026-11-17T01:00:00Z", repository: "example/project" }], + ["is for another repository", { token: "t", expiresAt: "2026-11-17T01:00:00Z", repository: "a/b", login: "x" }], + [ + "is about to expire", + { token: "t", expiresAt: "2026-11-17T00:01:00Z", repository: "example/project", login: "x" }, + ], + ])("a mint that %s fails rather than reads on it", async (_, answer) => { + const w = world({ mint: () => Response.json(answer) }); + await expect(liveFor(repository, w.deps)).rejects.toThrow("failed POST /installation-token"); + expect(w.github).toEqual([]); + }); + + test("a cache that cannot be written fails, since every command would mint", async () => { + const w = world(); + writeFileSync(join(cache, "quest"), "a file where the directory goes"); + await expect(liveFor(repository, w.deps)).rejects.toThrow(/cannot (read|keep) installation tokens/); + }); +}); + +/** The tokens kept on disk. */ +const files = (env: NodeJS.ProcessEnv) => + existsSync(installationDirectory(env)) ? readdirSync(installationDirectory(env)) : []; + +/** A comment its author edited after the wait began. */ +const edited = (id: number, login: string) => ({ + id, + body: "My reply", + created_at: "2026-10-06T12:00:00Z", + updated_at: "2026-10-07T12:05:00Z", + user: { login }, + html_url: `https://github.com/example/project/pull/1#issuecomment-${id}`, +}); + +describe("quest wait on a minted token", () => { + test("the person's own reply, reaction, label, and edit do not wake it, though the token's account is the App's", async () => { + const label = (event: string, id: number, name: string, login: string) => ({ + event, + id, + created_at: wait.POINT, + actor: { login }, + label: { name, color: "ffffff" }, + }); + const fixture = wait.setup( + [ + wait.pull(), + wait.response([wait.pushed()]), + wait.response([label("labeled", 1, "merge", "waiter")], { etag: '"t"' }), + wait.response([label("labeled", 1, "merge", "waiter"), label("labeled", 3, "needs review", "person")]), + ], + [wait.A], + { + comments: [ + wait.response([ + wait.replied(1, wait.POINT, "reviewer", null), + wait.replied(2, wait.POINT, "waiter"), + ]), + wait.response([ + wait.replied(1, wait.POINT, "reviewer", null), + wait.replied(2, wait.POINT, "waiter"), + ]), + ], + graphql: [wait.reactions([wait.reacted("r1", wait.POINT, "waiter")])], + edits: [wait.response([edited(1, "waiter")])], + // On an installation token GitHub says the viewer is the App. + viewer: wait.response({ data: { viewer: { login: "quest[bot]" } } }), + }, + ); + const w = world({ github: fixture.deps.fetch }); + const deps: ForgeDependencies = { + ...w.deps, + github: () => ({ ...fixture.deps, token: PERSON }) as GitHubDependencies, + }; + const lines = await waitForActivity(wait.pr, {}, { choose: async (pull) => liveFor(pull, deps) }, fixture.deps); + expect(lines.map((line) => line.split(" ").slice(1, 3).join(" "))).toEqual(["labeled:needs_review person"]); + const tokens = new Set( + [...fixture.calls, ...fixture.sideCalls, ...fixture.editCalls, ...fixture.checkCalls].map((call) => + call.headers.get("authorization"), + ), + ); + expect(tokens).toEqual(new Set(["Bearer minted-1"])); + expect(w.mints).toHaveLength(1); + }); +}); diff --git a/test/pull-files.test.ts b/test/pull-files.test.ts index 2429156b..5ce830f4 100644 --- a/test/pull-files.test.ts +++ b/test/pull-files.test.ts @@ -117,6 +117,8 @@ describe("quest pr list in a fork on GitHub", () => { vi.stubGlobal("fetch", async (input: URL | string, init?: { body?: string }) => { const url = new URL(input); asked.push(url.pathname); + // Kixel Quest does not serve this repository, so the person's own token reads it. + if (url.pathname === "/installation-token") return new Response("{}", { status: 404 }); if (url.pathname === "/repos/me/project") return json(info("me/project", { fork: true, parent: info("example/project") })); if (url.pathname === "/repos/example/project") return json(info("example/project")); diff --git a/test/start.test.ts b/test/start.test.ts index 799985ec..f04b22bc 100644 --- a/test/start.test.ts +++ b/test/start.test.ts @@ -10,7 +10,7 @@ import { afterEach, describe, expect, test, vi } from "vitest"; import { claims, openDrafts, target } from "../src/cli/claims"; import { githubRepository, readRemote, remoteRepository } from "../src/cli/github"; -import { type GitHubDependencies, type ObjectValue } from "../src/github/client"; +import { type GitHubDependencies, type ObjectValue, reading } from "../src/github/client"; import { GitHubForge } from "../src/github/forge"; import { type Output, main } from "../src/cli/main"; import { Refusal } from "../src/core"; @@ -202,7 +202,8 @@ class FakeGitHub { function deps(github: FakeGitHub, warnings: string[] = []) { return { github: () => github.deps(), - forge: async () => new GitHubForge(github.deps()), + forge: async () => new GitHubForge(reading(github.deps())), + live: async () => new GitHubForge(reading(github.deps())), warn: (message: string) => warnings.push(message), }; } @@ -849,7 +850,8 @@ test("openDrafts skips drafts with a warning when GitHub cannot be read", async github: () => { throw new Error("set GH_TOKEN or GITHUB_TOKEN, or sign in with gh auth login"); }, - forge: async () => new GitHubForge(offline.github()), + forge: async () => new GitHubForge(reading(offline.github())), + live: async () => new GitHubForge(reading(offline.github())), warn: (message: string) => warnings.push(message), }; expect(await openDrafts(work, "origin", offline)).toEqual([]); diff --git a/test/status-fakes.ts b/test/status-fakes.ts index 533289bd..8c2b924d 100644 --- a/test/status-fakes.ts +++ b/test/status-fakes.ts @@ -1,7 +1,7 @@ // A fake GitHub for `quest status`: recorded GraphQL answers and the REST reads around them. import { expect } from "vitest"; -import { type GitHubDependencies } from "../src/github/client"; +import { type GitHubReadDependencies } from "../src/github/client"; export const A = "a".repeat(40); export const B = "b".repeat(40); @@ -137,8 +137,8 @@ export function setup( const eventPages = [...(options.eventPages ?? [])]; const activityPages = [...(options.activity ?? [])]; const activityRequests: string[] = []; - const deps: GitHubDependencies = { - token: "test-token", + const deps: GitHubReadDependencies = { + readToken: "test-token", quota: "wait", now: () => options.now ?? 0, sleep: async () => {}, diff --git a/test/status.test.ts b/test/status.test.ts index b209760f..dbb394cc 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from "vitest"; -import { GitHub } from "../src/github/client"; +import { GitHubReader } from "../src/github/client"; import { main } from "../src/cli/main"; import { statusLines } from "../src/cli/status"; import { pullRequestStatus, requiredOf } from "../src/github/status"; @@ -410,7 +410,7 @@ test("a base's requirements read once give the status a read of its own would, a expect(own.reads).not.toEqual([]); const shared = counted(); - const needs = await requiredOf(new GitHub(shared.deps), pr, "main"); + const needs = await requiredOf(new GitHubReader(shared.deps), pr, "main"); const before = shared.reads.length; expect(await pullRequestStatus(pr, shared.deps, { ...pr, branch: "main", needs })).toEqual(expected); expect(shared.reads).toHaveLength(before); diff --git a/test/usage.test.ts b/test/usage.test.ts index 8eec15c3..ce37d62e 100644 --- a/test/usage.test.ts +++ b/test/usage.test.ts @@ -823,6 +823,7 @@ describe("usage", () => { warn: () => {}, }), forge: () => Promise.reject(new Error("usage reads no forge")), + live: () => Promise.reject(new Error("usage reads no forge")), warn: () => {}, sessions: (since: Date, ssh: string[]) => { calls.push([since, ssh]); diff --git a/test/wait-fakes.ts b/test/wait-fakes.ts index aa1e4942..5426320e 100644 --- a/test/wait-fakes.ts +++ b/test/wait-fakes.ts @@ -1,5 +1,5 @@ // A fake GitHub for `quest wait`: scripted REST pages and GraphQL answers, and a clock that advances as it sleeps. -import { type CachedResponse, type GitHubDependencies } from "../src/github/client"; +import { type CachedResponse, type GitHubReadDependencies } from "../src/github/client"; import { GitHubForge } from "../src/github/forge"; import { waitForActivity, type WaitOptions } from "../src/cli/wait"; @@ -186,8 +186,8 @@ export function setup( const sleeps: number[] = []; const warnings: string[] = []; const stored = new Map(); - const deps: GitHubDependencies = { - token: "test-token", + const deps: GitHubReadDependencies = { + readToken: "test-token", quota: "wait", cache: { get: async (key) => stored.get(key), set: async (key, entry) => void stored.set(key, entry) }, now: () => now, @@ -264,7 +264,7 @@ export function setup( } /** Wait on GitHub, with the fixture's clock. */ -export function waitOn(pull: typeof pr, options: WaitOptions, deps: GitHubDependencies): Promise { +export function waitOn(pull: typeof pr, options: WaitOptions, deps: GitHubReadDependencies): Promise { return waitForActivity(pull, options, { choose: async () => new GitHubForge(deps) }, deps); } From 549fcac8653c90d67db21e3c7eabde95f7e2bf98 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:21:02 -0800 Subject: [PATCH 3/4] fix(github): mint an installation token once between parallel agents Co-Authored-By: Claude Sonnet 5.5 --- src/cli/forge.ts | 57 +++++++++++++++++++++++---------- src/cli/installation.ts | 67 ++++++++++++++++++++++++++++++++++++++- src/cli/main.ts | 1 + src/cli/send.ts | 9 +++++- test/forge.test.ts | 1 + test/installation.test.ts | 38 +++++++++++++++++++++- 6 files changed, 154 insertions(+), 19 deletions(-) diff --git a/src/cli/forge.ts b/src/cli/forge.ts index 791d3a20..6403369d 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -34,7 +34,15 @@ import { import { type GitHubDependencies, reading } from "../github/client"; import { GitHubForge } from "../github/forge"; import { pullRequest, readRemote, remoteHost } from "./github"; -import { type Installation, REUSE_MARGIN, installationDirectory, keep, kept } from "./installation"; +import { + type Installation, + LockDeadline, + REUSE_MARGIN, + exclusive, + installationDirectory, + keep, + kept, +} from "./installation"; import { kixelUrl, tokenFor, tokensPath } from "./tokens"; /** The variable that, set to `github`, reads GitHub even where Kixel Quest serves the repository. */ @@ -45,6 +53,7 @@ export interface ForgeDependencies { env: NodeJS.ProcessEnv; fetch: typeof fetch; now(): number; + sleep(milliseconds: number): Promise; /** Called only once a read goes to GitHub, so Kixel Quest's reads need no GitHub token. */ github(): GitHubDependencies; /** What a Kixel Quest failure tells the person to do; by default, to read GitHub instead. */ @@ -217,24 +226,40 @@ export class KixelQuest { } const path = "/installation-token"; const name = `${repository.owner}/${repository.repo}`; - const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); - if (response.status === 404) return null; - if (response.status === 429) { - const wait = Number(response.headers.get("retry-after")); - throw this.#failed( - "POST", - path, - `you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`, - ); - } - if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`); - const installation = this.#minted(text, name); + const mint = async (): Promise => { + // Another agent may have minted while this one waited for the lock. + try { + const have = kept(directory, this.url, this.token, repository, this.deps.now()); + if (have !== null) return have; + } catch (error) { + throw keeping("read", error); + } + const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); + if (response.status === 404) return null; + if (response.status === 429) { + const wait = Number(response.headers.get("retry-after")); + throw this.#failed( + "POST", + path, + `you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`, + ); + } + if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`); + const installation = this.#minted(text, name); + try { + keep(directory, this.url, this.token, repository, installation); + } catch (error) { + throw keeping("keep", error); + } + return installation; + }; try { - keep(directory, this.url, this.token, repository, installation); + return await exclusive(directory, this.url, this.token, repository, this.deps, deadline, mint); } catch (error) { - throw keeping("keep", error); + if (error instanceof LockDeadline) throw this.#failed("POST", path, error.message); + if ((error as NodeJS.ErrnoException).code !== undefined) throw keeping("lock", error); + throw error; } - return installation; } /** The token in a mint's answer, `{token, expiresAt, repository, login}`, for `name`. */ diff --git a/src/cli/installation.ts b/src/cli/installation.ts index aa6923a3..a2925cda 100644 --- a/src/cli/installation.ts +++ b/src/cli/installation.ts @@ -1,7 +1,7 @@ // The App installation tokens Kixel Quest mints for a person's reads, kept on disk until shortly before they expire: // a person's hourly cap on minting is spent within a minute if each command mints its own. import { createHash } from "node:crypto"; -import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; @@ -72,3 +72,68 @@ export function keep( writeFileSync(temporary, JSON.stringify(installation), { mode: 0o600 }); renameSync(temporary, path); } + +/** How long a lock may stand before it is taken for a crashed holder's, and how often a waiter looks again. */ +const STALE = 30_000; +const POLL = 100; + +/** The clock a lock waits on. */ +export interface Clock { + now(): number; + sleep(milliseconds: number): Promise; +} + +/** A lock was still held when the caller's deadline passed. */ +export class LockDeadline extends Error { + constructor() { + super("its deadline passed while another quest minted the token"); + } +} + +/** + * Run `run` while holding the one lock for `repository`'s token, so parallel agents on a cold or expiring cache mint + * once between them: each waits, then finds the winner's token. The lock is a file created exclusively, holding its + * time, so a holder that crashed is taken over after `STALE` milliseconds; two waiters that take over at once may + * mint twice, which only spends one more of the cap. Waits until `deadline`, epoch milliseconds. + */ +export async function exclusive( + directory: string, + url: string, + kixelToken: string, + repository: Repository, + clock: Clock, + deadline: number, + run: () => Promise, +): Promise { + mkdirSync(directory, { recursive: true, mode: 0o700 }); + const lock = `${file(directory, url, kixelToken, repository)}.lock`; + for (;;) { + try { + writeFileSync(lock, String(clock.now()), { flag: "wx", mode: 0o600 }); + break; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; + } + let since = Number.NaN; + try { + const text = readFileSync(lock, "utf8"); + // Created but not yet written: its holder has only just taken it. + since = text === "" ? clock.now() : Number(text); + } catch (error) { + // Released between the two reads: try to take it again. + if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; + throw error; + } + if (!(clock.now() - since <= STALE)) { + rmSync(lock, { force: true }); + continue; + } + if (clock.now() >= deadline) throw new LockDeadline(); + await clock.sleep(Math.min(POLL, deadline - clock.now())); + } + try { + return await run(); + } finally { + rmSync(lock, { force: true }); + } +} diff --git a/src/cli/main.ts b/src/cli/main.ts index 107f025b..23d0c5c8 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -148,6 +148,7 @@ export function main(argv: string[], out: Output): number | Promise { env: process.env, fetch: globalThis.fetch, now: Date.now, + sleep, github: () => gitHubDependencies(warn, quota), }); const claimDependencies = (): ClaimDependencies => ({ diff --git a/src/cli/send.ts b/src/cli/send.ts index 0b241e48..5dd7d5b6 100644 --- a/src/cli/send.ts +++ b/src/cli/send.ts @@ -324,7 +324,14 @@ async function sendOnce(deps: SendDependencies, dir: string): Promise { const kixel = new KixelQuest( url, token, - { env: deps.env, fetch: deps.fetch, now: deps.now, github: deps.github, remedy: "its records stay queued" }, + { + env: deps.env, + fetch: deps.fetch, + now: deps.now, + sleep: async () => {}, + github: deps.github, + remedy: "its records stay queued", + }, false, ); /** Kixel Quest refused the token, which every group shares: nothing more is sent, and what is queued is dropped. */ diff --git a/test/forge.test.ts b/test/forge.test.ts index d9ece492..6aa4afbb 100644 --- a/test/forge.test.ts +++ b/test/forge.test.ts @@ -107,6 +107,7 @@ function dependencies( env: { XDG_CONFIG_HOME: config, XDG_CACHE_HOME: join(config, "cache"), ...env }, fetch, now: () => 0, + sleep: async () => {}, // The fake's token is the person's own here. github: () => { const { readToken, ...rest } = github(); diff --git a/test/installation.test.ts b/test/installation.test.ts index fdd73c0a..52731ed8 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -1,5 +1,6 @@ // Reads on the installation token Kixel Quest mints, and writes on the person's own, against a fake Kixel Quest and a // fake GitHub that record the token each request carries. +import { createHash } from "node:crypto"; import { existsSync, mkdirSync, mkdtempSync, readdirSync, statSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -64,7 +65,13 @@ function world(options: { mint?: (n: number, repository: string) => Response; gi quota: "fail", warn: () => {}, }); - const deps: ForgeDependencies = { env, fetch: fetch as typeof globalThis.fetch, now: () => clock, github: person }; + const deps: ForgeDependencies = { + env, + fetch: fetch as typeof globalThis.fetch, + now: () => clock, + sleep: async (ms) => void (clock += ms), + github: person, + }; return { deps, mints, github, person, env }; } @@ -123,6 +130,35 @@ describe("reads on a minted installation token", () => { expect(statSync(directory).mode & 0o777).toBe(0o700); }); + test("agents starting on a cold cache mint once between them", async () => { + const w = world(); + // Each waiter lets the others run while it sleeps, as parallel processes do. + const slow: ForgeDependencies = { ...w.deps, sleep: async (ms) => void (await Promise.resolve((clock += ms))) }; + const forges = await Promise.all(Array.from({ length: 8 }, () => liveFor(repository, slow))); + await Promise.all(forges.map((forge) => forge.pulls(repository))); + expect(w.mints).toHaveLength(1); + expect(new Set(w.github.map((request) => request.token))).toEqual(new Set(["minted-1"])); + expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); + }); + + test("a lock a crashed agent left is taken over once stale, and a held one is waited for until the deadline", async () => { + const w = world(); + const lock = join( + installationDirectory(w.env), + `${createHash("sha256").update(`${KIXEL}\n${KIXEL_TOKEN}\nexample/project`).digest("hex")}.lock`, + ); + mkdirSync(installationDirectory(w.env), { recursive: true }); + writeFileSync(lock, String(clock)); + await expect(liveFor(repository, w.deps, clock + 1000)).rejects.toThrow( + "its deadline passed while another quest minted the token", + ); + expect(w.mints).toEqual([]); + clock += 60_000; + await liveFor(repository, w.deps); + expect(w.mints).toHaveLength(1); + expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); + }); + test("a person with another Kixel Quest token mints their own", async () => { const w = world(); await liveFor(repository, w.deps); From 466689da510218ac62e61a099a73f34e9b4ec7c9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:23:22 -0800 Subject: [PATCH 4/4] fix(github): keep a live minter's lock Co-Authored-By: Claude Sonnet 5.5 --- src/cli/forge.ts | 4 ++-- src/cli/installation.ts | 26 ++++++++++++++++++-------- test/installation.test.ts | 18 +++++++++++++++++- 3 files changed, 37 insertions(+), 11 deletions(-) diff --git a/src/cli/forge.ts b/src/cli/forge.ts index 6403369d..bbe7add3 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -226,7 +226,7 @@ export class KixelQuest { } const path = "/installation-token"; const name = `${repository.owner}/${repository.repo}`; - const mint = async (): Promise => { + const mint = async (until: number): Promise => { // Another agent may have minted while this one waited for the lock. try { const have = kept(directory, this.url, this.token, repository, this.deps.now()); @@ -234,7 +234,7 @@ export class KixelQuest { } catch (error) { throw keeping("read", error); } - const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); + const { response, text } = await this.#fetch("POST", path, { repository: name }, until); if (response.status === 404) return null; if (response.status === 429) { const wait = Number(response.headers.get("retry-after")); diff --git a/src/cli/installation.ts b/src/cli/installation.ts index a2925cda..52fa5f58 100644 --- a/src/cli/installation.ts +++ b/src/cli/installation.ts @@ -76,6 +76,8 @@ export function keep( /** How long a lock may stand before it is taken for a crashed holder's, and how often a waiter looks again. */ const STALE = 30_000; const POLL = 100; +/** The longest a holder works under its lock, well inside `STALE`, so a live holder is never taken over. */ +export const HOLD = 20_000; /** The clock a lock waits on. */ export interface Clock { @@ -92,9 +94,11 @@ export class LockDeadline extends Error { /** * Run `run` while holding the one lock for `repository`'s token, so parallel agents on a cold or expiring cache mint - * once between them: each waits, then finds the winner's token. The lock is a file created exclusively, holding its - * time, so a holder that crashed is taken over after `STALE` milliseconds; two waiters that take over at once may - * mint twice, which only spends one more of the cap. Waits until `deadline`, epoch milliseconds. + * once between them: each waits, then finds the winner's token. `run` gets the time, epoch milliseconds, it must + * finish by: the caller's `deadline`, or `HOLD` after it took the lock if sooner, so a live holder is never taken + * over. The lock is a file created exclusively, holding its time and its owner, so a holder that crashed is taken over + * after `STALE` milliseconds, and a holder releases only a lock still its own. Waits until `deadline`, epoch + * milliseconds; two waiters that take over a crashed holder's lock at once may mint twice. */ export async function exclusive( directory: string, @@ -103,13 +107,14 @@ export async function exclusive( repository: Repository, clock: Clock, deadline: number, - run: () => Promise, + run: (until: number) => Promise, ): Promise { mkdirSync(directory, { recursive: true, mode: 0o700 }); const lock = `${file(directory, url, kixelToken, repository)}.lock`; + const owner = crypto.randomUUID(); for (;;) { try { - writeFileSync(lock, String(clock.now()), { flag: "wx", mode: 0o600 }); + writeFileSync(lock, `${clock.now()} ${owner}`, { flag: "wx", mode: 0o600 }); break; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; @@ -118,7 +123,7 @@ export async function exclusive( try { const text = readFileSync(lock, "utf8"); // Created but not yet written: its holder has only just taken it. - since = text === "" ? clock.now() : Number(text); + since = text === "" ? clock.now() : Number(text.split(" ")[0]); } catch (error) { // Released between the two reads: try to take it again. if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; @@ -132,8 +137,13 @@ export async function exclusive( await clock.sleep(Math.min(POLL, deadline - clock.now())); } try { - return await run(); + return await run(Math.min(deadline, clock.now() + HOLD)); } finally { - rmSync(lock, { force: true }); + try { + if (readFileSync(lock, "utf8").endsWith(` ${owner}`)) rmSync(lock, { force: true }); + } catch (error) { + // Taken over and released by another, which owns the file's fate now. + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } } } diff --git a/test/installation.test.ts b/test/installation.test.ts index 52731ed8..32670c52 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -8,7 +8,7 @@ import { join } from "node:path"; import { beforeEach, describe, expect, test } from "vitest"; import { type ForgeDependencies, liveFor } from "../src/cli/forge"; -import { REUSE_MARGIN, installationDirectory } from "../src/cli/installation"; +import { HOLD, REUSE_MARGIN, exclusive, installationDirectory } from "../src/cli/installation"; import { waitForActivity } from "../src/cli/wait"; import { GitHubWrites } from "../src/cli/writes"; import { GitHub, type GitHubDependencies, GitHubReader, reading } from "../src/github/client"; @@ -159,6 +159,22 @@ describe("reads on a minted installation token", () => { expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); }); + test("a holder gets less time than it takes to be taken over, and never releases another's lock", async () => { + const directory = installationDirectory({ XDG_CACHE_HOME: cache }); + const clockwork = { now: () => clock, sleep: async (ms: number) => void (clock += ms) }; + let until = 0; + await exclusive(directory, KIXEL, KIXEL_TOKEN, repository, clockwork, Infinity, async (limit) => { + until = limit; + }); + expect(until).toBe(START + HOLD); + // A holder that overran, whose lock another took over, leaves the new holder's lock be. + await exclusive(directory, KIXEL, KIXEL_TOKEN, repository, clockwork, Infinity, async () => { + const [held] = readdirSync(directory); + writeFileSync(join(directory, held!), `${clock} another`); + }); + expect(readdirSync(directory).filter((name) => name.endsWith(".lock"))).toHaveLength(1); + }); + test("a person with another Kixel Quest token mints their own", async () => { const w = world(); await liveFor(repository, w.deps);