import type { AgentEvent, Session } from "../schema/index.ts"; import type { BlobStore, Config, IndexStore } from "../core/types.ts"; import type { ResourceLogs, ResourceSpans } from "../otel/model.ts"; import type { SpanEnricher } from "../otel/map.ts"; import { type Signal } from "../otel/receiver.ts"; import type { Logger } from "./log.ts"; import type { ServeMetrics } from "./metrics.ts"; export declare const DIRTY_KEY = "serve:dirty"; export type QueueEntry = { kind: "otlp"; project: string; signal: Signal; decoded: ResourceSpans[] | ResourceLogs[]; items: number; bytes: number; } | { kind: "native"; project: string; events: AgentEvent[]; items: number; bytes: number; }; export interface EntryResult { /** Events this request newly stored (see apportioning in `tick`). */ inserted: number; /** Events written (after mapping), new or not. */ stored: number; /** OTLP spans/log records the mapper rejected. */ rejected: number; message: string; } /** One request's share of a committed tick (see IngestQueueOptions.onCommit). */ export interface CommittedEntry { entry: QueueEntry; /** Events as stored: mapped, scoped to the project, redacted, priced. */ events: AgentEvent[]; /** * The ones of `events` this commit newly stored: what goes on to [[sinks]], so * a retried request is mirrored once. An id repeated inside one tick belongs * to the first request that carries it. */ insertedEvents: AgentEvent[]; /** The rebuilt sessions those events touch. */ sessions: Session[]; } export interface IngestQueueOptions { store: IndexStore; blobs: BlobStore; /** capture (redaction, metadata mode, maxInlineBytes) and pricing come from here. */ config: Config; maxEvents: number; maxBytes: number; /** Events per writer tick (default 5,000). */ tickEvents?: number; metrics?: ServeMetrics; log?: Logger; /** OTLP span enrichment (default: the receiver's defaultEnricher). */ enrichSpan?: SpanEnricher | false; /** Called once when the writer lease is found lost (see setWritable); the queue is standby by then. */ onLeaseLost?: (err: Error) => void; /** * Called after a tick committed (events stored, sessions rebuilt) and its * requests were answered: the OTLP forward and sink mirroring. Synchronous * hand-off only; errors are logged and never fail ingest. */ onCommit?: (committed: CommittedEntry[]) => void; /** * Keep the sessions a tick writes in the `serve:dirty` kv until they are * rebuilt, so the next writer repairs a crash (default true). The fetch * handler turns it off: many instances write at once, and a failed request * answers 503 and its retry rebuilds the same sessions. */ dirtyKv?: boolean; } export declare class IngestQueue { private readonly o; private readonly pending; private readonly exclusive; private readonly pipelines; private readonly redactor; private readonly prices; private readonly metadata; /** Sessions written by a failed tick, rebuilt by the next good one. */ private readonly dirty; /** Which events a tick newly stored, for onCommit; it also carries the ones a failed tick stored to the retry. */ private readonly insertedEvents; private queuedEvents; private queuedBytes; /** Observed write rate, events/second (EWMA). */ private rate; private writable; /** Throws once the writer lease was taken over (WriterLock.assertHeld). */ private fence; private closing; private stopped; private wake; private loop; private busy; constructor(o: IngestQueueOptions); get depth(): { events: number; bytes: number; max: number; }; /** * True while this replica may write (it holds the writer lock). `fence` * throws once the lock was lost: it is checked before every tick and * exclusive job, so a writer whose lease another replica broke never commits * another write (see leaseLost). */ setWritable(on: boolean, fence?: () => void): void; get isWritable(): boolean; /** Seconds a throttled client should wait: queued / write rate, 1..30, default 2. */ retryAfter(): number; /** Admits a request (or throws 429/503) and resolves once it is committed. */ submit(entry: QueueEntry): Promise; /** Runs fn between writer ticks (retention, crash repair), so it never races a write. */ runExclusive(fn: () => Promise): Promise; /** Rebuilds the sessions a crashed writer left in `serve:dirty`. Returns how many. */ repair(): Promise; start(): void; /** * Stops admitting, lets the writer finish what is queued for up to timeoutMs, * then fails whatever is left with 503 (clients retry). Resolves when the writer stopped. */ drain(timeoutMs: number): Promise<{ drained: boolean; left: number; }>; private kick; private release; /** * Undefined while this replica still holds the writer lease. Once it is lost: * standby, every queued request and job fails with 503 (clients retry against * the new writer), onLeaseLost fires, and the error is returned. */ private leaseLost; private run; private pipeline; private strip; private prepare; private tick; }