@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
191 lines (174 loc) • 7.52 kB
text/typescript
import { createServer } from "node:net";
/** An auxiliary bind cannot be repaired by selecting a different public port. */
export class AuxiliaryListenerBindError extends Error {
constructor(
readonly listener: "unauthenticatedLoopbackListener" | "hub.managementIngress",
readonly port: number,
readonly hostname: string,
cause: unknown,
) {
super(
`Could not bind ${listener} at ${hostname}:${port}. `
+ `Check that listener's address and port; the public proxy port was not retried.`,
{ cause },
);
this.name = "AuxiliaryListenerBindError";
}
}
/** Temporary bind probes must not let accepted peers hold server.close() open. */
function createProbeServer(): ReturnType<typeof createServer> {
const server = createServer();
server.on("connection", socket => {
socket.on("error", () => socket.destroy());
socket.destroy();
});
return server;
}
/**
* True when an error means "this port/address is already bound" — the only bind failure
* that is safe to answer with a retry on another port. Bun/Node surface it as
* `code: "EADDRINUSE"` or an EADDRINUSE / "address in use" message depending on the API.
*/
export function isAddrInUse(err: unknown): boolean {
if (!err || typeof err !== "object") return false;
const { code, message } = err as { code?: unknown; message?: unknown };
if (code === "EADDRINUSE") return true;
const text = typeof message === "string" ? message.toLowerCase() : "";
return text.includes("eaddrinuse") || text.includes("in use");
}
export async function isPortAvailable(port: number, hostname = "127.0.0.1"): Promise<boolean> {
return await new Promise(resolve => {
const server = createProbeServer();
// Fail closed: EACCES / EADDRNOTAVAIL / EPERM / unknown listen errors mean the
// requested bind is not available. Only the listening event reports free.
server.once("error", () => resolve(false));
server.once("listening", () => {
server.close(() => resolve(true));
});
server.listen({ port, host: hostname });
});
}
export type WaitForPortOptions = {
timeoutMs?: number;
intervalMs?: number;
};
/** Poll until `port` accepts a bind, or until the timeout elapses. */
export async function waitForPortAvailable(
port: number,
hostname = "127.0.0.1",
opts: WaitForPortOptions = {},
): Promise<boolean> {
const timeoutMs = opts.timeoutMs ?? 5000;
const intervalMs = opts.intervalMs ?? 50;
const deadline = Date.now() + timeoutMs;
for (;;) {
if (await isPortAvailable(port, hostname)) return true;
if (Date.now() >= deadline) return false;
await new Promise(resolve => setTimeout(resolve, intervalMs));
}
}
export type FindAvailablePortOptions = {
/** How long to keep retrying the preferred port before falling back to an ephemeral port. */
preferRetryMs?: number;
preferRetryIntervalMs?: number;
/**
* When false, never bind `port: 0` — prefer-retry then throw if the preferred port
* stays busy. Used for explicit `ocx start --port N` and service-baked pins so an
* update restart cannot hop to a random ephemeral listener (PR #152 gap).
*/
allowEphemeralFallback?: boolean;
/**
* A port this selection must never return, even when it is free (#1102).
*
* The unauthenticated loopback listener binds a fixed port from config. If the public
* listener took that port first — via an explicit `--port`, a `config.port` of 0, or the
* ephemeral fallback happening to land on it — the loopback bind would then fail with
* EADDRINUSE, and the startup transaction would roll back a public listener that had
* nothing wrong with it. Excluding the port here fails the right thing at the right time.
*/
reservedPort?: number;
};
export class PortUnavailableError extends Error {
readonly port: number;
constructor(port: number, hostname: string) {
super(`Port ${port} on ${hostname} is still busy after prefer-retry; refusing ephemeral fallback.`);
this.name = "PortUnavailableError";
this.port = port;
}
}
export async function findAvailablePort(
preferredPort: number,
hostname = "127.0.0.1",
opts: FindAvailablePortOptions = {},
): Promise<number> {
const preferRetryMs = opts.preferRetryMs ?? 0;
const allowEphemeral = opts.allowEphemeralFallback !== false;
const reserved = opts.reservedPort;
// An explicit preference for the reserved port is a configuration mistake, not a busy
// socket: retrying or hopping would hide it. Refuse before probing anything.
if (reserved !== undefined && preferredPort === reserved) {
throw new PortUnavailableError(preferredPort, hostname);
}
// Port 0 asks the OS to select an ephemeral port. Resolve it to that concrete
// port here so callers never persist or advertise an unusable `:0` endpoint.
if (preferredPort > 0 && preferRetryMs > 0) {
if (await waitForPortAvailable(preferredPort, hostname, {
timeoutMs: preferRetryMs,
intervalMs: opts.preferRetryIntervalMs ?? 50,
})) {
return preferredPort;
}
} else if (preferredPort > 0 && (await isPortAvailable(preferredPort, hostname))) {
return preferredPort;
}
if (!allowEphemeral) {
throw new PortUnavailableError(preferredPort, hostname);
}
// Bounded, not recursive. The OS can hand back the reserved port, and a redraw practically
// always differs — but "practically always" is not a termination argument, and an unbounded
// async recursion has no way to stop if the assumption is ever wrong.
for (let attempt = 0; attempt < EPHEMERAL_REDRAW_LIMIT; attempt += 1) {
const port = await allocateEphemeralPort(hostname);
if (port !== reserved) return port;
}
throw new Error("failed to allocate an available port");
}
/** How many times an ephemeral draw may come back reserved before we give up. */
const EPHEMERAL_REDRAW_LIMIT = 8;
/** Test seam: replace the OS ephemeral allocator so the redraw path is reachable. */
let ephemeralAllocator: ((hostname: string) => Promise<number>) | null = null;
export function setEphemeralPortAllocatorForTests(
allocator: ((hostname: string) => Promise<number>) | null,
): void {
ephemeralAllocator = allocator;
}
async function allocateEphemeralPort(hostname: string): Promise<number> {
if (ephemeralAllocator) return ephemeralAllocator(hostname);
return await new Promise<number>((resolve, reject) => {
const server = createProbeServer();
server.once("error", reject);
server.once("listening", () => {
const address = server.address();
const port = typeof address === "object" && address ? address.port : 0;
server.close(() => {
if (port > 0) resolve(port);
else reject(new Error("failed to allocate an available port"));
});
});
server.listen({ port: 0, host: hostname });
});
}
export function shouldPersistSelectedPort(
configPort: number | undefined,
selectedPort: number,
preferredPort: number,
options: { sibling?: boolean } = {},
): boolean {
// A sibling start (`--port X` beside a live proxy on the configured port) is a
// second instance, not a new home for this config. Persisting its port rewrote
// config.port under the still-running configured-port proxy, and the next
// `ocx service` install then baked the sibling's port into the service and
// re-pointed every client at a listener that no longer existed.
if (options.sibling) return false;
return selectedPort === preferredPort && configPort !== selectedPort;
}