From b27e1ffab8a1800c4fa2667c4274f2d6bc5c41e7 Mon Sep 17 00:00:00 2001 From: Danyang Chen Date: Sat, 21 Nov 2026 18:40:13 +0800 Subject: [PATCH] fix(gate): a stop request dequeues a queued entry (#3280) A stop request that lands after a queue entry's required checks have run is read by nothing: on #3279 `Test` went green at 04:47:33Z, the author's request landed at 04:47:43Z, and the queue merged at 04:47:58Z. Add an `issue_comment` workflow that takes the entry out through `dequeuePullRequest` when the body is `Stop request for this tip: ` and the sha is still the head. It runs only on a pull request based on `main`, only for the live tip, and writes one note naming the tip and the request it answered. Docs-not-needed: .github scripts and workflows own no subsystem page; the test-layer manifest and its generated doc are updated in this commit. --- .github/scripts/stop-request.mjs | 183 +++++++++++++++++++++++++ .github/scripts/stop-request.test.mjs | 187 ++++++++++++++++++++++++++ .github/workflows/stop-request.yml | 49 +++++++ docs/testing-layers.json | 9 ++ docs/testing-layers.md | 1 + 5 files changed, 429 insertions(+) create mode 100644 .github/scripts/stop-request.mjs create mode 100644 .github/scripts/stop-request.test.mjs create mode 100644 .github/workflows/stop-request.yml diff --git a/.github/scripts/stop-request.mjs b/.github/scripts/stop-request.mjs new file mode 100644 index 000000000..494c1bbf3 --- /dev/null +++ b/.github/scripts/stop-request.mjs @@ -0,0 +1,183 @@ +// The stop-request dequeue (#3280). `merge-gate` and `enqueue-guard` both read a stop request — but both +// have already run when one arrives after the required checks: on #3279 `Test` went green at 04:47:33Z, +// the author's "Stop request for this tip: do not merge `8bbd01ba…`" landed at 04:47:43Z, and the queue +// merged the entry at 04:47:58Z. The 25 s in between belong to no check, so nothing could refuse. This +// module closes that window from the other side: an `issue_comment` event whose body names the live tip +// takes the queued entry out through GitHub's `dequeuePullRequest`, and the pull request stays open at +// that head. +// +// It is not a second verdict reader, deliberately. The two gates decide whether the tip may merge; this +// only answers "does a person ask not to merge this exact tip, and is it still queued" — the sentence is +// the marker `Stop request for this tip: `, so a hold with no sha, a request naming an older tip +// and a merged pull request all change nothing. `enqueue-guard.mjs`/`enqueue-rules.mjs` carry the +// "do not merge" vocabulary but no sha marker (their stop request names no tip), so there is one +// implementation of this marker and it lives here; the other module is imported by nobody and edited by +// nobody from here. +import { readFileSync } from 'node:fs' +import { fileURLToPath } from 'node:url' + +const SHORT = 12 +const STOP_MARKER = /stop\s+request\s+for\s+this\s+tip\b/i +// A sha is the run of hex characters nobody longer; the lookarounds keep a 12-character prefix inside a +// longer word from being read as a tip. Parsing accepts 7 (the shortest GitHub shows), `sameSha` is what +// insists on 12 — a tip a person can name unambiguously. +const SHA = /(? error.message).join('; ')), { status: response.status }) + } + return payload?.data + } +} + +const PULL_QUERY = `query($owner: String!, $name: String!, $number: Int!) { + repository(owner: $owner, name: $name) { + pullRequest(number: $number) { id number headRefOid baseRefName merged state } + } +}` + +const DEQUEUE_MUTATION = `mutation($id: ID!) { + dequeuePullRequest(input: { id: $id }) { pullRequest { number headRefOid } } +}` + +async function readPull(graphql, repo, number) { + const [owner, name] = String(repo ?? '').split('/') + if (!owner || !name) throw new Error('set GITHUB_REPOSITORY or pass repo owner/name') + const data = await graphql(PULL_QUERY, { owner, name, number: Number(number) }) + return data?.repository?.pullRequest ?? null +} + +// Take the entry out, but only while the tip is still the one the caller judged: the head is read again +// here, so a push in the middle of `handleStopRequest` cannot dequeue a different commit than the one the +// stop request named. An entry that is already out (404/422, or the queue's own "not in the queue" +// refusal) is `skipped`, not an error: two comments in a row race the same queue and neither is a defect. +export async function dequeue(prNumber, expectedHeadOid, { graphql = graphqlClient(process.env.GITHUB_TOKEN), repo = process.env.GITHUB_REPOSITORY, pull = null } = {}) { + const target = pull ?? await readPull(graphql, repo, prNumber) + if (!target?.id) return 'skipped' + if (!sameSha(expectedHeadOid, target.headRefOid)) return 'skipped' + try { + await graphql(DEQUEUE_MUTATION, { id: target.id }) + return true + } catch (error) { + if (error?.status === 404 || error?.status === 422 || ALREADY_OUT.test(String(error?.message ?? ''))) return 'skipped' + throw error + } +} + +// The note the dequeue leaves on the pull request. `Dequeued by: Chief` is the line an operator looks for; +// the tip and the stop comment make the record checkable without a second API read. +export function dequeueNote({ head, stop }) { + const link = stop?.html_url ? `\n\nStop request: ${stop.html_url}` : '' + return [ + 'Written-by: Chief', + '', + 'Dequeued by: Chief', + '', + `The merge-queue entry at \`${head}\` was taken out of the queue after a stop request. The pull request stays open at this head.${link}`, + ].join('\n') +} + +async function commentOnPull({ prNumber, repo, body, token = process.env.GITHUB_TOKEN }) { + const [owner, name] = String(repo ?? '').split('/') + const response = await fetch(`https://api.github.com/repos/${owner}/${name}/issues/${prNumber}/comments`, { + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + Accept: 'application/vnd.github+json', + 'X-GitHub-Api-Version': '2022-11-28', + 'Content-Type': 'application/json', + 'User-Agent': 'flybot-stop-request', + }, + body: JSON.stringify({ body }), + }) + if (!response.ok) throw new Error(`could not comment on #${prNumber}: HTTP ${response.status} ${(await response.text()).slice(0, 300)}`) + return response.json() +} + +// One `issue_comment` event in, one outcome out. Nothing is written for a body that is not the marker, and +// the live head is compared before the queue is touched, so the one GraphQL route this module owns is +// reached only for a stop request that names the tip the pull request is at. +export async function handleStopRequest({ event, graphql = graphqlClient(process.env.GITHUB_TOKEN), repo = process.env.GITHUB_REPOSITORY, dequeue: dequeueImpl = dequeue, postComment = commentOnPull } = {}) { + const issue = event?.issue + const comment = event?.comment + const parsed = parseStopRequest(comment?.body) + if (!parsed) return { action: 'none', reason: 'not a stop request for a tip' } + if (!issue?.pull_request) return { action: 'none', reason: 'a comment on an issue, not a pull request' } + const prNumber = Number(issue.number) + if (!Number.isInteger(prNumber) || prNumber <= 0) return { action: 'none', reason: 'no pull request number' } + + const pull = await readPull(graphql, repo, prNumber) + if (!pull) return { action: 'skipped', reason: 'the pull request is gone', parsed } + if (pull.merged) return { action: 'ignored', reason: 'already merged', parsed, pull } + if (String(pull.baseRefName) !== 'main') return { action: 'ignored', reason: `base is ${pull.baseRefName}, not main`, parsed, pull } + if (!sameSha(parsed.sha, pull.headRefOid)) return { action: 'ignored', reason: 'the request names another tip', parsed, head: pull.headRefOid, pull } + + const outcome = await dequeueImpl(prNumber, pull.headRefOid, { graphql, repo }) + if (outcome !== true) return { action: 'skipped', reason: 'the entry is no longer in the queue', parsed, head: pull.headRefOid, pull } + + const body = dequeueNote({ head: pull.headRefOid, stop: comment }) + await postComment({ prNumber, repo, body }) + return { action: 'dequeued', parsed, head: pull.headRefOid, expectedHeadOid: pull.headRefOid, body, pull } +} + +export async function main({ eventPath = process.env.GITHUB_EVENT_PATH, env = process.env } = {}) { + const event = JSON.parse(readFileSync(eventPath, 'utf8')) + const result = await handleStopRequest({ + event, + repo: env.GITHUB_REPOSITORY, + graphql: graphqlClient(env.GITHUB_TOKEN), + }) + const at = result.head ? ` at ${result.head}` : '' + console.log(`stop-request: ${result.action}${result.reason ? ` — ${result.reason}` : ''}${at}`) + return result +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + main().catch((error) => { + console.error(`stop-request: ${error.message}`) + process.exit(1) + }) +} diff --git a/.github/scripts/stop-request.test.mjs b/.github/scripts/stop-request.test.mjs new file mode 100644 index 000000000..ef53240bb --- /dev/null +++ b/.github/scripts/stop-request.test.mjs @@ -0,0 +1,187 @@ +// The stop-request dequeue (#3280). A stop request that arrives after a queue entry's required checks +// have run and before the queue merges it is read by no check: on #3279 `Test` went green at 04:47:33Z, +// the author's request landed at 04:47:43Z, and the queue merged at 04:47:58Z. These tests pin the one +// decision that closes that window — dequeue the entry, and only when the request names the live tip — +// and they pin it offline: the GraphQL client is injected, so no test touches GitHub. +import { test } from 'node:test' +import assert from 'node:assert/strict' +import { dequeue, handleStopRequest, parseStopRequest, sameSha } from './stop-request.mjs' + +const TIP = '202fcc6711ac1e8af0877a7ab6865f05088487ae' +const OTHER = '8bbd01baeefa413a7dfbb4accc5f9d5ddf46f6fa' +const STOP_URL = 'https://github.com/ThinkFlowLab/FlyBot/pull/3280#issuecomment-7057486591' + +const pull = (over = {}) => ({ + id: 'PR_kwDOA-node-3280', + number: 3280, + headRefOid: TIP, + baseRefName: 'main', + merged: false, + state: 'OPEN', + ...over, +}) + +const comment = (over = {}) => ({ + id: 7057486591, + body: `Stop request for this tip: do not merge \`${TIP}\``, + html_url: STOP_URL, + user: { login: 'HugoXK', type: 'User' }, + ...over, +}) + +const event = (over = {}) => ({ + action: 'created', + issue: { number: 3280, pull_request: { url: 'https://api.github.com/repos/ThinkFlowLab/FlyBot/pulls/3280' } }, + comment: comment(), + ...over, +}) + +// A fake GraphQL client: it records every call, answers the pull-request read, and answers the dequeue +// mutation — or throws the error a real entry outside the queue would produce. +function fakeGraphql({ pr = pull(), dequeueError = null } = {}) { + const calls = [] + const client = async (query, variables) => { + calls.push({ query, variables }) + if (query.includes('dequeuePullRequest')) { + if (dequeueError) throw dequeueError + return { dequeuePullRequest: { pullRequest: { number: pr.number } } } + } + return { repository: { pullRequest: pr } } + } + return { client, calls, mutations: () => calls.filter((call) => call.query.includes('dequeuePullRequest')) } +} + +const graphqlError = (message, status) => Object.assign(new Error(message), { status }) + +test('#3280: parseStopRequest reads the tip request, its short sha and backticks, and nothing else', () => { + assert.deepEqual(parseStopRequest(`Stop request for this tip: \`${TIP}\``), { sha: TIP }) + assert.deepEqual(parseStopRequest(`stop REQUEST for this tip: ${TIP.slice(0, 12)}`), { sha: TIP.slice(0, 12) }) + // The request usually carries a sentence between the marker and the sha, and the sha may sit on the + // next line inside backticks — the shape #3279's comment used. + assert.deepEqual(parseStopRequest(`Stop request for this tip: do not merge\n\`${TIP}\``), { sha: TIP }) + assert.equal(parseStopRequest('please do not merge this tip'), null, 'a hold without a tip is not this marker') + assert.equal(parseStopRequest(`Stop request for this tip: nothing to name`), null, 'the marker names no sha') + assert.equal(parseStopRequest(''), null) +}) + +test('#3280: sameSha accepts a 12-character short sha either way and refuses another tip', () => { + assert.equal(sameSha(TIP, TIP), true) + assert.equal(sameSha(TIP, TIP.slice(0, 12)), true, 'a full sha matches the short form a person writes') + assert.equal(sameSha(TIP.slice(0, 12), TIP), true, 'a short sha matches the full form the API returns') + assert.equal(sameSha(TIP, OTHER), false) + assert.equal(sameSha(TIP, TIP.slice(0, 7)), false, 'under 12 characters names no tip on its own') + assert.equal(sameSha('', TIP), false) +}) + +test('#3280: dequeue takes the entry out through dequeuePullRequest at the tip it read', async () => { + const g = fakeGraphql() + const out = await dequeue(3280, TIP, { graphql: g.client, repo: 'ThinkFlowLab/FlyBot' }) + + assert.equal(out, true) + assert.equal(g.mutations().length, 1, 'one dequeuePullRequest mutation') + assert.deepEqual(g.mutations()[0].variables, { id: 'PR_kwDOA-node-3280' }, 'the mutation names the pull request node id') +}) + +test('#3280: dequeue is skipped, not failed, when the entry is no longer in the queue', async () => { + for (const status of [404, 422]) { + const g = fakeGraphql({ dequeueError: graphqlError('not in the queue', status) }) + assert.equal(await dequeue(3280, TIP, { graphql: g.client, repo: 'ThinkFlowLab/FlyBot' }), 'skipped', `HTTP ${status} means already out`) + } + // A GraphQL refusal arrives as a 200 body with an `errors` array; the message is what says "already out". + const body = fakeGraphql({ dequeueError: graphqlError('Pull request #3280 is not in the merge queue', 200) }) + assert.equal(await dequeue(3280, TIP, { graphql: body.client, repo: 'ThinkFlowLab/FlyBot' }), 'skipped') +}) + +test('#3280: dequeue never takes out an entry whose head already moved', async () => { + const g = fakeGraphql({ pr: pull({ headRefOid: OTHER }) }) + assert.equal(await dequeue(3280, TIP, { graphql: g.client, repo: 'ThinkFlowLab/FlyBot' }), 'skipped') + assert.equal(g.mutations().length, 0, 'the request names a tip that is no longer the head') +}) + +test('#3280: a stop request naming the live tip is dequeued and leaves Dequeued by: Chief', async () => { + const g = fakeGraphql() + const seen = [] + const posted = [] + const r = await handleStopRequest({ + event: event({ comment: comment({ body: `Stop request for this tip: do not merge\n\`${TIP.slice(0, 12)}\`` }) }), + graphql: g.client, + repo: 'ThinkFlowLab/FlyBot', + dequeue: async (prNumber, expectedHeadOid) => { seen.push([prNumber, expectedHeadOid]); return true }, + postComment: async (payload) => { posted.push(payload) }, + }) + + assert.equal(r.action, 'dequeued') + assert.deepEqual(r.parsed, { sha: TIP.slice(0, 12) }, 'the short sha the person wrote is what the request parsed') + assert.deepEqual(seen, [[3280, TIP]], 'dequeue got the pull request and the full live head it must still match') + assert.equal(posted.length, 1) + assert.match(posted[0].body, /Dequeued by: Chief/) + assert.ok(posted[0].body.includes(TIP), 'the note names the tip') + assert.ok(posted[0].body.includes(STOP_URL), 'the note links the stop request it answered') +}) + +test('#3280: a stop request naming another tip changes nothing', async () => { + const g = fakeGraphql() + let called = false + const r = await handleStopRequest({ + event: event({ comment: comment({ body: `Stop request for this tip: do not merge \`${OTHER}\`` }) }), + graphql: g.client, + repo: 'ThinkFlowLab/FlyBot', + dequeue: async () => { called = true; return true }, + postComment: async () => {}, + }) + + assert.equal(r.action, 'ignored') + assert.equal(called, false) + assert.equal(g.mutations().length, 0) +}) + +test('#3280: a comment that is not a stop request never calls GraphQL at all', async () => { + const g = fakeGraphql() + const r = await handleStopRequest({ + event: event({ comment: comment({ body: 'Looks good to me — thanks for the fix.' }) }), + graphql: g.client, + repo: 'ThinkFlowLab/FlyBot', + dequeue: async () => assert.fail('no dequeue for a comment that names no tip'), + postComment: async () => assert.fail('no note for a comment that names no tip'), + }) + + assert.equal(r.action, 'none') + assert.equal(g.calls.length, 0, 'not one request, so a stray stop request cannot touch the queue') +}) + +test('#3280: only a pull request based on main is read, and a merged one is never re-judged', async () => { + const notMain = fakeGraphql({ pr: pull({ baseRefName: 'release/v0.2.39' }) }) + const a = await handleStopRequest({ + event: event(), + graphql: notMain.client, + repo: 'ThinkFlowLab/FlyBot', + dequeue: async () => assert.fail('a release branch has no main queue entry'), + postComment: async () => {}, + }) + assert.equal(a.action, 'ignored') + assert.match(a.reason, /not main/) + + const merged = fakeGraphql({ pr: pull({ merged: true, state: 'MERGED' }) }) + const b = await handleStopRequest({ + event: event(), + graphql: merged.client, + repo: 'ThinkFlowLab/FlyBot', + dequeue: async () => assert.fail('a merged pull request is history, not a request'), + postComment: async () => {}, + }) + assert.equal(b.action, 'ignored') + assert.match(b.reason, /merged/) +}) + +test('#3280: a comment on a plain issue names no pull request and changes nothing', async () => { + const g = fakeGraphql() + const r = await handleStopRequest({ + event: { action: 'created', issue: { number: 12 }, comment: comment() }, + graphql: g.client, + repo: 'ThinkFlowLab/FlyBot', + dequeue: async () => assert.fail('an issue has no queue entry'), + postComment: async () => {}, + }) + assert.equal(r.action, 'none') + assert.equal(g.calls.length, 0) +}) diff --git a/.github/workflows/stop-request.yml b/.github/workflows/stop-request.yml new file mode 100644 index 000000000..5fc931ccf --- /dev/null +++ b/.github/workflows/stop-request.yml @@ -0,0 +1,49 @@ +name: Stop request + +# #3280. `merge-gate` and `enqueue-guard` read a stop request only while they run, and on #3279 both had +# already finished when the author posted one: `Test` went green at 04:47:33Z, the request landed at +# 04:47:43Z, and the merge queue merged the entry at 04:47:58Z. This workflow reads the request itself. +# +# `issue_comment` on a pull request only: the first job condition drops a comment on a plain issue, and +# `stop-request.mjs` drops anything that is not `Stop request for this tip: ` for the live head of a +# pull request based on `main`. The job takes its code from `main` and never from the pull request, so no +# pull request's tree is executed here, and it writes exactly one thing — the note that names the tip it +# dequeued (`Dequeued by: Chief`) — plus the dequeue itself. +# +# `issues: write` is for that note: GitHub posts a pull request comment through the issue-comments API. +# `pull-requests: write` is the queue mutation's permission. +on: + issue_comment: + types: [created] + +# One dequeue per pull request at a time: two comments can arrive together, and the second must read the +# queue after the first, not race it. +concurrency: + group: stop-request-${{ github.event.issue.number }} + cancel-in-progress: true + +permissions: + contents: read + issues: write + pull-requests: write + +jobs: + dequeue: + name: dequeue + # A comment on a plain issue is not a pull request; the script reads the rest of the event payload. + if: github.event.issue.pull_request != null + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: main + persist-credentials: false + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 24 + - name: Dequeue the entry when the comment is a stop request for the live tip + env: + GITHUB_TOKEN: ${{ github.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: node .github/scripts/stop-request.mjs diff --git a/docs/testing-layers.json b/docs/testing-layers.json index 2da62da3e..1a3319e34 100644 --- a/docs/testing-layers.json +++ b/docs/testing-layers.json @@ -163,6 +163,15 @@ "runs": "pull_request_target, pull_request_review, issue_comment, workflow_dispatch", "role": "Writes the `enqueue-guard` check run a merge on the fork requires: the decision of `enqueue-guard.mjs`, on the live head, from code taken from `main`. The ruleset refuses a merge while it is red (#812)." }, + { + "id": "stop-request", + "workflow": ".github/workflows/stop-request.yml", + "kind": "workflow-only", + "layer": "none", + "gate": false, + "runs": "issue_comment (created) on a pull request", + "reason": "Takes an entry out of the merge queue when a stop request posted after its required checks have run names the live tip (#3280). It is not a required check and writes only the dequeue and its note; the decision is `.github/scripts/stop-request.mjs`, tested by `.github/scripts/stop-request.test.mjs` in the L1 `scripts` suite, so this workflow has no test file of its own." + }, { "id": "docker", "workflow": ".github/workflows/docker.yml", diff --git a/docs/testing-layers.md b/docs/testing-layers.md index 405943563..4c52750ff 100644 --- a/docs/testing-layers.md +++ b/docs/testing-layers.md @@ -105,6 +105,7 @@ The tables below are generated: edit `docs/testing-layers.json`, then run | `test.yml` | gate | L2 | yes | push to main, pull_request, merge_group | Runs every L1 suite, the packaging and patch-pin checks, the strict typecheck, the changelog check and the workflow lint on `push`, `pull_request` and `merge_group`, and aggregates them as `tests-ok`, which `main` requires. | | `merge-gate.yml` | gate | L2 | yes | merge_group (reports on pull_request) | Re-reads `hold` and the newest conclusion at the entry's head, and fails the queue entry when either refuses it. On `pull_request` it also reports work `main` merged that the branch deletes (silent-revert, #914) — report only. | | `enqueue-guard.yml` | gate | L2 | yes | pull_request_target, pull_request_review, issue_comment, workflow_dispatch | Writes the `enqueue-guard` check run a merge on the fork requires: the decision of `enqueue-guard.mjs`, on the live head, from code taken from `main`. The ruleset refuses a merge while it is red (#812). | +| `stop-request.yml` | workflow-only | none | no | issue_comment (created) on a pull request | Takes an entry out of the merge queue when a stop request posted after its required checks have run names the live tip (#3280). It is not a required check and writes only the dequeue and its note; the decision is `.github/scripts/stop-request.mjs`, tested by `.github/scripts/stop-request.test.mjs` in the L1 `scripts` suite, so this workflow has no test file of its own. | | `docker.yml` | workflow-only | L2 | yes | pull_request that touches the image | Builds the container image and starts it, so a packaging change cannot merge without the image proving it starts. | | `live-e2e.yml` | workflow-only | L3 | no | daily on main | Drives the real end-to-end suite with a real model against `main`; it is the automation behind the self-test layer, and it never gates a merge. | | `review-gate.yml` | not-a-layer | none | no | — | Validates and posts the conclusion on a pull request. It gates nothing by itself: `merge-gate` re-judges the entry at merge time. |