effect-inspect 0.1.0 → 0.2.0

package/dist/protocol/Schema.js

@@ -28,8 +28,24 @@ export const Json = Schema.Union([
 ]);
 /** Span attributes, log annotations, and metric/event attributes. */
 export const Attributes = Schema.Record(Schema.String, Json);
-/** Identifies one run of an instrumented program. */
+/**
+ * Identifies one run of an instrumented program.
+ *
+ * Any string on the wire, so traces from older clients keep decoding. IDs a
+ * caller chooses are held to {@link isValidSessionId} by the client instead.
+ */
 export const SessionId = Schema.String;
+/** What {@link isValidSessionId} accepts, phrased for diagnostics. */
+export const sessionIdRule = '1-128 ASCII letters, digits, ".", "_" or "-", starting with a letter or digit';
+/**
+ * Whether a caller-chosen session ID is acceptable, such as `checkout-before-1`.
+ *
+ * Human-readable rather than UUID-shaped, and needs no quoting as a shell
+ * argument. No colon, so a chosen ID can never take the `loaded:` form the
+ * webapp gives sessions read from a saved file. A generated UUID also
+ * satisfies it.
+ */
+export const isValidSessionId = (id) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id);
 const sessionId = { sessionId: SessionId };
 /** Mirrors `Tracer.SpanKind`. */
 export const SpanKind = Schema.Literals(['internal', 'server', 'client', 'producer', 'consumer']);
@@ -64,6 +80,13 @@ export const Hello = Schema.Struct({
     runtime: Schema.String,
     protocolVersion: Schema.Natural,
     clock: Clock,
+    /**
+     * Random per client instance, fixed for its lifetime and re-sent on every
+     * reconnect. Tells a genuine reconnect (same instance) from an independent
+     * run that chose the same `sessionId`. Absent from older clients, which are
+     * treated as one instance per `sessionId`.
+     */
+    instanceId: Schema.optional(Schema.String),
 });
 /** The protocol version a `Hello` must carry. Bump on any breaking change. */
 export const protocolVersion = 1;
@@ -249,6 +272,12 @@ export const Session = Schema.Struct({
     clock: Clock,
     active: Schema.Boolean,
     endedAtEpochMillis: Schema.optional(Schema.Natural),
+    /**
+     * Connections refused because a different client instance announced this
+     * `sessionId` — an ID collision. Their telemetry was discarded, so this
+     * session holds only the first instance's run. Absent when there were none.
+     */
+    conflicts: Schema.optional(Schema.Natural),
 });
 /** Every session the collector holds. Sent on connect and on change. */
 export const SessionList = Schema.Struct({
@@ -302,6 +331,22 @@ export const Unsubscribe = Schema.Struct({
 });
 /** What the webapp sends to the collector. */
 export const WebappRequest = Schema.Union([Subscribe, Unsubscribe]);
+/**
+ * Collector-side loss counters for one session at snapshot time, carried in
+ * a trace file exported from the collector.
+ */
+export const TraceCapture = Schema.Struct({
+    /** Messages evicted by the collector's per-session capacity bound. */
+    droppedMessages: Schema.Natural,
+    /** Lines received for the session that could not be decoded. */
+    skippedLines: Schema.Natural,
+    /**
+     * Whether the collector could refuse an independent run reusing this ID.
+     * `false` when the owning client predates instance IDs, so a reused ID
+     * would have merged silently and `session.conflicts` proves nothing.
+     */
+    conflictDetection: Schema.Boolean,
+});
 /**
  * Line 1 of a saved trace file.
  *
@@ -322,6 +367,13 @@ export const TraceFileHeader = Schema.Struct({
     protocolVersion: Schema.Natural,
     session: Session,
     savedAtEpochMillis: Schema.Natural,
+    /**
+     * What the collector knew about loss when the file was exported from it.
+     * Absent from browser saves and older files: their capture completeness is
+     * unknown, not complete. Optional and additive, so older builds, which
+     * ignore unknown header keys, still read these files.
+     */
+    capture: Schema.optional(TraceCapture),
 });
 /** The trace file layout version. Bump only on a change to the header or the line layout. */
 export const traceFileFormatVersion = 1;

package/dist/query/Client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Calls a running collector's query API (see `collector/QueryApi.ts`).
+ *
+ * Never fails: transport problems become the same `QueryFailure` shape the
+ * collector returns, tagged `CollectorUnavailable` (nothing answered in time)
+ * or `CollectorError` (something answered, but not this API), so a caller
+ * prints one JSON contract whatever went wrong.
+ */
+import { Effect } from 'effect';
+import { HttpClient } from 'effect/unstable/http';
+import * as Query from './Query.ts';
+/** Where `effect-inspect start` listens by default. */
+export declare const defaultUrl = "http://localhost:34437";
+/** How long a call waits for the collector before `CollectorUnavailable`. */
+export declare const defaultTimeoutMs = 5000;
+export interface Options {
+    /** Collector base URL, e.g. {@link defaultUrl}. */
+    readonly url: string;
+    readonly timeoutMs?: number | undefined;
+}
+/** Sends one query request (validated by the collector) and returns its response. */
+export declare const query: (options: Options, request: unknown) => Effect.Effect<Query.QueryResponse, never, HttpClient.HttpClient>;
+/**
+ * Downloads one session's frozen snapshot as `.eitrace` text, loss counters
+ * included, for offline queries that answer exactly as the live one did.
+ */
+export declare const exportTrace: (options: Options, sessionId: string) => Effect.Effect<{
+    readonly ok: true;
+    readonly text: string;
+} | Query.QueryFailure, never, HttpClient.HttpClient>;

