import { carryPollError, tagPollProbeGuard, type PollProbeGuard } from "./server-poll-error-provenance.js" /** Bounded PG lease for opt-in probe storage. Construction/import performs no * checkout, schema change, execution, or registration. */ import type { QueryConfig } from "pg" import { principalSourceSql, principalSourceStatementName } from "../modules/mcp/principal-security-sql.js" import { ProbeStorageRefused, ProbeStorageUnknown, type ProbeStorageConnection, type ProbeStorageOptions } from "./server-probe-journal-maintenance.js" export interface ProbeStoragePgClient { query(config: QueryConfig & { query_timeout: number }): Promise<{ rows: Record[]; command: string }> release(unsafe?: boolean): void on?(event: "error", listener: (error: Error) => void): unknown removeListener?(event: "error", listener: (error: Error) => void): unknown } /** Trusted server source/test seam only; never accepted from request JSON. */ export type ProbeStorageCheckout = () => Promise const productionCheckout: ProbeStorageCheckout = async () => (await import("../db/index.js")).pool.connect() const MAX_TIMER = 2147483647 const alive = (deadlineAt: number, signals: readonly AbortSignal[]) => Date.now() < deadlineAt && signals.every(signal => !signal.aborted) const commits = (text: string) => /^(?:COMMIT|END)(?:\s+(?:WORK|TRANSACTION))?\s*;?$/i.test(text.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\r\n]*/g, " ").trim()) const queryKind = (text: unknown): PollProbeGuard["queryKind"] => text === "SELECT pg_advisory_xact_lock(hashtextextended('server-poll-storage-v1',0))" ? "storage-lock" : text === principalSourceSql ? "principal" : text === "SELECT o.id FROM mcp_operations o JOIN mcp_plans p ON p.id=o.plan_id JOIN mcp_operation_steps s ON s.operation_id=o.id WHERE o.connection_id=$1 AND p.operation_id=$2 AND s.step_index=0 AND s.intended_state=$3::jsonb LIMIT 2" ? "meta" : typeof text === "string" && commits(text) ? "commit" : "other" /** A real wall timer bounds drivers/pool waits even when their timeout or signal * support is absent. Late values/failures are always consumed. */ function bounded(work: () => Promise, deadlineAt: number, signals: readonly AbortSignal[], failure: (branch: "deadline" | "abort" | "driver-throw" | "driver-reject", original?: unknown) => Error, stop: () => void, late: (value: T) => void = () => {}): Promise { return new Promise((resolve, reject) => { let settled = false, timer: ReturnType | undefined const cleanup = () => { if (timer) clearTimeout(timer); for (const signal of signals) signal.removeEventListener("abort", onAbort) } const abort = (branch: "deadline" | "abort" | "driver-throw" | "driver-reject" = signals.some(signal => signal.aborted) ? "abort" : "deadline", original?: unknown) => { if (settled) return; settled = true; cleanup(); stop(); reject(failure(branch, original)) } const onAbort = () => abort("abort") const schedule = () => { if (!alive(deadlineAt, signals)) { abort(); return }; timer = setTimeout(schedule, Math.max(1, Math.min(MAX_TIMER, deadlineAt - Date.now()))) } for (const signal of signals) signal.addEventListener("abort", onAbort, { once: true }) if (!alive(deadlineAt, signals)) { abort(); return } schedule() let pending: Promise try { pending = work() } catch (error) { abort("driver-throw", error); return } Promise.resolve(pending).then(value => { if (settled) { late(value); return } if (!alive(deadlineAt, signals)) { abort(); late(value); return } settled = true; cleanup(); resolve(value) }, error => abort("driver-reject", error)) }) } export function createProbeStorageConnectionConnector(checkout: ProbeStorageCheckout = productionCheckout): (options: ProbeStorageOptions) => Promise { return async rawOptions => { const deadlineAt = rawOptions.deadlineAt, initialSignal = rawOptions.signal const signals = initialSignal ? [initialSignal] : [] if (!Number.isSafeInteger(deadlineAt) || !alive(deadlineAt, signals)) throw tagPollProbeGuard(new ProbeStorageRefused(), undefined, { phase: "checkout", queryKind: "other", branch: Number.isSafeInteger(deadlineAt) ? "inactive" : "input" }) const lifetime = new AbortController() const disposeLate = (client: ProbeStoragePgClient) => { lifetime.abort() // No facade was published. Absorb a delayed physical socket error even // when this abandoned checkout is destroyed after caller cancellation. try { client.on?.("error", () => {}) } catch { /* Still attempt destroy. */ } try { client.release(true) } catch { /* Never re-enter the pool healthy. */ } } const client = await bounded(checkout, deadlineAt, signals, (branch, original) => tagPollProbeGuard(new ProbeStorageRefused(), original, { phase: "checkout", queryKind: "other", branch }), () => lifetime.abort(), disposeLate) let closed = false, busy = false, interrupt: (() => void) | undefined, leaseTimer: ReturnType | undefined let leaseEnd: PollProbeGuard["branch"] = "lease-closed" const onError = () => { if (!closed) leaseEnd = "lease-error"; close(true) } const onInitialAbort = () => { if (!closed) leaseEnd = "lease-abort"; close(true) } const close = (unsafe: boolean) => { if (closed) return closed = true // Synchronous revocation precedes physical release and any external // asynchronous authority/Q continuation that still retains this facade. lifetime.abort() if (leaseTimer) clearTimeout(leaseTimer) initialSignal?.removeEventListener("abort", onInitialAbort) // Destroyed clients retain the error absorber for late socket errors. if (!unsafe) client.removeListener?.("error", onError) try { client.release(unsafe) } catch { /* Release is attempted exactly once, without private driver errors. */ } interrupt?.() } const scheduleLease = () => { if (closed) return if (!alive(deadlineAt, signals)) { leaseEnd = initialSignal?.aborted ? "lease-abort" : "lease-timeout"; close(true); return } leaseTimer = setTimeout(scheduleLease, Math.max(1, Math.min(MAX_TIMER, deadlineAt - Date.now()))) } client.on?.("error", onError) initialSignal?.addEventListener("abort", onInitialAbort, { once: true }) scheduleLease() if (closed) throw tagPollProbeGuard(new ProbeStorageRefused(), undefined, { phase: "checkout", queryKind: "other", branch: "closed" }) const facade: ProbeStorageConnection = { async query(text, values, options) { const refused = (branch: PollProbeGuard["branch"]) => tagPollProbeGuard(new ProbeStorageRefused(), undefined, { phase: "query", queryKind: queryKind(text), branch }) if (closed) throw refused("closed") if (busy) { close(true); throw refused("busy") } const requested = options?.timeoutMs ?? 10000, querySignal = options?.signal if (typeof text !== "string" || !text.trim() || !Number.isSafeInteger(requested) || requested < 1 || requested > 10000) throw refused("input") const allSignals = [...new Set([...signals, ...(querySignal ? [querySignal] : [])])] if (!alive(deadlineAt, allSignals)) { close(true); throw refused("inactive") } const queryDeadline = Math.min(deadlineAt, Date.now() + requested) busy = true const interrupted = new AbortController() interrupt = () => interrupted.abort() let inspectingResult = false, taggedResult = false try { // Prepare only this immutable statement, once per physical backend. // Every execution binds fresh values. Any schema/driver failure below // destroys the lease; there is no reparse, fallback or query replay. const result = await bounded(() => client.query({ text, values, ...(text === principalSourceSql ? { name: principalSourceStatementName } : {}), query_timeout: Math.max(1, Math.min(requested, queryDeadline - Date.now())) }), queryDeadline, [...allSignals, interrupted.signal], (branch, original) => tagPollProbeGuard(new ProbeStorageUnknown(), original, { phase: "query", queryKind: queryKind(text), branch: branch === "abort" && interrupted.signal.aborted && !allSignals.some(signal => signal.aborted) ? leaseEnd : branch }), () => close(true)) inspectingResult = true let rejected: PollProbeGuard["branch"] | undefined if (closed) rejected = "result-closed" else if (!alive(queryDeadline, allSignals)) rejected = "result-inactive" else if (!Array.isArray(result.rows)) rejected = "result-shape" else if (commits(text) && result.command !== "COMMIT") rejected = "commit-ack" if (rejected) { close(true); taggedResult = true; throw tagPollProbeGuard(new ProbeStorageUnknown(), undefined, { phase: "query", queryKind: queryKind(text), branch: rejected }) } return result } catch (error) { close(true) // A null/throwing result accessor is a result guard failure, not driver rejection. const source = inspectingResult && !taggedResult ? tagPollProbeGuard(new ProbeStorageUnknown(), error, { phase: "query", queryKind: queryKind(text), branch: "result-access" }) : error throw carryPollError(new ProbeStorageUnknown(), source, "probe.query") } finally { interrupt = undefined; busy = false } }, release(unsafe = false) { close(unsafe || busy || !alive(deadlineAt, signals)) }, } Object.defineProperty(facade, "lifetimeSignal", { value: lifetime.signal, enumerable: true, writable: false, configurable: false }) return facade } } /** Inert default connector. Fresh quarantine options create an independent lease. */ export const connectProbeStorage = createProbeStorageConnectionConnector()