@fougere/calls 0.5.0-alpha.0

package/dist/panel.js

@@ -0,0 +1,102 @@
+import { createServer } from 'node:http';
+import { page } from './page.js';
+/** How often the page is told how many calls are in flight. */
+const BEAT_MS = 1000;
+/**
+ * The panel's own door: the page, and the events that fill it.
+ *
+ * Its own server and not the app's, for one measured reason: `serve()` from
+ * `@fougere/transport-http` answers 404 to everything that is not `POST /_fougere/call`,
+ * which is what makes it safe to expose — a page cannot enter it without changing what it
+ * is. So the panel binds 127.0.0.1 only, and serves both halves itself, which also means
+ * the page reads its own origin and no CORS has to be arranged.
+ */
+export function servePanel(ring, options = {}) {
+    const title = options.title ?? 'fougere';
+    const readers = new Set();
+    const html = page(title);
+    const send = (event, data) => {
+        const framed = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const reader of readers) {
+            try {
+                reader.write(framed);
+            }
+            catch {
+                readers.delete(reader);
+            }
+        }
+    };
+    const stopWatching = ring.watch((record) => send('call', record));
+    const beat = setInterval(() => {
+        if (readers.size === 0)
+            return;
+        send('vitals', { inFlight: options.inFlight?.() ?? 0, dropped: ring.since(Number.MAX_SAFE_INTEGER).dropped });
+    }, BEAT_MS);
+    beat.unref();
+    const server = createServer((request, response) => {
+        const path = (request.url ?? '/').split('?')[0];
+        if (path === '/events') {
+            response.writeHead(200, {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-cache',
+                connection: 'keep-alive',
+            });
+            // The page is handed the ring as it stands, so a reader that opens late is not
+            // looking at an empty screen that suggests a quiet app.
+            const held = ring.since(0);
+            response.write(`event: hello\ndata: ${JSON.stringify({ calls: held.calls, fronds: options.fronds ?? [] })}\n\n`);
+            readers.add(response);
+            request.on('close', () => readers.delete(response));
+            return;
+        }
+        // One door per ring, each taking a cursor: a reader asks for what is above its own,
+        // which is the whole protocol — no subscription to hold, nothing to replay.
+        for (const [name, read] of [['logs', options.logs], ['errors', options.errors], ['queries', options.queries]]) {
+            if (path !== `/${name}.json`)
+                continue;
+            const since = Number(new URL(request.url ?? '/', 'http://panel').searchParams.get('since') ?? 0);
+            response.writeHead(200, { 'content-type': 'application/json' });
+            response.end(JSON.stringify(read?.(Number.isFinite(since) ? since : 0) ?? { lines: [], cursor: 0, dropped: 0 }));
+            return;
+        }
+        if (path === '/model.json') {
+            response.writeHead(200, { 'content-type': 'application/json' });
+            response.end(JSON.stringify(options.model ?? { fronds: [] }));
+            return;
+        }
+        if (path === '/calls.json') {
+            response.writeHead(200, { 'content-type': 'application/json' });
+            response.end(JSON.stringify(ring.since(0)));
+            return;
+        }
+        if (path === '/' || path === '/index.html') {
+            response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            response.end(html);
+            return;
+        }
+        response.writeHead(404, { 'content-type': 'text/plain' });
+        response.end('the panel serves /, /events, /calls.json, /model.json, /logs.json, /errors.json and /queries.json\n');
+    });
+    return new Promise((ready, refuse) => {
+        server.on('error', refuse);
+        // Loopback only. This door has no judge — `serve()` refuses to start beyond loopback
+        // without `verify`, and this one would not know how to refuse at all.
+        server.listen(options.port ?? 0, '127.0.0.1', () => {
+            const port = server.address().port;
+            options.announce?.(`http://127.0.0.1:${port}`);
+            ready(async () => {
+                clearInterval(beat);
+                stopWatching();
+                for (const reader of readers) {
+                    try {
+                        reader.end();
+                    }
+                    catch { /* going away */ }
+                }
+                readers.clear();
+                await new Promise((closed) => server.close(() => closed()));
+            });
+        });
+    });
+}
+//# sourceMappingURL=panel.js.map

package/dist/panel.js.map

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

package/dist/rings.d.ts

