offrouter-core 0.2.0 → 0.2.2

package/src/usage-file.test.ts

@@ -1,243 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  DEFAULT_NEAR_LIMIT_THRESHOLD,
-  FileUsageStore,
-  InMemoryUsageStore,
-  type UsageStore,
-} from "./usage-file.js";
-
-const tempDirs: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(
-    tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
-  );
-},);
-
-async function makeTempDir(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), "offrouter-usage-file-"));
-  tempDirs.push(dir);
-  return dir;
-}
-
-async function makeFileStore(
-  filePath?: string,
-): Promise<{ dir: string; path: string; store: FileUsageStore }> {
-  const dir = await makeTempDir();
-  const path = filePath ?? join(dir, "state", "usage.json");
-  const store = new FileUsageStore({ filePath: path });
-  return { dir, path, store };
-}
-
-describe("FileUsageStore", () => {
-  it("satisfies the UsageStore interface contract", () => {
-    const store: UsageStore = new FileUsageStore({
-      filePath: "/tmp/offrouter-usage-store-interface.json",
-    });
-    expect(typeof store.recordUsage).toBe("function");
-    expect(typeof store.isNearLimit).toBe("function");
-    expect(typeof store.record).toBe("function");
-  });
-
-  it("persists account usage across store instances sharing the same file", async () => {
-    const { path, store } = await makeFileStore();
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 42,
-      limit: 100,
-    });
-
-    const reloaded = new FileUsageStore({ filePath: path });
-    const snap = await reloaded.getAccountUsage("anthropic", "anthropic-1");
-    expect(snap?.used).toBe(42);
-    expect(snap?.limit).toBe(100);
-    expect(snap?.remaining).toBe(58);
-
-    // A fresh instance also sees near-limit state.
-    expect(await reloaded.isNearLimit("anthropic", "anthropic-1")).toBe(false);
-  });
-
-  it("marks an account near-limit at 85% consumed (threshold 0.2)", async () => {
-    const { store } = await makeFileStore();
-    const snap = await store.recordUsage("anthropic", "anthropic-1", {
-      used: 85,
-      limit: 100,
-    });
-    expect(snap.remaining).toBe(15);
-    expect(snap.percentRemaining).toBe(15);
-    expect(snap.nearLimit).toBe(true);
-    expect(snap.subscriptionStatus).toBe("near-limit");
-    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
-  });
-
-  it("does not mark an account near-limit at 50% consumed", async () => {
-    const { store } = await makeFileStore();
-    const snap = await store.recordUsage("anthropic", "anthropic-1", {
-      used: 50,
-      limit: 100,
-    });
-    expect(snap.nearLimit).toBe(false);
-    expect(snap.subscriptionStatus).toBe("active");
-    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(false);
-  });
-
-  it("respects a custom near-limit threshold", async () => {
-    const { store } = await makeFileStore();
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 85,
-      limit: 100,
-    });
-    // 15% remaining: near-limit at 0.2 default, not at stricter 0.1.
-    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
-    expect(await store.isNearLimit("anthropic", "anthropic-1", 0.1)).toBe(false);
-  });
-
-  it("marks an account exhausted at 100% consumed with dead health", async () => {
-    const { store } = await makeFileStore();
-    const snap = await store.recordUsage("anthropic", "anthropic-1", {
-      used: 100,
-      limit: 100,
-    });
-    expect(snap.subscriptionStatus).toBe("exhausted");
-    expect(snap.nearLimit).toBe(false);
-    expect(snap.health).toBe("dead");
-  });
-
-  it("writes the usage file with mode 0600 on POSIX", async () => {
-    if (process.platform === "win32") {
-      return;
-    }
-    const { path, store } = await makeFileStore();
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 1,
-      limit: 100,
-    });
-
-    const info = await stat(path);
-    expect(info.mode & 0o777).toBe(0o600);
-  });
-
-  it("falls back to an empty state on a corrupt file instead of crashing", async () => {
-    const dir = await makeTempDir();
-    const path = join(dir, "state", "usage.json");
-    await mkdir(join(dir, "state"), { recursive: true });
-    await writeFile(path, "{not valid json at all", "utf8");
-
-    const store = new FileUsageStore({ filePath: path });
-    // Reads do not throw; state is empty.
-    const snap = await store.getAccountUsage("anthropic", "anthropic-1");
-    expect(snap).toBeUndefined();
-    expect(await store.listAccountUsage()).toEqual([]);
-
-    // A subsequent write replaces the corrupt file with a valid document.
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 90,
-      limit: 100,
-    });
-    const raw = JSON.parse(await readFile(path, "utf8")) as {
-      version: number;
-      accounts: Record<string, unknown>;
-    };
-    expect(raw.version).toBe(1);
-    expect(Object.keys(raw.accounts)).toEqual(["anthropic:anthropic-1"]);
-  });
-
-  it("concurrent writes from two stores on the same file do not corrupt it", async () => {
-    const dir = await makeTempDir();
-    const path = join(dir, "state", "usage.json");
-    const s1 = new FileUsageStore({ filePath: path });
-    const s2 = new FileUsageStore({ filePath: path });
-
-    await Promise.all([
-      s1.recordUsage("anthropic", "anthropic-1", { used: 80, limit: 100 }),
-      s2.recordUsage("openai", "openai-1", { used: 90, limit: 100 }),
-    ]);
-
-    // The file is always valid JSON with the expected schema.
-    const raw = JSON.parse(await readFile(path, "utf8")) as {
-      version: number;
-      accounts: Record<string, { providerId: string }>;
-    };
-    expect(raw.version).toBe(1);
-    // Last-writer-wins is acceptable; corruption (invalid JSON) is not.
-    for (const doc of Object.values(raw.accounts)) {
-      expect(typeof doc.providerId).toBe("string");
-    }
-  });
-
-  it("writes on every mutation so a new process sees the latest usage", async () => {
-    const { path, store } = await makeFileStore();
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 10,
-      limit: 100,
-    });
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 88,
-      limit: 100,
-    });
-
-    const reloaded = new FileUsageStore({ filePath: path });
-    const snap = await reloaded.getAccountUsage("anthropic", "anthropic-1");
-    expect(snap?.used).toBe(88);
-    expect(snap?.nearLimit).toBe(true);
-  });
-
-  it("delegates provider health/quota logic to an in-memory store", async () => {
-    const { store } = await makeFileStore();
-    await store.setSubscriptionQuota("claude", {
-      limit: 10,
-      used: 9,
-      status: "active",
-    });
-    const snap = await store.getProvider("claude");
-    expect(snap?.subscriptionQuotaRemaining).toBe(1);
-    expect(snap?.health).toBe("healthy");
-  });
-
-  it("returns near-limit accounts across the persisted set", async () => {
-    const { store } = await makeFileStore();
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 85,
-      limit: 100,
-    });
-    await store.recordUsage("anthropic", "anthropic-2", {
-      used: 10,
-      limit: 100,
-    });
-    const near = await store.getNearLimitAccounts();
-    expect(near).toHaveLength(1);
-    expect(near[0]?.accountId).toBe("anthropic-1");
-  });
-
-  it("toJSON exposes diagnostics without throwing", async () => {
-    const { store } = await makeFileStore();
-    await store.recordUsage("anthropic", "anthropic-1", {
-      used: 85,
-      limit: 100,
-    });
-    const json = store.toJSON();
-    expect(json).toMatchObject({ kind: "file-usage" });
-    expect(JSON.stringify(json)).not.toContain("anthropic-1");
-  });
-
-  it("uses the default near-limit threshold constant", () => {
-    expect(DEFAULT_NEAR_LIMIT_THRESHOLD).toBe(0.2);
-  });
-
-  it("accepts an injected in-memory delegate for provider state", async () => {
-    const dir = await makeTempDir();
-    const path = join(dir, "state", "usage.json");
-    const delegate = new InMemoryUsageStore();
-    const wired = new FileUsageStore({ filePath: path, delegate });
-    await wired.setSubscriptionQuota("claude", {
-      limit: 5,
-      used: 1,
-      status: "active",
-    });
-    // Provider state lives on the injected delegate.
-    const snap = await delegate.getProvider("claude");
-    expect(snap?.subscriptionQuotaRemaining).toBe(4);
-  });
-});

