llm-relay 0.68.5 → 0.68.7

package/dist/accounting-state.d.ts

@@ -0,0 +1,74 @@
+/**
+ * MODULE CHARTER: Per-Request Accounting Lifecycle & Price Port Bridge (accounting-state.ts)
+ *
+ * 1. Domain Boundary & Responsibilities:
+ *    - Coordinates the per-request accounting lifecycle for all caller-visible proxy routes.
+ *    - Accumulates token metrics across multiple candidate attempts, failover walks, and streaming responses.
+ *    - Decouples pricing metadata and model catalog resolution from low-level storage mutation logic.
+ *
+ * 2. Request Accounting Lifecycle:
+ *    - Initiation: `createRequestAccountingState()` establishes request identity, timing, and caller attribution.
+ *    - Attempt Recording: Each backend egress records attempt start, headers arrival, streaming deltas, or premature error.
+ *    - Completion: Upon stream finish or error, `commit()` resolves final token usage, prices attempts via the price port,
+ *      and submits immutable `AccountingEvent` records to the registered `AccountingRecorder`.
+ *
+ * 3. Price Port Decoupling:
+ *    - Pricing logic is encapsulated via `AccountingPricePort` functional interfaces.
+ *    - Tier models and pricing rates are resolved from `tier-data.js` and `metadata.js` at runtime without locking the store.
+ *    - Missing or unpriced models gracefully emit unpriced token facts without halting accounting pipelines.
+ *
+ * 4. Caller Attribution & Path Classification:
+ *    - Routes are filtered via `isCallerVisibleAccountingPath()` to exclude health, models, and administrative endpoints.
+ *    - Attributions cleanly distinguish relay-held infrastructure actions from caller-operated interactions.
+ */
+import type { ServerResponse } from "node:http";
+import type { Config } from "./config.js";
+import type { ModelCatalog } from "./catalog.js";
+import { type AccountingAttempt, type AccountingPricePort, type AccountingRecorder, type TokenFactsInput } from "./accounting.js";
+import { type UsageAccumulator } from "./usage-observer.js";
+import type { ResolvedAttempt } from "./resolved-attempt.js";
+import type { Reshaper } from "./reshaper.js";
+export type ModelCallRecorder = (providerKey: string, modelId: string, callResult: {
+    ok: boolean;
+    latencyMs: number;
+    completionTokens?: number;
+}) => void;
+export type ProxyAccountingAttribution = "relay_held" | "caller_operated" | "unknown";
+export type ProxyAccountingFailureKind = "timeout" | "provider_error" | "auth_error" | "rate_limit" | "aborted" | "protocol" | "unknown";
+export declare function isCallerVisibleAccountingPath(method: string | undefined, pathname: string): boolean;
+export declare function recordEarlyTerminalAccounting(recorder: AccountingRecorder, startedAt: number, client: string): void;
+export declare function serveAccountingAttribution(attempt: ResolvedAttempt): ProxyAccountingAttribution;
+export declare function repairAccountingAttribution(state: ResolvedAttempt["credential"]["state"]): ProxyAccountingAttribution;
+export declare function accountingTokens(usage: UsageAccumulator, estimatedInputTokens: number, includeEstimatedOutput: boolean): TokenFactsInput;
+export declare function buildAccountingPricePort(catalog: ModelCatalog, cfg: Config): AccountingPricePort;
+export declare class RequestAccountingState {
+    private readonly estimatedInputTokens;
+    private readonly pricePort?;
+    private readonly onServedLatency?;
+    private readonly request;
+    private readonly active;
+    private readonly committed;
+    private readonly attemptDeployments;
+    private responseTerminal;
+    private finalized;
+    private successfulServe;
+    private committedServeAttribution;
+    private lastFailure;
+    private lastAttribution;
+    constructor(recorder: AccountingRecorder, response: ServerResponse, startedAt: number, estimatedInputTokens: number, client: string, pricePort?: AccountingPricePort | undefined, onServedLatency?: ((provider: string, model: string, ms: number, tokens: number | undefined) => void) | undefined);
+    startServe(attempt: ResolvedAttempt, startedAt: number): AccountingAttempt | null;
+    startRepair(options: {
+        readonly resolvedAttempt: ResolvedAttempt | null;
+        readonly credentialState: ResolvedAttempt["credential"]["state"];
+        readonly provider: string | null;
+        readonly model: string | null;
+        readonly credentialId: string | null;
+        readonly startedAt: number;
+    }): AccountingAttempt | null;
+    markCommitted(attempt: AccountingAttempt | null, at: number): void;
+    complete(attempt: AccountingAttempt | null, outcome: "success" | "error" | "cancelled", failureKind: ProxyAccountingFailureKind | null, usage: UsageAccumulator, endedAt?: number, abandonedByRelay?: boolean): void;
+    private start;
+    isRequestClosed(): boolean;
+    private finalizeIfReady;
+}
+export declare function withRepairAccounting(reshaper: Reshaper, accounting: RequestAccountingState | null): Reshaper;

