UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

610 lines (573 loc) • 37.8 kB
/** * The management side of the operation journal (src/link/operations-journal.ts; structure/remote-link.md, * "Operation journal"): the per-alias lock around apply and revoke, the handle apply marks its effects through, * the replay of a recorded outcome, and the recovery of an entry whose process died before it finished. */ import { randomUUID } from "node:crypto"; import { existsSync } from "node:fs"; import { AliasLockError, withAliasLock } from "../../link/alias-lock"; import type { ExplicitRoute } from "../../link/explicit-route"; import { assertRoomForNewOperation, findOperation, hasEffect, isOperationId, markRevokeLive, OPERATION_JOURNAL_MAX_RECENT_SETTLED, OPERATION_JOURNAL_MAX_UNSETTLED, OperationsJournalFullError, openEnrollmentFor, operationDigest, operationsJournalPath, readOperationsJournal, resolveLinkOperation, updateOperationsJournal, type EnrollEffect, type LinkOperation, type OperationsJournal, type OperationState, type RevokeEffect } from "../../link/operations-journal"; import { readLinkRetirement, type LinkRetirement } from "../../link/retirement"; import { residualRecovery } from "../../link/residual-recovery"; import { newLinkId } from "../../link/store"; import type { ManagementContext } from "./context"; import { compensateNewLink, fail, readStoreFor, revokeKeyIdempotent, type LinkRouteState } from "./link-route-state"; import type { RouteRequest } from "./link-route-request"; /** A damaged operations.json: nothing reads it as empty, so the answer names the way out. */ export function journalUnreadable(): Response { return fail("operation_journal_unreadable", "The link operation journal (<configDir>/link/operations.json) is damaged; keep a copy, move it aside, and retry. ocx link operations shows the same error; a revoke with --force still runs.", 500); } /** Compensation that could not finish: whether anything this operation created remains is unknown. */ const UNKNOWN_CODES = new Set(["compensation_failed", "key_cleanup_failed", "link_cleanup_uncertain", "key_issue_uncertain"]); /** The link a residual's Child step is bound to: an enrollment's reserved id, a revoke's own link. */ function residualLinkId(op: LinkOperation): string | undefined { return op.kind === "enroll" ? op.reserved?.linkId : op.linkId; } /** The Child's side of a residual, as a closed word a client maps to its own guidance. */ function residualKind(op: LinkOperation): "plant" | "enrollment" | undefined { if (op.state !== "residual" && !op.childResidual) return undefined; return hasEffect(op, "plant", "intent") ? "plant" : "enrollment"; } export interface OperationRequest { id: string; digest: string } export function journalPathFor(ctx: ManagementContext): string { return ctx.deps.linkOperationsPath?.() ?? operationsJournalPath(); } const nowOf = (ctx: ManagementContext) => (ctx.deps.now ?? Date.now)(); const iso = (ctx: ManagementContext) => new Date(nowOf(ctx)).toISOString(); /** * A revoke entry that still owns its link's retirement receipt is never pruned (#8416): its replay is the only path * that settles that receipt from its own evidence, recovery must not lose it between two effect marks, and a pruned * id could be reused by an unrelated operation. A receipt that cannot be read keeps the entry. */ export function ownsRetirement(op: LinkOperation): boolean { if (op.kind !== "revoke" || op.linkId === undefined) return false; // Its former owner too: every later plain force fences that entry, so it must outlive its retention while the receipt does. try { const receipt = readLinkRetirement(op.linkId); return receipt?.operationId === op.operationId || receipt?.formerOwner === op.operationId; } catch { return true; } } function retirementOutstanding(op: LinkOperation): boolean { if (op.linkId === undefined) return false; try { return readLinkRetirement(op.linkId) !== null; } catch { return true; } } /** * Whether the journal recorded the Child cleanup a receipt stands for (#8416): its owner (the revoke of that link under * the receipt's id) marked remote_cleanup done and, for a purge, holds the Child's purged:true for that link. This is * the evidence a replayed purge already answers from; the receipt alone is not. Unreadable is false. */ export function cleanupRecorded(ctx: ManagementContext, receipt: LinkRetirement): boolean { let owner: LinkOperation | undefined; try { owner = retirementOwner(readOperationsJournal(journalPathFor(ctx)), receipt); } catch { return false; } if (!owner || !hasEffect(owner, "remote_cleanup", "done")) return false; return receipt.mode !== "purge" || (owner.receipt?.purged === true && owner.receipt.linkId === receipt.link.id); } /** * The journalled owner of a retirement receipt: the revoke of that same link under the receipt's operation id. With * includeFormer, a receipt a plain --force disowned answers its former owner, which every later force fences too. */ export function retirementOwner(journal: OperationsJournal, receipt: LinkRetirement, includeFormer = false): LinkOperation | undefined { const id = receipt.operationId ?? (includeFormer ? receipt.formerOwner : undefined); if (id === undefined) return undefined; const op = findOperation(journal, id); return op && op.kind === "revoke" && op.linkId === receipt.link.id ? op : undefined; } function updateJournalPinned<T>(path: string, nowMs: number, change: (journal: OperationsJournal) => T): T { return updateOperationsJournal(path, nowMs, change, ownsRetirement); } /** * The parameters that name an enrollment. plant is left out: it follows from what the probe found, and a repeat * replays without probing, so it cannot restate it. */ export function enrollOperationDigest(params: { alias: string; fingerprint?: string; route: RouteRequest; requireEphemeral: boolean }): string { return operationDigest({ kind: "enroll", alias: params.alias, fingerprint: params.fingerprint ?? null, explicitRoute: params.route.explicitRoute, exclusive: params.route.exclusive, requireEphemeral: params.requireEphemeral }); } /** * Has this Home ever journalled an operation? Until it has, an apply or revoke without an operation id behaves * exactly as before: no lock file, no journal read, no new refusal. */ export function journalInUse(ctx: ManagementContext): boolean { return existsSync(journalPathFor(ctx)); } /** * Apply and revoke run under their alias's lock when required (an operation id, or a Home that has a journal); a * holder past the wait answers 409. Not required: the action runs as it always did. */ export async function underAliasLock(ctx: ManagementContext, alias: string, required: boolean, action: () => Promise<Response>): Promise<Response> { if (!required) return await action(); try { return await withAliasLock(alias, { ...ctx.deps.linkAliasLock, signal: ctx.req.signal }, action); } catch (error) { if (error instanceof AliasLockError) { if (error.code === "link_alias_lock_busy") return fail("link_operation_in_progress", "Another enrollment or revoke of this alias is running; try again when it ends.", 409); // The client went away while waiting: nothing ran, and nobody is left to read a longer answer. if (error.code === "link_alias_lock_aborted") return fail("link_operation_in_progress", "The request ended while it waited for this alias; nothing was changed.", 409); return fail("link_alias_lock_failed", "The alias lock could not be taken.", 500); } throw error; } } /** An open revoke entry of another operation for this link refuses every other revoke of it. */ export function openRevokeConflict(ctx: ManagementContext, linkId: string, except?: string, force = false): Response | null { if (!journalInUse(ctx)) return null; let open: LinkOperation | undefined; try { open = readOperationsJournal(journalPathFor(ctx)).operations.find(op => op.kind === "revoke" && op.state === "open" && op.linkId === linkId && op.operationId !== except); } catch { // --force is the escape hatch: it skips remote cleanup by design, so it must not be locked out by a damaged journal. if (force) { console.warn("[link] operation journal unreadable; force revoke proceeds without the open-entry check linkId=" + linkId); return null; } return journalUnreadable(); } return open ? fail("link_operation_open", "An unfinished revoke holds this link; repeat it with its operation id to settle it.", 409) : null; } /** An open enroll entry of another operation for this alias refuses every other enrollment. */ export function openEnrollmentConflict(ctx: ManagementContext, alias: string, except?: string): Response | null { if (!journalInUse(ctx)) return null; let open: LinkOperation | undefined; try { open = openEnrollmentFor(readOperationsJournal(journalPathFor(ctx)), alias, except); } catch { return journalUnreadable(); } return open ? fail("link_operation_open", "An unfinished enrollment holds this alias; repeat it with its operation id to settle it.", 409) : null; } function outcomeBody(op: LinkOperation): Record<string, unknown> { return { operationId: op.operationId, outcome: op.state }; } /** The recorded outcome as a response: committed answers like the apply that committed. */ /** A new operation's entry could not be written: 409 when the journal is full, 500 otherwise. Nothing ran either way. */ export function journalOpenFailure(error: unknown): Response { if (!(error instanceof OperationsJournalFullError)) return fail("operation_journal_failed", "The link operation journal could not be written; nothing was changed.", 500); const message = error.bound === "unsettled" ? "The link operation journal holds " + OPERATION_JOURNAL_MAX_UNSETTLED + " unsettled operations. Check the Child of each residual or unknown one and run ocx link operations resolve --operation-id <id> --yes; repeat an open one with its operation id first (ocx link operations lists them). Nothing was changed." : "The link operation journal holds " + OPERATION_JOURNAL_MAX_RECENT_SETTLED + " operations that settled within the last 2 hours and three minutes; retry once the oldest of them is older than that. Nothing was changed."; // bound is a closed field a CLI picks its own guidance by; it is additive, and an older CLI drops it and still refuses. return Response.json({ error: { code: "operation_journal_full", message }, bound: error.bound }, { status: 409, headers: { "cache-control": "no-store" } }); } export function replayResponse(op: LinkOperation): Response { if (op.state === "committed") { return Response.json(op.kind === "enroll" ? { linkId: op.reserved!.linkId, ...outcomeBody(op), ...(hasEffect(op, "plant", "done") ? { planted: true } : {}) } : { linkId: op.linkId, ...outcomeBody(op), ...(op.receipt ? { purged: true } : {}) }, { status: op.kind === "enroll" ? 202 : 200 }); } const error = op.error ?? { code: "operation_interrupted", status: 409 }; return Response.json({ error: { code: error.code, message: "The operation ended " + op.state + "; this is its recorded outcome." }, ...outcomeBody(op), // The Child's step is bound to the link id the journal recorded before anything changed (src/link/residual-recovery.ts). ...(residualKind(op) ? { residual: true, residualKind: residualKind(op), ...(residualLinkId(op) ? { linkId: residualLinkId(op) } : {}), recovery: residualRecovery(residualKind(op) === "plant" ? "plant" : "enrollment", residualLinkId(op)) } : {}), }, { status: error.status, headers: { "cache-control": "no-store" } }); } /** * A repeat: the same id with the same digest reads its outcome; another digest or kind is refused. An entry * still open here belongs to a process that died (this caller holds the alias lock), so it is recovered first. * null when there is no entry. */ export async function replayOperation(ctx: ManagementContext, state: LinkRouteState, request: OperationRequest, kind: LinkOperation["kind"]): Promise<Response | null> { let op: LinkOperation | undefined; try { op = findOperation(readOperationsJournal(journalPathFor(ctx)), request.id); } catch { return journalUnreadable(); } if (!op) return null; if (op.kind !== kind || op.digest !== request.digest) return fail("operation_mismatch", "This operation id was used with other parameters.", 409); if (op.state === "open") op = kind === "enroll" ? await recoverEnroll(ctx, state, op) : recoverRevoke(ctx, op); return replayResponse(op); } function settle(ctx: ManagementContext, operationId: string, outcome: OperationState, error?: { code: string; status: number }, childResidual = false): LinkOperation { return updateJournalPinned(journalPathFor(ctx), nowOf(ctx), journal => { const op = findOperation(journal, operationId)!; op.state = outcome; if (childResidual && op.kind === "enroll") op.childResidual = true; op.updatedAt = iso(ctx); if (outcome !== "open") op.finishedAt = op.updatedAt; if (error && outcome !== "committed") op.error = error; return structuredClone(op); }); } /** * Recovery by reserved id. A completed relay verification committed; only its outcome write was lost. Otherwise * whatever carries this operation's reserved link id or key id is undone; another link for the alias is not this * operation's and makes the outcome unknown, as does compensation that does not finish. A Child that was asked to * enroll, or given a plant, may still hold it: residual. */ async function recoverEnroll(ctx: ManagementContext, state: LinkRouteState, op: LinkOperation): Promise<LinkOperation> { const reserved = op.reserved!; const interrupted = { code: "operation_interrupted", status: 409 }; if (hasEffect(op, "relay_verified", "done")) return settle(ctx, op.operationId, "committed"); const store = readStoreFor(ctx), wanted = op.alias.toLowerCase(); const childTouched = hasEffect(op, "child_enrolled", "intent") || hasEffect(op, "plant", "intent"); if (store.links.some(link => link.direction === "hub-initiated" && link.alias.toLowerCase() === wanted && link.id !== reserved.linkId)) { // Which link is whose is unclear, so the outcome is unknown; but the reserved key id names only this operation's // key, and with no record carrying the reserved link id nothing depends on it. if (!store.links.some(link => link.id === reserved.linkId)) revokeKeyIdempotent(ctx, reserved.apiKeyId); return settle(ctx, op.operationId, "unknown", interrupted, childTouched); } const record = store.links.find(link => link.id === reserved.linkId); if (record) { if (await compensateNewLink(ctx, state, record)) return settle(ctx, op.operationId, "unknown", interrupted, childTouched); } else if (!revokeKeyIdempotent(ctx, reserved.apiKeyId)) { return settle(ctx, op.operationId, "unknown", interrupted, childTouched); } return settle(ctx, op.operationId, childTouched ? "residual" : "failed_clean", interrupted); } /** * A revoke whose process died, settled from its own marks only. Its link counts as removed by it only after its own * removal intent: every other revoke of the link was refused while this entry was open, so a record gone after that * mark went by this operation's write, and a record gone before it went some other way (unknown). With the record * still there, any started effect (cleanup on the Child, the key revoke, the removal) leaves it unknown. */ function recoverRevoke(ctx: ManagementContext, op: LinkOperation): LinkOperation { const removed = !readStoreFor(ctx).links.some(link => link.id === op.linkId); const removalStarted = hasEffect(op, "record_removed", "intent"); // A retirement receipt still outstanding for the link means its post-commit work has not finished (#8416): this // revoke's own receipt was resumed before replay, so one left here belongs to another identity or is unreadable. const outstanding = retirementOutstanding(op); if (removed && removalStarted && !outstanding) return settle(ctx, op.operationId, "committed"); // An outstanding receipt counts as touched: a removal was claimed and its outcome is not known to be nothing. const touched = removalStarted || outstanding || hasEffect(op, "remote_cleanup", "intent") || hasEffect(op, "key_revoked", "intent"); return settle(ctx, op.operationId, removed || touched ? "unknown" : "failed_clean", { code: "operation_interrupted", status: 409 }); } /** A plain --force's hold on the owner of the receipt it finishes (fenceRetirementOwnerForForce). */ export interface ForceTakeover { readonly operationId: string; /** * The journal the force's removal runs with: it writes no marks (the force claims nothing); its first intent, written just * before the tunnel is held and stopped, marks the takeover begun; the owner settles before the receipt is cleared; release * drops the owner's live mark with the tunnel hold. */ readonly journal: RevokeJournal; /** Whether the force's removal reached the tunnel (its first intent). */ readonly began: boolean; /** Drop the live mark and settle the owner unknown and unresolved: it is never credited with the force's removal. */ settle(): void; /** The takeover never began its removal: drop the live mark and restore the owner exactly as it was. */ abandon(): void; } /** * Before a plain --force finishes an owned receipt, fence its owner for the whole takeover (#8416). An open owner (its * process died; the force holds the alias lock and this runtime's per-alias set) or an unknown one is reopened as an * open, live revoke once that write is durable, so resolve refuses it while the force runs; the force's removal drops the * live mark in the same step that releases the tunnel hold, and settle() leaves the owner unknown and unresolved, so a * link the force could not remove stays suspended (revokeSuspendsLink). Null when there is no such owner to fence. */ export function fenceRetirementOwnerForForce(ctx: ManagementContext, receipt: LinkRetirement): ForceTakeover | null { const path = journalPathFor(ctx); // A receipt an earlier force disowned still fences its former owner: a later force could otherwise leave it resolvable. const owner = retirementOwner(readOperationsJournal(path), receipt, true); if (!owner || (owner.state !== "open" && owner.state !== "unknown")) return null; const operationId = owner.operationId; const prior = { state: owner.state, finishedAt: owner.finishedAt, resolvedAt: owner.resolvedAt, error: owner.error, updatedAt: owner.updatedAt }; updateJournalPinned(path, nowOf(ctx), journal => { const op = findOperation(journal, operationId); if (!op) throw new Error("the revoke operation is no longer journalled"); if (op.state !== "open") { op.state = "open"; delete op.finishedAt; delete op.resolvedAt; delete op.error; op.updatedAt = iso(ctx); } }); markRevokeLive(path, operationId, true); let live = true, began = false; const drop = (): void => { if (live) { live = false; markRevokeLive(path, operationId, false); } }; const settleOwner = (): void => { const op = findOperation(readOperationsJournal(path), operationId); if (op?.state === "open") settle(ctx, operationId, "unknown", { code: "operation_interrupted", status: 409 }); }; return { operationId, get began() { return began; }, journal: { intent() { began = true; }, done() {}, cleanupNotRun() {}, release: drop, finish: async response => response, // Settled before the receipt is cleared: a crash after the clear cannot leave the owner open with its own removal // intent and the record gone, which recovery would credit to it. A failed write keeps the receipt (and the owner). beforeReceiptCleared: () => { drop(); settleOwner(); }, }, settle() { drop(); settleOwner(); }, abandon() { drop(); if (prior.state === "open") return; updateJournalPinned(path, nowOf(ctx), journal => { const op = findOperation(journal, operationId); if (!op || op.state !== "open") return; op.state = prior.state; op.updatedAt = prior.updatedAt; if (prior.finishedAt !== undefined) op.finishedAt = prior.finishedAt; if (prior.resolvedAt !== undefined) op.resolvedAt = prior.resolvedAt; if (prior.error !== undefined) op.error = prior.error; }); }, }; } /** * A recorded revoke whose interrupted retirement was just finished (#8416): its own removal intent preceded the * record's disappearance, so it committed, whatever its live response, an earlier recovery or a resolve recorded. * The check and the write run in one journal section, so a concurrent resolve cannot leave a committed entry that * still carries resolvedAt (which the journal refuses to parse). */ export function settleRevokeAfterRetirement(ctx: ManagementContext, operationId: string): void { updateJournalPinned(journalPathFor(ctx), nowOf(ctx), journal => { const current = findOperation(journal, operationId); // failed_clean too: a write failure right after the receipt claim can leave the owner recorded clean (#8416). if (!current || current.kind !== "revoke" || (current.state !== "open" && current.state !== "unknown" && current.state !== "failed_clean")) return; if (!hasEffect(current, "record_removed", "intent") || readStoreFor(ctx).links.some(link => link.id === current.linkId)) return; current.state = "committed"; delete current.error; delete current.resolvedAt; current.updatedAt = iso(ctx); current.finishedAt = current.updatedAt; }); } /** * The journal of a recorded revoke resuming its interrupted retirement (#8416): the resumed key revoke and record * removal are marked on that same entry, so a crash after the resumed removal still settles it as committed. * Used only while the link record is present, so a record another removal already took is never credited here. * The entry settles before the receipt is cleared: a crash between them leaves the receipt for the next repeat to * resume, never a finished removal whose entry stays unknown with nothing left to resume. */ export function resumedRevokeJournal(ctx: ManagementContext, operationId: string, markEffects: boolean): RevokeJournal { const path = journalPathFor(ctx); let reopened = false; // The resumed removal runs as an open, live revoke from its first intent (written before stopLink, whether or not the // Child cleanup is rerun): resolve refuses an open entry, so no resolution (earlier or concurrent) can cover a removal // whose outcome is pending; a resume that fails settles it unknown and unresolved (settleResumedRevoke), so the link // stays suspended (revokeSuspendsLink). The live mark is set only once that reopening write is durable. const mark = (effect: RevokeEffect, phase: "intent" | "done", receipt?: { purged: true; linkId: string }) => { if (!markEffects) return; const reopen = phase === "intent" && !reopened; updateJournalPinned(path, nowOf(ctx), journal => { const op = findOperation(journal, operationId); if (!op) throw new Error("the revoke operation is no longer journalled"); // Recovery reads only whether a mark exists (hasEffect), so a mark already recorded is not appended again: repeated // resumes of a pinned entry cannot grow it past one intent and one completion per effect. if (!hasEffect(op, effect, phase)) op.effects.push({ effect, phase, at: iso(ctx) }); if (receipt) op.receipt = receipt; op.updatedAt = iso(ctx); if (reopen && op.state !== "open") { op.state = "open"; delete op.finishedAt; delete op.resolvedAt; delete op.error; } }); if (reopen) { reopened = true; markRevokeLive(path, operationId, true); } }; return { operationId, keepsTunnelDown: true, intent: effect => mark(effect, "intent"), // As for a fresh revoke: a completion is best effort unless it carries the Child's purge receipt. done: (effect, receipt) => { try { mark(effect, "done", receipt); } catch (error) { if (receipt) throw error; console.warn("[link] resumed revoke journal mark not written operation=" + operationId + " mark=" + effect + ":done"); } }, beforeReceiptCleared: () => settleRevokeAfterRetirement(ctx, operationId), cleanupNotRun: () => {}, release: () => { if (reopened) markRevokeLive(path, operationId, false); }, finish: async response => response, }; } /** * A resumed retirement that did not finish (#8416): an owner it left open settles unknown, unresolved, with the * failure's code, as a fresh revoke's finish settles it; its live mark goes in the same step. */ export async function settleResumedRevoke(ctx: ManagementContext, operationId: string, response: Response): Promise<void> { const path = journalPathFor(ctx); // Dropped before anything awaits: an open entry that is not live is suspended until it settles. markRevokeLive(path, operationId, false); try { let code = "revoke_failed"; try { const body = await response.clone().json() as { error?: { code?: unknown } }; if (typeof body.error?.code === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(body.error.code)) code = body.error.code; } catch { /* keeps revoke_failed */ } const op = findOperation(readOperationsJournal(path), operationId); if (op?.state === "open") settle(ctx, operationId, "unknown", { code, status: response.status >= 400 && response.status <= 599 ? response.status : 500 }); } finally { markRevokeLive(path, operationId, false); } } export interface EnrollJournal { readonly reservedLinkId?: string; readonly reservedKeyId?: string; intent(effect: EnrollEffect): void; done(effect: EnrollEffect): void; port(tunnelPort: number): void; /** Record the outcome of the live response and add operationId and outcome to it. */ finish(response: Response): Promise<Response>; } export const NO_ENROLL_JOURNAL: EnrollJournal = { intent() {}, done() {}, port() {}, finish: async response => response, }; /** Write the open entry with its reserved identities; any write failure throws before an effect runs. */ export function openEnrollJournal(ctx: ManagementContext, request: OperationRequest, alias: string, route: { explicitRoute?: ExplicitRoute; exclusive?: true }): EnrollJournal { const path = journalPathFor(ctx), reservedLinkId = newLinkId(), reservedKeyId = randomUUID(); updateJournalPinned(path, nowOf(ctx), journal => { assertRoomForNewOperation(journal, nowOf(ctx)); journal.operations.push({ operationId: request.id, kind: "enroll", alias, digest: request.digest, createdAt: iso(ctx), updatedAt: iso(ctx), state: "open", reserved: { linkId: reservedLinkId, apiKeyId: reservedKeyId, tunnelPort: null, ...route }, effects: [], }); }); const change = (edit: (op: LinkOperation) => void) => updateJournalPinned(path, nowOf(ctx), journal => { const op = findOperation(journal, request.id)!; edit(op); op.updatedAt = iso(ctx); }); return { reservedLinkId, reservedKeyId, intent: effect => change(op => { op.effects.push({ effect, phase: "intent", at: iso(ctx) }); }), done: effect => change(op => { op.effects.push({ effect, phase: "done", at: iso(ctx) }); }), port: tunnelPort => change(op => { op.reserved!.tunnelPort = tunnelPort; }), async finish(response) { let body: Record<string, unknown> = {}; try { body = await response.clone().json() as Record<string, unknown>; } catch { /* a body that is not JSON keeps its status */ } const errorCode = typeof (body.error as { code?: unknown } | undefined)?.code === "string" ? (body.error as { code: string }).code : "apply_failed"; // A plant that did not report completion may have installed the binary anyway (a timeout, a lost connection, an // exit after the install). Only the script's own refusal before installing (hash_tool_unavailable) proves none. let plantUnsettled = false; try { const op = findOperation(readOperationsJournal(path), request.id); plantUnsettled = !!op && hasEffect(op, "plant", "intent") && !hasEffect(op, "plant", "done"); } catch { plantUnsettled = true; } const hint = (body.error as { hint?: unknown } | undefined)?.hint; const outcome: OperationState = response.status === 202 ? "committed" : UNKNOWN_CODES.has(errorCode) ? "unknown" : body.residual === true || (plantUnsettled && hint !== "hash_tool_unavailable") ? "residual" : "failed_clean"; let op: LinkOperation; // The Child's side is kept apart from the outcome: an unknown key and a plant whose rollback failed are both true. const childResidual = outcome !== "committed" && (body.residual === true || plantUnsettled && hint !== "hash_tool_unavailable"); try { op = settle(ctx, request.id, outcome, { code: /^[a-z][a-z0-9_]{0,63}$/.test(errorCode) ? errorCode : "apply_failed", status: response.status }, childResidual); } catch { // The live outcome stands; the open entry is recovered by the next repeat. return response; } const kind = residualKind(op); const planted = op.state === "committed" && hasEffect(op, "plant", "done"); // A residual this answer settles on (a plant that did not report, which returns before the live residual is built) gets // the same step a replay gives: bound to the reserved link id. A live line is kept only when it was built for this kind. const residualFields = (): Record<string, unknown> => { const linkId = residualLinkId(op); const platform = body.remotePlatform === "posix" || body.remotePlatform === "windows" ? body.remotePlatform : undefined; const install = body.residualInstall === "ephemeral" || body.residualInstall === "full" ? body.residualInstall : "enrollment"; const keep = body.residualKind === kind && typeof body.recovery === "string" && body.linkId === linkId; return { residual: true, residualKind: kind, ...(linkId ? { linkId } : {}), recovery: keep ? body.recovery : residualRecovery(kind === "plant" ? "plant" : install, linkId, platform) }; }; return Response.json({ ...body, ...outcomeBody(op), ...(kind ? residualFields() : {}), ...(planted ? { planted: true } : {}) }, { status: response.status, headers: response.headers }); }, }; } export function revokeOperationDigest(params: { linkId: string; purge: boolean; force: boolean }): string { return operationDigest({ kind: "revoke", linkId: params.linkId, purge: params.purge, force: params.force }); } export interface RevokeJournal { /** The journalled revoke this removal runs under; its retirement receipt names it. */ readonly operationId?: string; /** Strict: a failed write throws before its effect runs. */ intent(effect: RevokeEffect): void; /** * Best effort without a receipt: the effect has already happened and recovery reads an intent without its completion * as "may have happened". With a receipt (the Child's purged:true for this link id) it is strict and throws, because * the link must not be removed on evidence that a crash would lose. */ done(effect: RevokeEffect, receipt?: { purged: true; linkId: string }): void; /** Runs after the post-commit cleanup and before the retirement receipt is cleared; a throw keeps the receipt. */ beforeReceiptCleared?(): void; /** * A resumed retirement (#8416): an earlier cleanup attempt may already have reached the Child, so a failed cleanup never * restarts the tunnel, even one that provably did not run this time; the owner settles unknown and stays suspended. */ readonly keepsTunnelDown?: boolean; /** The Child's cleanup failed before it ran (removeReserved): the outcome can be failed_clean despite its intent. */ cleanupNotRun(): void; /** Drop this revoke's live registration; finish does too, this covers a revoke that threw before it. */ release(): void; finish(response: Response): Promise<Response>; } export const NO_REVOKE_JOURNAL: RevokeJournal = { intent() {}, done() {}, cleanupNotRun() {}, release() {}, finish: async response => response }; /** Write the open revoke entry; a write failure throws before the revoke changes anything. */ export function openRevokeJournal(ctx: ManagementContext, request: OperationRequest, alias: string, linkId: string): RevokeJournal { const path = journalPathFor(ctx); updateJournalPinned(path, nowOf(ctx), journal => { assertRoomForNewOperation(journal, nowOf(ctx)); journal.operations.push({ operationId: request.id, kind: "revoke", alias, linkId, digest: request.digest, createdAt: iso(ctx), updatedAt: iso(ctx), state: "open", effects: [] }); }); // Until finish, this entry is the running revoke's: the supervisor does not suspend its link for it (revokeSuspendsLink). markRevokeLive(path, request.id, true); let cleanupRan = true; const change = (edit: (op: LinkOperation) => void) => updateJournalPinned(path, nowOf(ctx), journal => { const op = findOperation(journal, request.id)!; edit(op); op.updatedAt = iso(ctx); }); return { operationId: request.id, intent: effect => { ctx.deps.linkOperationMarkHook?.(effect, "intent"); change(op => { op.effects.push({ effect, phase: "intent", at: iso(ctx) }); }); }, done: (effect, receipt) => { try { ctx.deps.linkOperationMarkHook?.(effect, "done"); change(op => { op.effects.push({ effect, phase: "done", at: iso(ctx) }); if (receipt) op.receipt = receipt; }); } catch (error) { if (receipt) throw error; console.warn("[link] revoke journal mark not written operation=" + request.id + " mark=" + effect + ":done"); } }, cleanupNotRun: () => { cleanupRan = false; }, release: () => { markRevokeLive(path, request.id, false); }, async finish(response) { try { return await settleRevoke(response); } finally { markRevokeLive(path, request.id, false); } }, }; async function settleRevoke(response: Response): Promise<Response> { let body: Record<string, unknown> = {}; try { body = await response.clone().json() as Record<string, unknown>; } catch { /* keeps its status */ } const errorCode = typeof (body.error as { code?: unknown } | undefined)?.code === "string" ? (body.error as { code: string }).code : "revoke_failed"; let current: LinkOperation | undefined; try { current = findOperation(readOperationsJournal(path), request.id); } catch { current = undefined; } // Clean only when nothing was touched: a cleanup on the Child, a key revoke or a record removal that started // (finished or not) may have changed something the failed response does not describe. const touched = !current || (cleanupRan && hasEffect(current, "remote_cleanup", "intent")) || hasEffect(current, "key_revoked", "intent") || hasEffect(current, "record_removed", "intent"); const outcome: OperationState = response.status === 200 ? "committed" : touched ? "unknown" : "failed_clean"; let op: LinkOperation; try { op = settle(ctx, request.id, outcome, { code: /^[a-z][a-z0-9_]{0,63}$/.test(errorCode) ? errorCode : "revoke_failed", status: response.status }); } catch { return response; } return Response.json({ ...body, ...outcomeBody(op), ...(op.state === "committed" && op.receipt ? { purged: true } : {}) }, { status: response.status, headers: response.headers }); } } /** GET /api/link/operations[/{id}] and POST /api/link/operations/{id}/resolve (structure/remote-link.md, "Operation journal"). */ export function handleLinkOperationRoutes(ctx: ManagementContext): Response | null { const { url, req } = ctx; const read = () => readOperationsJournal(journalPathFor(ctx)); const headers = { "cache-control": "no-store" }; if (url.pathname === "/api/link/operations" && req.method === "GET") { try { return Response.json({ operations: read().operations }, { headers }); } catch { return journalUnreadable(); } } const one = /^\/api\/link\/operations\/([^/]+)(\/resolve)?$/.exec(url.pathname); if (!one) return null; let id: string; try { id = decodeURIComponent(one[1]!); } catch { return fail("invalid_operation_id", "The operation id is invalid.", 400); } if (!isOperationId(id)) return fail("invalid_operation_id", "The operation id is invalid.", 400); if (!one[2] && req.method === "GET") { let op: LinkOperation | undefined; try { op = findOperation(read(), id); } catch { return journalUnreadable(); } return op ? Response.json(op, { headers }) : fail("operation_not_found", "No operation has this id.", 404); } if (one[2] && req.method === "POST") { let resolved: ReturnType<typeof resolveLinkOperation>; try { resolved = resolveLinkOperation(journalPathFor(ctx), id, nowOf(ctx), ownsRetirement); } catch { return fail("operation_journal_failed", "The link operation journal could not be written.", 500); } if (resolved === null) return fail("operation_not_found", "No operation has this id.", 404); if (resolved === "not_resolvable") return fail("operation_not_resolvable", "Only a residual or unknown operation can be resolved.", 409); // An unknown revoke past its Child cleanup suspended its link's tunnel (revokeSuspendsLink); resolving lifts that, // and an idle link is not retried on a tick, so the tunnels are reloaded. Best effort: the resolve is already stored. if (resolved.kind === "revoke") { void ctx.deps.linkSupervisor?.()?.reload().catch(() => console.warn("[link] operation resolved; tunnel reload failed")); } return Response.json(resolved, { headers }); } return null; }