@allocator-one/rcl 4.4.19

package/dist/telemetry/outbox.d.ts

@@ -0,0 +1,166 @@
+import { type ArtifactKind, type RunEnvelope } from './envelope.js';
+import { type WireEvent } from './events.js';
+import type { HarnessSink } from './sink.js';
+/**
+ * Failed deliveries wait here (epic IO-12475, section 8.4): one directory
+ * per run under `<data dir>/outbox/`, holding the envelope, the artifacts
+ * and any events that could not be sent. Flushed at the start of every rcl
+ * command (bounded) and by `rcl telemetry flush` (to completion). Retried
+ * deliveries carry `delivery: {mode: retried, spooled_at}` and keep their
+ * original ids, so the server dedupes them.
+ *
+ * Nothing is evicted silently. Above the size cap the outbox stops spooling
+ * artifacts — envelopes and events are small and always kept — and records
+ * each affected run as a `loss` event of its own (stable id), reported on
+ * the next flush that reaches the server. A file that cannot be read is
+ * never treated as delivered: a torn file marks its entry failed, a
+ * transient read error leaves it for the next flush.
+ *
+ * Concurrency: two rcl processes may touch the outbox at once (a review
+ * finishing while another command flushes). Files are written atomically
+ * (temp + rename) and re-read before use; a flush removes only the files it
+ * delivered and never a directory that gained content meanwhile; an entry
+ * another process removed first counts as delivered by that process. The
+ * size cap is best-effort across processes, which is what a client-side
+ * courtesy cap needs to be. An entry whose spool was interrupted (no
+ * `meta.json` after a grace period) is listed as failed, never hidden.
+ */
+export declare const OUTBOX_DIR = "outbox";
+export declare const DEFAULT_OUTBOX_CAP_BYTES: number;
+/** A directory without `meta.json` older than this is an interrupted spool, not one in progress. */
+export declare const INTERRUPTED_SPOOL_MS: number;
+export declare class OutboxError extends Error {
+    constructor(message: string);
+}
+export interface OutboxMeta {
+    kind: 'run' | 'events';
+    spooled_at: string;
+    attempts: number;
+    /** The envelope was acknowledged; only artifacts/events remain. */
+    envelope_delivered?: boolean;
+    run_url?: string;
+    last_error?: string;
+}
+export interface OutboxEntry {
+    id: string;
+    meta: OutboxMeta;
+    bytes: number;
+    artifacts: ArtifactKind[];
+    events: number;
+    failed?: {
+        at: string;
+        reason: string;
+    };
+}
+export interface SpoolRunInput {
+    runId: string;
+    envelope: RunEnvelope;
+    /** The artifacts still to upload; when given, files of kinds not listed are removed (they were delivered). */
+    artifacts?: Partial<Record<ArtifactKind, string>>;
+    events?: WireEvent[];
+    /** The envelope already landed; spool artifacts/events only. */
+    envelopeDelivered?: boolean;
+    runUrl?: string;
+}
+export interface SpoolResult {
+    spooled: boolean;
+    /** Artifacts were not spooled because the outbox is over its cap. */
+    artifactsDropped: ArtifactKind[];
+}
+export interface FlushOptions {
+    /** Stop starting new requests after this many milliseconds. */
+    deadlineMs?: number;
+    /** Flush one entry only. */
+    runId?: string;
+    now?: () => number;
+}
+export interface FlushSummary {
+    delivered: string[];
+    remaining: string[];
+    /** Entries the server refused for good, left in place with a marker. */
+    failed: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Entries removed because the organization has switched review evidence off: nothing to keep. */
+    dropped: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Flushing stopped early: the server was unreachable or the deadline passed. */
+    stopped?: 'unavailable' | 'deadline';
+    /** Pending loss reports delivered in this flush. */
+    lossReported?: number;
+    /** Loss reports still waiting after this flush (unreachable, out of time, or not all acknowledged). */
+    lossPending?: number;
+}
+export declare class Outbox {
+    readonly dir: string;
+    private readonly capBytes;
+    private readonly now;
+    constructor(dir?: string, options?: {
+        capBytes?: number;
+        now?: () => number;
+    });
+    totalBytes(): Promise<number>;
+    /**
+     * Entry ids are run UUIDs or `events-<uuid>`, lower-cased so one id spelt
+     * two ways is one entry; nothing else becomes a path.
+     */
+    private entryDir;
+    /** Spool a run whose delivery failed (or whose artifacts could not be uploaded). */
+    spoolRun(input: SpoolRunInput): Promise<SpoolResult>;
+    /** Spool events that belong to no run delivery of their own (converge commands). */
+    spoolEvents(events: WireEvent[]): Promise<string>;
+    /** One file per loss, holding the event that will report it (stable id, no read-modify-write). */
+    private recordLoss;
+    /** The loss events still to report. */
+    pendingLoss(): Promise<WireEvent[]>;
+    /** Loss reports the server refused for good, kept on disk (`<id>.json.refused`) and never retried. */
+    refusedLoss(): Promise<string[]>;
+    /**
+     * Loss files whose name is `<uuid>.json` and whose event carries that very
+     * id — only such a file ever becomes a path again. Anything else in the
+     * directory is ignored, never reported and never touched.
+     */
+    private pendingLossFiles;
+    /**
+     * Every entry, or — given `only` — that one entry when it exists (a targeted
+     * flush reads nothing else). Sizes are walked only when asked for: a flush
+     * never reads them, `rcl telemetry status` does.
+     */
+    list(only?: string, options?: {
+        sizes?: boolean;
+    }): Promise<OutboxEntry[]>;
+    /**
+     * Deliver what waits. Stops at the first unreachable response (the server
+     * is down; hammering it helps nobody) or when the deadline passes. Entries
+     * the server refuses for good are marked and skipped afterwards. Pending
+     * loss reports go out on every flush that reached the server.
+     */
+    flush(sink: HarnessSink, options?: FlushOptions): Promise<FlushSummary>;
+    private flushEntry;
+    /**
+     * Everything this flush read has been delivered: remove exactly those
+     * files, then the directory — which stays, listed, if another process
+     * put something new into it meanwhile. Returns whether the directory went.
+     */
+    private finish;
+    /** Temp files a crashed writer left behind (a live writer's are younger than the grace period). */
+    private sweepTempFiles;
+    /** The organization switched evidence off: nothing in this entry will ever be wanted. */
+    private drop;
+    private markFailed;
+    /**
+     * Report pending losses with their stable ids, in bounded batches. A batch's
+     * files go once the server has taken every event in it (inserted or
+     * already known), or when the organization has switched evidence off
+     * (there is nobody to report to). A batch the server refuses is kept under
+     * a `.refused` suffix — visible on disk and in `rcl telemetry status`,
+     * never retried, never counted. An unreachable server or an expired
+     * deadline ends the pass with the rest still pending.
+     */
+    private reportLoss;
+    /** Remove one entry by id (validated like every other id). */
+    remove(id: string): Promise<void>;
+}