package/dist/accounting-state.js

@@ -0,0 +1,281 @@
+import { loadTierData, findTierModel } from "./tier-data.js";
+import { resolveMetadata } from "./metadata.js";
+import { createAccountingRequest, } from "./accounting.js";
+import { createUsageAccumulator } from "./usage-observer.js";
+export function isCallerVisibleAccountingPath(method, pathname) {
+    if (method !== "POST")
+        return false;
+    return pathname === "/v1/messages"
+        || pathname === "/v1/chat/completions"
+        || pathname === "/chat/completions"
+        || pathname === "/v1/responses"
+        || pathname === "/responses";
+}
+export function recordEarlyTerminalAccounting(recorder, startedAt, client) {
+    try {
+        createAccountingRequest({ recorder, startedAt, client }).complete({
+            outcome: "error",
+            failureKind: "unknown",
+            attribution: "unknown",
+            endedAt: Date.now(),
+        });
+    }
+    catch {
+    }
+}
+export function serveAccountingAttribution(attempt) {
+    if (attempt.credential.state === "declared-present")
+        return "relay_held";
+    if (attempt.credential.state === "not-declared" && attempt.target.credentialMode !== "contained") {
+        return "caller_operated";
+    }
+    return "unknown";
+}
+export function repairAccountingAttribution(state) {
+    return state === "declared-present" ? "relay_held" : "unknown";
+}
+export function accountingTokens(usage, estimatedInputTokens, includeEstimatedOutput) {
+    const estimatedOutputTokens = includeEstimatedOutput ? usage.estimatedOutputTokens : undefined;
+    const hasEstimatedOutput = typeof estimatedOutputTokens === "number"
+        && Number.isSafeInteger(estimatedOutputTokens)
+        && estimatedOutputTokens > 0;
+    const estimated = {
+        ...(estimatedInputTokens > 0
+            ? { inputTokens: estimatedInputTokens, inputMethod: "relay_estimate" }
+            : {}),
+        ...(hasEstimatedOutput
+            ? { outputTokens: estimatedOutputTokens, outputMethod: "relay_estimate" }
+            : {}),
+    };
+    return {
+        reported: {
+            ...(usage.inputTokens !== undefined ? { inputTokens: usage.inputTokens } : {}),
+            ...(usage.outputTokens !== undefined ? { outputTokens: usage.outputTokens } : {}),
+            ...(usage.cachedInputTokens !== undefined ? { cachedInputTokens: usage.cachedInputTokens } : {}),
+            ...(usage.cacheCreationInputTokens !== undefined
+                ? { cacheCreationInputTokens: usage.cacheCreationInputTokens }
+                : {}),
+            ...(usage.cacheReadInputTokens !== undefined ? { cacheReadInputTokens: usage.cacheReadInputTokens } : {}),
+        },
+        ...(estimatedInputTokens > 0 || hasEstimatedOutput
+            ? { estimated }
+            : {}),
+    };
+}
+export function buildAccountingPricePort(catalog, cfg) {
+    return (provider, model) => {
+        const p = cfg.providers[provider];
+        const providerLimits = p?.kind === "openai" && model
+            ? catalog.cachedLimits(provider, model)
+            : null;
+        const data = loadTierData();
+        const matched = data
+            ? findTierModel(model, data.byNorm, data.exactByNorm)
+            : null;
+        const tier = matched?.match === "exact" ? matched.rec : undefined;
+        const meta = resolveMetadata(model, {
+            providerLimits,
+            reference: tier
+                ? {
+                    pricePromptPerToken: typeof tier.price_prompt === "number" ? tier.price_prompt : null,
+                    priceCompletionPerToken: typeof tier.price_completion === "number" ? tier.price_completion : null,
+                    from: `openrouter:${tier.norm}`,
+                }
+                : null,
+        });
+        if (meta.priceSource === null)
+            return null;
+        return {
+            pricePerMillionIn: meta.pricePerMTokIn,
+            pricePerMillionOut: meta.pricePerMTokOut,
+            priceSource: meta.priceSource,
+        };
+    };
+}
+export class RequestAccountingState {
+    estimatedInputTokens;
+    pricePort;
+    onServedLatency;
+    request;
+    active = new Set();
+    committed = new Set();
+    attemptDeployments = new Map();
+    responseTerminal = null;
+    finalized = false;
+    successfulServe = false;
+    committedServeAttribution = null;
+    lastFailure = "unknown";
+    lastAttribution = "unknown";
+    constructor(recorder, response, startedAt, estimatedInputTokens, client, pricePort, onServedLatency) {
+        this.estimatedInputTokens = estimatedInputTokens;
+        this.pricePort = pricePort;
+        this.onServedLatency = onServedLatency;
+        try {
+            this.request = createAccountingRequest({ recorder, startedAt, client, pricePort });
+        }
+        catch {
+            this.request = null;
+        }
+        response.once("finish", () => {
+            if (this.responseTerminal === null)
+                this.responseTerminal = "finished";
+            this.finalizeIfReady();
+        });
+        response.once("close", () => {
+            if (this.responseTerminal === null) {
+                this.responseTerminal = response.writableFinished ? "finished" : "cancelled";
+            }
+            this.finalizeIfReady();
+        });
+    }
+    startServe(attempt, startedAt) {
+        return this.start("serve", {
+            startedAt,
+            attribution: serveAccountingAttribution(attempt),
+            provider: attempt.target.provider,
+            model: attempt.target.model ?? null,
+            credentialId: attempt.credentialId,
+        });
+    }
+    startRepair(options) {
+        return this.start("repair", {
+            startedAt: options.startedAt,
+            attribution: repairAccountingAttribution(options.credentialState),
+            provider: options.resolvedAttempt?.target.provider ?? options.provider,
+            model: options.resolvedAttempt?.target.model ?? options.model,
+            credentialId: options.resolvedAttempt?.credentialId ?? options.credentialId,
+        });
+    }
+    markCommitted(attempt, at) {
+        if (attempt === null)
+            return;
+        try {
+            if (attempt.markCommitted({ at })) {
+                this.committed.add(attempt);
+                if (attempt.role === "serve")
+                    this.committedServeAttribution = attempt.attribution;
+            }
+        }
+        catch {
+        }
+    }
+    complete(attempt, outcome, failureKind, usage, endedAt = Date.now(), abandonedByRelay = false) {
+        if (attempt === null)
+            return;
+        try {
+            attempt.complete({
+                outcome,
+                failureKind,
+                endedAt,
+                tokens: accountingTokens(usage, attempt.role === "serve" ? this.estimatedInputTokens : 0, attempt.role === "repair" || this.committed.has(attempt)),
+                abandonedByRelay,
+            });
+        }
+        catch {
+        }
+        const deployment = this.attemptDeployments.get(attempt);
+        this.attemptDeployments.delete(attempt);
+        if (this.onServedLatency &&
+            deployment &&
+            attempt.role === "serve" &&
+            outcome === "success" &&
+            typeof deployment.provider === "string" &&
+            typeof deployment.model === "string") {
+            const elapsed = endedAt - deployment.startedAt;
+            if (Number.isFinite(elapsed) && elapsed >= 0) {
+                try {
+                    this.onServedLatency(deployment.provider, deployment.model, elapsed, usage.outputTokens);
+                }
+                catch {
+                }
+            }
+        }
+        this.active.delete(attempt);
+        this.committed.delete(attempt);
+        this.lastAttribution = attempt.attribution;
+        if (attempt.role === "serve" && outcome === "success")
+            this.successfulServe = true;
+        if (outcome !== "success" && failureKind !== null)
+            this.lastFailure = failureKind;
+        this.finalizeIfReady();
+    }
+    start(role, options) {
+        if (this.request === null || this.finalized || this.responseTerminal === "cancelled")
+            return null;
+        try {
+            const attempt = this.request.startAttempt({ role, ...options });
+            this.active.add(attempt);
+            this.attemptDeployments.set(attempt, {
+                provider: options.provider,
+                model: options.model,
+                startedAt: options.startedAt,
+            });
+            this.lastAttribution = options.attribution;
+            return attempt;
+        }
+        catch {
+            return null;
+        }
+    }
+    isRequestClosed() {
+        return this.responseTerminal !== null || this.finalized;
+    }
+    finalizeIfReady() {
+        if (this.finalized || this.request === null || this.responseTerminal === null)
+            return;
+        if (this.active.size > 0) {
+            if (this.responseTerminal !== "finished")
+                return;
+            for (const attempt of [...this.active]) {
+                this.complete(attempt, "error", "unknown", createUsageAccumulator());
+            }
+        }
+        this.finalized = true;
+        try {
+            if (this.responseTerminal === "cancelled") {
+                this.request.complete({
+                    outcome: "cancelled",
+                    failureKind: "aborted",
+                    attribution: this.committedServeAttribution ?? this.lastAttribution,
+                });
+            }
+            else if (this.successfulServe) {
+                this.request.complete();
+            }
+            else {
+                this.request.complete({
+                    outcome: "error",
+                    failureKind: this.lastFailure,
+                    attribution: this.committedServeAttribution ?? this.lastAttribution,
+                });
+            }
+        }
+        catch {
+        }
+    }
+}
+export function withRepairAccounting(reshaper, accounting) {
+    if (accounting === null)
+        return reshaper;
+    const hooks = {
+        startRepairAttempt(options) {
+            const attempt = accounting.startRepair(options);
+            if (attempt === null)
+                return null;
+            return {
+                complete(completion) {
+                    accounting.complete(attempt, completion.outcome, completion.failureKind, completion.usage, completion.endedAt);
+                },
+            };
+        },
+        isRequestClosed() {
+            return accounting.isRequestClosed();
+        },
+    };
+    return {
+        reshape(request) {
+            return reshaper.reshape(request, hooks);
+        },
+    };
+}
+//# sourceMappingURL=accounting-state.js.map

