Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
perf(client): every client caps requests, bounds reads, retries a read once (CL-15)
KageBinary1ed09a764a70
diff --git a/ix-cli/src/cli/__tests__/client-defaults.test.ts b/ix-cli/src/cli/__tests__/client-defaults.test.tsnew file mode 100644index 00000000..0ce0c88f--- /dev/null+++ b/ix-cli/src/cli/__tests__/client-defaults.test.ts@@ -0,0 +1,160 @@+// Copyright 2026 Ix Infrastructure Inc.++import { createServer, type Server } from "node:http";++import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";++import { IxClient } from "../../client/api.js";+import { createClient, DEFAULT_READ_DEADLINE_MS, readDeadlineMs } from "../../client/factory.js";++/**+ * CL-15: only four query commands capped requests in flight, every read waited+ * up to 2 minutes on a hung backend, and one dropped connection or 503 failed+ * the command. Every client now caps at 12, reads are bounded per command, and+ * a read (never a write) is retried once.+ */++type Handler = (url: string, method: string) => { status: number; body: string; delayMs?: number } | "hang";+let handler: Handler = () => ({ status: 200, body: "[]" });+let server: Server;+let endpoint: string;+let inflight = 0;+let peak = 0;+const requests: string[] = [];++beforeAll(async () => {+ server = createServer((req, res) => {+ req.resume();+ req.on("end", () => {+ requests.push(`${req.method} ${req.url}`);+ const r = handler(req.url ?? "", req.method ?? "");+ if (r === "hang") return;+ inflight++;+ peak = Math.max(peak, inflight);+ setTimeout(() => {+ inflight--;+ res.writeHead(r.status, { "content-type": "application/json" });+ res.end(r.body);+ }, r.delayMs ?? 0);+ });+ });+ await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));+ const addr = server.address();+ endpoint = `http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : 0}`;+});++afterAll(async () => {+ server.closeAllConnections();+ await new Promise<void>((r) => server.close(() => r()));+});++let savedDeadline: string | undefined;+beforeEach(() => {+ requests.length = 0;+ inflight = 0;+ peak = 0;+ handler = () => ({ status: 200, body: "[]" });+ savedDeadline = process.env.IX_READ_DEADLINE_MS;+ delete process.env.IX_READ_DEADLINE_MS;+});+afterEach(() => {+ if (savedDeadline === undefined) delete process.env.IX_READ_DEADLINE_MS;+ else process.env.IX_READ_DEADLINE_MS = savedDeadline;+ // Not closeAllConnections(): that leaves the client's pooled keep-alive+ // sockets dead, and the next test's first request would spend its one retry+ // on one of them.+ vi.restoreAllMocks();+});++describe("every client caps requests in flight", () => {+ it("200 concurrent reads through createClient never put more than 12 in flight", async () => {+ handler = () => ({ status: 200, body: "[]", delayMs: 15 });+ const client = createClient({ endpoint });+ await Promise.all(Array.from({ length: 200 }, (_, i) => client.search(`t${i}`)));+ expect(requests).toHaveLength(200);+ expect(peak).toBeLessThanOrEqual(12);+ });+});++describe("one retry for a read, none for a write", () => {+ it("a 503 on a GET is asked again once and the answer used", async () => {+ let n = 0;+ handler = () => (n++ === 0 ? { status: 503, body: '{"error":"restarting"}' } : { status: 200, body: '{"rev":3}' });+ await expect(createClient({ endpoint }).currentRevision()).resolves.toEqual({ rev: 3 });+ expect(requests).toHaveLength(2);+ });++ it("a 503 on a read POST (search) is retried too", async () => {+ let n = 0;+ handler = () => (n++ === 0 ? { status: 502, body: "bad gateway" } : { status: 200, body: "[]" });+ await expect(createClient({ endpoint }).search("x")).resolves.toEqual([]);+ expect(requests).toHaveLength(2);+ });++ it("only once: a second 503 fails the read", async () => {+ handler = () => ({ status: 503, body: '{"error":"down"}' });+ await expect(createClient({ endpoint }).currentRevision()).rejects.toThrow(/^503:/);+ expect(requests).toHaveLength(2);+ });++ it("never retries a write", async () => {+ handler = () => ({ status: 503, body: '{"error":"restarting"}' });+ await expect(createClient({ endpoint }).deleteWorkspace("ws")).rejects.toThrow(/^503:/);+ expect(requests).toEqual(["POST /v1/reset/workspace"]);+ });++ it("does not retry a 500 or a 404", async () => {+ handler = () => ({ status: 500, body: '{"error":"boom"}' });+ await expect(createClient({ endpoint }).currentRevision()).rejects.toThrow(/^500:/);+ expect(requests).toHaveLength(1);+ });++ it("a refused or reset connection on a read is retried once", async () => {+ const real = globalThis.fetch;+ let calls = 0;+ vi.spyOn(globalThis, "fetch").mockImplementation(async (...args) => {+ calls++;+ if (calls === 1) throw Object.assign(new TypeError("fetch failed"), { cause: { code: "ECONNRESET" } });+ return real(...args);+ });+ await expect(createClient({ endpoint }).search("x")).resolves.toEqual([]);+ expect(calls).toBe(2);+ });++ it("a plain IxClient keeps the old behaviour: no retry", async () => {+ handler = () => ({ status: 503, body: '{"error":"restarting"}' });+ await expect(new IxClient(endpoint).currentRevision()).rejects.toThrow(/^503:/);+ expect(requests).toHaveLength(1);+ });+});++describe("a read deadline per command", () => {+ it("a hung backend fails a read at the deadline, not after 2 minutes", async () => {+ handler = () => "hang";+ process.env.IX_READ_DEADLINE_MS = "300";+ const t0 = Date.now();+ await expect(createClient({ endpoint }).search("x")).rejects.toThrow();+ expect(Date.now() - t0).toBeLessThan(2_000);+ });++ it("does not cut off a write", async () => {+ handler = (url) => (url.startsWith("/v1/reset/workspace") ? { status: 200, body: "{}", delayMs: 500 } : "hang");+ process.env.IX_READ_DEADLINE_MS = "200";+ await expect(createClient({ endpoint }).deleteWorkspace("ws")).resolves.toBeUndefined();+ });++ it("long-running clients and callers with their own deadline get none", async () => {+ handler = () => ({ status: 200, body: "[]", delayMs: 400 });+ process.env.IX_READ_DEADLINE_MS = "100";+ await expect(createClient({ endpoint, longRunning: true }).search("x")).resolves.toEqual([]);+ await expect(createClient({ endpoint, deadlineSignal: new AbortController().signal }).search("x")).resolves.toEqual([]);+ });++ it("IX_READ_DEADLINE_MS: a number of ms, 0 for none, anything else the default", () => {+ expect(readDeadlineMs({})).toBe(DEFAULT_READ_DEADLINE_MS);+ expect(DEFAULT_READ_DEADLINE_MS).toBe(60_000);+ expect(readDeadlineMs({ IX_READ_DEADLINE_MS: "5000" })).toBe(5000);+ expect(readDeadlineMs({ IX_READ_DEADLINE_MS: "0" })).toBe(0);+ expect(readDeadlineMs({ IX_READ_DEADLINE_MS: "soon" })).toBe(DEFAULT_READ_DEADLINE_MS);+ });+});diff --git a/ix-cli/src/cli/commands/stats.ts b/ix-cli/src/cli/commands/stats.tsindex e7893a3c..5520c619 100644--- a/ix-cli/src/cli/commands/stats.ts+++ b/ix-cli/src/cli/commands/stats.ts@@ -27,7 +27,8 @@ export function registerStatsCommand(program: Command): void {.description("Show graph statistics — node/edge counts by type").option("--format <fmt>", "Output format (text|json|llm)", "text").action(async (opts: { format: string }) => {- const client = createClient();+ // /v1/stats takes seconds on a large graph: no read deadline.+ const client = createClient({ longRunning: true });const systemId = await resolveReadSystemId(client);let result;try {diff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.tsindex 05ad1604..6848fedb 100644--- a/ix-cli/src/cli/config.ts+++ b/ix-cli/src/cli/config.ts@@ -309,7 +309,8 @@ export function clearLocalToken(): void {// that module imports `getEndpoint` from this one.export async function createClient(): Promise<IxClient> {const factory = await import("../client/factory.js");- return factory.createClient();+ // Pro's client may outlive one command: no read deadline.+ return factory.createClient({ longRunning: true });}export function loadWorkspaces(): WorkspaceConfig[] {diff --git a/ix-cli/src/client/api.ts b/ix-cli/src/client/api.tsindex 9d0b3a6d..7cf3c446 100644--- a/ix-cli/src/client/api.ts+++ b/ix-cli/src/client/api.ts@@ -37,6 +37,37 @@ export interface IxClientOptions {maxInFlight?: number;/** Sent as `Authorization: Bearer <token>` on every request (see `getLocalToken`). */token?: string;+ /**+ * Reads (GETs, and the POSTs in `SHARED_READ_PREFIXES`) fail once this many+ * ms have passed since the client was created: a whole-command bound on a+ * hung backend, which the 2-minute per-request timeout is not. Writes are+ * never cut off by it. 0 or absent: no such bound.+ */+ readDeadlineMs?: number;+ /**+ * Retry a read once, after a short random wait, when the connection was+ * refused or reset before it carried anything, or the answer was 502/503/504.+ * Writes are never retried.+ */+ retryReads?: boolean;+}++/** Statuses a proxy or a restarting backend answers with, for which one retry is worth it. */+const RETRYABLE_READ_STATUS = /^(502|503|504):/;++/**+ * A connection dropped mid-request. Not safe to repeat for a write, which may+ * have been applied; a read can simply be asked again.+ */+const DROPPED_CONNECTION_CODES = new Set(["ECONNRESET", "EPIPE", "UND_ERR_SOCKET"]);++function hasCode(err: unknown, codes: ReadonlySet<string>): boolean {+ for (let e: unknown = err, hops = 0; e && hops < 5; hops++) {+ const code = (e as { code?: unknown }).code;+ if (typeof code === "string" && codes.has(code)) return true;+ e = (e as { cause?: unknown }).cause;+ }+ return false;}/**@@ -56,6 +87,8 @@ export class IxClient {private readonly memo?: RequestMemo<SuccessBody>;private readonly limiter?: Limiter;private readonly token?: string;+ private readonly readDeadline?: AbortSignal;+ private readonly retryReads: boolean;// An optional deadline signal shared across every request this client makes.// `ix map` sets it to a hard wall-clock budget so that, even when the backend@@ -72,6 +105,9 @@ export class IxClient {if (options.shareReads) this.memo = new RequestMemo();if (options.maxInFlight !== undefined) this.limiter = new Limiter(options.maxInFlight);if (options.token) this.token = options.token;+ // Unref'd by Node, so it never holds a finished process open.+ if (options.readDeadlineMs && options.readDeadlineMs > 0) this.readDeadline = AbortSignal.timeout(options.readDeadlineMs);+ this.retryReads = options.retryReads === true;}/**@@ -91,13 +127,14 @@ export class IxClient {return this.memo?.hits ?? 0;}- // Combine a per-request timeout with the optional shared deadline. Whichever- // fires first aborts the fetch. AbortSignal.any propagates the first abort.- private signalFor(perRequestMs: number): AbortSignal {- const perRequest = AbortSignal.timeout(perRequestMs);- return this.deadlineSignal- ? AbortSignal.any([perRequest, this.deadlineSignal])- : perRequest;+ // Combine a per-request timeout with the optional shared deadline, and for a+ // read with the client's read deadline. Whichever fires first aborts the+ // fetch. AbortSignal.any propagates the first abort.+ private signalFor(perRequestMs: number, read = false): AbortSignal {+ const signals = [AbortSignal.timeout(perRequestMs)];+ if (this.deadlineSignal) signals.push(this.deadlineSignal);+ if (read && this.readDeadline) signals.push(this.readDeadline);+ return signals.length === 1 ? signals[0]! : AbortSignal.any(signals);}async query(@@ -743,8 +780,9 @@ export class IxClient {body: payload,// These small reads/writes (source-hashes, stitch, list, ...) had no// timeout, so a stalled connection could hang the process indefinitely.- // 2 min per request, also bounded by the shared deadline when set.- signal: this.signalFor(2 * 60 * 1000),+ // 2 min per request, also bounded by the shared deadline when set, and+ // by the read deadline when this POST is a read.+ signal: this.signalFor(2 * 60 * 1000, isSharedRead(path)),}));}@@ -752,23 +790,48 @@ export class IxClient {return this.read<T>("GET", path, "", () =>fetch(`${this.endpoint}${path}`, {headers: this.headers(false),- signal: this.signalFor(timeoutMs),+ signal: this.signalFor(timeoutMs, true),}));}+ /**+ * Whether a failed read is worth one more try: the request never reached a+ * backend (refused, unresolvable), the connection dropped under it, or a+ * proxy or a restarting backend answered 502/503/504. Never once a deadline+ * has fired.+ */+ private shouldRetry(err: unknown): boolean {+ if (!this.retryReads) return false;+ if (this.deadlineSignal?.aborted || this.readDeadline?.aborted) return false;+ if (isPreConnectionFailure(err) || hasCode(err, DROPPED_CONNECTION_CODES)) return true;+ return err instanceof Error && RETRYABLE_READ_STATUS.test(err.message);+ }+/*** One request whose body is JSON: sent under the in-flight limit when there* is one, shared with an identical earlier request when `shareReads` is on* and the path is a read, and parsed per caller either way.*/private async read<T>(method: string, path: string, payload: string, send: () => Promise<Response>): Promise<T> {+ const isRead = method === "GET" || isSharedRead(path);const fetchBody = async (): Promise<SuccessBody> => {- const run = async (): Promise<SuccessBody> => {+ const once = async (): Promise<SuccessBody> => {const resp = await send();const text = await resp.text();if (!resp.ok) throw httpError(resp.status, text);return { status: resp.status, text };};+ const run = async (): Promise<SuccessBody> => {+ try {+ return await once();+ } catch (err) {+ if (!isRead || !this.shouldRetry(err)) throw err;+ // 100-300 ms, so a burst of reads that all hit one restart does not+ // come back in lockstep.+ await new Promise((resolve) => setTimeout(resolve, 100 + Math.random() * 200));+ return once();+ }+ };return this.limiter ? this.limiter.run(run) : run();};const body = this.memo && isSharedRead(path)diff --git a/ix-cli/src/client/factory.ts b/ix-cli/src/client/factory.tsindex eba50e22..d8c7a01e 100644--- a/ix-cli/src/client/factory.ts+++ b/ix-cli/src/client/factory.ts@@ -15,6 +15,26 @@ export interface CreateClientOptions {* first response and requests in flight are capped (`QUERY_CLIENT_OPTIONS`).*/query?: boolean;+ /**+ * No read deadline: the command's reads may rightly take longer (`stats` on+ * a large graph), or the client is not one command's (`@ix/pro`'s). A caller+ * that passes its own `deadlineSignal` (`map`, `ingest`) gets none either:+ * it has already chosen its bound.+ */+ longRunning?: boolean;+}++/** The default whole-command bound on reads; `IX_READ_DEADLINE_MS` overrides it, 0 turns it off. */+export const DEFAULT_READ_DEADLINE_MS = 60_000;++/** At most this many requests in flight per client, for every command. */+export const DEFAULT_MAX_IN_FLIGHT = 12;++export function readDeadlineMs(env: NodeJS.ProcessEnv = process.env): number {+ const raw = env.IX_READ_DEADLINE_MS?.trim();+ if (!raw) return DEFAULT_READ_DEADLINE_MS;+ const n = Number(raw);+ return Number.isFinite(n) && n >= 0 ? n : DEFAULT_READ_DEADLINE_MS;}/**@@ -31,6 +51,12 @@ export function createClient(opts: CreateClientOptions = {}): IxClient {// Under `ix mcp`, the tool call's own deadline as well: its timeout aborts// this client's requests instead of leaving them open (see run-signal.ts).combineSignals(opts.deadlineSignal, currentRunSignal()),- { ...(opts.query ? QUERY_CLIENT_OPTIONS : {}), ...(token ? { token } : {}) },+ {+ maxInFlight: DEFAULT_MAX_IN_FLIGHT,+ retryReads: true,+ readDeadlineMs: opts.longRunning || opts.deadlineSignal ? 0 : readDeadlineMs(),+ ...(opts.query ? QUERY_CLIENT_OPTIONS : {}),+ ...(token ? { token } : {}),+ },);}