Retries

HTTP client

BrainHttpClient retries only the idempotent verbs — encode, whoami, capabilities — and only when the failure is a transport error (status === 0) or an HTTP 503. Every other status, including all 4xx, is terminal. Backoff grows exponentially from baseDelayMs, capped at maxDelayMs; a server Retry-After header overrides the schedule.

interface HttpRetryPolicy {
  maxAttempts: number; // total attempts including the first; 1 disables retry
  baseDelayMs: number; // first backoff; doubles each attempt
  maxDelayMs: number;  // cap on any single backoff (also caps Retry-After)
}

Configure it at construction:

import { BrainHttpClient, DEFAULT_HTTP_RETRY, NO_HTTP_RETRY } from "@brain-db/sdk";

// DEFAULT_HTTP_RETRY = { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2000 }
const brain = new BrainHttpClient({
  apiKey: process.env.BRAIN_API_KEY!,
  retry: { maxAttempts: 5 }, // merged over the default
});

// Opt out entirely:
const once = new BrainHttpClient({ apiKey: "…", retry: NO_HTTP_RETRY });

Wire client — withRetry

The wire client does not bake retry into each verb. Wrap a call in withRetry and it re-runs while the error is retryable (isRetryable) and attempts remain. Because each request builder mints a stable requestId, re-sending the same request is idempotent server-side (24h idempotency window), so a retried verb does not double-apply.

import { withRetry, DEFAULT_RETRY_POLICY, NO_RETRY } from "@brain-db/sdk";

// DEFAULT_RETRY_POLICY = { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 5000 }
const req = new ForgetBuilder(memoryId).build(); // build once → stable requestId
const res = await withRetry(() => client.forget(req), DEFAULT_RETRY_POLICY);

The backoff honors a server-supplied retryAfterMs when present, otherwise grows exponentially from baseDelayMs (capped at maxDelayMs), then applies full jitter so a herd of clients that failed together don't retry in lockstep.

Cancellation and deadlines

Neither client takes an external AbortSignal; a call is bounded by its configured deadline instead.

const brain = new BrainHttpClient({ apiKey: "…", timeoutMs: 5_000 });

const client = await BrainClient.connect("127.0.0.1", 9090, {
  auth: { kind: "token", token: tokenBytes },
  requestTimeoutMs: 5_000,
});