@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
771 lines (717 loc) • 29.5 kB
text/typescript
/**
* Derived request-history index (RI-02).
*
* `usage.jsonl` stays canonical; this module maintains a rebuildable SQLite
* projection (ADR-1, ADR-8). On every open/query it verifies schema version,
* file identity and byte offset, then appends whatever complete
* JSONL rows arrived since the last index. Missing/corrupt/stale index or a
* replaced/truncated source triggers an automatic full rebuild; canonical
* history is never touched.
*
* A full rebuild of a ledger of at least `REQUEST_HISTORY_WORKER_REBUILD_MIN_BYTES`
* runs on a worker thread (#6990): the worker writes a private build file and
* this thread swaps it in once complete. Async readers wait for it; the
* routing-time sync entry never waits and throws `RequestHistoryIndexBusyError`.
* Full integrity scans run on that worker at open and periodically while in
* use, never synchronously on the serving thread (#7966).
*/
import { Database } from "bun:sqlite";
import { existsSync, renameSync, unlinkSync } from "node:fs";
import { getConfigDir } from "../../config";
import { recordOwnedConfigPath } from "../../lib/config-ownership";
import {
currentUsageLogRevision,
encodePersistedRequestedModel,
normalizeUsageEntryForTest,
usageLogPath,
type PersistedUsageEntry,
type UsageLogRevision,
} from "../../usage/log";
import {
HISTORY_DDL,
HISTORY_META_KEYS,
HISTORY_SCHEMA_VERSION,
historyIndexPath,
} from "./schema";
import {
decodeHistoryCursor,
encodeHistoryCursor,
InvalidCursorError,
type HistoryCursor,
} from "./cursor";
import {
ingestSourceTail,
metaValue,
recordSourceMeta,
RequestHistoryIndexStaleError,
resetAndCreateSchema,
setMeta,
} from "./ingest";
import { buildFilePath, removeBuildFiles } from "./build-file";
import { RebuildWorkerJob } from "./rebuild-job";
import { RequestHistoryIntegrityMonitor, type RequestHistoryIntegrityOptions } from "./integrity";
import { isHistoryIndexCorruption } from "./sqlite-errors";
export {
REQUEST_HISTORY_INSERT_BATCH,
REQUEST_HISTORY_MAX_RECORD_BYTES,
REQUEST_HISTORY_READ_CHUNK_BYTES,
} from "./ingest";
export interface RequestHistoryIndexMeta {
schemaVersion: number;
dbPath: string;
sourceSize: number;
sourceMtimeMs: number;
indexedOffset: number;
indexedRows: number;
builtAtMs: number;
lastError: string | null;
}
export interface RequestHistoryFilters {
provider?: string;
model?: string;
requestedModel?: string;
status?: number;
conversationId?: string;
surface?: string;
inboundProtocol?: string;
apiKeyId?: string;
profileId?: string;
fallback?: boolean;
from?: number;
to?: number;
}
export interface RequestHistoryPage {
rows: PersistedUsageEntry[];
nextCursor?: string;
hasMore: boolean;
meta: RequestHistoryIndexMeta;
}
export const REQUEST_HISTORY_MAX_PAGE_SIZE = 100;
export const REQUEST_HISTORY_DEFAULT_PAGE_SIZE = 50;
// Ledgers at least this large rebuild on the worker; smaller ones rebuild
// inline, where a worker spawn would cost more than the ingest.
export const REQUEST_HISTORY_WORKER_REBUILD_MIN_BYTES = 1024 * 1024;
// A worker build that failed for any reason but a replaced ledger is not
// retried by routing-time reads for this long, so a persistent failure (disk
// full, unreadable ledger) cannot spawn a worker on every routing decision.
const WORKER_FAILURE_COOLDOWN_MS = 30_000;
// Async readers wait for at most this many worker rebuilds before reporting the
// index busy (a ledger replaced again during every build).
const MAX_ASYNC_REFRESH_BUILDS = 4;
/** The index is being rebuilt in the background; routing treats history as unknown meanwhile. */
export class RequestHistoryIndexBusyError extends Error {
readonly code = "request_history_index_busy";
constructor(message = "request-history index is rebuilding") {
super(message);
this.name = "RequestHistoryIndexBusyError";
}
}
/** The index was closed while a reader waited for its rebuild. */
export class RequestHistoryIndexClosedError extends Error {
readonly code = "request_history_index_closed";
constructor(message = "request-history index was closed during a rebuild") {
super(message);
this.name = "RequestHistoryIndexClosedError";
}
}
interface WorkerRebuild {
readonly job: RebuildJob;
readonly promise: Promise<void>;
}
/** The part of a rebuild worker job the indexer drives; tests substitute a failing one. */
type RebuildJob = Pick<RebuildWorkerJob, "build" | "dispose" | "afterExit">;
let createRebuildJob: () => RebuildJob = () => new RebuildWorkerJob();
/** Test seam: replace the worker job factory; `undefined` restores the real worker. */
export function setRequestHistoryRebuildJobFactoryForTests(factory: (() => RebuildJob) | undefined): void {
createRebuildJob = factory ?? (() => new RebuildWorkerJob());
}
/** Internal signal: the refresh needs a rebuild that is running (or now started) on the worker. */
class RebuildHandedOff {
constructor(readonly rebuild: WorkerRebuild) {}
}
/** An initial integrity check, or a scanner draining before index replacement. */
class IntegrityHandedOff {
constructor(readonly promise: Promise<void>) {}
}
let db: Database | null = null;
let dbPath = "";
let openPromise: Promise<RequestHistoryIndexMeta> | null = null;
let manualRebuild: Promise<RequestHistoryIndexMeta> | null = null;
let workerRebuild: WorkerRebuild | null = null;
let workerFailure: { at: number; error: unknown } | null = null;
let workerRebuildMinBytes = REQUEST_HISTORY_WORKER_REBUILD_MIN_BYTES;
let maxAsyncRefreshBuilds = MAX_ASYNC_REFRESH_BUILDS;
let buildSequence = 0;
// Bumped by closeRequestHistoryIndex, so a rebuild finishing after a close is discarded.
let indexLifetime = 0;
let integrity = new RequestHistoryIntegrityMonitor();
let integrityDrain: Promise<void> | null = null;
let corruptHandle: Database | null = null;
let validatedBuildPath: string | null = null;
/** Test seam: replace integrity scheduling without leaving a scanner on an old file. */
export function setRequestHistoryIntegrityOptionsForTests(options?: RequestHistoryIntegrityOptions): void {
closeRequestHistoryIndex();
integrity = new RequestHistoryIntegrityMonitor(options);
}
function stopIntegrityScan(): Promise<void> | null {
const pending = integrity.quiesce();
if (pending && !integrityDrain) {
const drained = pending.finally(() => {
if (integrityDrain === drained) integrityDrain = null;
});
integrityDrain = drained;
}
return integrityDrain;
}
/** Never delete/rename a database that a cancelled scanner may still hold on Windows. */
function prepareIndexReplacement(): void {
const pending = stopIntegrityScan();
if (pending) throw new IntegrityHandedOff(pending);
}
/** Test seam: move the worker threshold; `undefined` restores the default. */
export function setRequestHistoryWorkerRebuildMinBytesForTests(bytes: number | undefined): void {
workerRebuildMinBytes = bytes ?? REQUEST_HISTORY_WORKER_REBUILD_MIN_BYTES;
}
/** Test seam: how many worker rebuilds one async refresh waits for; `undefined` restores the default. */
export function setRequestHistoryAsyncRefreshBuildsForTests(builds: number | undefined): void {
maxAsyncRefreshBuilds = builds ?? MAX_ASYNC_REFRESH_BUILDS;
}
function indexDbPath(): string {
const dir = getConfigDir();
const path = historyIndexPath(dir);
recordOwnedConfigPath(dir, path);
return path;
}
function readIndexedMeta(dbHandle: Database): Omit<RequestHistoryIndexMeta, "dbPath"> {
const asNumber = (key: string): number => {
const value = metaValue(dbHandle, key);
const parsed = value === null ? NaN : Number(value);
return Number.isFinite(parsed) ? parsed : 0;
};
return {
schemaVersion: asNumber(HISTORY_META_KEYS.schemaVersion) || HISTORY_SCHEMA_VERSION,
sourceSize: asNumber(HISTORY_META_KEYS.sourceSize),
sourceMtimeMs: asNumber(HISTORY_META_KEYS.sourceMtimeMs),
indexedOffset: asNumber(HISTORY_META_KEYS.indexedOffset),
indexedRows: asNumber(HISTORY_META_KEYS.indexedRows),
builtAtMs: asNumber(HISTORY_META_KEYS.builtAtMs),
lastError: metaValue(dbHandle, HISTORY_META_KEYS.lastError),
};
}
function metaFor(dbHandle: Database): RequestHistoryIndexMeta {
return { dbPath, ...readIndexedMeta(dbHandle) };
}
function sourceIdentity(): UsageLogRevision | null {
return currentUsageLogRevision();
}
function readStoredMetaField(dbHandle: Database, key: string): string {
return metaValue(dbHandle, key) ?? "";
}
export function sourceIdentityMatches(dbHandle: Database, revision: UsageLogRevision | null): boolean {
const stored = readIndexedMeta(dbHandle);
if (revision === null) return stored.sourceSize === 0;
const storedPath = readStoredMetaField(dbHandle, HISTORY_META_KEYS.sourcePath);
if (!storedPath) return false;
// Compared as exact decimal strings; see UsageLogRevision for why ids are not Numbers.
const storedDev = readStoredMetaField(dbHandle, HISTORY_META_KEYS.sourceDev);
const storedIno = readStoredMetaField(dbHandle, HISTORY_META_KEYS.sourceIno);
const storedBirthtimeMs = Number(readStoredMetaField(dbHandle, HISTORY_META_KEYS.sourceBirthtimeMs));
return storedPath === revision.path
&& storedDev === revision.dev
&& storedIno === revision.ino
&& storedBirthtimeMs === Number(revision.birthtimeMs);
}
/** Remove the index file and its WAL side files. */
function removeIndexFiles(path: string): void {
// Windows: a partially-opened handle from a failed `new Database` can hold
// the file briefly after the throw. Retry the unlink before recreating.
for (let attempt = 0; attempt < 5; attempt++) {
try {
for (const suffix of ["-wal", "-shm"] as const) {
try { unlinkSync(`${path}${suffix}`); } catch { /* sidecar may not exist */ }
}
if (existsSync(path)) unlinkSync(path);
return;
} catch {
if (attempt === 4) return;
Bun.sleepSync(50);
}
}
}
function destroyAndRecreate(path: string, reason: string): Database {
prepareIndexReplacement();
if (db) {
try { db.close(); } catch { /* already closed */ }
db = null;
}
removeIndexFiles(path);
const fresh = new Database(path, { create: true });
fresh.exec("PRAGMA journal_mode = WAL");
fresh.exec("PRAGMA busy_timeout = 5000");
resetAndCreateSchema(fresh);
setMeta(fresh, HISTORY_META_KEYS.lastError, reason);
db = fresh;
corruptHandle = null;
validatedBuildPath = null;
return fresh;
}
function openIndexDb(): Database {
if (integrityDrain) throw new IntegrityHandedOff(integrityDrain);
const path = indexDbPath();
if (db) return db;
let handle: Database | undefined;
try {
handle = new Database(path, { create: true });
handle.exec("PRAGMA journal_mode = WAL");
handle.exec("PRAGMA busy_timeout = 5000");
handle.exec(HISTORY_DDL);
if (metaValue(handle, HISTORY_META_KEYS.schemaVersion) === null) {
// Fresh database: record the schema version so the next refresh treats
// it as current instead of destroying the file we just created.
setMeta(handle, HISTORY_META_KEYS.schemaVersion, HISTORY_SCHEMA_VERSION);
setMeta(handle, HISTORY_META_KEYS.indexedOffset, 0);
setMeta(handle, HISTORY_META_KEYS.indexedRows, 0);
setMeta(handle, HISTORY_META_KEYS.builtAtMs, Date.now());
setMeta(handle, HISTORY_META_KEYS.lastError, "created");
}
} catch (error) {
// A partially-opened handle on a corrupt file can hold the OS lock on
// Windows; close it before the destructive recreate.
if (handle) {
try { handle.close(); } catch { /* already unusable */ }
}
if (!isHistoryIndexCorruption(error)) throw error;
handle = destroyAndRecreate(path, "unreadable database recreated");
}
dbPath = path;
db = handle;
if (validatedBuildPath === path) {
integrity.acceptRebuilt(handle, path);
validatedBuildPath = null;
}
return handle;
}
function ensureSchemaAndIdentity(dbHandle: Database): "ready" | "rebuilt" {
try {
if (corruptHandle === dbHandle) {
destroyAndRecreate(dbPath, "integrity check failed; index rebuilt");
return "rebuilt";
}
const storedVersion = metaValue(dbHandle, HISTORY_META_KEYS.schemaVersion);
if (storedVersion !== String(HISTORY_SCHEMA_VERSION)) {
destroyAndRecreate(dbPath, `schema version ${storedVersion ?? "missing"} -> ${HISTORY_SCHEMA_VERSION}`);
return "rebuilt";
}
const revision = sourceIdentity();
if (!sourceIdentityMatches(dbHandle, revision)) {
destroyAndRecreate(dbPath, "source identity changed; index rebuilt");
return "rebuilt";
}
const check = integrity.inspect(dbHandle, dbPath);
if (check.state === "pending") throw new IntegrityHandedOff(check.promise);
if (check.state === "unavailable") {
throw new RequestHistoryIndexBusyError("request-history integrity check unavailable");
}
if (check.state === "corrupt") {
corruptHandle = dbHandle;
destroyAndRecreate(dbPath, "integrity check failed; index rebuilt");
return "rebuilt";
}
return "ready";
} catch (error) {
if (!isHistoryIndexCorruption(error)) throw error;
// A file that opens but is not actually SQLite (or is mid-corruption)
// throws on the first statement; treat it as corrupt and rebuild.
corruptHandle = dbHandle;
integrity.markCorrupt(dbHandle);
destroyAndRecreate(dbPath, "index unreadable; rebuilt");
return "rebuilt";
}
}
function fullRebuild(dbHandle: Database, reason: string): void {
prepareIndexReplacement();
resetAndCreateSchema(dbHandle);
setMeta(dbHandle, HISTORY_META_KEYS.lastError, reason);
const path = usageLogPath();
const revision = sourceIdentity();
recordSourceMeta(dbHandle, revision);
if (!existsSync(path)) {
setMeta(dbHandle, HISTORY_META_KEYS.sourceSize, 0);
setMeta(dbHandle, HISTORY_META_KEYS.indexedOffset, 0);
setMeta(dbHandle, HISTORY_META_KEYS.indexedRows, 0);
setMeta(dbHandle, HISTORY_META_KEYS.builtAtMs, Date.now());
integrity.acceptRebuilt(dbHandle, dbPath);
corruptHandle = null;
return;
}
const inserted = ingestSourceTail(dbHandle, path, 0);
const current = readIndexedMeta(dbHandle);
setMeta(dbHandle, HISTORY_META_KEYS.indexedRows, inserted);
setMeta(dbHandle, HISTORY_META_KEYS.indexedOffset, Math.max(current.indexedOffset, 0));
setMeta(dbHandle, HISTORY_META_KEYS.builtAtMs, Date.now());
integrity.acceptRebuilt(dbHandle, dbPath);
corruptHandle = null;
}
/**
* Start a worker rebuild of `revision`, or return null when no worker can be
* spawned (the caller then rebuilds inline, as before #6990).
*/
function workerCoolingDown(): boolean {
return workerFailure !== null && Date.now() - workerFailure.at < WORKER_FAILURE_COOLDOWN_MS;
}
function startWorkerRebuild(reason: string, revision: UsageLogRevision): WorkerRebuild | null {
let job: RebuildJob;
try {
job = createRebuildJob();
} catch {
return null;
}
const lifetime = indexLifetime;
const indexPath = dbPath || indexDbPath();
const buildPath = buildFilePath(indexPath, process.pid, ++buildSequence);
const rebuild: { job: RebuildJob; promise: Promise<void> } = { job, promise: Promise.resolve() };
rebuild.promise = job.build(indexPath, buildPath, reason, revision)
.then(() => {
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
installBuild(buildPath, indexPath);
workerFailure = null;
})
.catch((error: unknown) => {
// A replaced ledger is retried at once; a close is nobody's failure.
if (lifetime === indexLifetime && !(error instanceof RequestHistoryIndexStaleError)) {
workerFailure = { at: Date.now(), error };
}
throw error;
})
.finally(() => {
if (workerRebuild === rebuild) workerRebuild = null;
void job.afterExit(() => removeBuildFiles(buildPath));
});
// A rebuild started by the routing-time entry has no awaiting reader.
rebuild.promise.catch(() => undefined);
workerRebuild = rebuild;
return rebuild;
}
/** Swap a complete worker build in for the current index file. */
function installBuild(buildPath: string, indexPath: string): void {
prepareIndexReplacement();
if (db) {
try { db.close(); } catch { /* already closed */ }
db = null;
}
removeIndexFiles(indexPath);
renameSync(buildPath, indexPath);
corruptHandle = null;
validatedBuildPath = indexPath;
}
/**
* Who is refreshing. Routing-time reads never rebuild a large ledger inline;
* async readers do once the worker has just failed, which is the pre-#6990
* behaviour and better than leaving history unavailable.
*/
type RefreshCaller = "routing" | "reader";
/** Full rebuild, on the worker when the ledger is large enough to stall the event loop. */
function rebuildFromLedger(handle: Database, reason: string, caller: RefreshCaller): void {
prepareIndexReplacement();
const revision = sourceIdentity();
if (revision !== null && Number(revision.size) >= workerRebuildMinBytes) {
if (workerCoolingDown()) {
if (caller === "routing") {
const error = workerFailure!.error;
const cause = error instanceof Error ? error.message : String(error);
throw new RequestHistoryIndexBusyError(`request-history index rebuild failed recently: ${cause}`);
}
} else {
const rebuild = startWorkerRebuild(reason, revision);
if (rebuild) throw new RebuildHandedOff(rebuild);
}
}
fullRebuild(handle, reason);
}
function refreshOnceLockedSync(caller: RefreshCaller): RequestHistoryIndexMeta {
if (workerRebuild) throw new RebuildHandedOff(workerRebuild);
openIndexDb();
const state = ensureSchemaAndIdentity(db!);
const handle = db!;
const revision = sourceIdentity();
if (state === "rebuilt") {
rebuildFromLedger(handle, "rebuilt after identity/schema mismatch", caller);
return metaFor(handle);
}
const current = readIndexedMeta(handle);
if (revision === null) {
// Source gone: the derived index must not outlive its canonical ledger.
if (current.indexedRows > 0) fullRebuild(handle, "source ledger missing; index reset");
return metaFor(handle);
}
const tailNextOffset = current.indexedOffset;
if (Number(revision.size) < tailNextOffset) {
// Truncated source: offsets no longer make sense.
rebuildFromLedger(handle, "source truncated; index rebuilt", caller);
return metaFor(handle);
}
if (tailNextOffset < Number(revision.size)) {
const inserted = ingestSourceTail(handle, revision.path, tailNextOffset);
// A clean tail ingest proves the index is healthy: clear any earlier
// rebuild marker so status readers can distinguish rebuilds from tails.
if (inserted > 0) setMeta(handle, HISTORY_META_KEYS.lastError, "");
}
return metaFor(handle);
}
function refreshLockedSync(caller: RefreshCaller): RequestHistoryIndexMeta {
try {
return refreshOnceLockedSync(caller);
} catch (error) {
// Metadata reads and incremental writes can encounter damage even between
// scheduled checks. Operational failures (busy, locked, I/O, full) propagate.
if (!isHistoryIndexCorruption(error)) throw error;
if (db) {
corruptHandle = db;
integrity.markCorrupt(db);
}
const handle = destroyAndRecreate(dbPath, "SQLite corruption; index rebuilt");
rebuildFromLedger(handle, "SQLite corruption; index rebuilt", caller);
return metaFor(handle);
}
}
/**
* Synchronous refresh for routing-time evidence reads (RI-06+). Never waits
* for a worker rebuild: while one runs (this call may start it), throws
* `RequestHistoryIndexBusyError`, which health scoring reads as unknown evidence.
*/
export function openRequestHistoryIndexSync(): RequestHistoryIndexMeta {
if (manualRebuild) throw new RequestHistoryIndexBusyError();
try {
return refreshLockedSync("routing");
} catch (error) {
if (error instanceof RebuildHandedOff || error instanceof IntegrityHandedOff) throw new RequestHistoryIndexBusyError();
throw error;
}
}
async function refreshWaitingForWorker(fromManualRebuild = false): Promise<RequestHistoryIndexMeta> {
const lifetime = indexLifetime;
for (let builds = 0; ; ) {
if (manualRebuild && !fromManualRebuild) {
await manualRebuild;
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
continue;
}
let handedOff: RebuildHandedOff;
try {
return refreshLockedSync("reader");
} catch (error) {
if (error instanceof IntegrityHandedOff) {
await error.promise;
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
continue;
}
if (!(error instanceof RebuildHandedOff)) throw error;
handedOff = error;
}
// Only a refresh that needs yet another build hits the limit; one that
// follows a successful build returns that index above.
if (builds >= maxAsyncRefreshBuilds) throw new RequestHistoryIndexBusyError();
let failure: unknown = null;
await handedOff.rebuild.promise.catch((error: unknown) => { failure = error ?? new Error("rebuild failed"); });
builds += 1;
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
if (failure !== null && builds >= maxAsyncRefreshBuilds) throw failure;
}
}
/**
* Open (and refresh) the index. Single-flight: concurrent callers share one
* refresh, and wait for a worker rebuild without blocking the event loop.
* Missing/corrupt index or ledger state is repaired or reflected in the
* returned meta; a close during a rebuild rejects with
* `RequestHistoryIndexClosedError`.
*/
export function openRequestHistoryIndex(): Promise<RequestHistoryIndexMeta> {
if (!openPromise) {
const pending = refreshWaitingForWorker().finally(() => {
if (openPromise === pending) openPromise = null;
});
openPromise = pending;
}
return openPromise;
}
export function closeRequestHistoryIndex(): void {
indexLifetime += 1;
stopIntegrityScan();
corruptHandle = null;
validatedBuildPath = null;
const rebuild = workerRebuild;
workerRebuild = null;
workerFailure = null;
// The rebuild's own settlement removes its build files once the thread exits.
if (rebuild) void rebuild.job.dispose();
if (db) {
try { db.close(); } catch { /* ignore */ }
db = null;
}
openPromise = null;
manualRebuild = null;
}
/** Force a full rebuild from the canonical ledger (CLI / tests). */
export function rebuildRequestHistoryIndex(): Promise<RequestHistoryIndexMeta> {
if (!manualRebuild) {
const pending = rebuildManually(indexLifetime).finally(() => {
if (manualRebuild === pending) manualRebuild = null;
});
manualRebuild = pending;
}
return manualRebuild;
}
async function rebuildManually(lifetime: number): Promise<RequestHistoryIndexMeta> {
const draining = stopIntegrityScan();
if (draining) await draining;
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
while (workerRebuild) await workerRebuild.promise.catch(() => undefined);
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
const handle = openIndexDb();
const revision = sourceIdentity();
if (revision !== null && Number(revision.size) >= workerRebuildMinBytes) {
workerFailure = null;
const rebuild = startWorkerRebuild("manual rebuild requested", revision);
if (rebuild) {
try {
await rebuild.promise;
if (lifetime !== indexLifetime) throw new RequestHistoryIndexClosedError();
return refreshWaitingForWorker(true);
} catch (error) {
// A close is final; any other worker failure falls back to the inline rebuild below.
if (lifetime !== indexLifetime || error instanceof RequestHistoryIndexClosedError) throw error;
}
fullRebuild(openIndexDb(), "manual rebuild requested");
return metaFor(db!);
}
}
fullRebuild(handle, "manual rebuild requested");
return metaFor(handle);
}
type HistoryQueryRow = {
row_json: string;
timestamp?: number;
request_id?: string;
};
function queryRows(
handle: Database,
filters: RequestHistoryFilters,
cursor: HistoryCursor | null,
limit: number,
): { rows: Array<HistoryQueryRow>; fetched: number } {
const where: string[] = [];
const values: Array<string | number> = [];
const add = (clause: string, value: string | number) => {
where.push(clause);
values.push(value);
};
if (filters.provider !== undefined) add("provider = ?", filters.provider);
if (filters.model !== undefined) add("model = ?", filters.model);
// Rows store the bounded encoded form, so the lookup value must be encoded the
// same way — short selectors encode to themselves and still match verbatim.
if (filters.requestedModel !== undefined) add("requested_model = ?", encodePersistedRequestedModel(filters.requestedModel));
if (filters.status !== undefined) add("status = ?", filters.status);
if (filters.conversationId !== undefined) add("conversation_id = ?", filters.conversationId);
if (filters.surface !== undefined) add("surface = ?", filters.surface);
if (filters.inboundProtocol !== undefined) add("inbound_protocol = ?", filters.inboundProtocol);
if (filters.apiKeyId !== undefined) add("api_key_id = ?", filters.apiKeyId);
if (filters.profileId !== undefined) add("profile_id = ?", filters.profileId);
if (filters.fallback !== undefined) add("fallback = ?", filters.fallback ? 1 : 0);
if (filters.from !== undefined) add("timestamp >= ?", filters.from);
if (filters.to !== undefined) add("timestamp <= ?", filters.to);
if (cursor) {
where.push("(timestamp < ? OR (timestamp = ? AND request_id < ?))");
values.push(cursor.t, cursor.t, cursor.i);
}
const whereSql = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
const rows = handle.query(
`SELECT row_json, timestamp, request_id FROM requests${whereSql} ORDER BY timestamp DESC, request_id DESC LIMIT ?`,
).all(...values, limit + 1) as Array<HistoryQueryRow>;
return { rows, fetched: rows.length };
}
function requireDb(): Database {
const handle = db;
if (!handle) throw new Error("request-history index is not open");
return handle;
}
/** Invalidate only the live generation, including errors from routing's synchronous reads. */
export function reportRequestHistoryCorruption(error: unknown, handle: Database): boolean {
if (!isHistoryIndexCorruption(error)) return false;
if (db === handle) {
corruptHandle = handle;
integrity.markCorrupt(handle);
}
return true;
}
/** Read-only operations may retry once after repair; ordinary SQLite failures propagate. */
export async function withRequestHistoryRead<T>(read: (handle: Database, meta: RequestHistoryIndexMeta) => T): Promise<T> {
for (let attempt = 0; ; attempt++) {
const meta = await openRequestHistoryIndex();
const handle = requireDb();
try {
return read(handle, meta);
} catch (error) {
if (!reportRequestHistoryCorruption(error, handle) || attempt > 0) throw error;
}
}
}
function hydrateRow(row: HistoryQueryRow | undefined): PersistedUsageEntry | null {
if (!row) return null;
try {
const parsed = JSON.parse(row.row_json) as PersistedUsageEntry;
if (parsed && typeof parsed === "object" && typeof parsed.requestId === "string") {
return normalizeUsageEntryForTest(parsed);
}
} catch {
/* defensive: a damaged row is skipped, canonical ledger unaffected */
}
return null;
}
export async function queryRequestHistory(
filters: RequestHistoryFilters,
rawCursor: string | null | undefined,
pageSize: number | undefined,
): Promise<RequestHistoryPage> {
const cursor = decodeHistoryCursor(rawCursor);
if (rawCursor !== null && rawCursor !== undefined && cursor === null) {
throw new InvalidCursorError();
}
const limit = Math.min(
Math.max(1, Math.trunc(pageSize ?? REQUEST_HISTORY_DEFAULT_PAGE_SIZE)),
REQUEST_HISTORY_MAX_PAGE_SIZE,
);
const { rows, fetched, meta } = await withRequestHistoryRead((handle, meta) => ({
...queryRows(handle, filters, cursor, limit), meta,
}));
const hasMore = fetched > limit;
const pageRows = rows.slice(0, limit);
const entries: PersistedUsageEntry[] = [];
for (const row of pageRows) {
const entry = hydrateRow(row);
if (entry) entries.push(entry);
}
let nextCursor: string | undefined;
if (hasMore && pageRows.length > 0) {
const last = pageRows[pageRows.length - 1]!;
nextCursor = encodeHistoryCursor({ t: last.timestamp!, i: last.request_id! });
}
return { rows: entries, ...(nextCursor ? { nextCursor } : {}), hasMore, meta };
}
export async function requestHistoryRowById(requestId: string): Promise<PersistedUsageEntry | null> {
const row = await withRequestHistoryRead(handle => handle.query("SELECT row_json FROM requests WHERE request_id = ?").get(requestId) as
| { row_json: string }
| undefined);
return hydrateRow(row);
}
export async function requestHistoryIndexStatus(): Promise<RequestHistoryIndexMeta> {
return openRequestHistoryIndex();
}
/**
* Raw handle for analytics-style queries. Callers must await
* `openRequestHistoryIndex()` first; the handle is valid until
* `closeRequestHistoryIndex()`.
*/
export function requestHistoryDb(): Database {
if (!db) throw new Error("request-history index is not open");
return db;
}