@setu-ts/kernel 0.0.0-stage → 0.9.0

package/dist/diagnostics/collector.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Diagnostics collector — the kernel-owned writer and the public pull-only
+ * reader behind `IApplication.diagnostics`.
+ *
+ * Ownership is the whole design: only the kernel implementation writes here,
+ * at its own registration and execution boundaries, projecting bounded
+ * primitives captured once at the owning mutation. The reader offers exactly
+ * `snapshot()` and `read()` — neither can register a callback, invoke
+ * application code, resolve a service, or mutate state — so an external
+ * reader can be slow, stop polling, or throw after reading without any effect
+ * on the application.
+ *
+ * Every mutation and execution call site passes through {@linkcode
+ * DiagnosticsCollector.safeObserve}: an inspection failure must never change a
+ * response, a lifecycle result, or a startup error. An event-capture failure
+ * drops the record, increments a value-free counter, and disables further
+ * event capture; a topology-capture failure drops that entry and marks the
+ * snapshot truncated.
+ *
+ * @module
+ */
+import type { DiagnosticsBatch, DiagnosticsEventKind, DiagnosticsEventOutcome, DiagnosticsEventStage, DiagnosticsSnapshot, IDiagnosticsSource } from '@setu-ts/common';
+import type { RouteRegistrationEvent } from '../router/router.ts';
+import type { RegistryDiagnosticEvent } from '../registry/service-registry.ts';
+import type { DiagnosticsLabelAllowlists } from './projection.ts';
+/** Capture-time description of one plugin, taken at its registration boundary. */
+export interface PluginRegistrationInfo {
+    /** The plugin's declared `name`. */
+    readonly name: string;
+    /** The plugin's declared `version`, emitted only when it passes the bounded grammar. */
+    readonly version: string;
+    /** Declared `provides` tokens. */
+    readonly provides: readonly string[];
+    /** Declared `requires` tokens. */
+    readonly requires: readonly string[];
+    /** Declared `optionalDependencies` tokens. */
+    readonly optionalDependencies: readonly string[];
+    /** Declared `consumes` tokens. */
+    readonly consumes: readonly string[];
+}
+/** Capture-time description of one global middleware stage, in execution order. */
+export interface MiddlewareCompiledDescriptor {
+    readonly name: string;
+    readonly priority: number;
+    /** 1-based execution position in the stable priority sort. */
+    readonly position: number;
+}
+/** An operation allocated at entry, linking later records to their parent. */
+export interface DiagnosticsOperation {
+    readonly id: string;
+    readonly startedAtMs: number | null;
+}
+/** Parts of one completion record the collector turns into a stored event. */
+export interface CompletionRecordParts {
+    readonly kind: DiagnosticsEventKind;
+    readonly stage: DiagnosticsEventStage;
+    readonly operationId: string;
+    readonly parentOperationId: string | null;
+    readonly nodeId: string | null;
+    readonly outcome: DiagnosticsEventOutcome;
+    readonly startedAtMs: number | null;
+    readonly durationMs: number | null;
+    readonly statusCode?: number;
+    /** Whether the record may carry validated trace/span identifiers. */
+    readonly withTrace?: boolean;
+}
+/** The slice of `ITelemetryService` the collector reads, kept structural. */
+interface TraceReadingTelemetry {
+    activeSpanContext?(): {
+        readonly traceId: string;
+        readonly spanId: string;
+    } | undefined;
+}
+/**
+ * The collector. Instantiated ONLY when the application was created with
+ * `diagnostics` explicitly enabled; an omitted option never constructs one.
+ * @since 0.8.0
+ */
+export declare class DiagnosticsCollector implements IDiagnosticsSource {
+    #private;
+    constructor(labels: DiagnosticsLabelAllowlists);
+    /** @inheritDoc */
+    snapshot(): DiagnosticsSnapshot;
+    /** @inheritDoc */
+    read(after: number, limit?: number): DiagnosticsBatch;
+    /**
+     * Application start has begun. A start following a FAILED start resets the
+     * reader for the new attempt — the kernel rolls its own `#started` back so
+     * a start that failed before any plugin registered can be corrected and
+     * retried, and the reader must not keep
+     * reporting `failed` for a process that is starting (or later serving)
+     * again. The failed attempt's retained metadata was already cleared by
+     * `markStartupFailed`, so the reset recovers nothing sensitive; `closed`
+     * remains absolute (a stopped application never restarts its reader).
+     */
+    markStarting(): void;
+    /** Startup completed; the application is serving. */
+    markRunning(): void;
+    /** Shutdown has begun; the application is about to refuse requests. */
+    markStopping(): void;
+    /**
+     * Startup failed. Terminal: clears every retained node/edge/event buffer
+     * while preserving the caller's original error, so a reader sees only the
+     * coarse state, the failure code, and counters.
+     */
+    markStartupFailed(): void;
+    /**
+     * Shutdown finished (successfully or not). Terminal, like
+     * {@linkcode markStartupFailed}: retained buffers are cleared regardless of
+     * the outcome.
+     *
+     * @param shutdownFailed - `true` when a shutdown-phase hook rejected
+     */
+    markClosed(shutdownFailed: boolean): void;
+    /**
+     * Records runtime availability: the monotonic origin starts here and the
+     * instance UUID is generated once, through the registered runtime. Both are
+     * guarded — a failing runtime reports as unavailable (`null` timings, `null`
+     * instanceId) rather than turning startup into a diagnostics fault. Before
+     * this call, every timing is `null` and none is ever fabricated.
+     *
+     * @param runtime - The registered runtime services
+     * @param telemetryReader - Resolves the telemetry service WITHOUT resolving
+     * a lazy factory; `undefined` identifiers are reported as absence
+     */
+    initializeRuntime(runtime: {
+        readonly uuid: () => string;
+        readonly hrtime: () => number;
+    }, telemetryReader: (() => TraceReadingTelemetry | undefined) | undefined): void;
+    /**
+     * The one inspection boundary every capture passes through. An event-scope
+     * failure disables further event capture after saturating the drop counter;
+     * a topology-scope failure drops that entry and marks the snapshot
+     * truncated. Neither can propagate: an inspection failure must not change a
+     * response, a lifecycle result, or a startup error.
+     *
+     * @param scope - Which capture family the callback belongs to
+     * @param emit - The capture work
+     * @returns The callback's value, or `undefined` when it failed
+     */
+    safeObserve<T>(scope: 'event' | 'topology', emit: () => T): T | undefined;
+    /** Guarded monotonic offset in ms from runtime initialization, or `null`. */
+    monotonicMs(): number | null;
+    /**
+     * Captures one plugin at its registration boundary: the node plus its
+     * DECLARED dependency edges. Names are projected through the allowlists
+     * here, at capture — the collector never stores a label that was not
+     * explicitly approved.
+     *
+     * @param info - The declared plugin description
+     * @returns The plugin node id, or `undefined` when the capture was dropped
+     */
+    pluginRegistered(info: PluginRegistrationInfo): string | undefined;
+    /**
+     * Observes a successful registry registration (instance, factory, or
+     * multi-provider) or removal, using token metadata alone. The registry's
+     * existing logging observer is untouched.
+     *
+     * @param event - The registry's registration event
+     * @param owner - The plugin whose `register()` was running, when known
+     */
+    capabilityRegistrationObserved(event: RegistryDiagnosticEvent, owner: string | undefined): void;
+    /**
+     * Captures one route registration with its route-middleware nodes.
+     *
+     * @param event - The router's registration event
+     * @returns The route node id, or `undefined` when the capture was dropped
+     */
+    routeRegistered(event: RouteRegistrationEvent): string | undefined;
+    /**
+     * Captures the compiled global pipeline in execution order — the stable
+     * priority sort — so middleware stage records can name their node.
+     *
+     * @param descriptors - The compiled stages, in execution order
+     */
+    middlewareCompiled(descriptors: readonly MiddlewareCompiledDescriptor[]): void;
+    /** Route node id for a router entry index, when that route was captured. */
+    routeNodeIdOf(entryIndex: number): string | undefined;
+    /**
+     * Allocates an operation root at entry. The identifier exists before any
+     * record is written, so a child may reference a parent whose completion
+     * record appears later.
+     *
+     * @returns The operation handle
+     */
+    beginOperation(): DiagnosticsOperation;
+    /**
+     * Allocates the request operation for a context, stored in a private
+     * WeakMap — never in application state, never a caller-supplied id.
+     *
+     * @param ctx - The request context keying the operation
+     */
+    beginRequestOperation(ctx: object): void;
+    /**
+     * Emits the request operation's completion record.
+     *
+     * @param ctx - The request context keying the operation
+     * @param parts - Outcome and the produced status code
+     */
+    endRequestOperation(ctx: object, parts: {
+        outcome: DiagnosticsEventOutcome;
+        statusCode?: number;
+    }): void;
+    /**
+     * Emits one middleware stage completion record (global or route chain).
+     *
+     * @param parts - The stage observation from the chain executor
+     */
+    observeMiddlewareStage(parts: {
+        parentOperationId: string;
+        scope: 'global' | 'route';
+        position: number;
+        routeEntryIndex: number | undefined;
+        outcome: DiagnosticsEventOutcome;
+        startedAtMs: number | null;
+        durationMs: number | null;
+    }): void;
+    /**
+     * Emits one handler or protocol-boundary completion record.
+     *
+     * @param parts - The handler observation
+     */
+    observeHandlerStage(parts: {
+        parentOperationId: string;
+        stage: 'handler' | 'websocket-upgrade' | 'grpc-dispatch';
+        nodeId: string | null;
+        outcome: DiagnosticsEventOutcome;
+        startedAtMs: number | null;
+        durationMs: number | null;
+        statusCode?: number;
+    }): void;
+    /**
+     * Emits one request-scoped hook completion record (`request-hook`,
+     * `response-hook`, `error-hook`).
+     *
+     * @param parts - The hook observation
+     */
+    observeRequestStage(parts: {
+        parentOperationId: string;
+        stage: 'request-hook' | 'response-hook' | 'error-hook';
+        outcome: DiagnosticsEventOutcome;
+        startedAtMs: number | null;
+        durationMs: number | null;
+    }): void;
+    /**
+     * Emits one lifecycle completion record for an operation allocated at entry
+     * with {@linkcode beginOperation}.
+     *
+     * @param operation - The operation allocated at the boundary's entry
+     * @param stage - The lifecycle boundary that completed
+     * @param nodeId - The plugin node the boundary belongs to, when known
+     * @param outcome - How the boundary completed
+     */
+    observeLifecycleEvent(operation: DiagnosticsOperation, stage: DiagnosticsEventStage, nodeId: string | null, outcome: DiagnosticsEventOutcome): void;
+    /**
+     * Emits one per-hook lifecycle record observed by the lifecycle manager —
+     * fixed phase plus execution ordinal, never an inferred owner.
+     *
+     * @param observation - The manager's hook observation
+     */
+    observeLifecycleHook(observation: {
+        phase: 'register-hook' | 'init' | 'bootstrap' | 'stopping' | 'shutdown' | 'close';
+        ordinal: number;
+        failed: boolean;
+        startedAtMs: number | null;
+        durationMs: number | null;
+    }): void;
+    /**
+     * The request operation identifier keyed to a context, when one exists.
+     *
+     * @param ctx - The request context the operation was keyed under
+     * @returns The operation id, or `undefined`
+     */
+    requestOperationIdOf(ctx: object): string | undefined;
+    /**
+     * Inclusive monotonic elapsed time since a recorded start offset.
+     *
+     * @param startedAtMs - The recorded start offset, or `null`
+     * @returns Elapsed ms, or `null` when either reading was unavailable
+     */
+    elapsedSince(startedAtMs: number | null): number | null;
+}
+export {};
+//# sourceMappingURL=collector.d.ts.map

package/dist/diagnostics/collector.d.ts.map

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