@ngockhoale/ukit 2.3.15 → 2.3.17

package/src/core/gatewayProbe.js

@@ -0,0 +1,441 @@
+/**
+ * gatewayProbe.js (TASK-012)
+ *
+ * Live self-test for the gateway currently configured for Claude Code. Two sub-probes:
+ *   - streaming: posts a tiny `stream: true` request and counts SSE frames + distinct body
+ *     reads. All frames in one read = buffering (the 300s stall signature).
+ *   - non-streaming: posts a tiny `stream: false` request. PASS only if HTTP 200 + body is
+ *     an Anthropic Message (type === 'message' && Array.isArray(content)) AND a `request-id`
+ *     header is present. This is the exact check whose absence let the 888-byte gateway
+ *     error envelope slip through and kill the user's turn.
+ *
+ * Self-contained and hermetic: `fetchImpl` is injectable. `resolveGatewayBaseUrl` mirrors the
+ * 3-tier probe order from templates/.claude/ukit/index/unic-gateway.mjs (env → project
+ * .claude/settings.json → home ~/.claude/settings.json) but is intentionally duplicated
+ * here per PLAN.md §3 (cross-task coupling is the cheaper-than-it-looks debt — see plan).
+ *
+ * Never throws: any unexpected error in an individual probe is captured and reflected in the
+ * returned result so the doctor wiring stays safe and the test harness stays deterministic.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const GATEWAY_DOC = 'docs/GATEWAY.md';
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJson(filePath) {
+  const raw = safeReadFile(filePath);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function pickString(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+  }
+  return null;
+}
+
+function readEnvBaseUrl(env) {
+  const value = pickString(env?.ANTHROPIC_BASE_URL);
+  return value ? { baseUrl: value, source: 'env' } : null;
+}
+
+function readSettingsBaseUrl(filePath) {
+  const json = safeReadJson(filePath);
+  if (!json || typeof json !== 'object') return null;
+  const envBlock = json.env;
+  if (!envBlock || typeof envBlock !== 'object') return null;
+  const value = pickString(envBlock.ANTHROPIC_BASE_URL);
+  return value ? { baseUrl: value, source: 'claude-settings' } : null;
+}
+
+/**
+ * Detects the current custom-gateway base URL using the same 3-tier probe order as
+ * `templates/.claude/ukit/index/unic-gateway.mjs` (generalized — fires on any non-empty
+ * value, not only the UNIC token):
+ *   1. env.ANTHROPIC_BASE_URL
+ *   2. <projectRoot>/.claude/settings.json -> env.ANTHROPIC_BASE_URL
+ *   3. <homeDir>/.claude/settings.json -> env.ANTHROPIC_BASE_URL
+ *
+ * First hit wins. Never throws: a missing or malformed file in any tier is skipped.
+ *
+ * @param {{ projectRoot: string, homeDir?: string, env?: object }} options
+ * @returns {Promise<{ baseUrl: string|null, source: 'env'|'claude-settings'|null }>}
+ */
+export async function resolveGatewayBaseUrl({
+  projectRoot,
+  homeDir = os.homedir(),
+  env = process.env,
+}) {
+  const probes = [
+    () => readEnvBaseUrl(env ?? {}),
+    () => readSettingsBaseUrl(path.join(projectRoot, '.claude', 'settings.json')),
+    () => readSettingsBaseUrl(path.join(homeDir, '.claude', 'settings.json')),
+  ];
+  for (const probe of probes) {
+    try {
+      const hit = probe();
+      if (hit) return hit;
+    } catch {
+      // a single probe failing must never abort detection
+    }
+  }
+  return { baseUrl: null, source: null };
+}
+
+function pickApiKey(envLike) {
+  if (!envLike || typeof envLike !== 'object') return null;
+  // Source matters: ANTHROPIC_API_KEY is sent by Claude Code as `x-api-key`, while
+  // ANTHROPIC_AUTH_TOKEN is sent by Claude Code as `Authorization: Bearer`. Sending
+  // the wrong header causes token-auth gateways to 401 the probe.
+  if (typeof envLike.ANTHROPIC_API_KEY === 'string' && envLike.ANTHROPIC_API_KEY.length > 0) {
+    return { value: envLike.ANTHROPIC_API_KEY, source: 'api-key' };
+  }
+  if (typeof envLike.ANTHROPIC_AUTH_TOKEN === 'string' && envLike.ANTHROPIC_AUTH_TOKEN.length > 0) {
+    return { value: envLike.ANTHROPIC_AUTH_TOKEN, source: 'auth-token' };
+  }
+  return null;
+}
+
+function pickModel(envLike) {
+  if (!envLike || typeof envLike !== 'object') return null;
+  return pickString(envLike.ANTHROPIC_MODEL);
+}
+
+// Minimal VALID Anthropic Messages API body. The probe only measures transport shape
+// (SSE framing, Message envelope, request-id header) — not model capability — so the
+// prompt is intentionally tiny ("ping", 1 token of headroom). `max_tokens: 16` keeps
+// the call essentially free on a billed gateway.
+function buildRequestBody({ stream, model }) {
+  return JSON.stringify({
+    model,
+    max_tokens: 16,
+    stream,
+    messages: [{ role: 'user', content: 'ping' }],
+  });
+}
+
+// Auth headers must mirror how Claude Code itself forwards each env var:
+//   * ANTHROPIC_API_KEY     -> x-api-key (Anthropic-native)
+//   * ANTHROPIC_AUTH_TOKEN  -> Authorization: Bearer (OpenAI-style / proxy gateways)
+// Without this split, token-auth gateways 401 the probe even when transport shape is
+// valid (Reviewer Round-1 important finding #3).
+function buildAuthHeaders(keyValue, keySource) {
+  if (!keyValue) return {};
+  if (keySource === 'auth-token') {
+    return { Authorization: `Bearer ${keyValue}` };
+  }
+  // Default to the Anthropic-native scheme — covers explicit apiKey arg and
+  // ANTHROPIC_API_KEY env (the dominant case).
+  return { 'x-api-key': keyValue, 'anthropic-version': '2023-06-01' };
+}
+
+function getRequestId(headers) {
+  if (!headers || typeof headers.get !== 'function') return null;
+  return (
+    pickString(headers.get('request-id'), headers.get('anthropic-request-id')) ?? null
+  );
+}
+
+function parseSseEvents(text) {
+  // SSE frame is the chunk between blank lines; we count distinct `data:` lines as a
+  // pragmatic proxy for "events received" (matches what the gateway actually streams).
+  const lines = text.split(/\r?\n/);
+  let count = 0;
+  for (const line of lines) {
+    if (line.startsWith('data:')) count += 1;
+  }
+  return count;
+}
+
+/**
+ * Streaming probe: posts `stream: true` and counts SSE frames + distinct body reads.
+ *
+ * Buffered (the stall signature) is defined as: the FIRST body read alone already yields
+ * >=2 SSE events. A non-buffering gateway delivers events incrementally across reads; a
+ * buffering gateway dumps everything in one read.
+ *
+ * @returns {Promise<{ ok: boolean, eventsReceived: number, firstEventMs: number|null,
+ *                    chunks: number, buffered: boolean, error?: string }>}
+ */
+async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const startedAt = Date.now();
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers,
+      body: requestBody,
+      signal: controller.signal,
+    });
+    if (!response?.ok) {
+      return {
+        ok: false,
+        eventsReceived: 0,
+        firstEventMs: null,
+        chunks: 0,
+        buffered: false,
+        error: `HTTP ${response?.status ?? 'unknown'}`,
+      };
+    }
+    const body = response.body;
+    if (!body || typeof body.getReader !== 'function') {
+      return {
+        ok: false,
+        eventsReceived: 0,
+        firstEventMs: null,
+        chunks: 0,
+        buffered: false,
+        error: 'no readable body',
+      };
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let eventsReceived = 0;
+    let chunks = 0;
+    let firstEventMs = null;
+    let buffered = false;
+    let buffer = '';
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (!value) continue;
+        chunks += 1;
+        buffer += decoder.decode(value, { stream: true });
+        // Process complete SSE frames accumulated so far.
+        const frames = buffer.split(/\r?\n\r?\n/);
+        buffer = frames.pop() ?? ''; // keep incomplete trailing chunk
+        for (const frame of frames) {
+          if (!frame.trim()) continue;
+          const frameEvents = parseSseEvents(frame);
+          if (frameEvents > 0) {
+            if (firstEventMs === null) firstEventMs = Date.now() - startedAt;
+            eventsReceived += frameEvents;
+          }
+        }
+        // Buffered criterion: the first body read alone already yields >=2 SSE events.
+        if (chunks === 1 && eventsReceived >= 2) {
+          buffered = true;
+        }
+      }
+      // Flush any trailing buffer (no terminating blank line).
+      if (buffer.trim()) {
+        const trailing = parseSseEvents(buffer);
+        if (trailing > 0) {
+          if (firstEventMs === null) firstEventMs = Date.now() - startedAt;
+          eventsReceived += trailing;
+          // If we never got a second read, treat it as buffered when at least 2 events landed.
+          if (chunks < 2 && eventsReceived >= 2) buffered = true;
+        }
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        // reader may already be released
+      }
+    }
+    const ok = eventsReceived >= 1 && !buffered;
+    return {
+      ok,
+      eventsReceived,
+      firstEventMs,
+      chunks,
+      buffered,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      eventsReceived: 0,
+      firstEventMs: null,
+      chunks: 0,
+      buffered: false,
+      error: error?.message ?? String(error),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Non-streaming probe: posts `stream: false` and asserts the response is a real Anthropic
+ * Message with a `request-id` header. This is the missing check that let the 888-byte
+ * gateway error envelope slip through Claude Code's retry path and kill the user's turn.
+ *
+ * @returns {Promise<{ ok: boolean, httpOk: boolean, isAnthropicMessage: boolean,
+ *                    requestIdPresent: boolean, bodyBytes: number|null, error?: string }>}
+ */
+async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers,
+      body: requestBody,
+      signal: controller.signal,
+    });
+    const httpOk = Boolean(response?.ok);
+    const requestIdPresent = getRequestId(response?.headers) !== null;
+    if (!response?.ok) {
+      return {
+        ok: false,
+        httpOk: false,
+        isAnthropicMessage: false,
+        requestIdPresent,
+        bodyBytes: null,
+        error: `HTTP ${response?.status ?? 'unknown'}`,
+      };
+    }
+    const body = response.body;
+    if (!body || typeof body.getReader !== 'function') {
+      return {
+        ok: false,
+        httpOk: true,
+        isAnthropicMessage: false,
+        requestIdPresent,
+        bodyBytes: null,
+        error: 'no readable body',
+      };
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) text += decoder.decode(value, { stream: true });
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        // reader may already be released
+      }
+    }
+    const bodyBytes = Buffer.byteLength(text, 'utf8');
+    let parsed = null;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = null;
+    }
+    const isAnthropicMessage =
+      parsed !== null &&
+      typeof parsed === 'object' &&
+      parsed.type === 'message' &&
+      Array.isArray(parsed.content);
+    const ok = isAnthropicMessage && requestIdPresent;
+    return {
+      ok,
+      httpOk: true,
+      isAnthropicMessage,
+      requestIdPresent,
+      bodyBytes,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      httpOk: false,
+      isAnthropicMessage: false,
+      requestIdPresent: false,
+      bodyBytes: null,
+      error: error?.message ?? String(error),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Runs both probes against `baseUrl`. Returns a structured result; never propagates exceptions
+ * — every failure is reflected in the returned object so the CLI can print it.
+ *
+ * @param {{ baseUrl: string, apiKey?: string|null, model?: string|null,
+ *           env?: object, fetchImpl?: typeof fetch, timeoutMs?: number }} options
+ */
+export async function probeGateway({
+  baseUrl,
+  apiKey = null,
+  apiKeySource = null,
+  model = null,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 30000,
+}) {
+  // Resolve effective api key + its source. Order of precedence matches Claude Code
+  // itself: explicit apiKey arg wins; otherwise we read from env, preserving which env
+  // var produced it so we can pick the matching header scheme.
+  const envKey = pickApiKey(env);
+  const resolvedValue = pickString(apiKey, envKey?.value) ?? null;
+  const resolvedSource = apiKey
+    ? (apiKeySource ?? 'api-key')
+    : (envKey?.source ?? null);
+  const effectiveModel = pickString(model, pickModel(env)) ?? 'claude-sonnet-4-5';
+  const url = `${baseUrl.replace(/\/+$/, '')}/v1/messages`;
+  const headers = {
+    'content-type': 'application/json',
+    ...buildAuthHeaders(resolvedValue, resolvedSource),
+  };
+
+  const streamBody = buildRequestBody({ stream: true, model: effectiveModel });
+  const nonStreamBody = buildRequestBody({ stream: false, model: effectiveModel });
+
+  const [streaming, nonStreaming] = await Promise.all([
+    runStreamingProbe({ url, headers, body: streamBody, fetchImpl, timeoutMs }),
+    runNonStreamingProbe({ url, headers, body: nonStreamBody, fetchImpl, timeoutMs }),
+  ]);
+
+  const hints = [];
+  if (!streaming.ok) {
+    if (streaming.buffered) {
+      hints.push(
+        `Set CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000 in .claude/settings.json env — gateway appears to buffer the entire stream; see ${GATEWAY_DOC}.`,
+      );
+    } else if (streaming.error) {
+      hints.push(
+        `Streaming probe failed: ${streaming.error} — see ${GATEWAY_DOC}.`,
+      );
+    } else {
+      hints.push(
+        `Streaming probe returned no SSE events — see ${GATEWAY_DOC}.`,
+      );
+    }
+  }
+  if (!nonStreaming.ok) {
+    if (nonStreaming.httpOk && !nonStreaming.isAnthropicMessage) {
+      hints.push(
+        `Set CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 in .claude/settings.json env — non-streaming route returned JSON but not an Anthropic Message; see ${GATEWAY_DOC}.`,
+      );
+    } else if (nonStreaming.httpOk && !nonStreaming.requestIdPresent) {
+      hints.push(
+        `Gateway must set the request-id (or anthropic-request-id) response header — see ${GATEWAY_DOC}.`,
+      );
+    } else if (nonStreaming.error) {
+      hints.push(
+        `Non-streaming probe failed: ${nonStreaming.error} — see ${GATEWAY_DOC}.`,
+      );
+    } else {
+      hints.push(`Non-streaming probe failed — see ${GATEWAY_DOC}.`);
+    }
+  }
+
+  const verdict = streaming.ok && nonStreaming.ok ? 'pass' : 'fail';
+  return { streaming, nonStreaming, verdict, hints };
+}