@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
text/typescript
/**
* 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 + ").";
}