package/src/usage-file.ts

@@ -1,435 +0,0 @@
-/**
- * File-backed usage store for OffRouter.
- *
- * Wraps an in-memory provider-health/quota engine and adds JSON persistence for
- * per-account quota usage so near-limit detection survives across CLI
- * invocations and MCP server restarts.
- *
- * On-disk layout (`$OFFROUTER_HOME/state/usage.json`):
- *   { version: 1, accounts: Record<`${providerId}:${accountId}`, PersistedAccount> }
- *
- * Safety guarantees mirror FileSecretStore:
- *   - atomic write via temp file + rename
- *   - chmod 0600 on POSIX after every write
- *   - missing or corrupt file => graceful fallback to empty state (never throws)
- *
- * Provider health/quota math (sliding-window error budget, cooldown) stays
- * in-memory and process-local; only account quota usage is persisted, which is
- * what near-limit detection and quota reporting depend on across sessions.
- */
-import { readFileSync } from "node:fs";
-import {
-  chmod,
-  mkdir,
-  readFile,
-  rename,
-  unlink,
-  writeFile,
-} from "node:fs/promises";
-import { dirname } from "node:path";
-import { randomBytes } from "node:crypto";
-import {
-  computeAccountSnapshot,
-  InMemoryUsageStore,
-  type AccountUsageDoc,
-  type AccountUsageSnapshot,
-  type PaidFallbackExplanation,
-  type ProviderUsageSnapshot,
-  type RecordUsageResult,
-  type UsageEvent,
-  type UsageStore,
-} from "./usage.js";
-import type { ProviderHealth } from "./types.js";
-
-export { DEFAULT_NEAR_LIMIT_THRESHOLD } from "./usage.js";
-export { InMemoryUsageStore } from "./usage.js";
-export type { UsageStore } from "./usage.js";
-
-export interface FileUsageStoreFileSystem {
-  mkdir: typeof mkdir;
-  readFile: typeof readFile;
-  rename: typeof rename;
-  unlink: typeof unlink;
-  writeFile: typeof writeFile;
-  chmod: typeof chmod;
-}
-
-export interface FileUsageStoreOptions {
-  /** Absolute path to usage.json (typically `$OFFROUTER_HOME/state/usage.json`). */
-  filePath: string;
-  /** Injectable file operations for failure-path tests. Defaults to node fs. */
-  fileSystem?: Partial<FileUsageStoreFileSystem>;
-  /** Injectable clock for tests. */
-  now?: () => Date;
-  /**
-   * In-memory store that owns provider health/quota logic. Account usage is
-   * persisted separately and mirrored onto this delegate. Useful for tests.
-   */
-  delegate?: UsageStore;
-}
-
-/** On-disk schema for FileUsageStore. */
-interface PersistedAccount {
-  providerId: string;
-  accountId: string;
-  used: number;
-  limit?: number;
-  lastUpdated: string;
-  health?: ProviderHealth;
-  cooldownUntil?: number;
-  recentErrors?: number[];
-}
-
-interface PersistedUsageDocument {
-  version: 1;
-  accounts: Record<string, PersistedAccount>;
-}
-
-const EMPTY_DOC: PersistedUsageDocument = { version: 1, accounts: {} };
-
-function accountKey(providerId: string, accountId: string): string {
-  return `${providerId}:${accountId}`;
-}
-
-/**
- * Parse a persisted usage document leniently. A missing or corrupt file is
- * treated as empty state rather than a hard failure so a bad write can never
- * wedge the CLI.
- */
-function parseUsageDocument(raw: string): PersistedUsageDocument {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw) as unknown;
-  } catch {
-    // Corrupt JSON: fall back to empty instead of throwing.
-    return { ...EMPTY_DOC, accounts: {} };
-  }
-
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return { ...EMPTY_DOC, accounts: {} };
-  }
-
-  const record = parsed as Record<string, unknown>;
-  const accountsRaw = record.accounts;
-  if (
-    typeof accountsRaw !== "object" ||
-    accountsRaw === null ||
-    Array.isArray(accountsRaw)
-  ) {
-    return { ...EMPTY_DOC, accounts: {} };
-  }
-
-  const accounts: Record<string, PersistedAccount> = {};
-  for (const [key, value] of Object.entries(
-    accountsRaw as Record<string, unknown>,
-  )) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      continue;
-    }
-    const entry = value as Record<string, unknown>;
-    if (
-      typeof entry.providerId !== "string" ||
-      typeof entry.accountId !== "string" ||
-      typeof entry.used !== "number"
-    ) {
-      continue;
-    }
-    const doc: PersistedAccount = {
-      providerId: entry.providerId,
-      accountId: entry.accountId,
-      used: entry.used,
-      lastUpdated:
-        typeof entry.lastUpdated === "string" ? entry.lastUpdated : "",
-    };
-    if (typeof entry.limit === "number") {
-      doc.limit = entry.limit;
-    }
-    accounts[key] = doc;
-  }
-
-  return { version: 1, accounts };
-}
-
-/**
- * File-backed UsageStore. Persists per-account quota usage atomically and
- * delegates provider health/quota logic to an in-memory engine.
- */
-export class FileUsageStore implements UsageStore {
-  readonly filePath: string;
-  readonly #fs: FileUsageStoreFileSystem;
-  readonly #now: () => Date;
-  readonly #delegate: UsageStore;
-  /** In-memory mirror of persisted account docs, hydrated lazily. */
-  #accounts: Map<string, AccountUsageDoc> | null = null;
-  /** Serializes mutations so concurrent writes never interleave. */
-  #chain: Promise<unknown> = Promise.resolve();
-
-  constructor(options: FileUsageStoreOptions) {
-    if (!options?.filePath || typeof options.filePath !== "string") {
-      throw new TypeError("FileUsageStore requires options.filePath");
-    }
-    this.filePath = options.filePath;
-    this.#now = options.now ?? (() => new Date());
-    this.#delegate =
-      options.delegate ?? new InMemoryUsageStore({ now: this.#now });
-    this.#fs = {
-      mkdir,
-      readFile,
-      rename,
-      unlink,
-      writeFile,
-      chmod,
-      ...options.fileSystem,
-    };
-  }
-
-  #exclusive<T>(fn: () => T | Promise<T>): Promise<T> {
-    const run = this.#chain.then(fn, fn);
-    this.#chain = run.then(
-      () => undefined,
-      () => undefined,
-    );
-    return run;
-  }
-
-  /** Load the file once into the in-memory account map. Never throws. */
-  async #load(): Promise<Map<string, AccountUsageDoc>> {
-    if (this.#accounts) {
-      return this.#accounts;
-    }
-    let doc: PersistedUsageDocument;
-    try {
-      const raw = await this.#fs.readFile(this.filePath, "utf8");
-      doc = parseUsageDocument(raw);
-    } catch (err) {
-      if (
-        err &&
-        typeof err === "object" &&
-        "code" in err &&
-        (err as { code?: string }).code === "ENOENT"
-      ) {
-        doc = { ...EMPTY_DOC, accounts: {} };
-      } else {
-        // Any read failure (including corruption surfaced as a throw) is
-        // treated as empty state so the CLI keeps working.
-        doc = { ...EMPTY_DOC, accounts: {} };
-      }
-    }
-    const map = new Map<string, AccountUsageDoc>();
-    for (const [key, entry] of Object.entries(doc.accounts)) {
-      map.set(key, {
-        providerId: entry.providerId,
-        accountId: entry.accountId,
-        used: entry.used,
-        limit: entry.limit,
-        updatedAt: entry.lastUpdated,
-      });
-    }
-    this.#accounts = map;
-    return map;
-  }
-
-  /** Synchronous load for toJSON diagnostics; never throws. */
-  #loadKnownSync(): Map<string, AccountUsageDoc> {
-    if (this.#accounts) {
-      return this.#accounts;
-    }
-    let map = new Map<string, AccountUsageDoc>();
-    try {
-      const raw = readFileSync(this.filePath, "utf8");
-      const doc = parseUsageDocument(raw);
-      map = new Map();
-      for (const [key, entry] of Object.entries(doc.accounts)) {
-        map.set(key, {
-          providerId: entry.providerId,
-          accountId: entry.accountId,
-          used: entry.used,
-          limit: entry.limit,
-          updatedAt: entry.lastUpdated,
-        });
-      }
-    } catch {
-      map = new Map();
-    }
-    return map;
-  }
-
-  async #persist(accounts: Map<string, AccountUsageDoc>): Promise<void> {
-    const persistedAccounts: Record<string, PersistedAccount> = {};
-    for (const [key, doc] of accounts) {
-      const snap = computeAccountSnapshot(doc);
-      const entry: PersistedAccount = {
-        providerId: doc.providerId,
-        accountId: doc.accountId,
-        used: doc.used,
-        lastUpdated: doc.updatedAt,
-        health: snap.health,
-        recentErrors: [],
-      };
-      if (doc.limit !== undefined) {
-        entry.limit = doc.limit;
-      }
-      persistedAccounts[key] = entry;
-    }
-    const payload = `${JSON.stringify(
-      { version: 1 as const, accounts: persistedAccounts },
-      null,
-      2,
-    )}\n`;
-
-    await this.#fs.mkdir(dirname(this.filePath), { recursive: true });
-    const tmp = `${this.filePath}.${randomBytes(8).toString("hex")}.tmp`;
-    try {
-      await this.#fs.writeFile(tmp, payload, {
-        encoding: "utf8",
-        mode: 0o600,
-      });
-      await this.#fs.chmod(tmp, 0o600);
-      await this.#fs.rename(tmp, this.filePath);
-      await this.#fs.chmod(this.filePath, 0o600);
-    } catch (err) {
-      await this.#fs.unlink(tmp).catch((unlinkErr: unknown) => {
-        if (
-          unlinkErr &&
-          typeof unlinkErr === "object" &&
-          "code" in unlinkErr &&
-          (unlinkErr as { code?: string }).code === "ENOENT"
-        ) {
-          return;
-        }
-        throw unlinkErr;
-      });
-      throw err;
-    }
-  }
-
-  // ---- Provider health/quota: delegated to the in-memory engine ----
-
-  record(event: UsageEvent): Promise<RecordUsageResult> {
-    return this.#delegate.record(event);
-  }
-
-  getProvider(providerId: string): Promise<ProviderUsageSnapshot | undefined> {
-    return this.#delegate.getProvider(providerId);
-  }
-
-  listProviders(): Promise<ProviderUsageSnapshot[]> {
-    return this.#delegate.listProviders();
-  }
-
-  setSubscriptionQuota(
-    providerId: string,
-    input: {
-      limit?: number;
-      used?: number;
-      status?: import("./types.js").SubscriptionStatus;
-      modelId?: string;
-      at?: Date;
-    },
-  ): Promise<ProviderUsageSnapshot> {
-    return this.#delegate.setSubscriptionQuota(providerId, input);
-  }
-
-  explainPaidFallback(
-    providerId: string,
-    options?: { hasApiKeyCandidate?: boolean },
-  ): Promise<PaidFallbackExplanation> {
-    return this.#delegate.explainPaidFallback(providerId, options);
-  }
-
-  // ---- Per-account quota usage: persisted ----
-
-  async recordUsage(
-    providerId: string,
-    accountId: string,
-    input: { used?: number; limit?: number; at?: Date },
-  ): Promise<AccountUsageSnapshot> {
-    return this.#exclusive(async () => {
-      const accounts = await this.#load();
-      const at = input.at ?? this.#now();
-      const key = accountKey(providerId, accountId);
-      let doc = accounts.get(key);
-      if (!doc) {
-        doc = {
-          providerId,
-          accountId,
-          used: 0,
-          updatedAt: at.toISOString(),
-        };
-        accounts.set(key, doc);
-      }
-      if (input.used !== undefined) doc.used = input.used;
-      if (input.limit !== undefined) doc.limit = input.limit;
-      doc.updatedAt = at.toISOString();
-      await this.#persist(accounts);
-      return computeAccountSnapshot(doc);
-    });
-  }
-
-  async isNearLimit(
-    providerId: string,
-    accountId: string,
-    threshold?: number,
-  ): Promise<boolean> {
-    return this.#exclusive(async () => {
-      const accounts = await this.#load();
-      const doc = accounts.get(accountKey(providerId, accountId));
-      if (!doc) return false;
-      return computeAccountSnapshot(doc, threshold).nearLimit;
-    });
-  }
-
-  async getNearLimitAccounts(
-    threshold?: number,
-  ): Promise<AccountUsageSnapshot[]> {
-    return this.#exclusive(async () => {
-      const accounts = await this.#load();
-      const out: AccountUsageSnapshot[] = [];
-      for (const doc of accounts.values()) {
-        const snap = computeAccountSnapshot(doc, threshold);
-        if (snap.nearLimit) out.push(snap);
-      }
-      return out.sort((a, b) => {
-        if (a.providerId !== b.providerId)
-          return a.providerId.localeCompare(b.providerId);
-        return a.accountId.localeCompare(b.accountId);
-      });
-    });
-  }
-
-  async getAccountUsage(
-    providerId: string,
-    accountId: string,
-  ): Promise<AccountUsageSnapshot | undefined> {
-    return this.#exclusive(async () => {
-      const accounts = await this.#load();
-      const doc = accounts.get(accountKey(providerId, accountId));
-      if (!doc) return undefined;
-      return computeAccountSnapshot(doc);
-    });
-  }
-
-  async listAccountUsage(): Promise<AccountUsageSnapshot[]> {
-    return this.#exclusive(async () => {
-      const accounts = await this.#load();
-      const out: AccountUsageSnapshot[] = [];
-      for (const doc of accounts.values()) {
-        out.push(computeAccountSnapshot(doc));
-      }
-      return out.sort((a, b) => {
-        if (a.providerId !== b.providerId)
-          return a.providerId.localeCompare(b.providerId);
-        return a.accountId.localeCompare(b.accountId);
-      });
-    });
-  }
-
-  toJSON(): Record<string, unknown> {
-    const accounts = this.#loadKnownSync();
-    return {
-      kind: "file-usage",
-      filePath: this.filePath,
-      accountCount: accounts.size,
-    };
-  }
-}