effect-inspect 0.1.1 → 0.3.0

package/dist/cli.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
-import { Command } from 'effect/unstable/cli';
-export declare const cli: Command.Command<"effect-inspect", {}, {}, import("effect/Config").ConfigError | import("effect/unstable/http/HttpServerError").ServeError, import("effect/Scope").Scope>;
+export {};

package/dist/cli.js

@@ -6,24 +6,181 @@ import * as NodeServices from '@effect/platform-node/NodeServices';
 // oxlint-disable-next-line effecttsgo/node-builtin-import
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
-import { Effect, Layer, Schema } from 'effect';
+import { Effect, Exit, Layer, Runtime, Schema } from 'effect';
 import { FileSystem } from 'effect/FileSystem';
-import { Command } from 'effect/unstable/cli';
-import { collectorConfig } from './collector/Config.js';
+import * as Stdio from 'effect/Stdio';
+import { CliConfig, Command, GlobalFlag } from 'effect/unstable/cli';
+import { queryCommands, runCli } from './cli/QueryCommands.js';
+import { collectorConfig, defaultPort } from './collector/Config.js';
 import { run } from './collector/Server.js';
-import { layer as storeLayer } from './collector/Store.js';
+import { defaultCapacity, layer as storeLayer } from './collector/Store.js';
 import { loadWebApp } from './collector/WebApp.js';