package/dist/accounting-state.js.map

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

package/dist/accounting-store-io.d.ts

@@ -1,17 +1,25 @@
 /**
- * A deliberately small durability primitive for accounting's multi-file read model.
+ * MODULE CHARTER: Durable Snapshot Journal & File IO Subsystem (accounting-store-io.ts)
  *
- * It writes a full snapshot journal before replacing any target.  A later process can
- * therefore replay the journal after any target-write prefix without applying a delta
- * twice.  This module knows nothing about accounting's schemas; callers supply already
- * materialised snapshots and an explicit target allow-list. Only flat, portable direct
- * children of the root are supported for targets and the journal.
+ * 1. Domain Boundary & Responsibilities:
+ *    - Durability and transaction primitive for multi-file snapshot partition writes (day shards, lifetime rollups).
+ *    - Decoupled from higher-level accounting domain schemas: accepts opaque materialised snapshots and target allow-lists.
+ *    - Enforces directory containment for all target files and journal storage under a flat root directory.
  *
- * Threat model: the root and its parent must be trusted and non-adversarial against
- * concurrent same-user replacement. Race-proof filesystem containment against an actor
- * able to rename or replace the root is out of scope; root and final reparse points are
- * still checked before filesystem operations. Writer ownership is enforced only among
- * instances in this process; cross-process concurrent writers are unsupported.
+ * 2. Atomic Rename & Durability Invariants:
+ *    - All mutations follow a write-journal-first protocol before modifying any target snapshot file.
+ *    - Files are written to adjacent temporary files (`.tmp.<pid>.<nonce>`), fsynced to disk, and atomically renamed.
+ *    - Complete journal replay guarantees idempotency: target shards are replaced in full rather than updated via deltas.
+ *
+ * 3. Quarantine & Recovery Semantics:
+ *    - Uncommitted or interrupted transactions are detected and replayed upon startup via `recoverPendingJournal()`.
+ *    - Corrupted journals or files exceeding hard size limits are safely quarantined rather than panicking or crashing.
+ *    - Bounded data loss is tracked and reported via `lowerBoundLoss` metadata when recovery cannot reconcile stale state.
+ *
+ * 4. File Descriptor & Concurrency Guarantees:
+ *    - Single-writer mutex enforced in-process across store instances; cross-process concurrent writes are unsupported.
+ *    - All open file handles are immediately closed in `finally` blocks, preventing file descriptor leaks on Windows/POSIX.
+ *    - Hard byte ceilings (`SNAPSHOT_IO_HARD_MAX_FILE_BYTES`, `SNAPSHOT_IO_HARD_MAX_JOURNAL_BYTES`) guard against OOMs.
  */
 export declare const SNAPSHOT_JOURNAL_SCHEMA = "llm-relay.snapshot-journal.v1";
 export declare const SNAPSHOT_JOURNAL_VERSION = 1;