@@ -0,0 +1,88 @@
+import { type DispatchEvent, type LogRecord } from '@fougere/core';
+/** One line this process wrote. `args` is the developer's own choice of what to record. */
+export interface LogLine {
+    seq: number;
+    level: LogRecord['level'];
+    name: string;
+    message: string;
+    /** Rendered here, not held: a live object would let the panel show what it later became. */
+    args: string[];
+    at: number;
+}
+/** One statement, as the panel shows it — never a parameter's value. */
+export interface QueryLine {
+    seq: number;
+    storage: string;
+    sql: string;
+    parameters: number;
+    ms: number;
+    failed: boolean;
+    at: number;
+}
+/** One kind of refusal, and how often it happened. */
+export interface ErrorGroup {
+    seq: number;
+    key: string;
+    code: string;
+    entity?: string;
+    operation?: string;
+    message: string;
+    count: number;
+    firstAt: number;
+    lastAt: number;
+    /** Which field was refused, for a VALIDATION_FAILED — the whole point of this source. */
+    fields: {
+        path: string;
+        message: string;
+    }[];
+    /** `dispatch` when a call carried it, `log` when it happened outside any call. */
+    from: 'dispatch' | 'log';
+}
+/** A bounded list that counts what it drops, so a busy moment never reads as a quiet one. */
+declare class Ring<T extends {
+    seq: number;
+}> {
+    private readonly max;
+    protected readonly held: T[];
+    protected seq: number;
+    private lost;
+    constructor(max?: number);
+    protected keep(make: (seq: number) => T): T;
+    since(cursor: number): {
+        lines: T[];
+        cursor: number;
+        dropped: number;
+    };
+}
+/**
+ * What this process logged.
+ *
+ * Chronological and nothing more: correlating a line to its call needs an async context,
+ * which core's `Ambient` port does not provide (it answers about frames and emission
+ * chains) and only `@fougere/observability` has. Aligning by timestamp would be a guess
+ * dressed as a fact — the failure mode of every panel that lies.
+ */
+export declare class LogRing extends Ring<LogLine> {
+    record(line: LogRecord): void;
+}
+export declare class QueryRing extends Ring<QueryLine> {
+    record(event: Omit<QueryLine, 'seq'>): void;
+}
+/**
+ * What was refused, from TWO sources — and that is the point.
+ *
+ * Fed by the call flow alone, this screen would miss exactly the failures that matter: a
+ * storage that would not open, an export that could not be sent, an extension that fell
+ * over. None of those is a dispatch. It is the blind spot Symfony's Headers panel and
+ * Django's History panel both have, and the only cure is a second source.
+ */
+export declare class ErrorRing extends Ring<ErrorGroup> {
+    private readonly byKey;
+    /** A refusal that a call carried. `details` reaches here intact, unlike a span's code. */
+    fromDispatch(event: DispatchEvent): void;
+    /** A line written at `error` level, which is how a failure outside any call speaks. */
+    fromLog(line: LogRecord): void;
+    private group;
+}
+export {};
+//# sourceMappingURL=rings.d.ts.map

package/dist/rings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rings.d.ts","sourceRoot":"","sources":["../src/rings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAKvF,2FAA2F;AAC3F,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,kFAAkF;IAClF,IAAI,EAAE,UAAU,GAAG,KAAK,CAAC;CAC1B;AAED,6FAA6F;AAC7F,cAAM,IAAI,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE;IAKtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAM;IAClC,SAAS,CAAC,GAAG,SAAK;IAClB,OAAO,CAAC,IAAI,CAAK;IAEjB,YAA6B,GAAG,SAAO,EAAI;IAE3C,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,CAM1C;IAED,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAErE;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,OAAQ,SAAQ,IAAI,CAAC,OAAO,CAAC;IACxC,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAS5B;CACF;AAED,qBAAa,SAAU,SAAQ,IAAI,CAAC,SAAS,CAAC;IAC5C,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,IAAI,CAE1C;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,IAAI,CAAC,UAAU,CAAC;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,0FAA0F;IAC1F,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAYvC;IAED,uFAAuF;IACvF,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAI7B;IAED,OAAO,CAAC,KAAK;CAqBd"}

package/dist/rings.js

