@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
255 lines (247 loc) • 11.3 kB
text/typescript
import { currentUpstreamHistorySlim } from "../responses/history-slim";
import { codexWsIncrementalStats } from "../responses/codex-ws-incremental";
import { responseSpillCodecInfo } from "../../responses/state/spill-codec";
/**
* /api/system/* — service-process runtime/memory introspection (#314 WP3)
* and the memory-card drain-and-restart action (#563).
*
* Rides the standard management gate: every /api/* request already passed
* the independent management-auth gate + the origin check before dispatch, so these
* routes add no auth of their own. NEVER expose this data on the
* unauthenticated /healthz surface.
*
* The payload is scalar-only (numbers, enum strings, booleans): no paths, no
* tokens, no account identifiers. `external` and `arrayBuffers` keep Windows
* diagnostics honest when RSS/working-set counters under-report committed
* retention. `jscHeap` (bun:jsc heapStats) is useful context, but on Bun 1.3.14
* it is not a standalone leak discriminator. `responseState` attributes growth
* further: it is the proxy's previous_response_id continuation store, so a
* growing responseState.totalBytes under rising observed memory points at
* conversation retention rather than the runtime allocator. Spill counts,
* payload-byte totals, tombstones, failure counters, fixed health/error enums,
* and event timestamps remain finite scalars; response ids, raw errors,
* filenames, digests, paths, and payload content never leave the owner.
*
* `activeTurnCount` / `isDraining` are scalar lifecycle counters for the
* dashboard drain-and-restart confirm UX — never request bodies or IDs.
*/
import { selectEagerPath } from "../../lib/bun-stream-caps";
import { reportedBunRuntimeSource } from "../../lib/bun-runtime";
import { getActiveTurnCount, isDraining } from "../lifecycle";
import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
import { inspectResponseSpillStorage, responseStateMetrics, type ResponseSpillDirInspection } from "../../responses/state";
import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
import { readWindowsReplaceRetryCounters } from "../../lib/windows-atomic-replace";
import {
MEMORY_DRAIN_RESTART_MS,
SYSTEM_RESTART_EXPECTED_PID_HEADER,
parseExpectedSystemRestartPid,
} from "../../lib/system-restart-contract";
import {
CODEX_APP_SERVER_STATE_PATH,
CODEX_RESTART_PATH,
} from "../../lib/codex-restart-contract";
import { jsonResponse } from "../auth-cors";
import { getInspectionCounters } from "../relay";
import { spendLedgerDiagnosticsSnapshot } from "../../lib/spend-reservation-ledger";
import type {
performCodexRestart,
readCodexAppServerState,
} from "../../codex/app-server-restart-service";
import type { ManagementContext } from "./context";
import { acceptSystemRestart } from "./system-restart";
import { readOptionalManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
const ENDPOINT_SAMPLE_LIMIT = 60;
// The spill report reads the snapshot and walks the spill directory synchronously,
// so a polled memory endpoint reuses one result per window instead of rescanning.
const RESPONSE_SPILL_REPORT_TTL_MS = 30_000;
let responseSpillReport: { at: number; value: ResponseSpillDirInspection } | null = null;
function cachedResponseSpillReport(): ResponseSpillDirInspection {
const now = Date.now();
if (!responseSpillReport || now - responseSpillReport.at >= RESPONSE_SPILL_REPORT_TTL_MS) {
responseSpillReport = { at: now, value: inspectResponseSpillStorage() };
}
return responseSpillReport.value;
}
export async function handleSystemRoutes(ctx: ManagementContext): Promise<Response | null> {
const { req, url, config, version } = ctx;
if (url.pathname === "/api/system/health" && req.method === "GET") {
// Authenticated management counterpart to /healthz. Remote Hub deliberately keeps the
// unauthenticated liveness route off its management ingress, while the connected dashboard
// still needs bounded process identity and PID replacement evidence (#3158).
return jsonResponse({
status: "ok",
service: "opencodex",
version,
uptime: process.uptime(),
pid: process.pid,
spendLedger: spendLedgerDiagnosticsSnapshot(),
});
}
if (url.pathname === "/api/system/memory" && req.method === "GET") {
const usage = process.memoryUsage();
let jscHeap: { heapSize: number; heapCapacity: number; objectCount: number } | null = null;
try {
const { heapStats } = await import("bun:jsc");
const stats = heapStats();
jscHeap = {
heapSize: stats.heapSize,
heapCapacity: stats.heapCapacity,
objectCount: stats.objectCount,
};
} catch {
/* non-Bun tooling or unavailable introspection — omit the discriminator */
}
const watchdogInstance = getActiveMemoryWatchdog();
const observed = observedMemoryCounter({
rss: usage.rss,
external: usage.external,
arrayBuffers: usage.arrayBuffers,
});
const watchdog = watchdogInstance
? (() => {
const snap = watchdogInstance.snapshot();
return {
warnThresholdBytes: snap.warnThresholdBytes,
lastWarnAt: snap.lastWarnAt,
observedBytes: snap.observedBytes,
observedMetric: snap.observedMetric,
samples: snap.samples.slice(-ENDPOINT_SAMPLE_LIMIT),
};
})()
: null;
const streamMode = config.streamMode ?? "auto";
/**
* No request-specific rewrite context exists on this route, so report the
* effective no-client-rewrite baseline. Individual rewrite requests still
* stay on tee even when this baseline says eager.
*/
const eagerRelay = selectEagerPath(process.platform, false, streamMode);
return jsonResponse({
pid: process.pid,
bunVersion: Bun.version,
bunRevision: Bun.revision,
// Recorded at launch, not resolved now: absent means "this service predates the
// marker", which callers must report as unknown rather than guess.
bunRuntimeSource: reportedBunRuntimeSource(),
platform: process.platform,
uptimeSeconds: process.uptime(),
rss: usage.rss,
heapUsed: usage.heapUsed,
heapTotal: usage.heapTotal,
external: usage.external,
arrayBuffers: usage.arrayBuffers,
observedBytes: observed.observedBytes,
observedMetric: observed.observedMetric,
jscHeap,
responseState: responseStateMetrics(),
// Dry-run spill-directory counters: owned vs orphan-candidate bytes, same
// predicate the startup reclaim uses. Sibling of responseState, not a field
// in it — that block's key count is pinned. Still scalar-only. Cached for
// RESPONSE_SPILL_REPORT_TTL_MS.
responseSpill: cachedResponseSpillReport(),
appOwnedBytes: appOwnedBytesSnapshot(),
inspectionCounters: getInspectionCounters(),
streamMode,
eagerRelay,
watchdog,
activeTurnCount: getActiveTurnCount(),
isDraining: isDraining(),
upstreamHistorySlim: currentUpstreamHistorySlim(),
codexWsIncremental: codexWsIncrementalStats(),
responseSpillCodec: responseSpillCodecInfo(),
});
}
/**
* Windows atomic-replace retry counters.
*
* A sibling route rather than a field on /api/system/memory: that payload is
* memory-shaped, and appending unrelated filesystem counters to it makes both
* harder to consume.
*
* Keys are `publisher:CODE` where publisher is a closed union
* (ReplacePublisher) and never a path — a path could carry a username. The
* type is what enforces that; a text scan cannot see a runtime value.
*/
if (url.pathname === "/api/system/windows-replace-retries" && req.method === "GET") {
return jsonResponse({ counters: readWindowsReplaceRetryCounters() });
}
if (url.pathname === "/api/system/restart" && req.method === "POST") {
const expectedPid = parseExpectedSystemRestartPid(
req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),
);
if (expectedPid.kind === "invalid") {
return jsonResponse({
success: false,
error: "Invalid restart target identity.",
}, 400, req, config);
}
if (expectedPid.kind === "present" && expectedPid.pid !== process.pid) {
return jsonResponse({
success: false,
error: "Restart target identity changed.",
}, 409, req, config);
}
let body: unknown;
try { body = await readOptionalManagementJsonBody(req); }
catch (error) {
rethrowManagementBodyTooLarge(error);
return jsonResponse({ success: false, error: "Invalid restart JSON body." }, 400, req, config);
}
if (!body || typeof body !== "object" || Array.isArray(body)) {
return jsonResponse({ success: false, error: "Invalid restart JSON body." }, 400, req, config);
}
const drainGraceMs = (body as Record<string, unknown>).drainGraceMs;
if (drainGraceMs !== undefined && (
typeof drainGraceMs !== "number" || !Number.isSafeInteger(drainGraceMs)
|| drainGraceMs < 1 || drainGraceMs > MEMORY_DRAIN_RESTART_MS
)) {
return jsonResponse({ success: false, error: "drainGraceMs must be an integer from 1 to 60000." }, 400, req, config);
}
// The process capability signs the restart target, not this new body option.
if (drainGraceMs !== undefined && ctx.principal === "system-restart-capability") {
return jsonResponse({ success: false, error: "Short grace requires management authentication." }, 403, req, config);
}
// Omission retains the informed 60s drain; only an explicit API request shortens it.
const result = acceptSystemRestart(undefined, {}, { drainGraceMs });
return jsonResponse({
success: true,
message: result.alreadyDraining
? "Drain already in progress."
: "Draining in-flight requests, then restarting.",
activeTurnCount: result.activeTurnCount,
drainTimeoutMs: result.drainTimeoutMs,
alreadyDraining: result.alreadyDraining,
}, 202, req, config);
}
if (
(url.pathname === CODEX_APP_SERVER_STATE_PATH && req.method === "GET")
|| (url.pathname === CODEX_RESTART_PATH && req.method === "POST")
) {
// Resolved inside the path check, not at the top of this function: every
// /api/system/* request runs through here, and an unconditional import would
// pull the platform process-enumeration helpers into requests that never
// touch them.
// An explicit branch rather than `??`: the seam is an optional property, and
// narrowing through a nullish default keeps its `undefined` in the union.
let service: {
readState: typeof readCodexAppServerState;
performRestart: typeof performCodexRestart;
};
const injected = ctx.deps.codexRestartService;
if (injected) {
service = injected;
} else {
const module = await import("../../codex/app-server-restart-service");
service = {
readState: module.readCodexAppServerState,
performRestart: module.performCodexRestart,
};
}
if (req.method === "GET") {
return jsonResponse(await service.readState(), 200, req, config);
}
return jsonResponse(await service.performRestart(), 200, req, config);
}
return null;
}