Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 183 additions & 0 deletions .github/scripts/stop-request.mjs
Original file line number Diff line number Diff line change
@@ -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: <sha>`, 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 = /(?<![0-9a-f])[0-9a-f]{7,40}(?![0-9a-f])/i
const ALREADY_OUT = /not (?:in|currently in) the (?:merge )?queue|not currently queued|no longer in the queue|already been merged|already merged/i

export function parseStopRequest(body) {
const text = String(body ?? '')
const marker = STOP_MARKER.exec(text)
if (!marker) return null
const rest = text.slice(marker.index + marker[0].length)
const sha = SHA.exec(rest)
return sha ? { sha: sha[0].toLowerCase() } : null
}

// A short sha names a tip only when it is long enough to be one on its own, and either side may be the
// short form: a person writes 12 characters, the REST/GraphQL API returns 40.
export function sameSha(a, b) {
const x = String(a ?? '').toLowerCase()
const y = String(b ?? '').toLowerCase()
if (!/^[0-9a-f]+$/.test(x) || !/^[0-9a-f]+$/.test(y)) return false
if (x.length < SHORT || y.length < SHORT) return false
return x.startsWith(y) || y.startsWith(x)
}

const GITHUB_GRAPHQL = 'https://api.github.com/graphql'

// The injectable client: the tests hand in a fake, the CLI builds this one. A GraphQL refusal arrives as
// HTTP 200 with an `errors` array, so the status alone cannot tell "already out of the queue" from a real
// failure — `message` is what `dequeue` reads.
export function graphqlClient(token, endpoint = GITHUB_GRAPHQL) {
return async function graphql(query, variables = {}) {
const response = await fetch(endpoint, {
method: 'POST',
headers: {
Authorization: `bearer ${token}`,
'Content-Type': 'application/json',
'User-Agent': 'flybot-stop-request',
},
body: JSON.stringify({ query, variables }),
})
const text = await response.text()
if (response.status === 404 || response.status === 422) {
throw Object.assign(new Error(`GraphQL HTTP ${response.status}: ${text.slice(0, 300)}`), { status: response.status })
}
if (!response.ok) throw new Error(`GraphQL HTTP ${response.status}: ${text.slice(0, 300)}`)
let payload = null
try { payload = JSON.parse(text) } catch { /* the status above already refused a bad body */ }
if (payload?.errors?.length) {
throw Object.assign(new Error(payload.errors.map((error) => 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)
})
}
187 changes: 187 additions & 0 deletions .github/scripts/stop-request.test.mjs
Original file line number Diff line number Diff line change
@@ -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)
})
Loading
Loading