@cortexkit/common-auth 0.1.2 → 0.2.0

package/dist/routing/admission.d.ts

@@ -0,0 +1,93 @@
+import { type QuotaMap } from '../quota/map.js';
+import { type ProjectedQuota } from '../quota/projection.js';
+export type RowKind = 'oauth' | 'api-key';
+export interface RoutingRow {
+    id: string;
+    kind: RowKind;
+    /** The row's stored quota map; absent is the same as an empty map. */
+    quota?: QuotaMap;
+}
+export interface WindowRef {
+    scope: string;
+    label: string;
+}
+export interface ExclusionInputs {
+    /** Row id to the time (ms) a rate-limit mark expires. */
+    rateLimitMarks?: ReadonlyMap<string, number>;
+    /** Row id to the time (ms) a failed refresh may be retried. */
+    refreshBackoff?: ReadonlyMap<string, number>;
+}
+export interface AdmissionInput extends ExclusionInputs {
+    rows: readonly RoutingRow[];
+    /** `all` (the default) or a model family. */
+    scope?: string;
+    /** Labels the scope requires an entry for; defaults to `['primary']`. */
+    requiredLabels?: readonly string[];
+    now: number;
+    /**
+     * Called synchronously, once per refusal at gates 2 to 4, with the row id.
+     * Its return value is ignored and never awaited, so a pull the caller
+     * starts from here cannot delay the refusal.
+     */
+    requestPull?: (rowId: string) => void;
+}
+export type AdmissionRefusal = {
+    id: string;
+    stage: 1;
+    gate: 2;
+    reason: 'needs-first-reading';
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 3;
+    reason: 'unknown-window';
+    window: WindowRef;
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 4;
+    reason: 'unknown-reset';
+    window: WindowRef;
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 5;
+    reason: 'exhausted';
+    window: WindowRef;
+    resetsAt: string;
+    resetAtMs: number;
+} | {
+    id: string;
+    stage: 2;
+    reason: 'budget-spent';
+    resetsAt: string;
+    resetAtMs: number;
+};
+export interface AdmissionExclusion {
+    id: string;
+    reason: 'rate-limited' | 'refresh-backoff';
+    until: number;
+}
+export interface AdmittedRow {
+    id: string;
+    kind: RowKind;
+    /** The projection admission judged; absent for API-key rows. */
+    projection?: ProjectedQuota;
+    /** Set when a spent budget was kept because no other path survived. */
+    lastPath?: true;
+}
+export interface AdmissionResult {
+    /** In input order. */
+    admitted: AdmittedRow[];
+    refused: AdmissionRefusal[];
+    excluded: AdmissionExclusion[];
+    /** Ids a pull was requested for, in input order. */
+    pulls: string[];
+}
+/** The exclusion that applies to `id` at `now`, if any. */
+export declare function exclusionFor(id: string, inputs: ExclusionInputs, now: number): AdmissionExclusion | undefined;
+/** Runs both admission stages over `input.rows`. */
+export declare function admit(input: AdmissionInput): AdmissionResult;

package/dist/routing/admission.js

