effect-inspect 0.1.0

package/dist/protocol/Codec.d.ts

@@ -0,0 +1,575 @@
+/**
+ * NDJSON codec for the protocol unions.
+ *
+ * The whole encoding lives behind {@link Codec}: one line of JSON per message,
+ * `\n`-terminated. Swapping in a compact binary format later means another
+ * `make`-shaped factory, not touching callers.
+ */
+import { Result } from 'effect';
+declare const EncodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "EncodeError";
+} & Readonly<A>;
+/** Raised when a message cannot be encoded — an out-of-domain field value. */
+export declare class EncodeError extends EncodeError_base<{
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+declare const DecodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DecodeError";
+} & Readonly<A>;
+/** Raised when a line is not valid JSON, or not a valid message. */
+export declare class DecodeError extends DecodeError_base<{
+    readonly line: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+/** An encode/decode pair for one protocol union. */
+export interface Codec<A> {
+    /**
+     * Encodes one message as a single `\n`-terminated NDJSON line.
+     *
+     * Throws {@link EncodeError} if a field is out of its schema's domain (a
+     * `NaN` attribute, a negative count). That is a producer bug, not a runtime
+     * condition, so callers that would only rethrow need no branch; use
+     * {@link Codec.encodeResult} where the value came from outside.
+     */
+    readonly encode: (message: A) => string;
+    /** {@link Codec.encode} as a `Result`, for values from an untrusted source. */
+    readonly encodeResult: (message: A) => Result.Result<string, EncodeError>;
+    /** Decodes one NDJSON line. Surrounding whitespace is tolerated. */
+    readonly decode: (line: string) => Result.Result<A, DecodeError>;
+    /**
+     * Decodes every non-empty line of an NDJSON chunk.
+     *
+     * Fails on the first bad line rather than skipping it: a malformed line means
+     * the stream is out of sync, and silently dropping telemetry is worse than
+     * surfacing it.
+     */
+    readonly decodeAll: (chunk: string) => Result.Result<ReadonlyArray<A>, DecodeError>;
+}
+/** Instrumented program → collector. */
+export declare const clientCodec: Codec<{
+    readonly sessionId: string;
+    readonly _tag: "Hello";
+    readonly program: string;
+    readonly pid: number;
+    readonly runtime: string;
+    readonly protocolVersion: number;
+    readonly clock: {
+        readonly startTime: bigint;
+        readonly wallClockEpochMillis: number;
+    };
+} | {
+    readonly sessionId: string;
+    readonly _tag: "SpanStart";
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly parent?: {
+        readonly _tag: "LocalParent";
+        readonly spanId: string;
+    } | {
+        readonly _tag: "ExternalParent";
+        readonly spanId: string;
+        readonly traceId: string;
+        readonly sampled: boolean;
+    } | undefined;
+    readonly name: string;
+    readonly kind: "client" | "consumer" | "internal" | "producer" | "server";
+    readonly startTime: bigint;
+    readonly attributes: {
+        readonly [x: string]: import("./Schema.ts").Json;
+    };
+    readonly sampled: boolean;
+    readonly fiberId?: number | undefined;
+} | {
+    readonly sessionId: string;
+    readonly _tag: "SpanEnd";
+    readonly spanId: string;
+    readonly endTime: bigint;
+    readonly outcome: {
+        readonly _tag: "Success";
+    } | {
+        readonly _tag: "Failure";
+        readonly kind: "Die" | "Fail" | "Interrupt";
+        readonly error: string;
+        readonly stack?: string | undefined;
+    };
+    readonly attributes: {
+        readonly [x: string]: import("./Schema.ts").Json;
+    };
+} | {
+    readonly sessionId: string;
+    readonly _tag: "SpanEvent";
+    readonly spanId: string;
+    readonly name: string;
+    readonly time: bigint;
+    readonly attributes: {
+        readonly [x: string]: import("./Schema.ts").Json;
+    };
+} | {
+    readonly sessionId: string;
+    readonly _tag: "Log";
+    readonly time: bigint;
+    readonly level: "All" | "Debug" | "Error" | "Fatal" | "Info" | "None" | "Trace" | "Warn";
+    readonly message: import("./Schema.ts").Json;
+    readonly spanId?: string | undefined;
+    readonly fiberId?: number | undefined;
+    readonly annotations: {
+        readonly [x: string]: import("./Schema.ts").Json;
+    };
+} | {
+    readonly sessionId: string;
+    readonly _tag: "Metrics";
+    readonly time: bigint;
+    readonly metrics: readonly ({
+        readonly type: "Counter";
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly attributes: {
+            readonly [x: string]: string;
+        };
+        readonly state: {
+            readonly count: number;
+            readonly incremental: boolean;
+        };
+    } | {
+        readonly type: "Gauge";
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly attributes: {
+            readonly [x: string]: string;
+        };
+        readonly state: {
+            readonly value: number;
+        };
+    } | {
+        readonly type: "Histogram";
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly attributes: {
+            readonly [x: string]: string;
+        };
+        readonly state: {
+            readonly buckets: readonly (readonly [number, number])[];
+            readonly count: number;
+            readonly min: number;
+            readonly max: number;
+            readonly sum: number;
+        };
+    } | {
+        readonly type: "Frequency";
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly attributes: {
+            readonly [x: string]: string;
+        };
+        readonly state: {
+            readonly occurrences: {
+                readonly [x: string]: number;
+            };
+        };
+    } | {
+        readonly type: "Summary";
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly attributes: {
+            readonly [x: string]: string;
+        };
+        readonly state: {
+            readonly quantiles: readonly (readonly [number, number | null])[];
+            readonly count: number;
+            readonly min: number;
+            readonly max: number;
+            readonly sum: number;
+        };
+    })[];
+} | {
+    readonly sessionId: string;
+    readonly _tag: "FiberEvent";
+    readonly fiberId: number;
+    readonly event: "End" | "Resume" | "Start" | "Suspend";
+    readonly parentFiberId?: number | undefined;
+    readonly time: bigint;
+} | {
+    readonly sessionId: string;
+    readonly _tag: "MemorySample";
+    readonly time: bigint;
+    readonly heapUsed: number;
+    readonly heapTotal: number;
+    readonly rss: number;
+    readonly external: number;
+} | {
+    readonly sessionId: string;
+    readonly _tag: "Ping";
+}>;
+/** Collector → instrumented program. */
+export declare const collectorCodec: Codec<{
+    readonly sessionId: string;
+    readonly _tag: "Pong";
+} | {
+    readonly _tag: "MetricsRequest";
+}>;
+/** Collector → webapp. */
+export declare const webappCodec: Codec<{
+    readonly _tag: "SessionList";
+    readonly sessions: readonly {
+        readonly sessionId: string;
+        readonly program: string;
+        readonly pid: number;
+        readonly runtime: string;
+        readonly clock: {
+            readonly startTime: bigint;
+            readonly wallClockEpochMillis: number;
+        };
+        readonly active: boolean;
+        readonly endedAtEpochMillis?: number | undefined;
+    }[];
+} | {
+    readonly sessionId: string;
+    readonly _tag: "Backlog";
+    readonly messages: readonly ({
+        readonly sessionId: string;
+        readonly _tag: "Hello";
+        readonly program: string;
+        readonly pid: number;
+        readonly runtime: string;
+        readonly protocolVersion: number;
+        readonly clock: {
+            readonly startTime: bigint;
+            readonly wallClockEpochMillis: number;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "SpanStart";
+        readonly spanId: string;
+        readonly traceId: string;
+        readonly parent?: {
+            readonly _tag: "LocalParent";
+            readonly spanId: string;
+        } | {
+            readonly _tag: "ExternalParent";
+            readonly spanId: string;
+            readonly traceId: string;
+            readonly sampled: boolean;
+        } | undefined;
+        readonly name: string;
+        readonly kind: "client" | "consumer" | "internal" | "producer" | "server";
+        readonly startTime: bigint;
+        readonly attributes: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+        readonly sampled: boolean;
+        readonly fiberId?: number | undefined;
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "SpanEnd";
+        readonly spanId: string;
+        readonly endTime: bigint;
+        readonly outcome: {
+            readonly _tag: "Success";
+        } | {
+            readonly _tag: "Failure";
+            readonly kind: "Die" | "Fail" | "Interrupt";
+            readonly error: string;
+            readonly stack?: string | undefined;
+        };
+        readonly attributes: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "SpanEvent";
+        readonly spanId: string;
+        readonly name: string;
+        readonly time: bigint;
+        readonly attributes: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "Log";
+        readonly time: bigint;
+        readonly level: "All" | "Debug" | "Error" | "Fatal" | "Info" | "None" | "Trace" | "Warn";
+        readonly message: import("./Schema.ts").Json;
+        readonly spanId?: string | undefined;
+        readonly fiberId?: number | undefined;
+        readonly annotations: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "Metrics";
+        readonly time: bigint;
+        readonly metrics: readonly ({
+            readonly type: "Counter";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly count: number;
+                readonly incremental: boolean;
+            };
+        } | {
+            readonly type: "Gauge";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly value: number;
+            };
+        } | {
+            readonly type: "Histogram";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly buckets: readonly (readonly [number, number])[];
+                readonly count: number;
+                readonly min: number;
+                readonly max: number;
+                readonly sum: number;
+            };
+        } | {
+            readonly type: "Frequency";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly occurrences: {
+                    readonly [x: string]: number;
+                };
+            };
+        } | {
+            readonly type: "Summary";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly quantiles: readonly (readonly [number, number | null])[];
+                readonly count: number;
+                readonly min: number;
+                readonly max: number;
+                readonly sum: number;
+            };
+        })[];
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "FiberEvent";
+        readonly fiberId: number;
+        readonly event: "End" | "Resume" | "Start" | "Suspend";
+        readonly parentFiberId?: number | undefined;
+        readonly time: bigint;
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "MemorySample";
+        readonly time: bigint;
+        readonly heapUsed: number;
+        readonly heapTotal: number;
+        readonly rss: number;
+        readonly external: number;
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "Ping";
+    })[];
+    readonly complete: boolean;
+} | {
+    readonly _tag: "Live";
+    readonly message: {
+        readonly sessionId: string;
+        readonly _tag: "Hello";
+        readonly program: string;
+        readonly pid: number;
+        readonly runtime: string;
+        readonly protocolVersion: number;
+        readonly clock: {
+            readonly startTime: bigint;
+            readonly wallClockEpochMillis: number;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "SpanStart";
+        readonly spanId: string;
+        readonly traceId: string;
+        readonly parent?: {
+            readonly _tag: "LocalParent";
+            readonly spanId: string;
+        } | {
+            readonly _tag: "ExternalParent";
+            readonly spanId: string;
+            readonly traceId: string;
+            readonly sampled: boolean;
+        } | undefined;
+        readonly name: string;
+        readonly kind: "client" | "consumer" | "internal" | "producer" | "server";
+        readonly startTime: bigint;
+        readonly attributes: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+        readonly sampled: boolean;
+        readonly fiberId?: number | undefined;
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "SpanEnd";
+        readonly spanId: string;
+        readonly endTime: bigint;
+        readonly outcome: {
+            readonly _tag: "Success";
+        } | {
+            readonly _tag: "Failure";
+            readonly kind: "Die" | "Fail" | "Interrupt";
+            readonly error: string;
+            readonly stack?: string | undefined;
+        };
+        readonly attributes: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "SpanEvent";
+        readonly spanId: string;
+        readonly name: string;
+        readonly time: bigint;
+        readonly attributes: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "Log";
+        readonly time: bigint;
+        readonly level: "All" | "Debug" | "Error" | "Fatal" | "Info" | "None" | "Trace" | "Warn";
+        readonly message: import("./Schema.ts").Json;
+        readonly spanId?: string | undefined;
+        readonly fiberId?: number | undefined;
+        readonly annotations: {
+            readonly [x: string]: import("./Schema.ts").Json;
+        };
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "Metrics";
+        readonly time: bigint;
+        readonly metrics: readonly ({
+            readonly type: "Counter";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly count: number;
+                readonly incremental: boolean;
+            };
+        } | {
+            readonly type: "Gauge";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly value: number;
+            };
+        } | {
+            readonly type: "Histogram";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly buckets: readonly (readonly [number, number])[];
+                readonly count: number;
+                readonly min: number;
+                readonly max: number;
+                readonly sum: number;
+            };
+        } | {
+            readonly type: "Frequency";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly occurrences: {
+                    readonly [x: string]: number;
+                };
+            };
+        } | {
+            readonly type: "Summary";
+            readonly name: string;
+            readonly description?: string | undefined;
+            readonly attributes: {
+                readonly [x: string]: string;
+            };
+            readonly state: {
+                readonly quantiles: readonly (readonly [number, number | null])[];
+                readonly count: number;
+                readonly min: number;
+                readonly max: number;
+                readonly sum: number;
+            };
+        })[];
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "FiberEvent";
+        readonly fiberId: number;
+        readonly event: "End" | "Resume" | "Start" | "Suspend";
+        readonly parentFiberId?: number | undefined;
+        readonly time: bigint;
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "MemorySample";
+        readonly time: bigint;
+        readonly heapUsed: number;
+        readonly heapTotal: number;
+        readonly rss: number;
+        readonly external: number;
+    } | {
+        readonly sessionId: string;
+        readonly _tag: "Ping";
+    };
+} | {
+    readonly sessionId: string;
+    readonly _tag: "SessionEnded";
+    readonly endedAtEpochMillis: number;
+}>;
+/** Webapp → collector. */
+export declare const webappRequestCodec: Codec<{
+    readonly sessionId: string;
+    readonly _tag: "Subscribe";
+} | {
+    readonly sessionId: string;
+    readonly _tag: "Unsubscribe";
+}>;
+/** Line 1 of a saved trace file; the rest of the file is {@link clientCodec} lines. */
+export declare const traceFileHeaderCodec: Codec<{
+    readonly _tag: "TraceFileHeader";
+    readonly formatVersion: number;
+    readonly protocolVersion: number;
+    readonly session: {
+        readonly sessionId: string;
+        readonly program: string;
+        readonly pid: number;
+        readonly runtime: string;
+        readonly clock: {
+            readonly startTime: bigint;
+            readonly wallClockEpochMillis: number;
+        };
+        readonly active: boolean;
+        readonly endedAtEpochMillis?: number | undefined;
+    };
+    readonly savedAtEpochMillis: number;
+}>;
+export {};