@@ -0,0 +1,112 @@
+import { validationErrorsOf } from '@fougere/core';
+/** How many each ring keeps. Bounded by a NUMBER, never by a duration. */
+const KEPT = 300;
+/** A bounded list that counts what it drops, so a busy moment never reads as a quiet one. */
+class Ring {
+    max;
+    held = [];
+    seq = 0;
+    lost = 0;
+    constructor(max = KEPT) {
+        this.max = max;
+    }
+    keep(make) {
+        const one = make(++this.seq);
+        this.held.push(one);
+        if (this.held.length > this.max)
+            this.lost += this.held.splice(0, this.held.length - this.max).length;
+        return one;
+    }
+    since(cursor) {
+        return { lines: this.held.filter((one) => one.seq > cursor), cursor: this.seq, dropped: this.lost };
+    }
+}
+/**
+ * What this process logged.
+ *
+ * Chronological and nothing more: correlating a line to its call needs an async context,
+ * which core's `Ambient` port does not provide (it answers about frames and emission
+ * chains) and only `@fougere/observability` has. Aligning by timestamp would be a guess
+ * dressed as a fact — the failure mode of every panel that lies.
+ */
+export class LogRing extends Ring {
+    record(line) {
+        this.keep((seq) => ({
+            seq,
+            level: line.level,
+            name: line.name,
+            message: line.message,
+            args: line.args.map(render),
+            at: line.at,
+        }));
+    }
+}
+export class QueryRing extends Ring {
+    record(event) {
+        this.keep((seq) => ({ ...event, seq }));
+    }
+}
+/**
+ * What was refused, from TWO sources — and that is the point.
+ *
+ * Fed by the call flow alone, this screen would miss exactly the failures that matter: a
+ * storage that would not open, an export that could not be sent, an extension that fell
+ * over. None of those is a dispatch. It is the blind spot Symfony's Headers panel and
+ * Django's History panel both have, and the only cure is a second source.
+ */
+export class ErrorRing extends Ring {
+    byKey = new Map();
+    /** A refusal that a call carried. `details` reaches here intact, unlike a span's code. */
+    fromDispatch(event) {
+        const error = event.error;
+        const { entity, operation } = event.call.address;
+        this.group({
+            code: typeof error?.code === 'string' ? error.code : 'INTERNAL_ERROR',
+            entity,
+            operation,
+            message: error?.message ?? String(event.error),
+            fields: (validationErrorsOf(error) ?? []).map((one) => ({ path: one.path, message: one.message })),
+            from: 'dispatch',
+        });
+    }
+    /** A line written at `error` level, which is how a failure outside any call speaks. */
+    fromLog(line) {
+        if (line.level !== 'error')
+            return;
+        this.group({ code: line.name, message: line.message, fields: [], from: 'log' });
+    }
+    group(one) {
+        const key = [one.from, one.code, one.entity ?? '', one.operation ?? ''].join(' ');
+        const held = this.byKey.get(key);
+        const at = Date.now();
+        // Grouped, because a refusal seen forty times is one line with a count — not forty
+        // lines that push everything else out of a bounded ring.
+        if (held) {
+            held.count += 1;
+            held.lastAt = at;
+            held.message = one.message;
+            if (one.fields.length > 0)
+                held.fields = one.fields;
+            // Re-numbered so a reader that already saw this group is handed the higher count.
+            // Without it a refusal seen forty times reports one, forever: the group is mutated
+            // in place, and a cursor asks only for what is above it.
+            held.seq = ++this.seq;
+            return;
+        }
+        this.byKey.set(key, this.keep((seq) => ({ ...one, key, seq, count: 1, firstAt: at, lastAt: at })));
+    }
+}
+/** An argument as one line. A live object would change under the reader; a string cannot. */
+function render(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Error)
+        return `${value.name}: ${value.message}`;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=rings.js.map

package/dist/rings.js.map

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fougere/calls",
+  "version": "0.5.0-alpha.0",
+  "description": "Optional call log for Fougere: a bounded ring of every dispatch, served as an rpc operation. Read it with `fougere devtools`.",
+  "keywords": [
+    "fougere",
+    "typescript",
+    "devtools",
+    "observability",
+    "dispatch"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chok/fougere.git",
+    "directory": "packages/calls"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "@fougere/core": "^0.5.0-alpha.0",
+    "@fougere/adapter-sql": "^0.5.0-alpha.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.0",
+    "@fougere/adapter-sql": "0.5.0-alpha.0",
+    "@fougere/container": "0.5.0-alpha.0",
+    "@fougere/core": "0.5.0-alpha.0",
+    "@fougere/schema": "0.5.0-alpha.0",
+    "@fougere/transport-http": "0.5.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@fougere/adapter-sql": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  }
+}

package/src/CallRing.ts