package/dist/query/Client.js

@@ -0,0 +1,74 @@
+/**
+ * Calls a running collector's query API (see `collector/QueryApi.ts`).
+ *
+ * Never fails: transport problems become the same `QueryFailure` shape the
+ * collector returns, tagged `CollectorUnavailable` (nothing answered in time)
+ * or `CollectorError` (something answered, but not this API), so a caller
+ * prints one JSON contract whatever went wrong.
+ */
+import { Duration, Effect } from 'effect';
+import { HttpClient, HttpClientRequest } from 'effect/unstable/http';
+import { defaultPort } from '../collector/Config.js';
+import * as Query from './Query.js';
+/** Where `effect-inspect start` listens by default. */
+export const defaultUrl = `http://localhost:${defaultPort}`;
+/** How long a call waits for the collector before `CollectorUnavailable`. */
+export const defaultTimeoutMs = 5000;
+const unavailable = (op, url, detail) => Query.failure(op, 'CollectorUnavailable', `No collector answered at ${url}: ${detail}`, 'Start one with `effect-inspect start` (EFFECT_INSPECT_PORT sets its port) or point at the right URL; for saved traces query the file instead.', { url });
+const foreign = (op, url, detail) => Query.failure(op, 'CollectorError', `${url} did not answer as an effect-inspect query API: ${detail}`, 'The collector may predate the query API, or another service owns that port. Upgrade and restart the collector, or check the URL.', { url });
+const isResponse = (body) => typeof body === 'object' &&
+    body !== null &&
+    body.apiVersion === Query.apiVersion &&
+    typeof body.ok === 'boolean';
+const opOf = (request) => typeof request === 'object' &&
+    request !== null &&
+    typeof request.op === 'string'
+    ? request.op
+    : null;
+const withTimeout = (options, op, effect) => {
+    const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+    return Effect.timeoutOrElse(effect, {
+        duration: Duration.millis(timeoutMs),
+        orElse: () => Effect.succeed(unavailable(op, options.url, `no answer within ${timeoutMs}ms`)),
+    });
+};
+/** Sends one query request (validated by the collector) and returns its response. */
+export const query = (options, request) => {
+    const op = opOf(request);
+    // Bounded here too: a failure built from a long URL, or an oversized body
+    // from a collector that does not enforce the bound, must not escape it.
+    return Effect.map(withTimeout(options, op, Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        const response = yield* client.execute(HttpClientRequest.post(new URL('/api/v1/query', options.url)).pipe(HttpClientRequest.bodyJsonUnsafe(request)));
+        const body = yield* response.json;
+        return isResponse(body)
+            ? body
+            : foreign(op, options.url, `unexpected body (HTTP ${response.status})`);
+    }).pipe(Effect.catchTag('HttpClientError', (error) => Effect.succeed(error.reason._tag === 'TransportError' || error.reason._tag === 'InvalidUrlError'
+        ? unavailable(op, options.url, error.message)
+        : foreign(op, options.url, error.message))))), Query.limitResponse);
+};
+/**
+ * Downloads one session's frozen snapshot as `.eitrace` text, loss counters
+ * included, for offline queries that answer exactly as the live one did.
+ */
+export const exportTrace = (options, sessionId) => Effect.map(withTimeout(options, 'export', Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const url = new URL('/api/v1/export', options.url);
+    url.searchParams.set('sessionId', sessionId);
+    const response = yield* client.execute(HttpClientRequest.get(url));
+    // An older collector hands unknown paths to the web UI, which may answer 200 HTML.
+    if (response.status === 200 &&
+        response.headers['content-type']?.startsWith('application/x-ndjson') === true) {
+        return { ok: true, text: yield* response.text };
+    }
+    const body = yield* response.json;
+    return isResponse(body) && !body.ok
+        ? body
+        : foreign('export', options.url, `unexpected body (HTTP ${response.status})`);
+}).pipe(Effect.catchTag('HttpClientError', (error) => Effect.succeed(error.reason._tag === 'TransportError' || error.reason._tag === 'InvalidUrlError'
+    ? unavailable('export', options.url, error.message)
+    : foreign('export', options.url, error.message))))), 
+// The trace text is a lossless artifact and deliberately unbounded;
+// only failures are held to the JSON response bound.
+(result) => (result.ok ? result : Query.limitResponse(result)));