package/dist/protocol/Codec.js

@@ -0,0 +1,50 @@
+/**
+ * NDJSON codec for the protocol unions.
+ *
+ * The whole encoding lives behind {@link Codec}: one line of JSON per message,
+ * `\n`-terminated. Swapping in a compact binary format later means another
+ * `make`-shaped factory, not touching callers.
+ */
+import { Data, Result, Schema } from 'effect';
+import { ClientMessage, CollectorMessage, TraceFileHeader, WebappMessage, WebappRequest, } from './Schema.js';
+/** Raised when a message cannot be encoded — an out-of-domain field value. */
+export class EncodeError extends Data.TaggedError('EncodeError') {
+    get message() {
+        return `Unencodable protocol message: ${this.reason}`;
+    }
+}
+/** Raised when a line is not valid JSON, or not a valid message. */
+export class DecodeError extends Data.TaggedError('DecodeError') {
+    get message() {
+        return `Invalid protocol message: ${this.reason}`;
+    }
+}
+const make = (schema) => {
+    const json = Schema.fromJsonString(schema);
+    const encodeJson = Schema.encodeResult(json);
+    const decodeJson = Schema.decodeUnknownResult(json);
+    const encodeResult = (message) => Result.match(encodeJson(message), {
+        onSuccess: (line) => Result.succeed(`${line}\n`),
+        onFailure: (error) => Result.fail(new EncodeError({ reason: error.message })),
+    });
+    const decode = (line) => Result.mapError(decodeJson(line.trim()), (error) => new DecodeError({ line, reason: error.message }));
+    return {
+        encode: (message) => Result.getOrThrow(encodeResult(message)),
+        encodeResult,
+        decode,
+        decodeAll: (chunk) => Result.all(chunk
+            .split('\n')
+            .filter((line) => line.trim() !== '')
+            .map(decode)),
+    };
+};
+/** Instrumented program → collector. */
+export const clientCodec = make(ClientMessage);
+/** Collector → instrumented program. */
+export const collectorCodec = make(CollectorMessage);
+/** Collector → webapp. */
+export const webappCodec = make(WebappMessage);
+/** Webapp → collector. */
+export const webappRequestCodec = make(WebappRequest);
+/** Line 1 of a saved trace file; the rest of the file is {@link clientCodec} lines. */
+export const traceFileHeaderCodec = make(TraceFileHeader);