@iislee/opencodex 2.11.0 → 2.31.0

package/src/lib/pinned-http.ts

@@ -1,35 +1,63 @@
-import http, { type IncomingMessage, type RequestOptions } from "node:http";
+import http, { type ClientRequest, type IncomingMessage, type RequestOptions } from "node:http";
 import https from "node:https";
 
 export type PinnedAddress = { address: string; family: number };
 
-export interface PinnedHttpGetOptions {
+export type PinnedHttpErrorCode =
+  | "connect_timeout"
+  | "first_byte_timeout"
+  | "inactivity_timeout"
+  | "output_byte_limit";
+
+export class PinnedHttpError extends Error {
+  override readonly name = "PinnedHttpError";
+  constructor(readonly code: PinnedHttpErrorCode, message: string) { super(message); }
+}
+
+export interface PinnedHttpRequestOptions {
   headers?: HeadersInit;
   maxBytes?: number;
+  /** Optional deadline for establishing the TCP connection and, for HTTPS, completing TLS. */
+  connectTimeoutMs?: number;
+  /** Optional deadline from connection establishment until response headers arrive. */
+  firstByteTimeoutMs?: number;
+  /** Optional maximum idle interval between response-body chunks. */
+  inactivityTimeoutMs?: number;
+  /** @deprecated Use firstByteTimeoutMs and inactivityTimeoutMs. */
   idleTimeoutMs?: number;
   rejectUnauthorized?: boolean;
   context?: string;
 }
 
-/**
- * GET a URL through one previously validated address. The original hostname
- * remains authoritative for Host, SNI, and certificate verification.
- */
-export function pinnedHttpGet(
+/** @deprecated Use {@link PinnedHttpRequestOptions}. */
+export type PinnedHttpGetOptions = PinnedHttpRequestOptions;
+
+function pinnedHttpRequest(
   url: string,
   pinned: PinnedAddress,
+  method: "GET" | "POST",
+  body: string | undefined,
   signal?: AbortSignal,
-  options?: PinnedHttpGetOptions,
+  options?: PinnedHttpRequestOptions,
 ): Promise<Response> {
   const parsed = new URL(url);
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`${options?.context ?? "request"} must use HTTP or HTTPS, got ${parsed.protocol}`);
   }
   const context = options?.context ?? "request";
-  const idleTimeoutMs = options?.idleTimeoutMs ?? 60_000;
+  const connectTimeoutMs = options?.connectTimeoutMs;
+  const legacyIdleTimeoutMs = options?.idleTimeoutMs ?? 60_000;
+  const usesLegacyIdleTimeout = options?.firstByteTimeoutMs === undefined
+    && options?.inactivityTimeoutMs === undefined;
+  const firstByteTimeoutMs = options?.firstByteTimeoutMs ?? legacyIdleTimeoutMs;
+  const inactivityTimeoutMs = options?.inactivityTimeoutMs ?? legacyIdleTimeoutMs;
+  const legacyFirstByteDisabled = usesLegacyIdleTimeout && legacyIdleTimeoutMs === 0;
   const maxBytes = options?.maxBytes;
   const headers = new Headers(options?.headers);
   headers.set("host", parsed.host);
+  if (body !== undefined && !headers.has("content-length")) {
+    headers.set("content-length", String(Buffer.byteLength(body)));
+  }
   const requestHeaders: Record<string, string> = {};
   headers.forEach((value, key) => { requestHeaders[key] = value; });
 
@@ -40,18 +68,39 @@ export function pinnedHttpGet(
     }
 
     let settled = false;
+    let req: ClientRequest | undefined;
+    let connectTimer: ReturnType<typeof setTimeout> | undefined;
+    let firstByteTimer: ReturnType<typeof setTimeout> | undefined;
+    const clearConnectTimer = () => {
+      if (connectTimer !== undefined) clearTimeout(connectTimer);
+      connectTimer = undefined;
+    };
+    const clearFirstByteTimer = () => {
+      if (firstByteTimer !== undefined) clearTimeout(firstByteTimer);
+      firstByteTimer = undefined;
+    };
     const fail = (error: unknown) => {
-      try { req.destroy(); } catch { /* ignore */ }
+      clearConnectTimer();
+      clearFirstByteTimer();
+      try { req?.destroy(); } catch { /* ignore */ }
       if (settled) return;
       settled = true;
       reject(error instanceof Error ? error : new Error(String(error)));
     };
+    const startFirstByteTimer = () => {
+      clearFirstByteTimer();
+      if (settled || legacyFirstByteDisabled) return;
+      firstByteTimer = setTimeout(
+        () => fail(new PinnedHttpError("first_byte_timeout", `${context} first byte timed out`)),
+        firstByteTimeoutMs,
+      );
+    };
     const requestOptions: RequestOptions & { servername?: string } = {
       protocol: parsed.protocol,
       hostname: parsed.hostname,
       port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
       path: `${parsed.pathname}${parsed.search}`,
-      method: "GET",
+      method,
       headers: requestHeaders,
       ...(parsed.protocol === "https:"
         ? {
@@ -79,6 +128,8 @@ export function pinnedHttpGet(
     };
 
     const onResponse = (response: IncomingMessage) => {
+      clearConnectTimer();
+      clearFirstByteTimer();
       const status = response.statusCode ?? 0;
       const responseHeaders = new Headers();
       for (const [key, value] of Object.entries(response.headers)) {
@@ -92,7 +143,7 @@ export function pinnedHttpGet(
 
       if (status < 200 || status >= 300) {
         try { response.destroy(); } catch { /* ignore */ }
-        try { req.destroy(); } catch { /* ignore */ }
+        try { req?.destroy(); } catch { /* ignore */ }
         if (settled) return;
         settled = true;
         resolve(new Response(null, { status, headers: responseHeaders }));
@@ -102,32 +153,39 @@ export function pinnedHttpGet(
       let received = 0;
       const stream = new ReadableStream<Uint8Array>({
         start(controller) {
-          response.setTimeout(idleTimeoutMs, () => {
-            const error = new Error(`${context} stalled`);
-            fail(error);
+          let bodySettled = false;
+          const failBody = (error: Error) => {
+            if (bodySettled) return;
+            bodySettled = true;
             try { controller.error(error); } catch { /* closed */ }
+            try { response.destroy(); } catch { /* ignore */ }
+            try { req?.destroy(); } catch { /* ignore */ }
+          };
+
+          response.setTimeout(inactivityTimeoutMs, () => {
+            failBody(new PinnedHttpError("inactivity_timeout", `${context} stalled`));
           });
           response.on("data", (chunk: Buffer | string) => {
+            if (bodySettled) return;
             const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
             received += buffer.byteLength;
             if (maxBytes !== undefined && received > maxBytes) {
-              const error = new Error(`${context} exceeds ${maxBytes} byte cap`);
-              fail(error);
-              try { controller.error(error); } catch { /* closed */ }
+              failBody(new PinnedHttpError("output_byte_limit", `${context} exceeds ${maxBytes} byte cap`));
               return;
             }
             try { controller.enqueue(buffer); } catch { /* closed */ }
           });
           response.on("end", () => {
+            if (bodySettled) return;
+            bodySettled = true;
             try { controller.close(); } catch { /* closed */ }
           });
           response.on("error", (error: Error) => {
-            fail(error);
-            try { controller.error(error); } catch { /* closed */ }
+            failBody(error);
           });
         },
         cancel() {
-          req.destroy();
+          req?.destroy();
         },
       });
 
@@ -137,15 +195,76 @@ export function pinnedHttpGet(
     };
 
     const requestFn = parsed.protocol === "https:" ? https.request : http.request;
-    const req = requestFn(requestOptions, onResponse);
+    req = requestFn(requestOptions, onResponse);
+    if (usesLegacyIdleTimeout) startFirstByteTimer();
     const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
-    signal?.addEventListener("abort", onAbort, { once: true });
-    req.setTimeout(idleTimeoutMs, () => fail(new Error(`${context} timed out`)));
+    req.on("socket", (socket) => {
+      const connectedEvent = parsed.protocol === "https:" ? "secureConnect" : "connect";
+      if (!socket.connecting) {
+        if (!usesLegacyIdleTimeout) startFirstByteTimer();
+        return;
+      }
+      if (connectTimeoutMs !== undefined) {
+        connectTimer = setTimeout(
+          () => fail(new PinnedHttpError("connect_timeout", `${context} connect timed out`)),
+          connectTimeoutMs,
+        );
+      }
+      socket.once(connectedEvent, () => {
+        clearConnectTimer();
+        if (!usesLegacyIdleTimeout) startFirstByteTimer();
+      });
+      socket.once("error", () => {
+        clearConnectTimer();
+        clearFirstByteTimer();
+      });
+      socket.once("close", () => {
+        clearConnectTimer();
+        clearFirstByteTimer();
+      });
+    });
+    if (usesLegacyIdleTimeout) {
+      req.setTimeout(legacyIdleTimeoutMs, () => fail(new Error(`${context} timed out`)));
+    }
     req.on("error", error => {
       signal?.removeEventListener("abort", onAbort);
       fail(error);
     });
-    req.on("close", () => signal?.removeEventListener("abort", onAbort));
-    req.end();
+    req.on("close", () => {
+      clearConnectTimer();
+      clearFirstByteTimer();
+      signal?.removeEventListener("abort", onAbort);
+    });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted && !settled) onAbort();
+    if (settled) return;
+    req.end(body);
   });
 }
+
+/**
+ * GET a URL through one previously validated address. The original hostname
+ * remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpGet(
+  url: string,
+  pinned: PinnedAddress,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  return pinnedHttpRequest(url, pinned, "GET", undefined, signal, options);
+}
+
+/**
+ * POST a string body through one previously validated address. The original
+ * hostname remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpPost(
+  url: string,
+  pinned: PinnedAddress,
+  body: string,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  return pinnedHttpRequest(url, pinned, "POST", body, signal, options);
+}

package/src/lib/process-control.ts

@@ -52,6 +52,9 @@ export function gracefulStopHost(hostname: string | undefined): string {
  */
 export type GracefulStopResult = boolean | "refused";
 
+/** A proxy declined shutdown because a service under another home owns it (HTTP 409). */
+export class ProxyOwnershipRefusedError extends Error {}
+
 /**
  * Ask a running proxy to stop itself via the management API (`POST /api/stop`), which
  * drains in-flight turns, restores native Codex, and cleans its pid/runtime files.
@@ -110,7 +113,7 @@ export async function stopProxy(pid: number): Promise<void> {
   if (graceful === "refused") {
     // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
     // config while that service keeps the proxy alive.
-    throw new Error(
+    throw new ProxyOwnershipRefusedError(
       "The running proxy refused to stop: a service installed under a different "
       + "CODEX_HOME/OPENCODEX_HOME owns it. Run the stop from that home.",
     );

package/src/lib/provider-outbound.ts

@@ -6,17 +6,19 @@ import {
   providerDestinationConfigError,
   resolvePublicAddresses,
 } from "./destination-policy";
-import { pinnedHttpGet } from "./pinned-http";
+import { pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
 import { outboundProxyConfigured } from "./proxy-env";
 import { publicProviderBaseUrl } from "./provider-url";
 
 type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
+type ProviderPostInit = ProviderGetInit & { body: string };
 type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
   fetch?: typeof globalThis.fetch;
 };
 export interface ProviderOutboundDependencies {
   resolveAddresses?: typeof resolvePublicAddresses;
   pinnedGet?: typeof pinnedHttpGet;
+  pinnedPost?: typeof pinnedHttpPost;
 }
 
 export class ProviderOutboundPolicyError extends Error {
@@ -102,13 +104,18 @@ export async function providerRedirectError(response: Response, requestUrl: stri
   return `provider returned ${response.status} redirect to ${target}; configure the final provider URL directly`;
 }
 
-export async function providerOutboundGet(
+async function providerOutboundRequest(
   name: string,
   provider: ProviderOutboundConfig,
   url: string,
-  init: ProviderGetInit = {},
+  method: "GET" | "POST",
+  init: ProviderGetInit | ProviderPostInit,
   dependencies: ProviderOutboundDependencies = {},
 ): Promise<Response> {
+  const postUrl = method === "POST" ? new URL(url) : undefined;
+  if (postUrl?.protocol !== undefined && postUrl.protocol !== "https:") {
+    throw new ProviderOutboundPolicyError("provider POST URL must use HTTPS");
+  }
   if (provider.fetch) {
     // A caller-owned executor cannot be peer-pinned here. This branch keeps literal/config
     // checks and redirect blocking, but does not provide the resolved-address guarantees of
@@ -128,18 +135,26 @@ export async function providerOutboundGet(
       });
       if (destinationError) throw new ProviderOutboundPolicyError(destinationError);
     }
-    return provider.fetch(url, { ...init, method: "GET", redirect: "manual" });
+    return provider.fetch(url, { ...init, method, redirect: "manual" });
   }
-  const parsed = new URL(url);
+  const parsed = postUrl ?? new URL(url);
   const proxyConfigured = configuredProxyFor();
   const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
   const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
+  const pinnedPost = dependencies.pinnedPost ?? pinnedHttpPost;
   const allowPrivate = providerAllowsPrivateNetwork(name, provider);
   let resolved: Awaited<ReturnType<typeof resolvePublicAddresses>>;
   try {
     resolved = await resolveAddresses(url, {
       context: "provider URL",
       allowPrivateNetwork: allowPrivate,
+      // Clash/Surge/Mihomo fake-IP DNS (198.18.0.0/15) answers are admitted only
+      // when this exact host will use the configured outbound proxy: the hostname
+      // then rides the proxy as an ordinary CONNECT instead of failing as a private
+      // destination or being pin-connected to the fake-IP (credit #1748). A NO_PROXY
+      // match is a direct route, so it keeps the benchmark answer rejected. Image/Lab
+      // fetch never passes this flag.
+      allowBenchmarkAddresses: proxyConfigured && !noProxyMatches(parsed),
     });
   } catch (error) {
     const dnsResolutionFailed = error instanceof DestinationDnsResolutionError
@@ -150,11 +165,11 @@ export async function providerOutboundGet(
     if (!proxyConfigured) throw error;
     warnProxyBoundaryOnce();
     warnProxyDnsDegradationOnce();
-    return globalThis.fetch(url, { ...init, method: "GET", redirect: "manual" });
+    return globalThis.fetch(url, { ...init, method, redirect: "manual" });
   }
   if (proxyConfigured && !resolved.privateNetwork) {
     warnProxyBoundaryOnce();
-    return globalThis.fetch(url, { ...init, method: "GET", redirect: "manual" });
+    return globalThis.fetch(url, { ...init, method, redirect: "manual" });
   }
   if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
     const hostname = normalizeProxyHostname(parsed.hostname);
@@ -162,9 +177,34 @@ export async function providerOutboundGet(
       `provider URL resolves to a private-network destination; add ${hostname} to NO_PROXY before using allowPrivateNetwork with an outbound proxy`,
     );
   }
-  return pinnedGet(url, pickPinnedAddress(resolved.addresses), init.signal ?? undefined, {
+  const requestOptions = {
     headers: init.headers,
     rejectUnauthorized: true,
     context: "provider response",
-  });
+  };
+  const pinned = pickPinnedAddress(resolved.addresses);
+  if (method === "POST") {
+    return pinnedPost(url, pinned, (init as ProviderPostInit).body, init.signal ?? undefined, requestOptions);
+  }
+  return pinnedGet(url, pinned, init.signal ?? undefined, requestOptions);
+}
+
+export async function providerOutboundGet(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  init: ProviderGetInit = {},
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  return providerOutboundRequest(name, provider, url, "GET", init, dependencies);
+}
+
+export async function providerOutboundPost(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  init: ProviderPostInit,
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  return providerOutboundRequest(name, provider, url, "POST", init, dependencies);
 }