+/** Indents continuation lines under the help formatter's DESCRIPTION heading. */
+const text = (body) => body.trim().split('\n').join('\n  ');
 const start = Command.make('start', {}, () => Effect.gen(function* () {
     const { capacity, port } = yield* collectorConfig;
     const fetch = yield* loadWebApp;
     yield* Effect.logInfo(`effect-inspect listening at http://localhost:${port}`);
     return yield* Effect.provide(run(fetch), Layer.mergeAll(storeLayer({ capacity }), NodeHttpServer.layer(createServer, { port })));
-})).pipe(Command.withDescription('Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY)'));
-export const cli = Command.make('effect-inspect').pipe(Command.withDescription('Inspect Effect programs'), Command.withSubcommands([start]));
+})).pipe(Command.withShortDescription('Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY)'), Command.withDescription(text(`
+Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY).
+
+The collector receives telemetry from programs instrumented with Inspect.layer(),
+keeps it in memory per session, serves the web UI at http://localhost:PORT/ and
+answers the query commands (summary, spans, span, logs, export, sessions) on the same
+port. It runs in the foreground until stopped (Ctrl-C or SIGTERM); stopping it drops
+every trace it held, so \`export\` the sessions you want to keep first. Leave it
+running in its own terminal or as a background process while you query.
+
+ENVIRONMENT
+  EFFECT_INSPECT_PORT      Port to listen on (default ${defaultPort}). Query commands read
+                           the same variable to find the collector unless --url is given.
+  EFFECT_INSPECT_CAPACITY  Messages retained per session (default ${defaultCapacity}); older ones
+                           are evicted and reported as completeness.collectorDroppedMessages.
+
+CONNECTING PROGRAMS
+  Programs connect to ws://localhost:${defaultPort} by default. Inspect.layer() does not read
+  EFFECT_INSPECT_PORT: on another port pass Inspect.layer({ url: "ws://localhost:PORT" }).
+  (The examples in the effect-inspect repository do follow EFFECT_INSPECT_PORT.)
+  If no collector is listening, instrumented programs run normally but record nothing.
+
+OUTPUT AND EXIT
+  Logs "effect-inspect listening at http://localhost:PORT" on stdout once ready.
+  Exits 1 if the port is taken or the configuration is invalid; 130 on Ctrl-C.
+`)), Command.withExamples([
+    { command: 'effect-inspect start', description: 'Collector and UI on the default port' },
+    {
+        command: 'EFFECT_INSPECT_PORT=34500 effect-inspect start',
+        description: 'On another port; query it with EFFECT_INSPECT_PORT=34500 or --url',
+    },
+]));
+const rootHelp = text(`
+Inspect Effect programs: record their spans, span events, logs and memory samples,
+and query one exact run as JSON, live from a collector or offline from a saved
+.eitrace file. Written for coding agents: every query command prints one JSON
+document on stdout, diagnostics on stderr, and a distinct exit code per outcome.
+In this help, effect-inspect means however you run this CLI (npx effect-inspect,
+or node dist/cli.js in a built checkout of the repository).
+
+WHAT MUST BE TRUE
+  1. The program is instrumented: it provides Inspect.layer() from the effect-inspect
+     package (program.pipe(Effect.provide(Inspect.layer()))). Only Effect spans
+     (Effect.withSpan), span annotations/events, Effect logs and memory samples are
+     recorded. Nothing here instruments code for you, and no environment variable does.
+  2. For live queries a collector is running (\`effect-inspect start\`, leave it running)
+     and the program reaches it (ws://localhost:${defaultPort} by default). The collector
+     keeps sessions in memory until it stops, so a finished run can still be queried.
+  3. For offline queries you only need a .eitrace file (\`export\`); no collector.
+
+CHOOSE THE SESSION ID BEFORE LAUNCH
+  EFFECT_INSPECT_SESSION_ID=my-run-001 <command that runs the instrumented program>
+  then query exactly that run with --session my-run-001; no need to list sessions.
+  IDs: 1-128 ASCII letters, digits, ".", "_" or "-", starting with a letter or digit.
+  Use a new ID for every run, retry and instrumented child process. The program's
+  Inspect.layer({ sessionId }) option overrides the variable; with neither, the run
+  gets a random UUID (find it with \`sessions\`). An invalid or set-but-empty value
+  disables recording with a warning in the program's own logs; the program still
+  runs. A second run announcing an ID the collector holds is refused, the first run's
+  data is kept, and queries for that ID fail with SessionConflict instead of mixing.
+
+INVESTIGATION STEPS
+  1. summary --session ID                counts, failures, longest spans, completeness
+  2. spans   --session ID --status failed  find spans; --sort duration|outsideChildren
+  3. span    --session ID --span SPAN_ID   error, stack, attributes, ancestry, children
+  4. logs    --session ID --span SPAN_ID   logs in a span's subtree, or --from-ms/--to-ms
+  5. export  --session ID --out FILE       save the run; repeat 1-4 with --file FILE
+  sessions   lists sessions, only when you do not know the ID.
+
+SOURCES (every per-session query needs exactly one)
+  --session ID   live: the collector at --url, else http://localhost:$EFFECT_INSPECT_PORT,
+                 else http://localhost:${defaultPort}. Exact match; the newest session is never
+                 assumed and an unknown ID is SessionNotFound, never another run.
+  --file PATH    offline: a saved .eitrace; adding --session asserts the file's ID.
+
+OUTPUT AND EXIT CODES (all query commands)
+  stdout: one JSON document, pretty-printed; --json prints it compact on one line.
+    Success {"ok":true,"apiVersion":1,"op",...,"result"}; failure {"ok":false,
+    "apiVersion":1,"op","error":{"_tag","message","hint",...}}. The whole stdout,
+    newline included, is at most 1048576 bytes in either mode; pretty output is
+    larger, so a page that only fits compact gives ResponseTooLarge: add --json.
+  stderr: empty on success; a one-line diagnostic and a hint on failure.
+  0 ok (empty results too: result.total 0)   1 internal error
+  2 InvalidRequest          3 SessionNotFound         4 SpanNotFound
+  5 SessionConflict         6 ResponseTooLarge        7 TraceFileError
+  8 CollectorUnavailable    9 CollectorError          10 OutputError (export)
+  Each command's --help explains its errors and what to do next.
+
+JSON SHAPE (success, per-session queries)
+  Top-level keys: ok, apiVersion, op, query, notices (summary only), source, time,
+  termination, completeness, conflict, result (spans and logs add window).
+  Context keys are siblings of result, never inside it: .completeness, not
+  .result.completeness. Most-used paths:
+  .notices[]                  summary: read first; { code, message } facts easy to miss
+  .result.spans.open          summary: span counts by status (also total, ok, error, ...)
+  .result.unfinished          summary: innermost open spans and their open ancestors
+  .result.longest[].durationMs  summary: completed spans only, longest first
+  .result.memory              summary: heap peak, sampling gaps; null without samples
+  .result.items[]             spans and logs: the page (with total, nextOffset)
+  .completeness.status        noLossRecorded | lossRecorded | unknown
+  .termination.state          active | ended | unknown
+  Full field lists: \`<command> --help\` (RESULT FIELDS or SPAN ITEM FIELDS, CONTEXT FIELDS).
+
+EVIDENCE AND TIMING
+  Times are milliseconds since the session's clock origin (when its inspect client
+  started) and can be negative. durationMs is elapsed wall time; outsideChildrenMs is
+  elapsed time not covered by recorded child spans. Neither is CPU time or a verdict
+  that something is slow, and an open span (no end recorded) is not a deadlock.
+  Before concluding that something did not happen, read "completeness": lossRecorded
+  means evidence is missing, and noLossRecorded is not proof of completeness.
+
+Run \`effect-inspect <command> --help\` for the full flags, defaults, JSON fields and
+errors of each command.
+`);
+const cli = Command.make('effect-inspect').pipe(Command.withDescription(rootHelp), Command.withSubcommands([start, ...queryCommands]), Command.withExamples([
+    {
+        command: 'effect-inspect start',
+        description: 'Terminal 1: start the collector and leave it running',
+    },
+    {
+        command: 'EFFECT_INSPECT_SESSION_ID=failing-run-001 bun examples/failing.ts',
+        description: 'Terminal 2: run an instrumented program under a chosen ID (a repository example)',
+    },
+    {
+        command: 'effect-inspect summary --session failing-run-001 --json',
+        description: 'Overview of exactly that run',
+    },
+    {
+        command: 'effect-inspect spans --session failing-run-001 --status failed --json',
+        description: 'Its failed spans; copy a spanId and its parentSpanId',
+    },
+    { command: 'effect-inspect span --session failing-run-001 --span SPAN_ID --json' },
+    { command: 'effect-inspect logs --session failing-run-001 --span PARENT_SPAN_ID --json' },
+    {
+        command: 'effect-inspect export --session failing-run-001 --out failing-run-001.eitrace --json',
+        description: 'Save it, then query the file with no collector',
+    },
+    { command: 'effect-inspect summary --file failing-run-001.eitrace --json' },
+    { command: 'effect-inspect spans --file failing-run-001.eitrace --status failed --json' },
+]));
 const main = Effect.gen(function* () {
     const fs = yield* FileSystem;
     const packageJson = yield* fs.readFileString(fileURLToPath(new URL('../package.json', import.meta.url)));
     const { version } = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.String })))(packageJson);