@@ -0,0 +1,140 @@
+// Admission: which candidate rows may be dispatched for one request.
+//
+// Pure: the caller passes the candidate rows with their quota maps, the
+// request's scope, the window labels that scope requires, and the rate-limit
+// marks and refresh backoff it holds. Nothing is read or written here.
+//
+// A marked or backed-off row is excluded before the gates. Stage 1 then
+// judges each remaining row alone, in gate order:
+//   1. an API-key row is admitted without consulting quota;
+//   2. an OAuth row whose projection resolves no entry for the scope needs a
+//      first reading: refused, pull requested;
+//   3. a required label with no entry is unknown: refused, pull requested;
+//   4. a reading at or beyond 100% whose reset is missing, unparsable or not
+//      after `now` cannot confirm the exhaustion, so the window is unknown:
+//      refused, pull requested;
+//   5. a reading at or beyond 100% with a future reset is exhausted: refused.
+// Gates 4 and 5 look at every projected limit, not only the required labels.
+// Stage 2 judges the credit budget across the stage-1 survivors: a row whose
+// budget is known spent (reached, with a parsable future reset) is refused
+// unless every survivor's budget is spent, in which case all of them stay
+// admitted as the last path. Every missing, malformed or passed budget reset
+// fails open. Stage-1 refusals have no last-path exception.
+import { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, } from '../quota/map.js';
+import { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from '../quota/projection.js';
+/** The exclusion that applies to `id` at `now`, if any. */
+export function exclusionFor(id, inputs, now) {
+    const markedUntil = inputs.rateLimitMarks?.get(id);
+    if (markedUntil !== undefined && now < markedUntil) {
+        return { id, reason: 'rate-limited', until: markedUntil };
+    }
+    const backoffUntil = inputs.refreshBackoff?.get(id);
+    if (backoffUntil !== undefined && now < backoffUntil) {
+        return { id, reason: 'refresh-backoff', until: backoffUntil };
+    }
+    return undefined;
+}
+function judgeStageOne(id, projection, requiredLabels, now) {
+    if (projection.limits.length === 0) {
+        return {
+            id,
+            stage: 1,
+            gate: 2,
+            reason: 'needs-first-reading',
+            pullRequested: true,
+        };
+    }
+    for (const label of requiredLabels) {
+        if (!projection.limits.some((limit) => limit.label === label)) {
+            return {
+                id,
+                stage: 1,
+                gate: 3,
+                reason: 'unknown-window',
+                window: { scope: projection.scope, label },
+                pullRequested: true,
+            };
+        }
+    }
+    const exhausted = projection.limits.filter(readsExhausted);
+    for (const limit of exhausted) {
+        if (futureResetAt(limit, now) === undefined) {
+            return {
+                id,
+                stage: 1,
+                gate: 4,
+                reason: 'unknown-reset',
+                window: { scope: limit.scope, label: limit.label },
+                pullRequested: true,
+            };
+        }
+    }
+    for (const limit of exhausted) {
+        const resetAtMs = futureResetAt(limit, now);
+        if (resetAtMs !== undefined && typeof limit.resetsAt === 'string') {
+            return {
+                id,
+                stage: 1,
+                gate: 5,
+                reason: 'exhausted',
+                window: { scope: limit.scope, label: limit.label },
+                resetsAt: limit.resetsAt,
+                resetAtMs,
+            };
+        }
+    }
+    return undefined;
+}
+/** Runs both admission stages over `input.rows`. */
+export function admit(input) {
+    const scope = input.scope ?? ALL_SCOPE;
+    const requiredLabels = input.requiredLabels ?? DEFAULT_REQUIRED_LABELS;
+    const excluded = [];
+    const refused = [];
+    const survivors = [];
+    for (const row of input.rows) {
+        const exclusion = exclusionFor(row.id, input, input.now);
+        if (exclusion) {
+            excluded.push(exclusion);
+            continue;
+        }
+        if (row.kind === 'api-key') {
+            survivors.push({ id: row.id, kind: row.kind });
+            continue;
+        }
+        const projection = projectQuota(row.quota, scope);
+        const refusal = judgeStageOne(row.id, projection, requiredLabels, input.now);
+        if (refusal) {
+            refused.push(refusal);
+            continue;
+        }
+        survivors.push({ id: row.id, kind: row.kind, projection });
+    }
+    const spent = new Map(survivors.flatMap((row) => {
+        const reset = budgetExhaustedResetAt(row.projection, input.now);
+        return reset ? [[row.id, reset]] : [];
+    }));
+    const lastPath = spent.size > 0 && spent.size === survivors.length;
+    const admitted = [];
+    for (const row of survivors) {
+        const reset = spent.get(row.id);
+        if (reset === undefined) {
+            admitted.push(row);
+        }
+        else if (lastPath) {
+            admitted.push({ ...row, lastPath: true });
+        }
+        else {
+            refused.push({ id: row.id, stage: 2, reason: 'budget-spent', ...reset });
+        }
+    }
+    const order = new Map(input.rows.map((row, index) => [row.id, index]));
+    const byInput = (left, right) => (order.get(left.id) ?? 0) - (order.get(right.id) ?? 0);
+    refused.sort(byInput);
+    const pulls = refused
+        .filter((refusal) => 'pullRequested' in refusal)
+        .map((refusal) => refusal.id);
+    for (const id of pulls)
+        input.requestPull?.(id);
+    return { admitted, refused, excluded, pulls };
+}

package/dist/routing/index.d.ts

@@ -0,0 +1,8 @@
+export type { AdmissionExclusion, AdmissionInput, AdmissionRefusal, AdmissionResult, AdmittedRow, ExclusionInputs, RoutingRow, RowKind, WindowRef, } from './admission.js';
+export { admit, exclusionFor } from './admission.js';
+export type { OrderedAttempt, OrderedPlacement, OrderedRoute, OrderedRouteInput, ResolvedRoutingMode, RoutingMode, } from './ordered.js';
+export { DEFAULT_FORMER_MAIN_ID, nextOrderedAttempt, orderForPlacement, resolveRoutingMode, routeOrdered, } from './ordered.js';
+export type { StickyPin } from './pins.js';
+export { isPinValid, pendingBytesForPins } from './pins.js';
+export type { PinAction, StickyBreakDecision, StickyRoute, StickyRouteInput, StickySelection, StickySelectionCandidate, StickySelectionInput, } from './sticky.js';
+export { decideStickyBreak, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, STICKY_WINDOW_SLOTS, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';

package/dist/routing/index.js

@@ -0,0 +1,4 @@
+export { admit, exclusionFor } from './admission.js';
+export { DEFAULT_FORMER_MAIN_ID, nextOrderedAttempt, orderForPlacement, resolveRoutingMode, routeOrdered, } from './ordered.js';
+export { isPinValid, pendingBytesForPins } from './pins.js';
+export { decideStickyBreak, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, STICKY_WINDOW_SLOTS, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';

package/dist/routing/ordered.d.ts

@@ -0,0 +1,47 @@
+import { type AdmissionInput, type AdmissionResult } from './admission.js';
+export type RoutingMode = 'ordered' | 'sticky-balanced';
+/** Where `ordered` routing places the former main row. */
+export type OrderedPlacement = 'roster' | 'main-first' | 'fallback-first';
+export interface ResolvedRoutingMode {
+    mode: RoutingMode;
+    placement: OrderedPlacement;
+}
+/** The former main row's id when the caller supplies none. */
+export declare const DEFAULT_FORMER_MAIN_ID = "main";
+/**
+ * Resolves a persisted `routing.mode` value. `main-first` and
+ * `fallback-first` are aliases of `ordered` that move the former main row;
+ * an absent or unrecognised value is `ordered` in roster order. The
+ * persisted value is only read here, never rewritten.
+ */
+export declare function resolveRoutingMode(value: unknown): ResolvedRoutingMode;
+/**
+ * Orders `ids` (in roster order) for a placement: `main-first` moves the row
+ * named `formerMainId` to the front, `fallback-first` to the back, and
+ * `roster` (or a missing former main row) keeps roster order.
+ */
+export declare function orderForPlacement(ids: readonly string[], placement: OrderedPlacement, formerMainId?: string): string[];
+export interface OrderedRouteInput extends AdmissionInput {
+    placement?: OrderedPlacement;
+    formerMainId?: string;
+    /** Killswitch verdict per row; `false` drops the row, a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+}
+export interface OrderedRoute {
+    /** Admitted, non-killed row ids in the order they are to be tried. */
+    order: string[];
+    admission: AdmissionResult;
+}
+export declare function routeOrdered(input: OrderedRouteInput): OrderedRoute;
+export interface OrderedAttempt {
+    id: string;
+    /** The response status; undefined when no response arrived. */
+    status?: number;
+}
+/**
+ * The next row to try, given the attempts so far: the first row when none
+ * has been tried, the next untried row when the last attempt's status is one
+ * of `retryStatuses`, and undefined otherwise (the last response stands) or
+ * when every row has been tried.
+ */
+export declare function nextOrderedAttempt(order: readonly string[], attempts: readonly OrderedAttempt[], retryStatuses: readonly number[]): string | undefined;

package/dist/routing/ordered.js

@@ -0,0 +1,58 @@
+// `ordered` routing: admitted rows tried in a fixed order, moving to the next
+// row only when a response carries one of the caller's retry statuses.
+import { admit, } from './admission.js';
+/** The former main row's id when the caller supplies none. */
+export const DEFAULT_FORMER_MAIN_ID = 'main';
+/**
+ * Resolves a persisted `routing.mode` value. `main-first` and
+ * `fallback-first` are aliases of `ordered` that move the former main row;
+ * an absent or unrecognised value is `ordered` in roster order. The
+ * persisted value is only read here, never rewritten.
+ */
+export function resolveRoutingMode(value) {
+    switch (value) {
+        case 'sticky-balanced':
+            return { mode: 'sticky-balanced', placement: 'roster' };
+        case 'main-first':
+            return { mode: 'ordered', placement: 'main-first' };
+        case 'fallback-first':
+            return { mode: 'ordered', placement: 'fallback-first' };
+        default:
+            return { mode: 'ordered', placement: 'roster' };
+    }
+}
+/**
+ * Orders `ids` (in roster order) for a placement: `main-first` moves the row
+ * named `formerMainId` to the front, `fallback-first` to the back, and
+ * `roster` (or a missing former main row) keeps roster order.
+ */
+export function orderForPlacement(ids, placement, formerMainId = DEFAULT_FORMER_MAIN_ID) {
+    if (placement === 'roster' || !ids.includes(formerMainId))
+        return [...ids];
+    const rest = ids.filter((id) => id !== formerMainId);
+    return placement === 'main-first'
+        ? [formerMainId, ...rest]
+        : [...rest, formerMainId];
+}
+export function routeOrdered(input) {
+    const admission = admit(input);
+    const admitted = new Set(admission.admitted.map((row) => row.id));
+    const order = orderForPlacement(input.rows.map((row) => row.id), input.placement ?? 'roster', input.formerMainId).filter((id) => admitted.has(id) && input.killswitch?.get(id) !== false);
+    return { order, admission };
+}
+/**
+ * The next row to try, given the attempts so far: the first row when none
+ * has been tried, the next untried row when the last attempt's status is one
+ * of `retryStatuses`, and undefined otherwise (the last response stands) or
+ * when every row has been tried.
+ */
+export function nextOrderedAttempt(order, attempts, retryStatuses) {
+    const last = attempts.at(-1);
+    if (last !== undefined) {
+        if (last.status === undefined || !retryStatuses.includes(last.status)) {
+            return undefined;
+        }
+    }
+    const tried = new Set(attempts.map((attempt) => attempt.id));
+    return order.find((id) => !tried.has(id));
+}

package/dist/routing/pins.d.ts

@@ -0,0 +1,22 @@
+export interface StickyPin {
+    accountId: string;
+    /** The row's recorded wire identity when the pin was made, if known. */
+    wireIdentity?: string;
+    /** The request size recorded with the pin; weighs pending bytes. */
+    inputBytes?: number;
+    /** The projection time the placement was judged on. */
+    quotaCheckedAt?: number;
+}
+/**
+ * A pin survives while its row id is in `validIds` and the row still holds
+ * the account it was placed on. Only two known, differing identities prove
+ * the account changed: an unknown identity on either side keeps the pin,
+ * because re-placing a session on missing evidence throws its cache away.
+ */
+export declare function isPinValid(pin: StickyPin, validIds: ReadonlySet<string>, currentIdentity: string | undefined): boolean;
+/**
+ * Sums the request bytes of every other session's pin per row, as openai-auth
+ * does. A pin counts only while it was judged on the row's current
+ * projection time, so a fresh reading resets the row's pending load.
+ */
+export declare function pendingBytesForPins(pins: Iterable<readonly [sessionKey: string, pin: StickyPin]>, quotaCheckedAtById: ReadonlyMap<string, number | undefined>, excludedSessionKey?: string): Map<string, number>;

package/dist/routing/pins.js

@@ -0,0 +1,34 @@
+// Session pins for `sticky-balanced` routing.
+//
+// A pin records which row a session was placed on so its prompt cache stays
+// warm. The library persists no pin: the caller holds pins (in memory, or in
+// a cross-process file it owns) and passes the relevant ones in per call.
+/**
+ * A pin survives while its row id is in `validIds` and the row still holds
+ * the account it was placed on. Only two known, differing identities prove
+ * the account changed: an unknown identity on either side keeps the pin,
+ * because re-placing a session on missing evidence throws its cache away.
+ */
+export function isPinValid(pin, validIds, currentIdentity) {
+    if (!validIds.has(pin.accountId))
+        return false;
+    return !(typeof pin.wireIdentity === 'string' &&
+        typeof currentIdentity === 'string' &&
+        pin.wireIdentity !== currentIdentity);
+}
+/**
+ * Sums the request bytes of every other session's pin per row, as openai-auth
+ * does. A pin counts only while it was judged on the row's current
+ * projection time, so a fresh reading resets the row's pending load.
+ */
+export function pendingBytesForPins(pins, quotaCheckedAtById, excludedSessionKey) {
+    const pending = new Map();
+    for (const [sessionKey, pin] of pins) {
+        if (sessionKey === excludedSessionKey)
+            continue;
+        if (pin.quotaCheckedAt !== quotaCheckedAtById.get(pin.accountId))
+            continue;
+        pending.set(pin.accountId, (pending.get(pin.accountId) ?? 0) + (pin.inputBytes ?? 0));
+    }
+    return pending;
+}

package/dist/routing/sticky.d.ts

@@ -0,0 +1,118 @@
+import { type ProjectedQuota } from '../quota/projection.js';
+import { type AdmissionInput, type AdmissionRefusal, type AdmissionResult, type WindowRef } from './admission.js';
+import { type StickyPin } from './pins.js';
+export declare const QUOTA_STALENESS_MS: number;
+export declare const MIN_RESET_HOURS: number;
+export declare const MIN_WEIGHT = 0.000001;
+/**
+ * How many window readings the selection primitives judge, as openai-auth's
+ * primary and secondary slots did. The projection's first readings in its
+ * order fill the slots; any further window is judged by admission only.
+ */
+export declare const STICKY_WINDOW_SLOTS = 2;
+/** The projection's time, else the caller's cache-entry time. */
+export declare function snapshotCheckedAt(quota: ProjectedQuota | null | undefined, entryCheckedAt?: number): number | undefined;
+export type StickyBreakDecision = {
+    action: 'retain';
+    reason: 'unknown' | 'stale' | 'healthy' | 'transient';
+} | {
+    action: 'migrate';
+    reason: 'exhausted' | 'permanent' | 'killswitch';
+    /** The exhausted limit, named by its (scope, label), not its position. */
+    window?: WindowRef;
+    resetsAt?: string;
+};
+/** Classifies whether a pinned session should leave its row after a failure. */
+export declare function decideStickyBreak(input: {
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    status?: number;
+    now: number;
+    killswitchPasses?: boolean;
+}): StickyBreakDecision;
+export declare function sustainableWindowWeight(window: {
+    remainingPercent: number;
+    resetsAt?: string;
+}, reservePercent: number, now: number): number;
+export interface StickySelectionCandidate {
+    accountId: string;
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    /** Reserve percent per window label; a missing label reserves nothing. */
+    reservePercent: Readonly<Record<string, number>>;
+    configuredOrder: number;
+    resetCreditsApplicable?: number;
+    /** `false` excludes the candidate from weighted and fallback placement. */
+    killswitchPasses?: boolean;
+}
+export interface StickySelectionInput {
+    candidates: readonly StickySelectionCandidate[];
+    pendingBytes: ReadonlyMap<string, number>;
+    requestBytes: number;
+    now: number;
+    onEmptyWeightedSet?: () => void;
+}
+export interface StickySelection {
+    accountId: string;
+    quotaCheckedAt?: number;
+    source: 'weighted' | 'mode-fallback';
+}
+/**
+ * Places a session: the lowest projected pressure among candidates with a
+ * fresh positive weight, else (`mode-fallback`) the first candidate in
+ * configured order, preferring one with an applicable reset credit.
+ */
+export declare function selectStickyCandidate(input: StickySelectionInput): StickySelection | undefined;
+export interface StickyRouteInput extends AdmissionInput {
+    requestBytes: number;
+    /** Bytes already committed per row, for example from other sessions' pins. */
+    pendingBytes?: ReadonlyMap<string, number>;
+    /** Killswitch verdict per row; a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+    /** Reserve percent per window label, applied to every row. */
+    reservePercent?: Readonly<Record<string, number>>;
+    resetCreditsApplicable?: ReadonlyMap<string, number>;
+    /** The session's current pin, if it has one. */
+    pin?: StickyPin;
+    /** Each row's recorded wire identity; missing means unknown. */
+    identities?: ReadonlyMap<string, string | undefined>;
+    onEmptyWeightedSet?: () => void;
+}
+/**
+ * What the caller does with the session's pin: keep it, replace it with
+ * `pin`, or drop it. A valid pin is always kept, even when this request was
+ * routed elsewhere because its row was refused or excluded.
+ */
+export type PinAction = {
+    action: 'retain';
+} | {
+    action: 'assign';
+    pin: StickyPin;
+} | {
+    action: 'clear';
+} | {
+    action: 'none';
+};
+export type StickyRoute = {
+    outcome: 'dispatch';
+    accountId: string;
+    source: 'pin' | 'weighted' | 'mode-fallback';
+    quotaCheckedAt?: number;
+    pin: PinAction;
+    /** Rows that selection chose and admission then refused, in selection order. */
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+} | {
+    outcome: 'no-admissible-account';
+    pin: PinAction;
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+};
+/**
+ * Routes one request in `sticky-balanced` mode. A valid pin whose row is
+ * admitted, not excluded and not killed is dispatched as is. Otherwise
+ * selection runs over the non-excluded rows; each selected row admission
+ * refused is removed and selection re-runs, so the loop ends either on an
+ * admitted row or with no admissible account.
+ */
+export declare function routeSticky(input: StickyRouteInput): StickyRoute;