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
3 changes: 3 additions & 0 deletions changelog.d/540-merge-command.fixed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Written-by: HugoXK

The console merge button now runs through the management contract: a merge whose answer from GitHub is lost leaves an `unknown` receipt instead of a 500, and submitting the same form again reads the pull request back, records the merge once (work item, PR state, audit) and never merges it twice.
19 changes: 19 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2281,6 +2281,25 @@ effect is what moved the revision), `absent` resends exactly once under the same
revision fence, and `still-unknown` — or an operation with no hook at all —
answers `management_unknown` and writes nothing. Nothing is resent blind.

`task.merge` (#540 slice 6) is the first command whose durable effect is not in
SQLite: GitHub performs the merge. The gates and the merge call stay in
`Jobs.tryMerge`, which the auto-merge path uses too, so the two paths cannot
disagree about what may merge. The operation calls `Jobs.manualMerge` with the
transport failure rethrown, which is what turns a lost answer into an `unknown`
receipt instead of a refusal. The stable marker is the remote pull request, read
back by `Jobs.probePullRequestMerged`: `merged` settles the receipt with
`reconciled: true`, and the verdict's `settle` callback writes the work item, the
PR state, the `job.manually_merged` audit row and the job event that the lost
answer skipped — inside the receipt transaction, exactly where `commit` runs on
the accepted path. The merge already moved the revision, so the settle does not
bump it. A probe that finds the pull request not merged proves the effect absent
and the command runs once more under the same fence. A fresh key that finds the
pull request already merged is a success (`alreadyMerged`), not the old failure
sentence, and `recordMerge` skips the counter, audit and event when the merge is
already recorded. Merging requires the new `job.merge` capability, held by
`maintainer` only; `release.manage` is also maintainer-only, but cutting a
release is not merging this pull request.

`ManagementService.markUnknown` is for an adapter that learns about a lost
response itself, such as a future API or chat channel: only the principal on the
receipt may call it, it applies only while the receipt is still `accepted`, and a
Expand Down
67 changes: 60 additions & 7 deletions src/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2197,6 +2197,13 @@ export async function buildApp(options: BuildOptions): Promise<BuiltApp> {
commands[`work-scope:${item.id}`] = fields()
commands[`work-verify:${item.id}`] = fields()
}
// #540 slice 6: each delivery row's merge button carries its own job
// revision and key, so a double click replays one receipt and a page
// rendered before the job moved on conflicts instead of merging blind.
const prJobs = store.listPrJobsForRepo(repo.id, 10)
for (const prJob of prJobs) {
commands[`merge:${prJob.id}`] = { revision: management.revisionOf('job', prJob.id), idempotencyKey: randomId('cmd') }
}
return reply.type('text/html').send(
repoPage({
config,
Expand All @@ -2214,7 +2221,7 @@ export async function buildApp(options: BuildOptions): Promise<BuiltApp> {
},
jobs: store.listJobsPageForRepo(repo.id, 10, (jobsPage - 1) * 10),
queued: store.listQueuedJobs(),
prJobs: store.listPrJobsForRepo(repo.id, 10),
prJobs,
workItems,
// #379: the repository page lists every state the ledger can hold. These
// are the ids jobs reported, not GitHub's alert store.
Expand Down Expand Up @@ -3616,18 +3623,64 @@ export async function buildApp(options: BuildOptions): Promise<BuiltApp> {
return reply.redirect(`/repos/${repo.id}/jobs/${job.id}?${key}=${encodeURIComponent(message)}`)
})

// #540 slice 6: the merge button is a command whose durable effect is on
// GitHub. The gates and the merge call stay in `Jobs.tryMerge`; the route
// resolves the actor, the job and the revision the page rendered, and turns the
// receipt into a redirect. A lost answer leaves the receipt `unknown`, and
// resubmitting the same form reconciles against the pull request first.
app.post('/repos/:id/jobs/:jobId/merge', async (request, reply) => {
// #708: expensive — a merge writes to the upstream repository.
if (!limits.take('expensive', `job-merge:${rateLimitKey(request)}`)) return refuseTooMany(request, reply)
const { viewer, repo } = ownedRepo(request, String((request.params as Record<string, string>).id), true)
const job = store.getJob(String((request.params as Record<string, string>).jobId))
if (job === undefined || job.repo_id !== repo.id) throw httpError(404, '任务不存在。', 'JOB_NOT_FOUND')
if (repo.repo_role !== 'maintainer') return reply.redirect(`/repos/${repo.id}/jobs/${job.id}?error=${encodeURIComponent('只有 maintainer 可以合并 PR。')}`)
const result = await jobs.manualMerge(repo, job)
store.audit(viewer.user.id, 'job.merge_requested', `${job.id}: ${result.ok ? 'merged' : (result.message ?? 'failed')}`)
const key = result.ok ? 'notice' : 'error'
const message = result.ok ? 'PR 已合并。' : (result.message ?? '合并失败。')
return reply.redirect(`/repos/${repo.id}/jobs/${job.id}?${key}=${encodeURIComponent(message)}`)
const back = `/repos/${repo.id}/jobs/${job.id}`
const t = translator(request.locale ?? 'zh')
const today = async (): Promise<{ notice: string } | { error: string }> => {
if (repo.repo_role !== 'maintainer') return { error: t('只有 maintainer 可以合并 PR。', 'Only a maintainer can merge a pull request.') }
const result = await jobs.manualMerge(repo, job)
const merged = result.ok || result.alreadyMerged === true
store.audit(viewer.user.id, 'job.merge_requested', `${job.id}: ${merged ? 'merged' : (result.message ?? 'failed')}`)
return merged ? { notice: t('PR 已合并。', 'The pull request is merged.') } : { error: result.message ?? t('合并失败。', 'The merge failed.') }
}
const answer = (result: { notice: string } | { error: string }) => ('notice' in result
? reply.redirect(`${back}?notice=${encodeURIComponent(result.notice)}`)
: reply.redirect(`${back}?error=${encodeURIComponent(result.error)}`))

if (config.managementService === 'off') return answer(await today())

const parts = commandParts(form(request), management.revisionOf('job', job.id))
const actor = managementActor({ store, userId: viewer.user.id, repo, channel: 'web', requestId: request.id })
const envelope = {
operation: 'task.merge',
target: { projectId: repo.id, jobId: job.id },
arguments: {},
expectedRevision: parts.expectedRevision,
idempotencyKey: parts.idempotencyKey,
}

if (config.managementService === 'shadow') {
const begun = management.begin(actor, envelope)
const result = await today()
// The receipt records what the contract would have done with the same form;
// a replay never rewrites a receipt that already answered.
if (begun.ok && !begun.replayed) {
management.settle(begun.receipt.id, 'notice' in result
? { ok: true, result: { jobId: job.id, shadow: true } }
: { ok: false, code: 'job_not_merged', message: 'the route refused the merge' })
}
return answer(result)
}

const outcome = await management.run(actor, envelope)
if (outcome.ok) return answer({ notice: t('PR 已合并。', 'The pull request is merged.') })
// A gate refusal is not a management code: its sentence is the reason the
// service wrote (a stale check, a missing approval), which is what the job
// page showed before this slice.
const sentence = outcome.code === 'job_not_merged'
? (outcome.message === '' ? t('合并失败。', 'The merge failed.') : outcome.message)
: managementFailure(t, outcome, t('合并失败。', 'The merge failed.'))
return reply.redirect(`${back}?error=${encodeURIComponent(sentence)}&code=${outcome.code}`)
})

app.post('/repos/:id/jobs/:jobId/approve-plan', async (request, reply) => {
Expand Down
7 changes: 6 additions & 1 deletion src/identity/authorization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ export type Capability =
// (maintainer only) so moving the write behind the contract does not take the
// action away from the role that held it before.
| 'repo.policy'
// #540 slice 6: merging a pull request. `release.manage` is also maintainer
// only, but "may cut a release" is not "may merge this PR", and the capability
// is the only place that distinction can live.
| 'job.merge'

export const ALL_CAPABILITIES: readonly Capability[] = [
'tasks.read',
Expand All @@ -41,13 +45,14 @@ export const ALL_CAPABILITIES: readonly Capability[] = [
'job.resume',
'job.retry',
'repo.policy',
'job.merge',
]

export const REPO_ROLES = ['maintainer', 'developer', 'viewer'] as const
export type RepoRole = (typeof REPO_ROLES)[number]

const ROLE_CAPABILITIES: Readonly<Record<RepoRole, readonly Capability[]>> = {
maintainer: ['tasks.read', 'tasks.write', 'config.write', 'repo.policy', 'release.manage', 'knowledge.read', 'knowledge.write', 'schedules.manage', 'job.cancel', 'job.pause', 'job.create', 'job.resume', 'job.retry'],
maintainer: ['tasks.read', 'tasks.write', 'config.write', 'repo.policy', 'release.manage', 'knowledge.read', 'knowledge.write', 'schedules.manage', 'job.cancel', 'job.pause', 'job.create', 'job.resume', 'job.retry', 'job.merge'],
// #624 added `job.create`, `job.resume` and `job.retry` as commands the
// connection owner holds. `deriveRepoRole` maps a write-permission connection to
// `developer`, so that role must carry them or an owner with a write token loses
Expand Down
60 changes: 47 additions & 13 deletions src/jobs/service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2343,7 +2343,7 @@ export class Jobs {
return { block, reused: false, refusal: null }
}

private async tryMerge(job: JobRow, prUrl: string, manual: boolean): Promise<{ ok: boolean; message?: string }> {
private async tryMerge(job: JobRow, prUrl: string, manual: boolean, rethrowTransport = false): Promise<{ ok: boolean; message?: string; alreadyMerged?: boolean }> {
if (job.kind !== 'iterate') return { ok: false, message: '只有 iterate 任务可以合并。' }
let repo = this.store.getRepo(job.repo_id)
if (repo === undefined) return { ok: false, message: '仓库不存在。' }
Expand Down Expand Up @@ -2423,8 +2423,12 @@ export class Jobs {
}
}
if (pr.merged) {
// #540 slice 6: a merge command that finds the pull request already
// merged did not fail — the effect it wanted is there. The caller records
// the local rows the lost answer skipped; the auto-merge path keeps
// treating it as "nothing to do" and is unchanged.
this.store.updateJobsPrState(prUrl, 'merged')
return { ok: false, message: 'PR 已合并。' }
return { ok: false, message: 'PR 已合并。', alreadyMerged: true }
}
if (pr.state !== 'open' || pr.draft) return { ok: false, message: 'PR 不是 open 状态。' }
const guard = await this.pathGuardFor(client, owner, name, number, job, repo, pr.changedFiles)
Expand Down Expand Up @@ -2534,26 +2538,56 @@ export class Jobs {
const requestedMethod = repo.merge_method === 'merge' || repo.merge_method === 'rebase' ? repo.merge_method : 'squash'
const merged = await client.mergePullRequest(owner, name, number, { sha: pr.headSha, mergeMethod: requestedMethod })
if (merged.merged) {
const workItem = job.work_item_id === null ? undefined : this.store.getWorkItem(job.work_item_id)
if (workItem !== undefined) {
this.store.updateWorkItem(workItem.id, { state: 'merged', pr_state: 'merged', merged_at: nowIso(), merge_commit: merged.sha ?? null })
}
incCounter('fledge_merges_total', { result: 'merged' }, 1, 'Pull request merge results')
this.store.updateJobsPrState(prUrl, 'merged')
this.store.audit(job.user_id, manual ? 'job.manually_merged' : 'job.auto_merged', `${job.id}: PR ${number} ${merged.sha ?? ''}`)
this.store.event('job_auto_merged', { userId: job.user_id, repoId: job.repo_id, jobId: job.id, meta: `pr=${number}` })
this.store.recordJobEvent({ jobId: job.id, repoId: job.repo_id, userId: job.user_id, kind: 'job.merged', step: `pr=${number}`, meta: merged.sha ?? null })
this.recordMerge(job, merged.sha, manual)
return { ok: true, message: '已合并。' }
}
this.store.audit(job.user_id, 'job.merge_skipped', `${job.id}: ${merged.message ?? 'merge rejected'}`)
return { ok: false, message: merged.message ?? 'GitHub 拒绝了合并。' }
} catch (error) {
this.store.audit(job.user_id, 'job.merge_failed', `${job.id}: ${String(error).slice(0, 300)}`)
log.warn('merge failed', { trace: job.id, pr: number, error: String(error) })
// #540 slice 6: a transport failure may have crossed the commit boundary —
// GitHub can have merged while the answer was lost. The command path needs
// the error to reach the service so the receipt becomes `unknown`; every
// other caller keeps today's refusal sentence.
if (rethrowTransport) throw error
return { ok: false, message: error instanceof Error ? error.message : String(error) }
}
}

// #540 slice 6: the local record of a merged pull request, in one place so the
// auto-merge path, the console command and a reconciled `unknown` write the
// same rows. `already` is read before the write: a merge recorded by this job's
// own answer or by the webhook is not counted or announced a second time.
recordMerge(job: JobRow, sha: string | undefined, manual = true): void {
const prUrl = job.pr_url
if (prUrl === null) return
const number = /\/pull\/(\d+)/.exec(prUrl)?.[1] ?? ''
const already = this.store.getJob(job.id)?.pr_state === 'merged'
const workItem = job.work_item_id === null ? undefined : this.store.getWorkItem(job.work_item_id)
if (workItem !== undefined) {
this.store.updateWorkItem(workItem.id, { state: 'merged', pr_state: 'merged', merged_at: nowIso(), merge_commit: sha ?? null })
}
this.store.updateJobsPrState(prUrl, 'merged')
if (already) return
incCounter('fledge_merges_total', { result: 'merged' }, 1, 'Pull request merge results')
this.store.audit(job.user_id, manual ? 'job.manually_merged' : 'job.auto_merged', `${job.id}: PR ${number} ${sha ?? ''}`)
this.store.event('job_auto_merged', { userId: job.user_id, repoId: job.repo_id, jobId: job.id, meta: `pr=${number}` })
this.store.recordJobEvent({ jobId: job.id, repoId: job.repo_id, userId: job.user_id, kind: 'job.merged', step: `pr=${number}`, meta: sha ?? null })
}

// #540 slice 6: the reconcile probe for `task.merge`. It reads the one remote
// fact the command needs — whether the pull request is merged — and never calls
// the merge endpoint. A probe that throws leaves the receipt unknown.
async probePullRequestMerged(repo: RepoRow, job: JobRow): Promise<{ merged: boolean; sha?: string }> {
if (job.pr_url === null) return { merged: false }
const parsed = parsePrUrl(repo, job.pr_url, this.config.github.apiBase)
if (!parsed.ok) return { merged: false }
const token = await repoGithubToken(repo, this.config, this.githubApp, this.store)
const pr = await new GithubClient(token, this.config.github.apiBase).getPullRequest(parsed.ref.owner, parsed.ref.name, parsed.ref.number)
return { merged: pr.merged, ...(pr.mergeCommitSha === undefined ? {} : { sha: pr.mergeCommitSha }) }
}

private async verifyAndMaybeMerge(jobId: string): Promise<void> {
const current = this.store.getJob(jobId)
if (current === undefined || current.pr_url === null) return
Expand Down Expand Up @@ -2616,10 +2650,10 @@ export class Jobs {
return { merged, skipped }
}

async manualMerge(repo: RepoRow, job: JobRow): Promise<{ ok: boolean; message?: string }> {
async manualMerge(repo: RepoRow, job: JobRow, options: { rethrowTransport?: boolean } = {}): Promise<{ ok: boolean; message?: string; alreadyMerged?: boolean }> {
if (job.repo_id !== repo.id) return { ok: false, message: '任务不属于这个仓库。' }
if (job.pr_url === null) return { ok: false, message: '这个任务没有 PR。' }
return this.tryMerge(job, job.pr_url, true)
return this.tryMerge(job, job.pr_url, true, options.rethrowTransport === true)
}

private async resolveHeadSha(repo: RepoRow, prUrl: string): Promise<string | undefined> {
Expand Down
57 changes: 56 additions & 1 deletion src/management/catalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,11 @@ export interface OperationResult {
// it provably did not happen, so resending is safe; `still-unknown` means the
// probe itself could not decide, and the receipt has to stay `unknown`.
export type ReconcileVerdict =
| { state: 'applied'; result?: Record<string, unknown> }
// `settle` is for an effect whose local record depends on the external answer:
// a merge that GitHub performed but whose response was lost left the work item,
// the PR state and the audit row unwritten. The service runs it inside the
// receipt transaction, exactly where `commit` runs on the accepted path.
| { state: 'applied'; result?: Record<string, unknown>; settle?: () => void }
| { state: 'absent' }
| { state: 'still-unknown' }

Expand Down Expand Up @@ -354,9 +358,60 @@ const repoUpdate: Operation = {
},
}

// #540 slice 6: the console merge button, whose durable effect is not in SQLite.
// The gates and the merge call stay in `Jobs.tryMerge`, which the auto-merge path
// uses too; this operation only names the command. A transport failure is
// rethrown so the receipt becomes `unknown`, and the probe reads the pull request
// back before anything is resent.
const taskMerge: Operation = {
kind: 'command',
capabilities: ['job.merge'],
requiredTarget: ['projectId', 'jobId'],
revisionTarget: 'jobId',
revisionType: 'job',
async execute(context, target) {
const repo = context.store.getRepo(target.projectId ?? '')
if (repo === undefined) return { status: 'failed', errorCode: 'project_not_found', errorMessage: 'the project does not exist' }
const job = context.store.getJob(target.jobId ?? '')
if (job === undefined || job.repo_id !== repo.id) return { status: 'failed', errorCode: 'job_not_found', errorMessage: 'the job does not exist in this project' }
const result = await context.jobs.manualMerge(repo, job, { rethrowTransport: true })
if (!result.ok) {
// A fresh key after a merge that landed elsewhere is not a failure: the
// effect this command wanted is there. The commit writes the local rows the
// earlier attempt may have skipped, and `recordMerge` keeps it idempotent.
if (result.alreadyMerged === true) {
return {
status: 'succeeded',
result: { jobId: job.id, merged: true, alreadyMerged: true },
commit: () => context.jobs.recordMerge(job, undefined),
}
}
return { status: 'failed', errorCode: 'job_not_merged', errorMessage: result.message ?? 'the pull request was not merged' }
}
return { status: 'succeeded', result: { jobId: job.id, merged: true } }
},
// The stable marker is the remote pull request, read back. `merged` means the
// effect happened whoever performed it, and the settle writes the local record
// the lost answer skipped; anything else proves the merge did not happen, so a
// resend is safe.
async reconcile(context, target) {
const repo = context.store.getRepo(target.projectId ?? '')
const job = context.store.getJob(target.jobId ?? '')
if (repo === undefined || job === undefined) return { state: 'applied', result: { jobId: target.jobId ?? '', reconciled: true } }
const probe = await context.jobs.probePullRequestMerged(repo, job)
if (!probe.merged) return { state: 'absent' }
return {
state: 'applied',
result: { jobId: job.id, merged: true, ...(probe.sha === undefined ? {} : { sha: probe.sha }) },
settle: () => context.jobs.recordMerge(job, probe.sha),
}
},
}

export const OPERATIONS: Readonly<Record<string, Operation>> = Object.freeze({
'repo.update': repoUpdate,
'task.cancel': taskCancel,
'task.merge': taskMerge,
'task.pause': taskPause,
'task.create': taskCreate,
'task.resume': taskResume,
Expand Down
Loading
Loading