@senpi/runtime 3.0.123 → 3.0.124

package/dist/telemetry/live-telemetry.d.ts

@@ -1,238 +0,0 @@
-/**
- * The publisher: the piece that turns the buffer and the three builders into frames on the gateway
- * websocket, plus the snapshot a client reads when it connects.
- *
- * Two things about the transport shape the whole module:
- * - The only route to the websocket is a captured `context.broadcast`, and `context` exists only
- *   inside a gateway RPC handler — the plugin api object has no push surface at all. So the handle is
- *   captured from the FIRST request of ANY kind, not only from the subscribe method: a box whose
- *   client never calls subscribe would otherwise hold nothing to publish through, silently.
- * - The gateway drops any event name that does not start with `plugin.`, and closes the socket with
- *   1008 for a slow client unless the call passes `dropIfSlow`. Both are enforced here rather than at
- *   each call site, because either mistake is invisible until a client is missing frames.
- *
- * Three cadences, because the three payloads cost different things to build:
- * - timeline, on the flush tick — a drain plus a filter, cheap, and the one a live screen feels.
- * - stats, on the sample tick — a scan of the whole held window and an async read of every runtime's
- *   health and system state, so it runs an order of magnitude less often.
- * - topology, on the sample tick but published only when it changes — it rides the same gather as
- *   stats, and nothing in the plugin signals a topology change, so "on change" means polled and
- *   diffed rather than pushed.
- *
- * The snapshot is what stops a client that joins mid-life from seeing an empty screen: it is read
- * from the buffer's held window, which the flush drain never evicts.
- *
- * A fourth broadcast sits outside all of that. The tick frame is a LEVEL — the latest finished run of
- * each scanner, most of which produce nothing and so leave no record anywhere — and it is published
- * on a window of its own, driven by the runs themselves rather than by a timer that is always
- * running. It carries no seq, is never buffered, is not in the snapshot and is not replayed, because
- * a client that misses one is made whole by the next one. Keeping it off the buffer is the point: the
- * buffer is where decision records live, and per-tick facts would evict them.
- *
- * Everything that leaves the box is scrubbed here. `logger.event` redacts its `redact` slot and not
- * its `attributes`, which is sound for the disk ring — that never leaves — but not for a stream a
- * browser reads. There are four ways out — the timeline frame, the stats frame, the tick frame and
- * the snapshot that carries one of the first three — and two kinds of free text between them, so the
- * scrub sits in two places:
- * - {@link toWireRecord} for a timeline record's attributes. It is what makes the flush tick
- *   asynchronous and gives it an in-flight guard.
- * - {@link scrubScannerText} for text a scanner process authored: the scanner state's three
- *   free-text fields, via {@link scrubStatsPayload}, which reach both the stats frame and the
- *   snapshot; and a tick's `outcome`. Their content is a stringified throwable or status from a
- *   scanner process, so they are the strings on the wire with no bound of their own and they are
- *   capped as well as scrubbed.
- *
- * The topology payload carries no captured text: its `name` and `scannerId` are operator-authored
- * config keys the client joins on, and the scanner `config` that could hold a resolved secret is
- * never copied onto it.
- */
-import type { EventName } from "../utils/event-catalog.js";
-import { type TimelineBuffer } from "./timeline-buffer.js";
-import { type ScannerRunFacts } from "./scanner-tick-feed.js";
-import { type TickFramePayload, type TickTelemetryConfig } from "./tick-frame.js";
-import { type ScannerStateSnapshot, type ScannerStatsPayload } from "./scanner-stats.js";
-import { type IdMembership, type RuntimeHealthLike, type StrategyTopologyPayload, type TopologyStrategySource } from "./strategy-topology.js";
-/** The gateway drops any broadcast whose name does not carry this prefix, with no error. */
-export declare const EVENT_TIMELINE = "plugin.senpi.timeline";
-export declare const EVENT_STATS = "plugin.senpi.scanner.stats";
-export declare const EVENT_TOPOLOGY = "plugin.senpi.strategies";
-export declare const EVENT_TICK = "plugin.senpi.tick";
-/**
- * Byte ceiling for one frame. A frame published here travels southbound — gateway to bridge — and
- * meets the bridge's southbound read limit, 1 MiB unless a deployment sets its own; a frame past it
- * takes the whole connection down rather than costing the one frame. The budget is set far inside
- * that: the payload envelope the gateway wraps around ours, and the growth of a single record's
- * attribute bag, both have to fit in the margin, and neither is measured here.
- */
-export declare const MAX_FRAME_BYTES: number;
-/**
- * Character ceiling for one of the scanner state's free-text fields on the wire — `lastRunReason`,
- * `lastRunStatus` and `degradedReason`.
- *
- * These carry a stringified throwable from a scanner process, which nothing upstream bounds: an HTTP
- * client's error message alone runs to a few hundred characters and a stack-bearing one to
- * kilobytes, once per scanner per sample. 1024 holds the sentence that says what failed — the error
- * type, the operation and the endpoint. It is also what keeps the payload bounded at all: this frame
- * is published whole, with no splitting of the kind the timeline does, so two hundred scanners each
- * reporting a 4 KiB error in every one of the three fields serialise to about 1.7 MB — past the read
- * limit that ends the connection — and at this cap the same box lands under half of it.
- */
-export declare const MAX_SCANNER_TEXT_CHARS = 1024;
-/**
- * What one of those fields reads as when its text could not be scrubbed — no redactor registered, or
- * a redactor that threw.
- *
- * Not `null` and not an absent key: the producer reporting no reason and this box withholding one it
- * cannot vouch for are different facts, and a summary screen is read as if they were the same.
- */
-export declare const SCANNER_TEXT_WITHHELD = "[withheld: not scrubbed]";
-/** Flush cadence for the timeline. A live screen feels this number. */
-export declare const DEFAULT_FLUSH_INTERVAL_MS = 1000;
-/**
- * Sample cadence for stats and topology. Both are built from one async read of every runtime's health
- * and system state, so they share a tick. Five seconds is roughly a third of the default bucket width
- * — fast enough that a counter visibly moves and a hung scan is seen while it is still running, slow
- * enough that the per-scanner store read behind the system state is not a poll loop.
- */
-export declare const DEFAULT_SAMPLE_INTERVAL_MS = 5000;
-/**
- * How long the first tick of a frame waits for the ticks that land beside it.
- *
- * Scanners on a box share cadences — a recipe gives several of them the same interval, and every
- * runtime starts them within the same boot — so their terminal callbacks arrive in clumps. A frame per
- * callback would put one websocket write per scanner per cadence on the wire for a payload of seven
- * scalars; one window collapses a clump into a single write. It is short enough that the level a
- * dashboard shows is still the current one, and it is not the timeline's flush tick because a tick
- * frame must not wait behind a scrub of hundreds of records.
- */
-export declare const TICK_COALESCE_MS = 250;
-/**
- * The PUBLICATION list: what leaves on the timeline event. A name being on this list AND on the
- * admission list is the normal case, not a duplication — `signal.outcome` is the decision row the feed
- * is built around and the source of `opens`/`closes`/`skips`, and the two `scaffold.tick_*` names are
- * the source of `errors` and the rows behind the Errors filter. A failing external scanner has to
- * leave a visible line, not only a number that silently goes up.
- *
- * The two lists are separate so admission can be widened for a counter the feed does not display,
- * which is the direction that has to stay open: the display filter belongs here at publish time,
- * where it is still recoverable, never at append time, where it is not. Today nothing is admitted for
- * counting alone, so the sets are equal — the seam is what matters, not the difference.
- */
-export declare const PUBLISHED_EVENT_NAMES: ReadonlySet<EventName>;
-/**
- * The share of its own interval a tick may take before it is warned about. A fraction rather than a
- * constant, so a deployment that changes a cadence gets a proportional threshold: 250ms on the
- * one-second timeline flush, 1.25s on the five-second sample.
- *
- * A quarter, not a whole interval. Both ticks share an event loop with the serial trading path, so a
- * tick holding it for a quarter of its own period is already adding latency to trading; and a tick
- * that fills its interval has already started stacking on the next one, which is too late to be told.
- */
-export declare const SLOW_TICK_FRACTION = 0.25;
-/**
- * How often the timing summary is logged, and the floor between two slow-tick warns of the same kind.
- * The flush tick runs every second, so a line per tick would be tens of thousands a day for numbers
- * that only mean anything aggregated — and a repeating tick that is slow is slow every time.
- */
-export declare const TIMING_REPORT_INTERVAL_MS = 60000;
-export interface GatewayBroadcastOpts {
-    dropIfSlow?: boolean;
-    stateVersion?: number;
-}
-export type GatewayBroadcastFn = (event: string, payload: unknown, opts?: GatewayBroadcastOpts) => void;
-/** One record as it goes on the wire. */
-export interface TimelineWireRecord {
-    seq: number;
-    ts: number;
-    name: string;
-    level: string;
-    address: string;
-    scannerId?: string;
-    body: string;
-    attrs: Record<string, string | number | boolean>;
-}
-export interface TimelinePayload {
-    v: 1;
-    epoch: string;
-    batchSeq: number;
-    records: TimelineWireRecord[];
-}
-/**
- * A tick frame, in the compact wire shape {@link ./tick-frame.js} builds: a per-frame string
- * dictionary, index references into it, times as offsets from one `t0`, and short keys.
- *
- * It carries no `batchSeq` and its entries carry no `seq`, because there is nothing to resume: this
- * is the current state of a set of scanners, and a client that misses a frame is made whole by the
- * next one rather than by a replay.
- */
-export type ScannerTickPayload = TickFramePayload;
-export interface TelemetrySnapshot {
-    epoch: string;
-    topology: StrategyTopologyPayload;
-    stats: ScannerStatsPayload;
-    recent: TimelinePayload;
-    /**
-     * The client asked to resume from a cursor inside THIS epoch whose successor is no longer held, or
-     * the window it is owed did not fit one frame. Either way there is a gap this response cannot fill,
-     * and only the box knows it: `recent.records` alone looks like a normal short window.
-     *
-     * A cursor from another epoch is not truncation. It buys nothing, so the whole retained window is
-     * served — which is the most this box could ever serve, and so nothing was withheld.
-     */
-    truncated: boolean;
-}
-/** Everything the two builders need that the buffer cannot supply, gathered once per tick. */
-export interface TelemetryFacts {
-    strategies: TopologyStrategySource[];
-    runningRuntimeIds: IdMembership;
-    unwiredRuntimeIds: IdMembership;
-    readHealth?: (runtimeId: string) => RuntimeHealthLike | undefined;
-    scannerState: ScannerStateSnapshot[];
-}
-export interface LiveTelemetryOptions {
-    /** Defaults to the process buffer — one per process, shared by every address. */
-    buffer?: TimelineBuffer;
-    collectFacts: () => Promise<TelemetryFacts>;
-    flushIntervalMs?: number;
-    sampleIntervalMs?: number;
-    now?: () => number;
-    /**
-     * Monotonic millisecond reader for tick durations. Defaults to `performance.now`; `now` is wall
-     * clock and can step backwards under NTP, which would report a negative tick.
-     */
-    monotonicMs?: () => number;
-    /**
-     * How much detail a tick frame carries, as the plugin config states it. Plugin config and not an
-     * env var on purpose: `register()` re-reads plugin config on a config reload, while a service
-     * variable change restarts the container. An unusable value warns and falls back rather than
-     * throwing — a configuration mistake must not be why a box goes dark.
-     */
-    tickTelemetry?: TickTelemetryConfig;
-}
-export interface LiveTelemetry {
-    readonly epoch: string;
-    /** Take the broadcast handle off a gateway request context if we do not hold one yet. */
-    captureBroadcast(ctx: unknown, methodName: string): void;
-    /** `afterSeq` counts only when `afterEpoch` is the epoch this box is running. */
-    snapshot(params?: {
-        afterEpoch?: unknown;
-        afterSeq?: unknown;
-    }): Promise<TelemetrySnapshot>;
-    /** One flush tick: drain, filter to the publication list, scrub, frame, broadcast. */
-    flushTimeline(): Promise<void>;
-    /** One sample tick: stats always, topology when it changed. */
-    sample(): Promise<void>;
-    /**
-     * Take one finished scanner run for the next tick frame. Synchronous, never throws, and returns
-     * without building anything when no client has ever connected. `start` registers this as the
-     * process tick sink; it is on the interface so a caller holding the publisher can drive it directly.
-     */
-    recordTick(run: ScannerRunFacts, startedAt: number | undefined, finishedAt: number): void;
-    /** Publish whatever the current coalescing window holds, now. */
-    flushTicks(): Promise<void>;
-    start(): void;
-    /** Clear every timer, release the tick sink, drop the captured handle, and empty the timelineBuffer(). */
-    stop(): void;
-}
-export declare function createLiveTelemetry(options: LiveTelemetryOptions): LiveTelemetry;
-//# sourceMappingURL=live-telemetry.d.ts.map

package/dist/telemetry/live-telemetry.d.ts.map

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