@openlimiter/core 0.4.0 → 1.3.1

package/dist/acquire/cadence.d.ts

@@ -0,0 +1,74 @@
+import type { AcquisitionOutcome } from "./transport.js";
+/** The ordinary interval between two reads of one provider. */
+export declare const ACQUISITION_INTERVAL_SECONDS = 900;
+/** How long a rate limited provider is left alone. */
+export declare const ACQUISITION_RATE_LIMIT_BACKOFF_SECONDS = 3600;
+/** How long a provider that refused this client outright is left alone. */
+export declare const ACQUISITION_BLOCKED_BACKOFF_SECONDS = 86400;
+/**
+ * How long a desktop write keeps the command line tool from polling.
+ *
+ * The same fifteen minutes as one poll interval, because that is exactly the
+ * claim being made: a desktop that wrote inside the last interval is the
+ * refresher on this machine, and a second poll would only duplicate its work.
+ */
+export declare const DESKTOP_OWNERSHIP_SECONDS = 900;
+/** File the per provider schedule is kept in, beside the cache. */
+export declare const ACQUISITION_STATE_FILE_NAME = "openlimiter-acquisition.json";
+/** Document version of the schedule file. */
+export declare const ACQUISITION_STATE_VERSION = 1;
+export interface AcquisitionProviderSchedule {
+    /** When the last attempt was made. */
+    readonly lastAttemptAt: string;
+    /** The earliest instant the next attempt may be made. */
+    readonly nextAttemptAt: string;
+    /** What the last attempt achieved. */
+    readonly outcome: AcquisitionOutcome;
+}
+export type AcquisitionSchedule = Readonly<Record<string, AcquisitionProviderSchedule>>;
+/**
+ * How long to wait after an attempt with this outcome.
+ *
+ * A provider that told us to go away is obeyed and then some: its Retry-After
+ * is a floor under our own backoff, never a replacement for it, so a header
+ * asking for less than our interval cannot talk us into polling sooner.
+ */
+export declare function backoffSecondsFor(outcome: AcquisitionOutcome, retryAfterSeconds?: number | null): number;
+/** The instant an attempt with this outcome earns, or null on an unread clock. */
+export declare function nextAttemptInstant(outcome: AcquisitionOutcome, now: string, retryAfterSeconds?: number | null): string | null;
+/**
+ * Whether a provider may be read now.
+ *
+ * No schedule at all is due, which is what makes a first run work. A schedule
+ * this build cannot read is also due, because the alternative is a provider
+ * that never refreshes again on the strength of one unreadable value, and the
+ * first successful attempt replaces it with a readable one.
+ */
+export declare function isProviderDue(schedule: AcquisitionProviderSchedule | undefined, now: string): boolean;
+/** Providers a schedule document may name, bounded so a file cannot grow forever. */
+export declare const MAX_SCHEDULE_ENTRIES = 32;
+/**
+ * Read the schedule file.
+ *
+ * Every failure is an empty schedule rather than an exception: a schedule this
+ * build cannot read means every provider is due, which is the same place a
+ * fresh machine starts from and is never worse than not refreshing at all.
+ */
+export declare function readAcquisitionSchedule(directory?: string): Promise<AcquisitionSchedule>;
+/**
+ * Replace the schedule file.
+ *
+ * Written atomically like every other state document, so a status line reading
+ * it while a refresh writes it sees one version or the other and never half of
+ * one. It carries no credential, no address and no response, only three fields
+ * per provider.
+ */
+export declare function writeAcquisitionSchedule(schedule: AcquisitionSchedule, directory?: string): Promise<void>;
+/**
+ * One sentence per outcome, for the row a person reads.
+ *
+ * The backoff instant is rendered beside it by the caller; these sentences say
+ * what happened, in words that do not need the reader to know HTTP.
+ */
+export declare const ACQUISITION_OUTCOME_SENTENCE: Readonly<Record<AcquisitionOutcome, string>>;
+//# sourceMappingURL=cadence.d.ts.map