@@ -0,0 +1,119 @@
+import { RPC_ENTITY, type CallPage, type CallRecord, type DispatchEvent } from '@fougere/core';
+
+/** The message and the code of a refusal, without the stack that carries a body. */
+function refusalOf(error: unknown): CallRecord['refusal'] {
+  if (error === null || error === undefined) return { message: 'unknown refusal' };
+  const held = error as { code?: unknown; message?: unknown };
+
+  return {
+    ...(typeof held.code === 'string' ? { code: held.code } : {}),
+    message: typeof held.message === 'string' ? held.message : String(error),
+  };
+}
+
+/**
+ * A bounded log of what this process dispatched.
+ *
+ * The five transitions of one call are folded into one record: `received` opens it,
+ * `resolved` names the route, `completed`/`failed` settle the verdict, `settled` closes
+ * the duration. They are matched by the identity of the `Call`, which is the same frozen
+ * object across all five.
+ */
+export class CallRing {
+  private readonly held: CallRecord[] = [];
+  private readonly open = new WeakMap<object, CallRecord>();
+  private seq = 0;
+  private lost = 0;
+  private readonly watching = new Set<(record: CallRecord) => void>();
+
+  constructor(
+    private readonly max = 500,
+    private readonly frondOf: (entity: string) => string | undefined = () => undefined,
+  ) {}
+
+  /**
+   * KNOWN LIMIT — a call this process ORIGINATES carries no trace here.
+   *
+   * `trace()` writes the traceparent inside the middleware chain, so inside
+   * `route.execute(call)`; the observer saw the `Call` at `received`, and that object is
+   * frozen. An ARRIVING call is unaffected: its traceparent is already on the invocation
+   * the transport handed over, which is why a hosted frond shows traces and its consumer
+   * does not.
+   *
+   * Closing it means `DispatchEvent` carrying the invocation as it ENDED rather than as it
+   * arrived — a core change, deliberately not smuggled in here. Until then the Traces view
+   * speaks for the side that receives.
+   */
+  record(event: DispatchEvent): void {
+    // A reader reaches this ring through `rpc`, so recording that would make the panel
+    // watch itself — one reader, one line, forever.
+    if (event.call.address.entity === RPC_ENTITY) return;
+
+    if (event.stage === 'received') return this.opened(event);
+
+    const record = this.open.get(event.call);
+    if (!record) return;
+
+    if (event.stage === 'resolved' && event.routeKind) record.route = event.routeKind;
+    if (event.stage === 'completed') record.verdict = 'ok';
+    if (event.stage === 'failed') {
+      record.verdict = 'failed';
+      record.refusal = refusalOf(event.error);
+    }
+    if (event.stage === 'settled') {
+      record.ms = Date.now() - record.startedAt;
+      if (event.routeKind) record.route = event.routeKind;
+      this.open.delete(event.call);
+      for (const told of this.watching) {
+        // A watcher's own failure is not the dispatch's problem — the same rule
+        // `DispatchLifecycle` applies to an observer.
+        try { told(record); } catch { /* observational */ }
+      }
+    }
+  }
+
+  private opened(event: DispatchEvent): void {
+    const { entity, operation, surface } = event.call.address;
+    const frond = this.frondOf(entity);
+    const { trace, caller } = event.call.invocation;
+    const record: CallRecord = {
+      seq: ++this.seq,
+      ...(frond ? { frond } : {}),
+      entity,
+      operation,
+      ...(surface !== undefined ? { surface } : {}),
+      ...(trace ? { trace } : {}),
+      ...(caller ? { caller } : {}),
+      startedAt: Date.now(),
+      verdict: 'running',
+    };
+
+    this.held.push(record);
+    this.open.set(event.call, record);
+
+    if (this.held.length > this.max) this.lost += this.held.splice(0, this.held.length - this.max).length;
+  }
+
+  /**
+   * Be told when a record settles, and get the unsubscription back.
+   *
+   * A page that polls is a page that is always a little wrong; this is what lets a door
+   * push instead. Told at `settled` and not at `received`, because a record is only
+   * complete then — a reader would otherwise redraw the same line four times.
+   */
+  watch(told: (record: CallRecord) => void): () => void {
+    this.watching.add(told);
+
+    return () => this.watching.delete(told);
+  }
+
+  /** Everything above `cursor`, and what was lost while the reader was away. */
+  since(cursor: number, inFlight = 0): CallPage {
+    return {
+      calls: this.held.filter((record) => record.seq > cursor),
+      cursor: this.seq,
+      inFlight,
+      dropped: this.lost,
+    };
+  }
+}