-    return yield* Command.run(cli, { version });
+    const args = yield* (yield* Stdio.Stdio).args;
+    return yield* runCli(cli, version, args);
+});
+NodeRuntime.runMain(main.pipe(Effect.scoped, 
+// No interactive wizard: agents drive this CLI without a terminal.
+Effect.provide(Layer.mergeAll(NodeServices.layer, CliConfig.layer({
+    builtIns: [
+        GlobalFlag.Help,
+        GlobalFlag.Version,
+        GlobalFlag.Completions,
+        GlobalFlag.LogLevel,
+    ],
+})))), {
+    // `main` succeeds with the exit code; failures keep the default mapping.
+    teardown: (exit, onExit) => Exit.isSuccess(exit) && typeof exit.value === 'number'
+        ? onExit(exit.value)
+        : Runtime.defaultTeardown(exit, onExit),
 });
-NodeRuntime.runMain(main.pipe(Effect.scoped, Effect.provide(NodeServices.layer)));

package/dist/client/Client.d.ts

@@ -24,7 +24,7 @@
  * socket slow enough for a realistic burst to overrun the queue in the first
  * place.
  */
-import { Context, Effect, type Scope } from 'effect';
+import { Context, Effect, Result, type Scope } from 'effect';
 import type { Socket } from 'effect/unstable/socket';
 import * as Protocol from '../protocol/Schema.ts';
 declare const InspectClient_base: Context.ServiceClass<InspectClient, "effect-inspect/client/InspectClient", {
@@ -39,8 +39,21 @@ declare const InspectClient_base: Context.ServiceClass<InspectClient, "effect-in
  */
 export declare class InspectClient extends InspectClient_base {
 }
+/** Environment variable a launcher sets to choose the session ID. */
+export declare const sessionIdEnv = "EFFECT_INSPECT_SESSION_ID";
 /** Options accepted by the inspect layers. */
 export interface Options {
+    /**
+     * The session ID this run reports under, e.g. `checkout-before-1`, so it can
+     * be queried by that exact name. Takes precedence over the
+     * `EFFECT_INSPECT_SESSION_ID` environment variable; a random UUID is used
+     * when neither is set. Must satisfy {@link Protocol.isValidSessionId}.
+     *
+     * Use one ID per run: a second client instance announcing an ID the
+     * collector already holds is refused as a collision, and its telemetry is
+     * discarded — by a collector from this release on; older ones merge them.
+     */
+    readonly sessionId?: string | undefined;
     /** Name shown for this program in the webapp. Defaults to the entry script's file name. */
     readonly programName?: string | undefined;
     /** Outbound queue capacity, in messages. Defaults to 131072 (~34 MB). */
@@ -54,12 +67,40 @@ export interface Options {
      */
     readonly memoryIntervalMillis?: number | undefined;
 }
+/**
+ * Picks this client's session ID: the `sessionId` option, else the exact
+ * `EFFECT_INSPECT_SESSION_ID` key of the environment, else a random UUID.
+ *
+ * | Input                                   | Result                   |
+ * | --------------------------------------- | ------------------------ |
+ * | option given (env never touched)        | the option, if valid     |
+ * | no environment, or exact key absent     | random UUID              |
+ * | exact key set, valid                    | that value               |
+ * | exact key set but empty, or invalid     | failure (diagnostic)     |
+ * | environment exists but cannot be read   | failure (diagnostic)     |
+ *
+ * `env` yields the raw record, read directly rather than through Effect's
+ * `ConfigProvider`: the env provider reports an empty value as missing, and
+ * this setting has to tell a set-but-empty variable (`ID=$UNSET_VAR`, a
+ * launcher mistake) from an absent one. So only the exact key counts —
+ * similarly prefixed variables are irrelevant. An unreadable environment is
+ * not treated as absence: the launcher may well have chosen an ID there.
+ *
+ * Never throws: a failure is a diagnostic, and the caller records nothing
+ * rather than report under a substituted ID nobody can find. Exported for
+ * tests only; not part of the public API.
+ */
+export declare const resolveSessionId: (options: Options | undefined, env?: () => Readonly<Record<string, string | undefined>> | undefined) => Result.Result<Protocol.SessionId, string>;
 /**
  * Builds the client service and forks the fiber that owns the connection.
  *
  * The returned effect never fails and never waits for the collector: if it is
  * unreachable the fiber retries in the background while `sendUnsafe` keeps
  * accepting (and dropping) messages, so the host program is unaffected.
+ *
+ * The session ID is resolved once, here, and re-announced unchanged on every
+ * reconnect. If the chosen ID is invalid the client logs a warning and records
+ * nothing, rather than reporting under an ID nobody asked for.
  */
 export declare const make: (options?: Options) => Effect.Effect<InspectClient['Service'], never, Scope.Scope | Socket.Socket>;
 export {};

package/dist/client/Client.js

@@ -92,6 +92,8 @@ const reconnectSchedule = Schedule.exponential(Duration.millis(250)).pipe(Schedu
  */
 export class InspectClient extends Context.Service()('effect-inspect/client/InspectClient') {
 }
+/** Environment variable a launcher sets to choose the session ID. */
+export const sessionIdEnv = 'EFFECT_INSPECT_SESSION_ID';
 /**
  * The name this program lists as.
  *
@@ -128,6 +130,77 @@ const memoryUsage = () => {
     const usage = globalThis.process?.memoryUsage;
     return typeof usage === 'function' ? usage.bind(globalThis.process) : undefined;
 };
+/**
+ * The raw process environment, or `undefined` when the runtime has none.
+ *
+ * Throws when an environment exists but may not be read. Deno is asked first,
+ * with `permissions.querySync`, which reports `granted` / `prompt` / `denied`
+ * without ever prompting: reading `process.env` there without permission
+ * either throws `NotCapable` or, in a terminal, stops the host program at an
+ * interactive prompt — and inspection must never block the program it
+ * watches.
+ */
+const processEnv = () => {
+    const process = globalThis.process;
+    if (process === undefined)
+        return undefined;
+    const deno = globalThis.Deno;
+    if (deno !== undefined) {
+        const state = deno.permissions?.querySync?.({ name: 'env', variable: sessionIdEnv }).state;
+        if (state !== 'granted') {
+            throw new Error(`env access is ${state ?? 'unknown'} (Deno: --allow-env=${sessionIdEnv})`);
+        }
+    }
+    return process.env;
+};
+/**
+ * Picks this client's session ID: the `sessionId` option, else the exact
+ * `EFFECT_INSPECT_SESSION_ID` key of the environment, else a random UUID.
+ *
+ * | Input                                   | Result                   |
+ * | --------------------------------------- | ------------------------ |
+ * | option given (env never touched)        | the option, if valid     |
+ * | no environment, or exact key absent     | random UUID              |
+ * | exact key set, valid                    | that value               |
+ * | exact key set but empty, or invalid     | failure (diagnostic)     |
+ * | environment exists but cannot be read   | failure (diagnostic)     |
+ *
+ * `env` yields the raw record, read directly rather than through Effect's
+ * `ConfigProvider`: the env provider reports an empty value as missing, and
+ * this setting has to tell a set-but-empty variable (`ID=$UNSET_VAR`, a
+ * launcher mistake) from an absent one. So only the exact key counts —
+ * similarly prefixed variables are irrelevant. An unreadable environment is
+ * not treated as absence: the launcher may well have chosen an ID there.
+ *
+ * Never throws: a failure is a diagnostic, and the caller records nothing
+ * rather than report under a substituted ID nobody can find. Exported for
+ * tests only; not part of the public API.
+ */
+export const resolveSessionId = (options, env = processEnv) => {
+    const fromOption = options?.sessionId;
+    const source = fromOption === undefined ? sessionIdEnv : 'the sessionId option';
+    let chosen = fromOption;
+    if (chosen === undefined) {
+        try {
+            chosen = env()?.[sessionIdEnv];
+        }
+        catch (error) {
+            return Result.fail(`${sessionIdEnv} could not be read: ${String(error)}`);
+        }
+    }
+    if (chosen === undefined) {
+        // Effect's `Crypto` can fail with a PlatformError and nothing on this path
+        // is allowed to fail; a session id needs uniqueness, not strength.
+        // oxlint-disable-next-line effecttsgo/crypto-random-uuid
+        return Result.succeed(crypto.randomUUID());
+    }
+    if (chosen === '')
+        return Result.fail(`${source} is set but empty: unset it or choose an ID`);
+    if (!Protocol.isValidSessionId(chosen)) {
+        return Result.fail(`${source} is not a valid session ID "${chosen}": use ${Protocol.sessionIdRule}`);
+    }
+    return Result.succeed(chosen);
+};
 /**
  * Forks the fiber that samples process memory into the outbound queue.
  *
@@ -166,15 +239,25 @@ const forkMemorySampler = (deps) => Effect.suspend(() => {
  * The returned effect never fails and never waits for the collector: if it is
  * unreachable the fiber retries in the background while `sendUnsafe` keeps
  * accepting (and dropping) messages, so the host program is unaffected.
+ *
+ * The session ID is resolved once, here, and re-announced unchanged on every
+ * reconnect. If the chosen ID is invalid the client logs a warning and records
+ * nothing, rather than reporting under an ID nobody asked for.
  */
 export const make = (options) => Effect.gen(function* () {
+    const resolved = resolveSessionId(options);
+    if (Result.isFailure(resolved)) {
+        yield* Effect.logWarning(`effect-inspect disabled: ${resolved.failure}`);
+        return InspectClient.of({ sessionId: '', sendUnsafe: () => { } });
+    }
+    const sessionId = resolved.success;
+    // Distinguishes this client from an independent run that chose the same
+    // session ID; fixed for the client's lifetime so a reconnect still matches.
+    // oxlint-disable-next-line effecttsgo/crypto-random-uuid-in-effect
+    const instanceId = crypto.randomUUID();
     const socket = yield* SocketService.Socket;
     const capacity = options?.bufferSize ?? defaultBufferSize;
     const queue = yield* Queue.dropping(capacity);
-    // Effect's `Crypto` can fail with a PlatformError and nothing on this path
-    // is allowed to fail; a session id needs uniqueness, not strength.
-    // oxlint-disable-next-line effecttsgo/crypto-random-uuid-in-effect
-    const sessionId = crypto.randomUUID();
     // Tracked here rather than inside the queue so a drop survives a
     // reconnect: it is reported on the next `Hello`, which every reconnect
     // re-sends.
@@ -204,6 +287,7 @@ export const make = (options) => Effect.gen(function* () {
         pid: globalThis.process?.pid ?? 0,
         runtime: runtimeName(),
         protocolVersion: Protocol.protocolVersion,
+        instanceId,
         clock: {
             startTime: clock.currentTimeNanosUnsafe(),
             // Deliberately the wall clock: this is the anchor that maps the

package/dist/collector/QueryApi.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The collector's read-only query API over HTTP, on the collector's port.
+ *
+ * - `POST /api/v1/query` — body: a `Query.QueryRequest` JSON object. Reply:
+ *   a `Query.QueryResponse` JSON object. The body is authoritative; the
+ *   status mirrors it (200 ok, 400 InvalidRequest, 404 SessionNotFound or
+ *   SpanNotFound, 409 SessionConflict, 413 ResponseTooLarge). Every JSON
+ *   reply, errors included, is held to `Query.limits.responseBytes`.
+ * - `GET /api/v1/export?sessionId=ID` — the session's frozen snapshot as
+ *   `.eitrace` text with its loss counters in the header (200), or a
+ *   `QueryFailure` JSON body (400/404). A conflicted session still exports,
+ *   so the evidence is kept; queries against the file refuse it the same way.
+ *   Export is a lossless artifact transfer, so it is not held to the JSON
+ *   response bound: its size is the retained session (up to capacity).
+ *
+ * Each request answers from one atomic snapshot of one session. Two requests
+ * against an active session see different snapshots; compare
+ * `completeness.messagesObserved` to tell whether data changed between pages.
+ */
+import { Effect } from 'effect';
+import { HttpServerRequest, HttpServerResponse } from 'effect/unstable/http';
+import * as Query from '../query/Query.ts';
+import { Store } from './Store.ts';
+/** Path prefix of the query API. */
+export declare const apiPath = "/api/v1/";
+/** Answers one decoded request from the store. */
+export declare const answer: (input: unknown) => Effect.Effect<Query.QueryResponse, never, Store>;
+/** Handles a request under {@link apiPath}. */
+export declare const handle: (request: HttpServerRequest.HttpServerRequest, url: URL) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, Store>;

package/dist/collector/QueryApi.js

@@ -0,0 +1,91 @@
+/**
+ * The collector's read-only query API over HTTP, on the collector's port.
+ *
+ * - `POST /api/v1/query` — body: a `Query.QueryRequest` JSON object. Reply:
+ *   a `Query.QueryResponse` JSON object. The body is authoritative; the
+ *   status mirrors it (200 ok, 400 InvalidRequest, 404 SessionNotFound or
+ *   SpanNotFound, 409 SessionConflict, 413 ResponseTooLarge). Every JSON
+ *   reply, errors included, is held to `Query.limits.responseBytes`.
+ * - `GET /api/v1/export?sessionId=ID` — the session's frozen snapshot as
+ *   `.eitrace` text with its loss counters in the header (200), or a
+ *   `QueryFailure` JSON body (400/404). A conflicted session still exports,
+ *   so the evidence is kept; queries against the file refuse it the same way.
+ *   Export is a lossless artifact transfer, so it is not held to the JSON
+ *   response bound: its size is the retained session (up to capacity).
+ *
+ * Each request answers from one atomic snapshot of one session. Two requests
+ * against an active session see different snapshots; compare
+ * `completeness.messagesObserved` to tell whether data changed between pages.
+ */
+import { Clock, Effect, Result } from 'effect';
+import { HttpServerRequest, HttpServerResponse } from 'effect/unstable/http';
+import * as Query from '../query/Query.js';
+import { Store } from './Store.js';
+/** Path prefix of the query API. */
+export const apiPath = '/api/v1/';
+const statusOf = (response) => {
+    if (response.ok)
+        return 200;
+    switch (response.error._tag) {
+        case 'InvalidRequest':
+            return 400;
+        case 'SessionNotFound':
+        case 'SpanNotFound':
+            return 404;
+        case 'SessionConflict':
+            return 409;
+        case 'ResponseTooLarge':
+            return 413;
+        default:
+            return 500;
+    }
+};
+/** Every JSON reply goes through the response byte bound, errors included. */
+const reply = (unbounded) => {
+    const response = Query.limitResponse(unbounded);
+    return HttpServerResponse.jsonUnsafe(response, { status: statusOf(response) });
+};
+/** Answers one decoded request from the store. */
+export const answer = (input) => Effect.gen(function* () {
+    const decoded = Query.decodeRequest(input);
+    if (Result.isFailure(decoded))
+        return decoded.failure;
+    const request = decoded.success;
+    const store = yield* Store;
+    if (request.op === 'sessions') {
+        return Query.listSessions({ kind: 'live', file: null }, yield* store.sessions, request);
+    }
+    if (request.sessionId === undefined)
+        return Query.sessionRequired(request.op);
+    const snapshot = yield* store.snapshot(request.sessionId);
+    if (snapshot === undefined)
+        return Query.liveSessionNotFound(request.op, request.sessionId);
+    // ponytail: rebuilds the trace model per request (~O(retained messages)),
+    // synchronously, which can delay ingest on this event loop meanwhile.
+    // Cache by `messagesObserved` if repeated queries on huge sessions show up.
+    return Query.run(Query.fromSnapshot(snapshot, yield* Clock.currentTimeMillis), request);
+});
+/** Handles a request under {@link apiPath}. */
+export const handle = (request, url) => Effect.gen(function* () {
+    if (url.pathname === `${apiPath}query` && request.method === 'POST') {
+        const body = yield* Effect.result(request.json);
+        if (Result.isFailure(body)) {
+            return reply(Query.failure(null, 'InvalidRequest', 'The request body is not JSON.', 'Send a JSON query object.'));
+        }
+        return reply(yield* answer(body.success));
+    }
+    if (url.pathname === `${apiPath}export` && request.method === 'GET') {
+        const sessionId = url.searchParams.get('sessionId');
+        if (sessionId === null)
+            return reply(Query.sessionRequired('export'));
+        const store = yield* Store;
+        const snapshot = yield* store.snapshot(sessionId);
+        if (snapshot === undefined)
+            return reply(Query.liveSessionNotFound('export', sessionId));
+        const source = Query.fromSnapshot(snapshot, yield* Clock.currentTimeMillis);
+        return HttpServerResponse.text(Query.toTraceFile(source), {
+            contentType: 'application/x-ndjson',
+        });
+    }
+    return reply(Query.failure(null, 'InvalidRequest', `Unknown endpoint ${request.method} ${url.pathname}.`, `Use POST ${apiPath}query or GET ${apiPath}export?sessionId=ID.`));
+});

package/dist/collector/Server.d.ts

@@ -20,5 +20,5 @@ export declare const webappPath = "/webapp";
  * released when that one connection ends, and nothing outlives it.
  */
 export declare const handleConnection: (socket: Socket.Socket, path: string) => Effect.Effect<void, never, Store>;
-/** Serves instrumented clients, webapp sockets, and the bundled web UI. */
+/** Serves instrumented clients, webapp sockets, the query API and the bundled web UI. */
 export declare const run: (fetch?: (request: Request) => Promise<Response>) => Effect.Effect<never, never, HttpServer.HttpServer | import("effect/Scope").Scope | Store>;

package/dist/collector/Server.js

@@ -11,6 +11,7 @@ import { Effect, Fiber, PubSub, Result } from 'effect';
 import { HttpServer, HttpServerRequest, HttpServerResponse } from 'effect/unstable/http';
 import { Socket } from 'effect/unstable/socket';
 import { clientCodec, collectorCodec, webappCodec, webappRequestCodec } from '../protocol/Codec.js';
+import * as QueryApi from './QueryApi.js';
 import { Store } from './Store.js';
 /** Path a webapp client connects on; anything else is an instrumented program. */
 export const webappPath = '/webapp';
@@ -71,26 +72,29 @@ const handleClient = Effect.fnUntraced(function* (socket) {
     const store = yield* Store;
     const pull = yield* readerFor(socket);
     const writer = yield* socket.writer;
+    /** This connection's identity, so the store can tell it from a collision. */
+    const connection = Symbol('connection');
     /** The session this connection belongs to, learned from its `Hello`. */
     let sessionId;
     const onMessage = (message) => Effect.gen(function* () {
         sessionId = message.sessionId;
         switch (message._tag) {
             case 'Hello':
-                yield* store.hello(message);
+                yield* store.hello(message, connection);
                 return;
             case 'Ping':
                 // A failed write means the client is gone; the read loop notices.
                 yield* Effect.ignore(writer.write(collectorCodec.encode({ _tag: 'Pong', sessionId: message.sessionId })));
                 return;
             default:
-                yield* store.append(message);
+                yield* store.append(message, connection);
         }
     });
-    yield* readLines(pull, clientCodec.decode, onMessage, () => Effect.suspend(() => store.skipLine(sessionId))).pipe(
+    yield* readLines(pull, clientCodec.decode, onMessage, () => Effect.suspend(() => store.skipLine(sessionId, connection))).pipe(
     // However the connection ends — clean close, crash, kill -9 — the session
-    // is marked ended. A reconnect with the same id resumes it.
-    Effect.ensuring(Effect.suspend(() => (sessionId === undefined ? Effect.void : store.end(sessionId)))));
+    // is marked ended, if this connection still owns it. A reconnect from the
+    // same client instance resumes it.
+    Effect.ensuring(Effect.suspend(() => sessionId === undefined ? Effect.void : store.end(sessionId, connection))));
 });
 /** Handles one webapp client's connection for its lifetime. */
 const handleWebapp = Effect.fnUntraced(function* (socket) {
@@ -146,12 +150,15 @@ const handleWebapp = Effect.fnUntraced(function* (socket) {
  * released when that one connection ends, and nothing outlives it.
  */
 export const handleConnection = (socket, path) => Effect.scoped(path === webappPath ? handleWebapp(socket) : handleClient(socket));
-/** Serves instrumented clients, webapp sockets, and the bundled web UI. */
+/** Serves instrumented clients, webapp sockets, the query API and the bundled web UI. */
 export const run = (fetch) => Effect.gen(function* () {
     const server = yield* HttpServer.HttpServer;
     yield* server.serve(Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest;
-        const path = new URL(request.url, 'http://localhost').pathname;
+        const url = new URL(request.url, 'http://localhost');
+        const path = url.pathname;
+        if (path.startsWith(QueryApi.apiPath))
+            return yield* QueryApi.handle(request, url);
         if (request.headers.upgrade?.toLowerCase() === 'websocket') {
             const socket = yield* request.upgrade;
             yield* handleConnection(socket, path);
@@ -162,7 +169,7 @@ export const run = (fetch) => Effect.gen(function* () {
                 status: 426,
             });
         }
-        const response = yield* Effect.promise(() => fetch(new Request(new URL(request.url, 'http://localhost').href, {
+        const response = yield* Effect.promise(() => fetch(new Request(url.href, {
             method: request.method,
             headers: request.headers,
         })));