UNPKG

@bitkyc08/opencodex

Version:

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

334 lines (310 loc) • 16.2 kB
/** * Caller side of the checked Windows service stop (#7771, 030 "Where it sits"). * * Every Windows stop path reaches Part A and Part B through this module: ocx stop with and * without a consent snapshot, ocx uninstall, /api/stop, ocx service stop / uninstall / * remove, prepareServiceInstall and the updater. It owns: * * - the stop deadline (030 "Time budget"): --deadline-ms or OCX_STOP_DEADLINE_MS for * ocx stop, measured from the command's start (performance.now() counts from * performance.timeOrigin, the process start, so the deadline is an absolute value on the * Part A clock); every other caller starts the default 60 s when its stop phase begins, * because registration and the UAC prompt can come first; * - the admission inputs and the mapping of Part A onto ServiceStopOutcome; * - the Part A record a teardown receipt carries, so /api/stop can skip a second Part A; * - a hook seam so caller tests run hermetically (no schtasks, PowerShell or FFI). */ import { loadConfig } from "../config"; import { endpointsToProve, type ProbeEndpoint } from "../cli/uninstall-plan"; import { probeEndpointLiveness, type EndpointLiveness } from "../server/proxy-liveness"; import type { PendingTeardownPartA } from "../config/pending-teardown"; import { readRuntimePort } from "../config/process-state"; import type { WinswStatus } from "../lib/winsw"; import type { ServiceStopOutcome } from "./orchestration"; import { guardedStopWindowsServiceChecked, snapshotWindowsCheckedStopResult, stopWindowsServiceChecked, WindowsCheckedStopRefusedError, windowsStopClock, type WindowsCheckedStopDeps, type WindowsCheckedStopOptions, type WindowsCheckedStopResult, type WindowsStopAdmission, type WindowsStopReason } from "./windows-checked-stop"; import { stopperUnderHomeWrapper, windowsCheckedStopLiveDeps, windowsStopConfirmLiveDeps, type WindowsCheckedStopLiveOptions } from "./windows-checked-stop-live"; import { windowsListenPort } from "./windows-ops"; import type { WindowsStopProcessEntry } from "./windows-process-evidence"; import { confirmWindowsStopFreed, resolveWindowsStopPort, type WindowsStopConfirmResult } from "./windows-stop-confirm"; import { windowsStopDeadlineAt } from "./windows-stop-deadline"; export { parseStopDeadlineMs, resolveStopDeadlineMs, setStopDeadlineMs, STOP_DEADLINE_ENV, windowsStopDeadlineAt } from "./windows-stop-deadline"; /** Time left on the stop deadline, measured on the Part A clock (one clock read). */ export function windowsStopRemainingMs(now: () => number = windowsStopClock.now): number { const at = now(); return windowsStopDeadlineAt(at) - at; } export function configuredShutdownTimeoutMs(): number | undefined { try { const value = loadConfig().shutdownTimeoutMs; return typeof value === "number" && value > 0 ? value : undefined; } catch { return undefined; } } export function windowsStopAdmission(input: { orphanDiscovery: boolean; inheritedReceipts?: number; partB?: boolean; }): WindowsStopAdmission { return { deadlineAt: windowsStopDeadlineAt(), budget: { orphanDiscovery: input.orphanDiscovery, inheritedReceipts: input.inheritedReceipts ?? 0, shutdownTimeoutMs: configuredShutdownTimeoutMs(), partB: input.partB ?? true, }, }; } export interface WindowsPartARequest { admission?: WindowsStopAdmission; /** The evidence snapshot (windowsProcessSnapshot) a guarded revalidation already read. */ bindSnapshot?: readonly WindowsStopProcessEntry[]; /** The updater's authorizer, called at entry and at each stop or terminate boundary. */ authorize?: () => void | Promise<void>; /** * A hard cap (the route: 6 s with a receipt, 4 s for a stray sweep). An overrun answers * unknown, and nothing further is changed: the manager commands and every terminate are * gated off once the cap has passed. */ capMs?: number; /** * The stopping process may descend from this home's wrapper. Only the /api/stop route * (it IS the wrapped proxy) and the updater (its worker descends from the service-run * proxy) pass true; every interactive caller refuses such a stop with nothing changed. */ allowUnderOwnWrapper?: boolean; } export interface WindowsPartBRequest { port: number; remainingMs: number; /** The final enumeration; the guarded path wraps it to share the table it read. */ snapshot?: (timeoutMs: number) => Promise<readonly WindowsStopProcessEntry[] | null>; } export interface WindowsServiceStopHooks { partA?: (request: WindowsPartARequest) => Promise<WindowsCheckedStopResult>; /** Run the real Part A against these deps instead of the live ones. */ liveDeps?: (options: WindowsCheckedStopLiveOptions) => WindowsCheckedStopDeps; partB?: (request: WindowsPartBRequest) => Promise<WindowsStopConfirmResult>; /** The evidence snapshot the guarded inspection and the bind share. */ snapshot?: () => Promise<readonly WindowsStopProcessEntry[] | null>; schedulePid?: () => Promise<number | null>; /** The route's registration re-check against a receipt's Part A record. */ registration?: () => Promise<{ scheduler: "present" | "absent" | "unknown"; winsw: WinswStatus }>; } let hooks: WindowsServiceStopHooks | null = null; /** Test-only: replace Part A / Part B / the evidence reads with hermetic fakes. */ export function setWindowsServiceStopHooksForTests(next: WindowsServiceStopHooks | null): void { hooks = next; } export function windowsServiceStopHooks(): WindowsServiceStopHooks | null { return hooks; } function unknownResult(detail: string): WindowsCheckedStopResult { return { outcome: "unknown", reason: "evidence-unreadable", detail, registration: { scheduler: "unknown", winsw: "unknown" }, bound: [], unbound: [], terminated: [], changed: false, }; } export const UNDER_OWN_WRAPPER_DETAIL = "this stop runs under this home's service wrapper; run it from a separate terminal"; /** Part A with the live dependencies (or the test hook), optionally capped. */ export async function runWindowsServiceStopPartA(request: WindowsPartARequest = {}): Promise<WindowsCheckedStopResult> { const deadline = request.capMs === undefined ? Infinity : performance.now() + request.capMs; const cancellation = new AbortController(); const remainingMs = () => Math.max(0, deadline - performance.now()); let expired = false; const withinCap = () => !expired && !cancellation.signal.aborted && remainingMs() > 0; let progress: WindowsCheckedStopResult | undefined; let underOwnWrapper = false; const options: WindowsCheckedStopOptions = { ...(request.admission ? { admission: request.admission } : {}), ...(request.bindSnapshot ? { bindSnapshot: request.bindSnapshot } : {}), onProgress: result => { progress = result; }, }; const run = async (): Promise<WindowsCheckedStopResult> => { if (hooks?.partA) return hooks.partA(request); const live: WindowsCheckedStopLiveOptions = { gate: withinCap, remainingMs, signal: cancellation.signal }; const base = (hooks?.liveDeps ?? windowsCheckedStopLiveDeps)(live); const selfPid = base.selfPid ?? process.pid; const guard = (table: readonly WindowsStopProcessEntry[] | null): boolean => !request.allowUnderOwnWrapper && table !== null && stopperUnderHomeWrapper(table, base.canonicalPaths, selfPid); // The guarded path binds on a snapshot it already read: check it before anything runs. if (request.bindSnapshot && guard(request.bindSnapshot)) return unknownResult(UNDER_OWN_WRAPPER_DETAIL); // Otherwise the bind enumeration is checked as it arrives; a hit reads as an unreadable // table, which Part A answers before /end when a manager is registered. const deps = { ...base, enumerate: async (timeoutMs: number) => { const table = await base.enumerate(timeoutMs); if (!guard(table)) return table; underOwnWrapper = true; return null; }, }; const authorize = async (): Promise<void> => { if (!withinCap()) throw new Error("the checked stop's cap has passed"); await request.authorize?.(); if (!withinCap()) throw new Error("the checked stop's cap has passed"); }; const result = await (request.authorize || request.capMs !== undefined ? guardedStopWindowsServiceChecked(authorize, deps, options) : stopWindowsServiceChecked(deps, options)); // The refusal is the answer whatever the stray path would have concluded: with nothing // registered an unreadable enumeration reads as absent ("nothing to end"), which would // let the caller stop the child and restore shared config beneath this home's own looping // wrapper. Nothing has been changed at this point in either path, so it is unknown. if (underOwnWrapper) { result.outcome = "unknown"; result.reason = "evidence-unreadable"; result.detail = UNDER_OWN_WRAPPER_DETAIL; result.changed = false; } return result; }; if (request.capMs === undefined) return run().finally(() => cancellation.abort()); const work = run().catch(error => { if (error instanceof WindowsCheckedStopRefusedError && (!request.authorize || !withinCap())) return error.partial; throw error; }); let timer: ReturnType<typeof setTimeout> | undefined; const cap = new Promise<null>(resolve => { timer = setTimeout(() => { expired = true; cancellation.abort(); resolve(null); }, Math.ceil(deadline - performance.now())); }); try { const result = await Promise.race([work, cap]); if (result !== null && withinCap()) return result; const refusal = unknownResult("the checked stop did not finish within its cap"); return { ...snapshotWindowsCheckedStopResult(result ?? progress ?? refusal), outcome: refusal.outcome, reason: refusal.reason, detail: refusal.detail }; } finally { if (timer) clearTimeout(timer); cancellation.abort(); } } /** Part A onto the existing ServiceStopOutcome (030 "Outcomes"). */ export function serviceStopOutcomeFromWindows(result: WindowsCheckedStopResult): ServiceStopOutcome { switch (result.outcome) { case "absent": return "absent"; case "stopped": return "stopped"; case "unknown": return "state-unknown"; default: return "failed"; } } /** The additive ocx-stop/1 serviceStopReason for a Part A result, if it has one. */ export function windowsStopReason(result: WindowsCheckedStopResult | null | undefined): WindowsStopReason | undefined { if (!result || result.outcome === "stopped" || result.outcome === "absent") return undefined; return result.reason ?? undefined; } /** One operator-facing line for a Part A result that was not stopped/absent. */ export function describeWindowsPartA(result: WindowsCheckedStopResult): string { switch (result.reason) { case "access-denied": return "The Windows service stop was denied for this account; run the stop from an elevated terminal."; case "unbound-wrapper": return "A service wrapper of this home is running but could not be tied to the service; end the wscript.exe/cmd.exe running the opencodex service script, then retry."; case "unverified-budget": return "The remaining time cannot hold a verified Windows service stop, so nothing was changed; retry from a terminal."; case "evidence-unreadable": return "The Windows service or process state could not be read (" + result.detail + "); nothing that could not be verified was stopped."; default: return "The Windows service manager or its wrapper is still running (" + result.detail + ")."; } } /** What a teardown receipt records after Part A (030 "/api/stop"). */ export function windowsPartARecord(result: WindowsCheckedStopResult): PendingTeardownPartA | null { if (result.outcome !== "stopped" && result.outcome !== "absent") return null; return { partA: result.outcome, manager: { scheduler: result.registration.scheduler === "present", winsw: result.registration.winsw !== "nonexistent" && result.registration.winsw !== "unknown", }, wrappers: result.bound.map(wrapper => ({ pid: wrapper.pid, startTime: wrapper.startTime })), }; } /** * Every endpoint this home could be serving on, exactly the set `ocx uninstall` proves. * * The receipt endpoint is ONE candidate; a stale runtime record naming a closed port must * not stand in for the configured port where a live listener can sit (#3008, #7771). */ export function windowsRemovalEndpoints(): ProbeEndpoint[] { let config: { port?: number; hostname?: string } = {}; try { config = loadConfig(); } catch { /* defaults below */ } return endpointsToProve(readRuntimePort(), config); } /** * Definitive absence on EVERY candidate. "unknown" is not absence: a listener that * accepts connections but withholds /healthz, or one that times out, is exactly the state * where deleting a registration or installing over it is most harmful. */ export async function endpointsAllDead( endpoints: readonly ProbeEndpoint[], probe: (endpoint: ProbeEndpoint) => Promise<EndpointLiveness> = probeEndpointLiveness, ): Promise<{ dead: boolean; live: number[]; unknown: number[] }> { const results = await Promise.all(endpoints.map(async endpoint => ( await probe(endpoint).catch((): EndpointLiveness => "unknown") ))); const live: number[] = []; const unknown: number[] = []; endpoints.forEach((endpoint, index) => { const answer = results[index]; if (answer === "live") live.push(endpoint.port); else if (answer !== "dead") unknown.push(endpoint.port); }); // No candidate is not proof of anything. return { dead: endpoints.length > 0 && live.length === 0 && unknown.length === 0, live, unknown }; } /** * The endpoint a teardown receipt should name: the runtime record when it has one, the * configured address otherwise. `exact` is the only source a stop may defer against. */ export function windowsReceiptEndpoint(): { endpoint: { hostname: string; port: number }; source: "exact" | "guessed" } { const runtime = readRuntimePort(); if (runtime?.port) return { endpoint: { hostname: runtime.hostname ?? "127.0.0.1", port: runtime.port }, source: "exact" }; try { const config = loadConfig(); return { endpoint: { hostname: config.hostname ?? "127.0.0.1", port: typeof config.port === "number" && config.port > 0 ? config.port : 10100 }, source: "guessed" }; } catch { return { endpoint: { hostname: "127.0.0.1", port: 10100 }, source: "guessed" }; } } /** The port Part B watches: runtime record, then the wrapper's baked port, then the config. */ export function windowsServiceStopPort(): number { return resolveWindowsStopPort({ runtimePort: () => readRuntimePort()?.port ?? null, wrapperPort: () => windowsListenPort(), configuredPort: () => { try { const port = loadConfig().port; return typeof port === "number" && port > 0 ? port : 10100; } catch { return 10100; } }, }).port; } /** Part B with the live dependencies (or the test hook). */ export async function confirmWindowsServiceStop(request: WindowsPartBRequest): Promise<WindowsStopConfirmResult> { if (hooks?.partB) return hooks.partB(request); return confirmWindowsStopFreed(windowsStopConfirmLiveDeps(request.port, request.remainingMs, request.snapshot ? { snapshot: request.snapshot } : {})); } /** One operator-facing line for a Part B result other than freed. */ export function describeWindowsPartB(result: WindowsStopConfirmResult): string { if (result.outcome === "port-held-by-foreign") { const owner = result.listener?.ownerPid ? " (PID " + result.listener.ownerPid + ")" : ""; return "Another program" + owner + " holds port " + result.port + " after the stop."; } if (result.outcome === "survived") { return result.lateWrappers.length > 0 ? "A service wrapper of this home started again after the stop; it can relaunch the proxy." : "The proxy answers on port " + result.port + " again after the stop; it is being respawned."; } return "Port " + result.port + " could not be confirmed free after the stop (" + result.detail + ")."; }