package/dist/accounting-store-io.js

@@ -312,39 +312,62 @@ class SnapshotJournalIoImpl {
             return this.withPendingRecoveryLoss(mutationResult("failed", { error: safeError(error), retryable: true }));
         }
     }
+    validateSnapshotsPreWrite(snapshots) {
+        const config = this.config;
+        if (!config)
+            return { ok: false, failure: mutationResult("invalid", { error: this.configError ?? "config", retryable: false }) };
+        const recovery = this.recoverUnlocked();
+        if (recovery.status === "failed" || recovery.status === "invalid")
+            return { ok: false, failure: recovery };
+        const lowerBoundLoss = recovery.lowerBoundLoss;
+        const encoded = this.encodeSnapshots(snapshots);
+        if (encoded === null) {
+            return { ok: false, failure: mutationResult("invalid", { error: "snapshots", lowerBoundLoss, retryable: false }) };
+        }
+        return { ok: true, encoded, lowerBoundLoss };
+    }
+    serializeAndCommitJournal(config, encoded, lowerBoundLoss) {
+        const transactionId = this.transactionId();
+        const payload = {
+            schema: SNAPSHOT_JOURNAL_SCHEMA,
+            version: SNAPSHOT_JOURNAL_VERSION,
+            transactionId,
+            createdAtMs: this.now(),
+            targets: encoded,
+        };
+        const text = JSON.stringify(payload);
+        if (utf8Bytes(text) > config.maxJournalBytes) {
+            return { ok: false, failure: mutationResult("invalid", { error: "journal-size", lowerBoundLoss, retryable: false }) };
+        }
+        const written = this.atomicReplace(config.journalPath, Buffer.from(text, "utf8"), "journal", null);
+        if (!written.ok) {
+            return {
+                ok: false,
+                failure: this.withPendingRecoveryLoss(mutationResult("failed", { transactionId, lowerBoundLoss, error: written.error, retryable: true })),
+            };
+        }
+        const journal = this.decodeJournal(Buffer.from(text, "utf8"));
+        if (journal === null) {
+            return {
+                ok: false,
+                failure: this.withPendingRecoveryLoss(mutationResult("failed", { transactionId, lowerBoundLoss, error: "journal-encode", retryable: true })),
+            };
+        }
+        return { ok: true, journal, transactionId };
+    }
     commitUnlocked(snapshots) {
         try {
             const config = this.config;
             if (!config)
                 return mutationResult("invalid", { error: this.configError ?? "config", retryable: false });
-            const recovery = this.recoverUnlocked();
-            if (recovery.status === "failed" || recovery.status === "invalid")
-                return recovery;
-            const lowerBoundLoss = recovery.lowerBoundLoss;
-            const encoded = this.encodeSnapshots(snapshots);
-            if (encoded === null)
-                return mutationResult("invalid", { error: "snapshots", lowerBoundLoss, retryable: false });
-            const transactionId = this.transactionId();
-            const payload = {
-                schema: SNAPSHOT_JOURNAL_SCHEMA,
-                version: SNAPSHOT_JOURNAL_VERSION,
-                transactionId,
-                createdAtMs: this.now(),
-                targets: encoded,
-            };
-            const text = JSON.stringify(payload);
-            if (utf8Bytes(text) > config.maxJournalBytes) {
-                return mutationResult("invalid", { error: "journal-size", lowerBoundLoss, retryable: false });
-            }
-            const written = this.atomicReplace(config.journalPath, Buffer.from(text, "utf8"), "journal", null);
-            if (!written.ok)
-                return this.withPendingRecoveryLoss(mutationResult("failed", { transactionId, lowerBoundLoss, error: written.error, retryable: true }));
-            const journal = this.decodeJournal(Buffer.from(text, "utf8"));
-            if (journal === null) {
-                return this.withPendingRecoveryLoss(mutationResult("failed", { transactionId, lowerBoundLoss, error: "journal-encode", retryable: true }));
-            }
-            const result = this.applyJournal(journal, "committed");
-            const merged = result.lowerBoundLoss === lowerBoundLoss ? result : { ...result, lowerBoundLoss };
+            const preWrite = this.validateSnapshotsPreWrite(snapshots);
+            if (!preWrite.ok)
+                return preWrite.failure;
+            const journalCommit = this.serializeAndCommitJournal(config, preWrite.encoded, preWrite.lowerBoundLoss);
+            if (!journalCommit.ok)
+                return journalCommit.failure;
+            const result = this.applyJournal(journalCommit.journal, "committed");
+            const merged = result.lowerBoundLoss === preWrite.lowerBoundLoss ? result : { ...result, lowerBoundLoss: preWrite.lowerBoundLoss };
             return this.withPendingRecoveryLoss(merged, merged.status === "committed");
         }
         catch (error) {
@@ -579,7 +602,7 @@ class SnapshotJournalIoImpl {
                 throw error;
             const inspected = this.inspectExistingPath(path, false);
             if (inspected.status !== "ok")
-                throw new Error(inspected.error ?? "path");
+                throw new Error(inspected.error ?? "path", { cause: error });
             return openSync(path, "r");
         }
     }