@iislee/opencodex 2.11.0 → 2.35.0

package/src/server/readiness.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-server readiness gate for the opencodex proxy.
+ *
+ * `GET /healthz` answers "is the process alive and serving HTTP?" the instant the
+ * listener binds. Readiness is stricter: the proxy is "ready" only after the
+ * post-startup Codex catalog/config sync (`syncModelsToCodex`) has settled with
+ * `ok=true` and no catalog-sync warning. Until then the process is live (Codex can
+ * open a socket) but not ready (a request would race the sync or hit a stale
+ * catalog), so clients should back off.
+ *
+ * Design contract (per P1 review):
+ *  - NO module-global mutable state. Each `startServer` invocation gets its own
+ *    private gate via `createReadinessGate()`, captured by that listener's
+ *    closure. Starting/failing a second server in the same process can never
+ *    reset or mutate the first server's gate.
+ *  - Only the fixed sanitized status enum `pending | ready | failed` is stored
+ *    and exposed. There is no `changedAt`, no free-form failure reason, no sync
+ *    message, no warning text, no catalog path, no provider output, and no
+ *    account data — those are private diagnostic data and are never exposed by
+ *    `/readyz`.
+ */
+
+/** Sanitized readiness state. Exactly these three values, nothing else. */
+export type ReadinessStatus = "pending" | "ready" | "failed";
+
+/**
+ * Private per-server readiness controller. The status starts at `pending` and
+ * transitions at most once (to `ready` or `failed`) when the post-startup sync
+ * settles. The gate is owned by the listener closure that requested it.
+ */
+export interface ReadinessGate {
+  /** Current sanitized status. */
+  getStatus(): ReadinessStatus;
+  /** Mark the proxy ready (post-startup sync settled cleanly). */
+  markReady(): void;
+  /** Mark the proxy failed. No reason is stored or exposed. */
+  markFailed(): void;
+}
+
+/**
+ * Create a fresh private gate for one `startServer` invocation. The returned
+ * gate is the only way to read or mutate this server's readiness.
+ */
+export function createReadinessGate(): ReadinessGate {
+  let status: ReadinessStatus = "pending";
+  return {
+    getStatus: () => status,
+    markReady: () => {
+      if (status === "pending") status = "ready";
+    },
+    markFailed: () => {
+      if (status === "pending") status = "failed";
+    },
+  };
+}
+
+/** Minimal shape of the post-startup sync outcome the gate cares about. */
+export interface SyncOutcomeLike {
+  ok?: boolean;
+  warning?: string;
+  /** #1046: whether the sync actually rewrote the on-disk catalog/cache. */
+  catalogWritten?: boolean;
+  cacheSynced?: boolean;
+}
+
+/**
+ * Drive the gate from the post-startup sync. Awaits `syncFn`; the gate goes to
+ * `ready` ONLY on `ok=true` with no nonempty warning. A throw, `null`, `ok=false`,
+ * or a nonempty warning transitions to `failed`. Used directly by `handleStart`
+ * so the startup transition is unit-testable without spawning the proxy. Returns
+ * the raw sync outcome so a caller that also needs the #1046 write flags (did the
+ * sync actually write the catalog/cache?) can keep them without a second call.
+ */
+export async function runStartupReadinessSync(
+  gate: ReadinessGate,
+  syncFn: () => Promise<SyncOutcomeLike | null>,
+): Promise<SyncOutcomeLike | null> {
+  let result: SyncOutcomeLike | null;
+  try {
+    result = await syncFn();
+  } catch {
+    gate.markFailed();
+    return null;
+  }
+  if (result === null) {
+    gate.markFailed();
+    return null;
+  }
+  if (result.ok !== true) {
+    gate.markFailed();
+    return result;
+  }
+  if (result.warning !== undefined && result.warning !== "") {
+    gate.markFailed();
+    return result;
+  }
+  gate.markReady();
+  return result;
+}

package/src/server/relay-eager.ts

@@ -24,11 +24,18 @@
  * up to the drain window.
  */
 
-import { buildFailedTailPayload } from "./relay";
+import {
+  adapterEofIncompleteFrame,
+  createSseTerminalOutputBoundary,
+  doneFrame,
+  failedTailFrame,
+} from "./relay";
 import {
   nextSseBlock,
+  payloadRewriteAsBlockRewrite,
   replaceSseDataPayload,
   sseDataPayload,
+  type SseBlockRewrite,
   type SsePayloadRewrite,
 } from "./sse-payload-rewrite";
 import type { TranslatorBudget } from "../lib/translator-budget";