package/dist/acquire/cadence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.d.ts","sourceRoot":"","sources":["../../src/acquire/cadence.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,+DAA+D;AAC/D,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,sDAAsD;AACtD,eAAO,MAAM,sCAAsC,OAAQ,CAAC;AAE5D,2EAA2E;AAC3E,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,iCAAiC,CAAC;AAE1E,6CAA6C;AAC7C,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,MAAM,WAAW,2BAA2B;IAC1C,sCAAsC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,iBAAiB,GAAE,MAAM,GAAG,IAAW,GACtC,MAAM,CAgBR;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,MAAM,EACX,iBAAiB,GAAE,MAAM,GAAG,IAAW,GACtC,MAAM,GAAG,IAAI,CAOf;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,2BAA2B,GAAG,SAAS,EACjD,GAAG,EAAE,MAAM,GACV,OAAO,CAOT;AAwBD,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,SAA0B,GAClC,OAAO,CAAC,mBAAmB,CAAC,CA0B9B;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,SAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EACvC,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAU5C,CAAC"}

package/dist/acquire/cadence.js

@@ -0,0 +1,171 @@
+/**
+ * How often a terminal may ask a provider anything, and how long it stays away
+ * after being told to.
+ *
+ * The numbers are the desktop's, deliberately: two clients on one machine that
+ * disagree about cadence are two clients that between them poll twice as often
+ * as either intended, and the provider only sees the total. Mirrors
+ * `apps/desktop/src-tauri/src/claude_oauth.rs` lines 20 to 23.
+ *
+ * The arithmetic here is pure. The caller supplies the clock, so a whole
+ * backoff history replays to the same instants on every machine.
+ */
+import path from "node:path";
+import { MAX_JSON_FILE_BYTES, readJsonFileSafely, resolveStateDirectory, writeFileAtomically } from "../cache.js";
+import { canonicalJson } from "../normalizer.js";
+/** The ordinary interval between two reads of one provider. */
+export const ACQUISITION_INTERVAL_SECONDS = 900;
+/** How long a rate limited provider is left alone. */
+export const ACQUISITION_RATE_LIMIT_BACKOFF_SECONDS = 3_600;
+/** How long a provider that refused this client outright is left alone. */
+export const ACQUISITION_BLOCKED_BACKOFF_SECONDS = 86_400;
+/**
+ * How long a desktop write keeps the command line tool from polling.
+ *
+ * The same fifteen minutes as one poll interval, because that is exactly the
+ * claim being made: a desktop that wrote inside the last interval is the
+ * refresher on this machine, and a second poll would only duplicate its work.
+ */
+export const DESKTOP_OWNERSHIP_SECONDS = 900;
+/** File the per provider schedule is kept in, beside the cache. */
+export const ACQUISITION_STATE_FILE_NAME = "openlimiter-acquisition.json";
+/** Document version of the schedule file. */
+export const ACQUISITION_STATE_VERSION = 1;
+/**
+ * How long to wait after an attempt with this outcome.
+ *
+ * A provider that told us to go away is obeyed and then some: its Retry-After
+ * is a floor under our own backoff, never a replacement for it, so a header
+ * asking for less than our interval cannot talk us into polling sooner.
+ */
+export function backoffSecondsFor(outcome, retryAfterSeconds = null) {
+    /* A provider that serves a field only to its own tools will answer the same
+       way in fifteen minutes, so that outcome waits a day like a refusal does.
+       Retrying it on the ordinary interval would be ninety six pointless requests
+       a day against an answer that cannot change until we change. */
+    const base = outcome === "rate_limited"
+        ? ACQUISITION_RATE_LIMIT_BACKOFF_SECONDS
+        : outcome === "blocked" || outcome === "identity_refused"
+            ? ACQUISITION_BLOCKED_BACKOFF_SECONDS
+            : ACQUISITION_INTERVAL_SECONDS;
+    if (retryAfterSeconds === null ||
+        !Number.isFinite(retryAfterSeconds) ||
+        retryAfterSeconds <= 0)
+        return base;
+    return Math.max(base, Math.min(retryAfterSeconds, ACQUISITION_BLOCKED_BACKOFF_SECONDS));
+}
+/** The instant an attempt with this outcome earns, or null on an unread clock. */
+export function nextAttemptInstant(outcome, now, retryAfterSeconds = null) {
+    const current = Date.parse(now);
+    if (!Number.isFinite(current))
+        return null;
+    const instant = new Date(current + backoffSecondsFor(outcome, retryAfterSeconds) * 1_000);
+    return Number.isFinite(instant.getTime()) ? instant.toISOString() : null;
+}
+/**
+ * Whether a provider may be read now.
+ *
+ * No schedule at all is due, which is what makes a first run work. A schedule
+ * this build cannot read is also due, because the alternative is a provider
+ * that never refreshes again on the strength of one unreadable value, and the
+ * first successful attempt replaces it with a readable one.
+ */
+export function isProviderDue(schedule, now) {
+    const current = Date.parse(now);
+    if (!Number.isFinite(current))
+        return false;
+    if (schedule === undefined)
+        return true;
+    const next = Date.parse(schedule.nextAttemptAt);
+    if (!Number.isFinite(next))
+        return true;
+    return current >= next;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isIsoInstant(value) {
+    if (typeof value !== "string")
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+const outcomeNames = new Set([
+    "ok",
+    "unauthorized",
+    "rate_limited",
+    "blocked",
+    "remote_error",
+    "transport",
+    "too_large",
+    "drift",
+    "identity_refused"
+]);
+/** Providers a schedule document may name, bounded so a file cannot grow forever. */
+export const MAX_SCHEDULE_ENTRIES = 32;
+/**
+ * Read the schedule file.
+ *
+ * Every failure is an empty schedule rather than an exception: a schedule this
+ * build cannot read means every provider is due, which is the same place a
+ * fresh machine starts from and is never worse than not refreshing at all.
+ */
+export async function readAcquisitionSchedule(directory = resolveStateDirectory()) {
+    const document = await readJsonFileSafely(path.join(directory, ACQUISITION_STATE_FILE_NAME), MAX_JSON_FILE_BYTES);
+    if (!document.ok || !isRecord(document.value))
+        return {};
+    const version = document.value["version"];
+    if (version !== undefined && version !== ACQUISITION_STATE_VERSION)
+        return {};
+    const providers = document.value["providers"];
+    if (!isRecord(providers))
+        return {};
+    const schedule = {};
+    for (const key of Object.keys(providers).slice(0, MAX_SCHEDULE_ENTRIES)) {
+        const entry = providers[key];
+        if (!isRecord(entry))
+            continue;
+        const lastAttemptAt = entry["lastAttemptAt"];
+        const nextAttemptAt = entry["nextAttemptAt"];
+        const outcome = entry["outcome"];
+        if (!isIsoInstant(lastAttemptAt) || !isIsoInstant(nextAttemptAt))
+            continue;
+        if (typeof outcome !== "string" || !outcomeNames.has(outcome))
+            continue;
+        schedule[key] = {
+            lastAttemptAt,
+            nextAttemptAt,
+            outcome: outcome
+        };
+    }
+    return schedule;
+}
+/**
+ * Replace the schedule file.
+ *
+ * Written atomically like every other state document, so a status line reading
+ * it while a refresh writes it sees one version or the other and never half of
+ * one. It carries no credential, no address and no response, only three fields
+ * per provider.
+ */
+export async function writeAcquisitionSchedule(schedule, directory = resolveStateDirectory()) {
+    await writeFileAtomically(path.join(directory, ACQUISITION_STATE_FILE_NAME), canonicalJson({ providers: schedule, version: ACQUISITION_STATE_VERSION }));
+}
+/**
+ * One sentence per outcome, for the row a person reads.
+ *
+ * The backoff instant is rendered beside it by the caller; these sentences say
+ * what happened, in words that do not need the reader to know HTTP.
+ */
+export const ACQUISITION_OUTCOME_SENTENCE = {
+    ok: "read",
+    unauthorized: "the provider refused this login, open its own tool once to refresh it",
+    rate_limited: "the provider asked for fewer requests, so this one is waiting",
+    blocked: "the provider refused this client, so this one is waiting a day",
+    remote_error: "the provider could not answer this time",
+    transport: "this machine could not reach the provider",
+    too_large: "the provider's answer was larger than this build accepts",
+    drift: "the provider answered in a shape this build does not understand",
+    identity_refused: "the provider serves this reading only to its own tools"
+};
+//# sourceMappingURL=cadence.js.map

package/dist/acquire/cadence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.js","sourceRoot":"","sources":["../../src/acquire/cadence.ts"],"names":[],"mappings":"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"}

package/dist/acquire/coordination.d.ts

@@ -0,0 +1,157 @@
+import type { Snapshot, SnapshotWriter } from "../types.js";
+/**
+ * How old the cache may be before a render starts a refresh behind itself.
+ *
+ * A minute, which is the number Lucas's own status line has used for months. It
+ * is short enough that a person who opens a terminal sees current bars and long
+ * enough that a status line redrawing on every keystroke starts nothing.
+ */
+export declare const CACHE_REFRESH_STALE_SECONDS = 60;
+/** The lock one detached refresh holds, beside the cache lock and separate. */
+export declare const REFRESH_LOCK_NAME = "openlimiter-refresh.lock";
+/**
+ * How often a running refresh says it is still alive.
+ *
+ * The lock's modification time is the signal, so the heartbeat only touches the
+ * file and never rewrites it: the token inside has to stay byte for byte the
+ * same, because that token is what proves ownership at every write below.
+ */
+export declare const REFRESH_LOCK_HEARTBEAT_MILLISECONDS = 10000;
+/**
+ * How long a silent lock is honoured before it is treated as abandoned.
+ *
+ * Six missed heartbeats. The bound used to be a flat two minutes measured from
+ * when the lock was TAKEN, which quietly assumed a whole round fits in two
+ * minutes; seven providers, two of them two hop, each with a fifteen second
+ * budget, does not fit, so a legitimate refresh could be declared dead and
+ * raced by the next status line render. Measuring from the last heartbeat
+ * instead means the bound is about liveness rather than about duration, and a
+ * round may take as long as it takes.
+ */
+export declare const REFRESH_LOCK_STALE_MILLISECONDS = 60000;
+/** The newest observation in a set of rows, in epoch milliseconds, or null. */
+export declare function newestObservedMilliseconds(snapshots: readonly Snapshot[]): number | null;
+/**
+ * How old the freshest row is, in seconds.
+ *
+ * An empty cache has no age, which the caller reads as "refresh": there is
+ * nothing to be stale, and nothing to show either.
+ */
+export declare function cacheAgeSeconds(snapshots: readonly Snapshot[], now: string): number | null;
+/**
+ * Whether a writer has kept this cache fresh inside the ownership window.
+ *
+ * Absent markers answer false, which is the backward compatible reading: a
+ * cache written before this field existed says nothing about who wrote it, and
+ * a reader that assumed a desktop was running would stop refreshing on a
+ * machine that has none.
+ */
+export declare function writerHoldsCache(snapshots: readonly Snapshot[], writer: SnapshotWriter, now: string, withinSeconds?: number): boolean;
+/** Whether a running desktop is already keeping this cache fresh. */
+export declare function desktopHoldsCache(snapshots: readonly Snapshot[], now: string, withinSeconds?: number): boolean;
+/** Stamp rows with the process that is about to write them. */
+export declare function withWriter(snapshots: readonly Snapshot[], writer: SnapshotWriter): Snapshot[];
+export type RefreshDecision = {
+    refresh: true;
+} | {
+    refresh: false;
+    reason: "fresh" | "desktop_running";
+};
+/**
+ * Whether this render should start a refresh behind itself.
+ *
+ * Three inputs and no side effects, so the whole policy is one testable
+ * function rather than a condition spread across two commands.
+ */
+export declare function shouldStartRefresh(snapshots: readonly Snapshot[], now: string, staleSeconds?: number): RefreshDecision;
+/**
+ * Whether a refresh is running right now.
+ *
+ * A lock file older than the stale bound is not a running refresh, it is a
+ * process that died, and it is reported as free so the next render can take
+ * over. Nothing is deleted here: reclaiming belongs to the acquisition below,
+ * which does it under the same create attempt that would have failed.
+ */
+export declare function refreshLockHeld(directory?: string, nowMilliseconds?: number): Promise<boolean>;
+export interface RefreshLockHolder {
+    /** Give the lock up. Safe to call twice, and never removes somebody else's. */
+    readonly release: () => Promise<void>;
+    /**
+     * Whether this holder still owns the lock.
+     *
+     * Checked before every write a round makes, because a reclaim is always
+     * possible in principle and a round that lost its lock must not keep writing
+     * over the round that took it.
+     */
+    readonly stillOwned: () => Promise<boolean>;
+}
+export type RefreshLockResult = ({
+    ok: true;
+} & RefreshLockHolder) | {
+    ok: false;
+    reason: "held" | "unavailable";
+};
+/**
+ * Take the refresh lock, or say why not.
+ *
+ * Exclusive creation is the whole mechanism: the operating system decides the
+ * winner, so two terminals starting a refresh in the same millisecond produce
+ * exactly one round of requests. The token inside the file is checked before
+ * the release, so a process that lost its lock to the stale reclaim cannot
+ * delete the lock its successor is holding.
+ */
+export declare function acquireRefreshLock(directory?: string, nowMilliseconds?: number): Promise<RefreshLockResult>;
+/** The file that remembers a refresh this machine could not start. */
+export declare const REFRESH_SPAWN_FAILURE_NAME = "openlimiter-refresh-spawn.json";
+/**
+ * Remember that a background refresh could not be started.
+ *
+ * A detached spawn fails asynchronously: the executable is missing, or the
+ * platform refuses, and the error arrives after the status line has already
+ * drawn and returned. There is nobody left to tell at that point, so the fact
+ * is written down instead and doctor reads it back. Best effort throughout,
+ * because a machine that cannot start a refresh may well not be able to write
+ * this either, and neither failure may break a render.
+ */
+export declare function recordRefreshSpawnFailure(directory: string, now: string): Promise<void>;
+/** When the last background refresh failed to start, if one did. */
+export declare function readRefreshSpawnFailure(directory?: string): Promise<string | null>;
+/** Forget it, which a refresh that actually ran is the proof of. */
+export declare function clearRefreshSpawnFailure(directory?: string): Promise<void>;
+export interface DetachedSpawn {
+    (executable: string, argumentsList: readonly string[], options: {
+        readonly cwd?: string;
+        /**
+         * Called when the child fails to start, which happens after this
+         * function has already returned. The spawner must swallow the error
+         * itself and call this, never let it reach the process as unhandled.
+         */
+        readonly onError?: () => void;
+    }): void;
+}
+export interface SpawnRefreshOptions {
+    readonly snapshots: readonly Snapshot[];
+    readonly now: string;
+    readonly stateDirectory?: string;
+    readonly nodeExecutable: string;
+    readonly openLimiterScript: string;
+    readonly spawn: DetachedSpawn;
+    readonly staleSeconds?: number;
+}
+export type SpawnRefreshResult = {
+    spawned: true;
+} | {
+    spawned: false;
+    reason: "fresh" | "desktop_running" | "already_running" | "no_script" | "failed";
+};
+/**
+ * Start a refresh behind the caller, and never wait for it.
+ *
+ * Everything expensive happens in the child. This function creates one lock
+ * file and hands the operating system a detached process, so the render that
+ * called it returns in the time a file create takes. A failure to spawn is
+ * reported and never thrown: a status line that cannot start a refresh still
+ * has to draw the bars it already has.
+ */
+export declare function spawnDetachedRefresh(options: SpawnRefreshOptions): Promise<SpawnRefreshResult>;
+//# sourceMappingURL=coordination.d.ts.map

package/dist/acquire/coordination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../src/acquire/coordination.ts"],"names":[],"mappings":"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"}