Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

9.1 KB
Raw Blame
/**
 * Deferred retry for usage writes blocked by a locked database.
 *
 * The hot-path writers here are best-effort: the database caps a contended
 * write at 2 s (`busy_timeout = 2000` in `src/lib/db/core.ts`) so a busy disk
 * cannot freeze the event loop. When a write still meets a lock, the first
 * failure is swallowed silently and the entry is attempted once more after a
 * short delay, off the request path (`setTimeout`, never awaited). If the
 * second attempt fails the existing log line is written and the row is
 * dropped. Any other error keeps the current behaviour: logged at once,
 * never retried. If the server stops during the wait the row is lost as
 * before, on a best-effort basis (the timer never keeps the loop alive).
 *
 * @module lib/usage/usageWriteRetry
 */

import { getDbInstance } from "../db/core";
import { resolveProviderId } from "@/shared/constants/providers";
import {
  resolveOrphanedUsageAccountIdentity,
  resolveUsageAccountIdentity,
} from "./accountIdentity";
import { normalizeServiceTier } from "./usageHistory/helpers";
import { readReportedCost } from "./creditMeteredProviders";
import { emitUsageRecorded } from "./usageEvents";
import {
  getLoggedInputTokens,
  getLoggedOutputTokens,
  getPromptCacheCreationTokens,
  getPromptCacheReadTokens,
  getReasoningTokens,
} from "./tokenAccounting";
import { backfillDuplicateUsageEntry } from "./usageHistory/duplicateEntry";
import type { UsageEntry } from "./usageHistory";

/** Delay before the single deferred attempt. Internal, not user-facing. */
const RETRY_DELAY_MS = 1000;

/**
 * True when the error is a database lock, in any shape the supported drivers
 * report it. Restricted to locks: only a lock is expected to clear within the
 * retry delay. Lock classification mirrors the lock subset of the probe
 * classifier and the busy checker (drivers report plain "database is locked"
 * while better-sqlite3 carries the name in `code` and node:sqlite the numeric
 * primary code in `errcode`, extended codes in the high bits).
 */
export function isWriteLockError(error: unknown): boolean {
  const details = error as { code?: unknown; errcode?: unknown; message?: unknown } | null;
  const code = details?.code ?? details?.errcode;
  if (typeof code === "string" && isLockCodeName(code)) return true;
  if (typeof code === "number" && isLockCodeNumber(code)) return true;
  const message = error instanceof Error ? error.message : String(details?.message ?? error);
  return isLockMessage(message);
}

function isLockCodeName(code: string): boolean {
  return /^SQLITE_(BUSY|LOCKED)/.test(code);
}

function isLockCodeNumber(code: number): boolean {
  const primary = code & 0xff;
  return primary === 5 || primary === 6;
}

function isLockMessage(message: string): boolean {
  return /database(?: table| schema)? is (?:locked|busy)|SQLITE_BUSY|SQLITE_LOCKED/i.test(message);
}

/** Legacy natural-key dedup stays on unless the caller owns a physical attempt. */
type UsageWriteOptions = {
  deduplicate?: boolean;
};

/**
 * Single write attempt. Throws on failure so the caller decides between a
 * deferred retry (lock) and an immediate log (anything else).
 *
 * `deduplicate: false` is the image-attempt opt-out: two real upstream calls
 * can share every natural-key field, including the millisecond timestamp.
 */
export function attemptWrite(entry: UsageEntry, options: UsageWriteOptions = {}): void {
  const db = getDbInstance();
  const prepared = prepareEntry(db, entry);
  let inserted = false;
  const deduplicate = options.deduplicate !== false;

  db.transaction(() => {
    if (!deduplicate) {
      insertEntry(db, prepared);
      inserted = true;
      return;
    }
    inserted = insertUnlessDuplicate(db, prepared);
  })();

  // Decoupled via the event bus so usageHistory never imports providerLimits
  // (which would pull the executors/translator graph into the type-check surface).
  // Only emit when a row was actually inserted — not on dedup no-ops.
  if (inserted) {
    emitUsageRecorded(entry.provider, entry.connectionId);
  }
}

type PreparedEntry = {
  entry: UsageEntry;
  timestamp: string;
  serviceTier: string;
  tokensInput: number;
  tokensOutput: number;
  accountIdentity: {
    accountKey: string | null;
    accountLabel: string | null;
    accountLabelPriority: number;
  };
};

function prepareEntry(db: ReturnType<typeof getDbInstance>, entry: UsageEntry): PreparedEntry {
  const timestamp = entry.timestamp || new Date().toISOString();
  const connection = entry.connectionId
    ? (db.prepare("SELECT * FROM provider_connections WHERE id = ?").get(entry.connectionId) as
        Record<string, unknown> | undefined)
    : undefined;
  return {
    entry,
    timestamp,
    serviceTier: normalizeServiceTier(entry.serviceTier ?? entry.service_tier),
    tokensInput: getLoggedInputTokens(entry.tokens),
    tokensOutput: getLoggedOutputTokens(entry.tokens),
    accountIdentity: connection
      ? resolveUsageAccountIdentity(connection)
      : resolveOrphanedUsageAccountIdentity(entry.provider, entry.connectionId),
  };
}