@@ -43,6 +50,12 @@ export type EagerRelayHooks = {
    * Bun#32111-unsafe tee()+JS-pull chain (#864).
    */
   rewritePayload?: SsePayloadRewrite;
+  /**
+   * Optional block-level rewrite (zero or more blocks out per upstream
+   * block) for lifecycle event injection (#893). Takes precedence over
+   * rewritePayload when both are set.
+   */
+  rewriteBlocks?: SseBlockRewrite;
   /** Flush inspection at upstream end (createSseInspector.finish). */
   finishInspection: () => void;
   /** Drop inspector-owned frame/item state during producer teardown. */
@@ -92,9 +105,21 @@ export function relaySseEagerBounded(
   const now = opts?.now ?? Date.now;
 
   const reader = body.getReader();
-  const rewrite = hooks.rewritePayload;
-  const rewriteDecoder = rewrite ? new TextDecoder() : null;
-  const rewriteEncoder = rewrite ? new TextEncoder() : null;
+  const terminalEncoder = new TextEncoder();
+  const adapterEofFrame = adapterEofIncompleteFrame(terminalEncoder);
+  const terminalSentinel = doneFrame(terminalEncoder);
+  const terminalBoundary = createSseTerminalOutputBoundary();
+  const activeRewrite: SseBlockRewrite | undefined = hooks.rewriteBlocks
+    ?? (hooks.rewritePayload ? payloadRewriteAsBlockRewrite(hooks.rewritePayload) : undefined);
+  const encodeFailedTail = (error: unknown): Uint8Array | null => {
+    try {
+      return failedTailFrame(terminalEncoder, error);
+    } catch {
+      return null;
+    }
+  };
+  const rewriteDecoder = activeRewrite ? new TextDecoder() : null;
+  const rewriteEncoder = activeRewrite ? new TextEncoder() : null;
   const rewriteBudget = opts?.rewriteBudget;
   let frameBuffer = "";
   let frameBufferBytes = 0;
@@ -121,15 +146,9 @@ export function relaySseEagerBounded(
     for (;;) {
       const next = nextSseBlock(frameBuffer);
       if (!next) break;
-      const payload = sseDataPayload(next.block);
-      const rewrittenPayload = payload === null ? null : rewrite!(payload);
-      // Replace only on an actual change: replaceSseDataPayload collapses
-      // multi-data-line events and normalizes newline style even when the
-      // payload is identical, which corrupts valid streams.
-      const block = payload !== null && rewrittenPayload !== payload
-        ? replaceSseDataPayload(next.block, rewrittenPayload!)
-        : next.block;
-      out += block + next.delimiter;
+      for (const outBlock of activeRewrite!(next.block)) {
+        out += outBlock + next.delimiter;
+      }
       frameBuffer = next.rest;
     }
     if (rewriteBudget) {
@@ -143,14 +162,13 @@ export function relaySseEagerBounded(
   };
   /** Flush any trailing partial block at upstream end (rewrite applied, matching the pull relay). */
   const flushRewriteTail = (): Uint8Array => {
-    if (!rewrite) return new Uint8Array(0);
+    if (!activeRewrite) return new Uint8Array(0);
     // Decoder-flushed bytes logically follow everything already decoded.
     let tail = frameBuffer + rewriteDecoder!.decode();
-    const payload = sseDataPayload(tail);
-    if (payload !== null) {
-      const rewrittenPayload = rewrite(payload);
-      if (rewrittenPayload !== payload) tail = replaceSseDataPayload(tail, rewrittenPayload);
-    }
+    const rewritten = activeRewrite(tail);
+    // Multiple emitted blocks must stay separately framed (#893 review);
+    // join places the delimiter only between blocks, never after the last.
+    tail = rewritten.join(tail.includes("\r\n") ? "\r\n\r\n" : "\n\n");
     frameBuffer = "";
     if (rewriteBudget && frameBufferBytes > 0) {
       rewriteBudget.releaseRetained(frameBufferBytes, { kind: "live_transient" });
@@ -166,7 +184,16 @@ export function relaySseEagerBounded(
   // turn unregistration stay reachable, drainAndShutdown never hangs).
   let wake: (() => void) | null = null;
   const wakeUp = () => { const w = wake; wake = null; w?.(); };
-  const paused = () => new Promise<void>(resolve => { wake = resolve; });
+  const paused = () => new Promise<void>(resolve => {
+    wake = resolve;
+    // A pull, cancel, or abort can win the tiny window between the loop's
+    // predicate check and installing this resolver. Re-check every wake
+    // predicate after installation so that an already-fired wake cannot leave
+    // the producer parked forever.
+    if (queuedBytes <= maxQueueBytes || cancelled || upstream.signal.aborted) {
+      wakeUp();
+    }
+  });
   upstream.signal.addEventListener("abort", wakeUp, { once: true });
 
   let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
@@ -192,35 +219,78 @@ export function relaySseEagerBounded(
 
   const producer = async () => {
     let syntheticKind: "incomplete" | "failed" | null = null;
+    let deliveryFallbackSent = false;
+    let priorRewriteFailure = false;
+    let priorRewriteError: unknown;
     // reader.read() is not intrinsically tied to the upstream AbortController
     // (a fetch body usually rejects on abort, but that coupling is the fetch
-    // implementation's, not the stream's). Race every read against the abort
-    // signal so cancel-drain expiry and shutdown teardown ALWAYS break the
-    // loop even on a silent upstream.
-    const aborted: Promise<"aborted"> = new Promise(resolve => {
-      if (upstream.signal.aborted) resolve("aborted");
-      else upstream.signal.addEventListener("abort", () => resolve("aborted"), { once: true });
-    });
+    // implementation's, not the stream's), so abort must break a parked read on
+    // a silent upstream. Cancelling the reader does that: the pending read
+    // settles and the loop observes the abort. This is deliberately NOT a
+    // shared `Promise.race([reader.read(), aborted])` companion — racing every
+    // read against one never-settled promise retains a reaction per chunk, and
+    // that is the exact retention class relay.ts avoids at its own drain.
+    const wakeParkedRead = () => { reader.cancel(upstream.signal.reason).catch(() => {}); };
+    if (upstream.signal.aborted) wakeParkedRead();
+    else upstream.signal.addEventListener("abort", wakeParkedRead, { once: true });
     try {
       for (;;) {
-        const result = await Promise.race([reader.read(), aborted]);
-        if (result === "aborted") break;
+        const result = await reader.read();
         const { done: upstreamDone, value } = result;
+        // A chunk that already settled is INSPECTED before abort is honored. A read
+        // can settle with a real chunk in the same tick the signal fires (post-cancel
+        // drain: the terminal frame arrives, then the drain timer aborts upstream).
+        // Checking the signal first discarded that frame, so the terminal was never
+        // recorded and the turn was accounted as a plain cancel.
+        if (!upstreamDone && value !== undefined) hooks.inspectChunk(value);
+        if (upstream.signal.aborted) break;
         if (upstreamDone) {
           hooks.finishInspection();
-          if (rewrite) {
-            const tail = flushRewriteTail();
-            if (tail.byteLength > 0 && !cancelled) {
-              queuedBytes += tail.byteLength;
-              try { controllerRef?.enqueue(tail); } catch { /* client already gone */ }
+          const boundedTail = terminalBoundary.finish();
+          let clientTail = boundedTail;
+          let rewriteFailed = false;
+          let rewriteError: unknown;
+          if (activeRewrite) {
+            try {
+              const rewritten = rewriteOutbound(boundedTail);
+              clientTail = joinUint8Arrays(rewritten, flushRewriteTail());
+            } catch (error) {
+              rewriteFailed = true;
+              rewriteError = error;
+              clientTail = new Uint8Array(0);
+            }
+          }
+          if (rewriteFailed) {
+            const safeTail = encodeFailedTail(rewriteError);
+            if (safeTail && !cancelled && !upstream.signal.aborted) {
+              if (!hooks.sawTerminal()) syntheticKind = "failed";
+              queuedBytes += safeTail.byteLength;
+              try { controllerRef?.enqueue(safeTail); } catch { /* client already torn down */ }
+              try { controllerRef?.close(); } catch { /* client already gone */ }
             }
+            break;
+          }
+          if (clientTail.byteLength > 0 && !cancelled) {
+            queuedBytes += clientTail.byteLength;
+            try { controllerRef?.enqueue(clientTail); } catch { /* client already gone */ }
           }
-          if (!hooks.sawTerminal() && !cancelled && !upstream.signal.aborted) {
+          if (terminalBoundary.terminalSeen()) {
+            if (!terminalBoundary.doneSeen() && !cancelled) {
+              queuedBytes += terminalSentinel.byteLength;
+              try { controllerRef?.enqueue(terminalSentinel); } catch { /* client already gone */ }
+            }
+          } else if (!hooks.sawTerminal() && !cancelled && !upstream.signal.aborted) {
+            // A clean 200 EOF without a Responses terminal must be visible to
+            // Codex as one incomplete turn, followed by the normal sentinel.
+            queuedBytes += adapterEofFrame.byteLength + terminalSentinel.byteLength;
+            try {
+              controllerRef?.enqueue(adapterEofFrame);
+              controllerRef?.enqueue(terminalSentinel);
+            } catch { /* client already gone */ }
             syntheticKind = "incomplete";
           }
           break;
         }
-        hooks.inspectChunk(value);
         if (cancelled) {
           // Discard-drain: inspection only, nothing queued. Stop at terminal
           // or when the bounded window expires.
@@ -230,17 +300,44 @@ export function relaySseEagerBounded(
           }
           continue;
         }
-        const outbound = rewrite ? rewriteOutbound(value) : value;
-        if (outbound.byteLength === 0) continue;
-        queuedBytes += outbound.byteLength;
-        try {
-          controllerRef?.enqueue(outbound);
-        } catch {
-          // Controller already torn down (client went away without cancel()).
-          cancelled = true;
-          drainDeadline = now() + drainMs;
-          armDrainTimer();
-          continue;
+        const terminalBounded = terminalBoundary.feed(value);
+        let outbound: Uint8Array;
+        if (activeRewrite) {
+          try {
+            outbound = rewriteOutbound(terminalBounded);
+          } catch (error) {
+            // Preserve the first rewrite failure across the teardown flush. A
+            // second empty flush may succeed, but the terminal bytes still
+            // must not bypass the failed rewrite or become DONE-only output.
+            priorRewriteFailure = true;
+            priorRewriteError = error;
+            throw error;
+          }
+        } else {
+          outbound = terminalBounded;
+        }
+        if (outbound.byteLength > 0) {
+          queuedBytes += outbound.byteLength;
+          try {
+            controllerRef?.enqueue(outbound);
+          } catch {
+            // Controller already torn down (client went away without cancel()).
+            cancelled = true;
+            drainDeadline = now() + drainMs;
+            armDrainTimer();
+            continue;
+          }
+        }
+        if (terminalBoundary.terminalSeen()) {
+          // The Responses terminal event ends the turn even when a compatible
+          // gateway keeps its HTTP connection alive. Add the conventional
+          // sentinel and stop the single-reader relay at that protocol boundary.
+          if (!terminalBoundary.doneSeen()) {
+            queuedBytes += terminalSentinel.byteLength;
+            try { controllerRef?.enqueue(terminalSentinel); } catch { /* client already gone */ }
+          }
+          reader.cancel("Responses terminal event received").catch(() => {});
+          break;
         }
         while (queuedBytes > maxQueueBytes && !cancelled && !upstream.signal.aborted) {
           await paused();
@@ -249,16 +346,75 @@ export function relaySseEagerBounded(
     } catch (err) {
       // Upstream read failure. Distinguish genuine mid-stream reset from
       // abort-driven teardown (shutdown/cancel-expiry) — audit M3.
-      if (!hooks.sawTerminal() && !cancelled && !upstream.signal.aborted) {
+      // A read can fail after delivering an unterminated terminal block. Flush
+      // both observers before deciding whether this is a synthetic reset so
+      // eager mode matches the tee/pull boundary semantics at EOF.
+      let boundedTail: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+      let tailTerminal = false;
+      let tailDone = false;
+      try { hooks.finishInspection(); } catch { /* preserve the original read failure */ }
+      try {
+        boundedTail = terminalBoundary.finish();
+        tailTerminal = terminalBoundary.terminalSeen();
+        tailDone = terminalBoundary.doneSeen();
+      } catch {
+        // A near-cap ambiguous delimiter tail may itself overflow at EOF.
+        // Preserve the original read/framing failure and continue emitting
+        // the bounded failed tail instead of letting cleanup throw again.
+      }
+      let clientTail: Uint8Array<ArrayBufferLike> = boundedTail;
+      let rewriteFailed = false;
+      let rewriteError: unknown;
+      if (priorRewriteFailure) {
+        rewriteFailed = true;
+        rewriteError = priorRewriteError;
+        clientTail = new Uint8Array(0);
+      } else if (activeRewrite) {
+        try {
+          const rewritten = rewriteOutbound(boundedTail);
+          clientTail = joinUint8Arrays(rewritten, flushRewriteTail());
+        } catch (error) {
+          rewriteFailed = true;
+          rewriteError = error;
+          clientTail = new Uint8Array(0);
+        }
+      }
+      if (clientTail.byteLength > 0 && !cancelled && !upstream.signal.aborted) {
+        queuedBytes += clientTail.byteLength;
+        try { controllerRef?.enqueue(clientTail); } catch { /* client already torn down */ }
+      }
+      if (rewriteFailed && !cancelled && !upstream.signal.aborted) {
+        // Never bypass a client rewrite after it fails: boundedTail can contain
+        // provider metadata or content that the active rewrite was required to
+        // remove. Emit one safe failed envelope instead. When inspection has
+        // already reported the real upstream terminal, this is a delivery
+        // fallback only and must not create a second accounting outcome.
+        const safeTail = encodeFailedTail(rewriteError ?? err);
+        if (safeTail && !cancelled && !upstream.signal.aborted) {
+          if (!hooks.sawTerminal()) syntheticKind = "failed";
+          deliveryFallbackSent = true;
+          queuedBytes += safeTail.byteLength;
+          try { controllerRef?.enqueue(safeTail); } catch { /* client already torn down */ }
+          try { controllerRef?.close(); } catch { /* client already gone */ }
+        }
+      } else if (tailTerminal && !cancelled && !upstream.signal.aborted) {
+        if (!tailDone) {
+          queuedBytes += terminalSentinel.byteLength;
+          try { controllerRef?.enqueue(terminalSentinel); } catch { /* client already gone */ }
+        }
+      } else if (!tailTerminal && !cancelled && !upstream.signal.aborted) {
         // Serializing `err` can run user-defined accessors (Error.message
         // getters, toString) that re-entrantly cancel the client or abort the
         // upstream. Build the tail FIRST, then re-check eligibility before
         // committing to the synthetic terminal (adversarial review blocker).
-        const tail = new TextEncoder().encode(
-          `\n\nevent: response.failed\ndata: ${buildFailedTailPayload(err)}\n\ndata: [DONE]\n\n`,
-        );
-        if (!hooks.sawTerminal() && !cancelled && !upstream.signal.aborted) {
-          syntheticKind = "failed";
+        const tail = encodeFailedTail(err);
+        if (tail && !cancelled && !upstream.signal.aborted) {
+          // Inspection and client framing have separate bounded parsers. If
+          // inspection resynchronized after an oversized frame and observed a
+          // later real terminal, it still must not suppress a terminal delivery
+          // to the client. Only accounting remains tied to the inspected result.
+          if (!hooks.sawTerminal()) syntheticKind = "failed";
+          deliveryFallbackSent = true;
           queuedBytes += tail.byteLength;
           try { controllerRef?.enqueue(tail); } catch { /* client already torn down */ }
           try { controllerRef?.close(); } catch { /* client already torn down */ }
@@ -272,11 +428,12 @@ export function relaySseEagerBounded(
         try { rewriteBudget.releaseRetained(frameBufferBytes, { kind: "live_transient" }); } catch { /* teardown must not throw */ }
         frameBufferBytes = 0;
       }
+      terminalBoundary.dispose();
       if (syntheticKind) hooks.onSynthetic(syntheticKind);
       if (cancelled && !hooks.sawTerminal()) {
         hooks.onClientCancel();
       }
-      if (cancelled || upstream.signal.aborted || syntheticKind === "failed") {
+      if (cancelled || upstream.signal.aborted || syntheticKind === "failed" || deliveryFallbackSent) {
         upstream.abort();
         reader.cancel().catch(() => {});
       }
@@ -284,6 +441,7 @@ export function relaySseEagerBounded(
         try { controllerRef?.close(); } catch { /* already closed/errored */ }
       }
       try { hooks.disposeInspection?.(); } catch { /* inspection teardown must not block lifecycle cleanup */ }
+      try { activeRewrite?.dispose?.(); } catch { /* rewrite teardown must not block lifecycle cleanup */ }
       fireDone();
     }
   };
@@ -311,3 +469,12 @@ export function relaySseEagerBounded(
     },
   });
 }
+
+function joinUint8Arrays(first: Uint8Array, second: Uint8Array): Uint8Array {
+  if (first.byteLength === 0) return second;
+  if (second.byteLength === 0) return first;
+  const joined = new Uint8Array(first.byteLength + second.byteLength);
+  joined.set(first);
+  joined.set(second, first.byteLength);
+  return joined;
+}