Claude API のスケジュール運用で観察した tail latency と、リトライストームを抑えるガードレール設計

// retry.ts
type RetryConfig = {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
  jitterRatio: number; // 0.0 〜 1.0
};
 
const DEFAULT: RetryConfig = {
  maxAttempts: 3, // 4.6 回 → 3 回上限に絞る
  baseDelayMs: 1_000,
  maxDelayMs: 30_000,
  jitterRatio: 0.5,
};
 
export async function retryWithJitter<T>(
  fn: (attempt: number) => Promise<T>,
  cfg: Partial<RetryConfig> = {},
): Promise<T> {
  const c = { ...DEFAULT, ...cfg };
  let lastErr: unknown;
  for (let attempt = 1; attempt <= c.maxAttempts; attempt++) {
    try {
      return await fn(attempt);
    } catch (err) {
      lastErr = err;
      if (attempt === c.maxAttempts) break;
      if (!isRetryable(err)) break;
      const expo = Math.min(
        c.baseDelayMs * Math.pow(2, attempt - 1),
        c.maxDelayMs,
      );
      const jitter = expo * c.jitterRatio * Math.random();
      const wait = expo + jitter - (expo * c.jitterRatio) / 2;
      await sleep(wait);
    }
  }
  throw lastErr;
}
 
function isRetryable(err: unknown): boolean {
  if (!err || typeof err !== "object") return false;
  const status = (err as { status?: number }).status;
  return status === 429 || status === 529 || (status !== undefined && status >= 500);
}
 
const sleep = (ms: number) =>
  new Promise((resolve) => setTimeout(resolve, ms));

// budget.ts
type BudgetState = {
  windowStartMs: number;
  windowSizeMs: number;
  callCount: number;
  maxCalls: number;
};
 
const STATE: Map<string, BudgetState> = new Map();
 
export function tryConsume(
  key: string,
  maxCalls: number,
  windowSizeMs = 60_000,
): boolean {
  const now = Date.now();
  const s = STATE.get(key) ?? {
    windowStartMs: now,
    windowSizeMs,
    callCount: 0,
    maxCalls,
  };
  if (now - s.windowStartMs > s.windowSizeMs) {
    s.windowStartMs = now;
    s.callCount = 0;
  }
  if (s.callCount >= s.maxCalls) {
    STATE.set(key, s);
    return false;
  }
  s.callCount += 1;
  STATE.set(key, s);
  return true;
}
 
export async function withBudget<T>(
  key: string,
  maxCalls: number,
  fn: () => Promise<T>,
): Promise<T | null> {
  if (!tryConsume(key, maxCalls)) return null;
  return fn();
}

// breaker.ts
type BreakerState = {
  failures: number;
  successes: number;
  openedAt: number | null;
  cooldownMs: number;
  failureRatio: number; // 例: 0.5
  minSamples: number;   // 例: 10
};
 
const BREAKERS: Map<string, BreakerState> = new Map();
 
export function shouldAttempt(key: string): boolean {
  const b = BREAKERS.get(key);
  if (!b || b.openedAt === null) return true;
  if (Date.now() - b.openedAt > b.cooldownMs) {
    b.openedAt = null;
    b.failures = 0;
    b.successes = 0;
    return true;
  }
  return false;
}
 
export function recordResult(key: string, ok: boolean) {
  const b = BREAKERS.get(key) ?? {
    failures: 0,
    successes: 0,
    openedAt: null,
    cooldownMs: 60_000,
    failureRatio: 0.5,
    minSamples: 10,
  };
  if (ok) b.successes += 1;
  else b.failures += 1;
  const total = b.successes + b.failures;
  if (total >= b.minSamples && b.failures / total >= b.failureRatio) {
    b.openedAt = Date.now();
  }
  BREAKERS.set(key, b);
}