// Dedup guard: skip INSERT when an identical row already exists in the same
// second. This prevents double-counting when onRequestSuccess fires more
// than once (e.g. combo routing calling the callback from both the
// streaming and non-streaming paths for the same underlying request).
// Keyed on the natural identity of a request: timestamp + provider + model
// + connectionId + apiKeyId + token counts. If only the endpoint is missing
// on the existing row, fill it in rather than inserting a duplicate.
function insertUnlessDuplicate(
  db: ReturnType<typeof getDbInstance>,
  prepared: PreparedEntry
): boolean {
  const { entry, timestamp, tokensInput, tokensOutput } = prepared;
  if (backfillDuplicateUsageEntry(db, entry, timestamp, tokensInput, tokensOutput)) {
    return false;
  }

  insertEntry(db, prepared);
  return true;
}

function insertEntry(db: ReturnType<typeof getDbInstance>, prepared: PreparedEntry): void {
  const { entry, timestamp, serviceTier, tokensInput, tokensOutput, accountIdentity } = prepared;
  const { providerCredits, providerCostUsd } = readReportedCost(entry.provider, entry.tokens);
  db.prepare(
    `
    INSERT INTO usage_history (provider, model, connection_id, account_key, account_label,
      account_label_priority, api_key_id, api_key_name, tokens_input, tokens_output,
      tokens_cache_read, tokens_cache_creation, tokens_reasoning, service_tier, status, success,
      latency_ms, ttft_ms, error_code, combo_strategy, endpoint, cpa_auth_index, timestamp,
      provider_credits, provider_cost_usd)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
  `
  ).run(
    entry.provider ? resolveProviderId(entry.provider) : null,
    entry.model || null,
    entry.connectionId || null,
    accountIdentity.accountKey,
    accountIdentity.accountLabel,
    accountIdentity.accountLabelPriority,
    entry.apiKeyId || null,
    entry.apiKeyName || null,
    tokensInput,
    tokensOutput,
    getPromptCacheReadTokens(entry.tokens),
    getPromptCacheCreationTokens(entry.tokens),
    getReasoningTokens(entry.tokens),
    serviceTier,
    entry.status || null,
    entry.success === false ? 0 : 1,
    toFinite(entry.latencyMs),
    toFirstToken(entry),
    entry.errorCode || null,
    entry.comboStrategy || entry.combo_strategy || null,
    entry.endpoint || null,
    entry.cpaAuthIndex || null,
    timestamp,
    providerCredits,
    providerCostUsd
  );
}

function toFinite(value: unknown): number {
  return Number.isFinite(Number(value)) ? Number(value) : 0;
}

function toFirstToken(entry: UsageEntry): number {
  if (Number.isFinite(Number(entry.timeToFirstTokenMs))) return Number(entry.timeToFirstTokenMs);
  return toFinite(entry.latencyMs);
}

/**
 * Schedule the single deferred retry, off the request path. Never chained:
 * the retry attempts the write once and, on failure, writes the existing log
 * line and stops.
 */
export function scheduleWriteRetry(
  task: () => void,
  onFinalFailure: (error: unknown) => void
): Promise<void>;
export function scheduleWriteRetry(entry: UsageEntry, options?: UsageWriteOptions): void;
export function scheduleWriteRetry(
  taskOrEntry: (() => void) | UsageEntry,
  optionsOrFailure?: UsageWriteOptions | ((error: unknown) => void)
): Promise<void> | void {
  if (typeof taskOrEntry !== "function") {
    const entry = taskOrEntry;
    void scheduleWriteRetry(
      () => attemptWrite(entry, typeof optionsOrFailure === "object" ? optionsOrFailure : {}),
      (retryError) => console.error("Failed to save usage stats:", retryError)
    );
    return;
  }
  const task = taskOrEntry;
  const fail = typeof optionsOrFailure === "function" ? optionsOrFailure : () => {};
  return new Promise<void>((resolve) => {
    const timer = setTimeout(() => {
      try {
        task();
      } catch (retryError) {
        fail(retryError);
      } finally {
        resolve();
      }
    }, RETRY_DELAY_MS);
    // Allow Node.js to exit naturally even if the timer is still pending
    // (avoids keeping the event loop alive for a stray retry).
    detachTimer(timer);
  });
}

type DetachableTimer = { unref?: () => void };

function detachTimer(timer: DetachableTimer): void {
  timer.unref?.();
}