@hediet/linkrpc-hub 0.0.1

package/dist/chunks/nodeTransit-cmtZgdpW.d.ts

@@ -0,0 +1,226 @@
+import { IMessageTransport, JsonValue, RequestId } from "@hediet/linkrpc";
+import { TrafficTransitEvent } from "@hediet/linkrpc/inspection";
+//#region src/hub/server/nodeTransit.d.ts
+/** What kind of message crossed the node. Cancel/ping/pong are stream controls. */
+type TransitKind = 'request' | 'notification' | 'response' | 'stream';
+/** What the node did with the message. */
+type TransitDisposition = 'forwarded' | 'consumed' | 'dropped' | 'unroutable';
+/** One side of a transit: the edge, plus the request id as it appears there. */
+interface TransitEndpoint {
+  readonly edgeId: string;
+  /** Stable topology port id. Older/custom emitters may omit it. */
+  readonly portId?: string;
+  /** JSON-RPC request id on this edge. Absent for notifications. */
+  readonly requestId?: RequestId;
+}
+/** Wire-shaped error mirrored onto a `response` transit. */
+interface TransitError {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: JsonValue;
+}
+/**
+ * A single message passing through a node. `in` absent ⇒ the message
+ * originated here; `out` absent ⇒ it was consumed or dropped here.
+ */
+interface NodeTransit {
+  readonly timeMs: number;
+  readonly nodeId: string;
+  readonly in?: TransitEndpoint;
+  readonly out?: TransitEndpoint;
+  readonly disposition: TransitDisposition;
+  readonly kind: TransitKind;
+  readonly method?: string;
+  readonly params?: JsonValue;
+  readonly result?: JsonValue;
+  readonly error?: TransitError;
+}
+/** Sink for node transits. Synchronous; keep it cheap. */
+type NodeTransitObserver = (transit: NodeTransit) => void;
+/** Status of a coalesced flow at the moment it is reported. */
+type FlowStatus = 'completed' | 'failed' | 'pending' | 'dropped' | 'unroutable';
+/** One stream frame (`$stream::send`) attached to a flow, in arrival order. */
+interface FlowStreamMessage {
+  readonly timeMs: number;
+  /** `toCaller` = callee→caller (progress); `toCallee` = caller→callee (input/cancel). */
+  readonly dir: 'toCaller' | 'toCallee';
+  /** Reserved control verb (`cancel`/`ping`/`pong`), if this is a control frame. */
+  readonly control?: string;
+  /** App stream payload (typed per call by the originating method's stream schema). */
+  readonly payload?: JsonValue;
+}
+/** A coalesced logical operation, reported once (or twice: partial → final). */
+interface FlowSummary {
+  readonly id: string;
+  readonly kind: TransitKind;
+  readonly method: string | undefined;
+  readonly params: JsonValue | undefined;
+  readonly status: FlowStatus;
+  readonly result?: JsonValue;
+  readonly error?: TransitError;
+  readonly startTs: number;
+  readonly endTs: number | undefined;
+  readonly durationMs: number;
+  /** Ordered, interleaved edge/node labels the message traversed. */
+  readonly path: readonly string[];
+  /** True when reported while still in flight (slow / stuck). */
+  readonly partial: boolean;
+  /**
+   * Stream frames (`$stream::send`) seen on this flow, in arrival order. Only
+   * populated when the hub is configured to emit stream transits (debug+); an
+   * absent/empty array means "not captured", not "no streaming happened".
+   */
+  readonly stream?: readonly FlowStreamMessage[];
+}
+interface TransitAggregatorOptions {
+  /** Called once a flow settles, or once when it is first reported partial. */
+  readonly onFlow: (summary: FlowSummary) => void;
+  /** Quiet-period before a flow is flushed. Default 50ms. */
+  readonly flushDelayMs?: number;
+  /** Drop an unsettled flow after this long (leak guard). Default 5min. */
+  readonly giveUpMs?: number;
+  /**
+   * How long after a request starts its stream frames stay attached to that
+   * request's flow. Frames within this window fold into the request summary;
+   * later frames are logged independently (live), so a long-running request's
+   * stream output is visible promptly and doesn't accumulate unbounded in the
+   * pending flow. Default 1000ms.
+   */
+  readonly streamRetainMs?: number;
+  /** Map an edgeId to a friendly label for {@link FlowSummary.path}. */
+  readonly labelOf?: (edgeId: string) => string | undefined;
+  /** Injected clock (tests). Default {@link Date.now}. */
+  readonly now?: () => number;
+  /** Injected timer (tests). Default {@link setTimeout}. */
+  readonly setTimer?: (cb: () => void, ms: number) => unknown;
+  /** Injected timer clear (tests). Default {@link clearTimeout}. */
+  readonly clearTimer?: (handle: unknown) => void;
+  /** Hash params for the notification-correlation heuristic. Default JSON. */
+  readonly hashParams?: (params: JsonValue | undefined) => string;
+}
+/**
+ * Coalesces {@link NodeTransit}s into per-operation {@link FlowSummary}s and
+ * reports each after a short quiet period. A fast request is reported **once**
+ * (path + params + response); a slow/stuck one is reported **partial** while
+ * in flight and again on completion.
+ *
+ * Correlation:
+ * - request ↔ response and adjacent-node hops join by shared
+ *   `(edgeId, requestId)` endpoints;
+ * - **notifications** (no request id) join heuristically by
+ *   `(edgeId, method, paramsHash)` — same edge + method + params ⇒ same message.
+ */
+declare class TransitAggregator {
+  private readonly _options;
+  private readonly _flushDelayMs;
+  private readonly _giveUpMs;
+  private readonly _streamRetainMs;
+  private readonly _now;
+  private readonly _setTimer;
+  private readonly _clearTimer;
+  private readonly _hashParams;
+  private readonly _labelOf;
+  private readonly _flows;
+  private readonly _endpointToFlow;
+  private _nextId;
+  constructor(_options: TransitAggregatorOptions);
+  add(transit: NodeTransit): void;
+  /** Drop all pending flows and timers. Does not emit. */
+  dispose(): void;
+  /** Emit pending flows as partial summaries before a diagnostic capture ends. */
+  flush(): void;
+  /** First flow registered under any of `keys`, if any (no merge/create). */
+  private _findFlow;
+  /**
+   * Report a single stream frame as its own one-line flow, correlated to its
+   * owning request by method + path (the request itself is reported separately
+   * when it settles). Used for frames that arrive after {@link _streamRetainMs}
+   * so they surface live instead of waiting on a slow request to finish.
+   */
+  private _emitStandaloneStream;
+  /** Path for a lone stream transit (in → node → out), with labels applied. */
+  private _buildStreamPath;
+  private _endpointKeys;
+  private _merge;
+  private _armFlush;
+  private _flush;
+  private _giveUp;
+  private _delete;
+  private _summarize;
+  private _buildPath;
+  private _label;
+}
+/**
+ * Presentation adapter that coalesces the public traffic stream into legacy
+ * {@link FlowSummary} values. Routing and endpoint observation stay entirely
+ * behind the inspection interfaces; consumers only provide formatting/UI.
+ */
+declare class TrafficFlowAggregator {
+  private readonly _portLabels;
+  private readonly _aggregator;
+  constructor(options: TransitAggregatorOptions);
+  add(transit: TrafficTransitEvent): void;
+  setPortLabel(portId: string, label: string): void;
+  flush(): void;
+  dispose(): void;
+}
+/**
+ * Render a {@link FlowSummary} as a single, human-readable log line. Payloads
+ * are JSON-stringified and truncated. Intended for a VS Code output channel.
+ */
+declare function formatFlowSummary(s: FlowSummary, maxPayload?: number): string;
+interface FlowLoggerOptions {
+  /** Sink for the formatted, one-line-per-flow output. */
+  readonly log: (line: string) => void;
+  /**
+   * Max JSON length per payload before truncation. Default 200; pass
+   * {@link Number.POSITIVE_INFINITY} for full, untruncated payloads.
+   */
+  readonly maxPayload?: number;
+  /** Quiet-period before a flow is flushed. Default 50ms. */
+  readonly flushDelayMs?: number;
+  /** Drop an unsettled flow after this long (leak guard). Default 5min. */
+  readonly giveUpMs?: number;
+  /** Map an edgeId to a friendly label for the rendered path. */
+  readonly labelOf?: (edgeId: string) => string | undefined;
+}
+/** A ready-to-attach flow logger: an {@link NodeTransitObserver} + teardown. */
+interface FlowLogger {
+  /** Wire this as a hub / overlay `onTransit` observer. */
+  readonly onTransit: NodeTransitObserver;
+  /** Flush nothing; just clear pending timers. */
+  dispose(): void;
+}
+/**
+ * Wire a {@link TransitAggregator} to a line sink: each settled (or partial)
+ * flow is rendered with {@link formatFlowSummary} and handed to `log`. This is
+ * the shared engine behind both the VS Code "linkrpc Flows" output channel and
+ * the CLI's `--log-messages` flag.
+ */
+declare function createFlowLogger(opts: FlowLoggerOptions): FlowLogger;
+interface WireTapOptions {
+  /** Sink for the formatted, one-line-per-flow output. */
+  readonly log: (line: string) => void;
+  /** Max JSON length per payload before truncation. Default 200. */
+  readonly maxPayload?: number;
+  /** Edge label for the near end (the tapping side). Default `"local"`. */
+  readonly localLabel?: string;
+  /** Edge label for the far end (the peer). Default `"peer"`. */
+  readonly remoteLabel?: string;
+  /** Synthetic node id for the tap point. Default = {@link localLabel}. */
+  readonly nodeId?: string;
+}
+/**
+ * Wrap an {@link IMessageTransport} so every JSON-RPC message crossing it — in
+ * both directions — is rendered to a line sink, exactly like {@link Hub} traffic.
+ *
+ * No hub is involved: the tap point is modelled as a single node with two edges
+ * (`local`, `peer`). Each outbound message is a transit `local → peer`, each
+ * inbound one `peer → local`; requests and their responses still pair by their
+ * shared `(peer-edge, requestId)`, so the rendered flows match the hub view.
+ * Use this to inspect a *direct* connection that never touches a local hub.
+ */
+declare function tapTransport(inner: IMessageTransport, opts: WireTapOptions): IMessageTransport;
+//#endregion
+export { formatFlowSummary as _, FlowSummary as a, TrafficFlowAggregator as c, TransitDisposition as d, TransitEndpoint as f, createFlowLogger as g, WireTapOptions as h, FlowStreamMessage as i, TransitAggregator as l, TransitKind as m, FlowLoggerOptions as n, NodeTransit as o, TransitError as p, FlowStatus as r, NodeTransitObserver as s, FlowLogger as t, TransitAggregatorOptions as u, tapTransport as v };
+//# sourceMappingURL=nodeTransit-cmtZgdpW.d.ts.map