@adonis-agora/telescope 0.1.0

package/dist/src/diagnostics_watcher.d.ts

@@ -0,0 +1,72 @@
+import { type DiagnosticEvent } from './diagnostics_registry.js';
+import { type RecordInput } from './entry.js';
+import type { TelescopeStore } from './store.js';
+/** Telescope entry `type` produced by this watcher. */
+export declare const DIAGNOSTIC_ENTRY_TYPE: "diagnostic";
+/**
+ * What a single recorded diagnostic entry looks like. Mirrors the
+ * {@link DiagnosticEvent} envelope, with the library-defined data preserved
+ * verbatim under `payload`.
+ */
+export interface DiagnosticEntryContent {
+    /** Envelope schema version, or `null` on a legacy (pre-versioning) envelope. */
+    v: number | null;
+    /** The emitting library, e.g. `'billing'`. */
+    lib: string;
+    /** The event within that library, e.g. `'invoice-paid'`. */
+    event: string;
+    /** Epoch millis the producer stamped the event with. */
+    ts: number;
+    /** The trace id the producer resolved, or `null` when none. */
+    traceId: string | null;
+    /** The library-defined payload, recorded as-is. */
+    payload: unknown;
+}
+/**
+ * The ONE generic watcher behind `@adonis-agora/telescope`'s diagnostics integration. It
+ * records every event any `@adonis-agora/*` library emits through `@adonis-agora/diagnostics` —
+ * one `diagnostic` entry per `agora:<lib>:<event>` publish — without a bespoke
+ * watcher per library. This is the Agora equivalent of NestJS's
+ * `@dudousxd/nestjs-diagnostics-telescope` extension.
+ *
+ * ## Cross-repo decoupling
+ * Telescope CANNOT import `@adonis-agora/diagnostics`. Instead it reads the registry
+ * `@adonis-agora/diagnostics` publishes on `Symbol.for('@agora/diagnostics:registry')`
+ * (`{ channels, listeners }`) and subscribes to each channel via the Node builtin
+ * `node:diagnostics_channel` — no Agora import needed.
+ *
+ * ## How it auto-subscribes to current + future channels
+ * `node:diagnostics_channel` has no wildcard, so on {@link start} the watcher:
+ *  1. subscribes to every channel already in `registry.channels`, and
+ *  2. adds a listener to `registry.listeners` so any channel that appears later
+ *     (a library's first emit) is subscribed too.
+ *
+ * Subscribing also flips each producer's `channel.hasSubscribers` to `true`, which
+ * is what makes the producer build + publish envelopes at all (zero-overhead when
+ * nobody listens).
+ */
+export declare class DiagnosticsWatcher {
+    private readonly store;
+    readonly type: "diagnostic";
+    private started;
+    /** The listener we added to `registry.listeners`, for exact removal on stop. */
+    private registryListener;
+    /** name → the subscribe handler we attached, so cleanup can detach exactly. */
+    private readonly subscriptions;
+    constructor(store: TelescopeStore);
+    /**
+     * Begin recording. Subscribes to every currently-registered channel and arms a
+     * listener for future ones. A no-op when `@adonis-agora/diagnostics` is not loaded
+     * (the registry slot is absent) — telescope degrades gracefully.
+     */
+    start(): void;
+    /** Unsubscribe from every channel and stop watching for new ones. */
+    stop(): void;
+    /** Subscribe once to `name`, recording each publish as a `diagnostic` entry. */
+    private subscribe;
+    /** Validate + record, swallowing any failure so a producer can never break. */
+    private safeRecord;
+}
+/** Map a {@link DiagnosticEvent} envelope to a Telescope {@link RecordInput}. */
+export declare function buildDiagnosticEntry(msg: DiagnosticEvent): RecordInput<DiagnosticEntryContent>;
+//# sourceMappingURL=diagnostics_watcher.d.ts.map

package/dist/src/diagnostics_watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics_watcher.d.ts","sourceRoot":"","sources":["../../src/diagnostics_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,cAAuB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAkB;IAQjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPlC,QAAQ,CAAC,IAAI,eAAyB;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,gFAAgF;IAChF,OAAO,CAAC,gBAAgB,CAAyC;IACjE,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6C;gBAE9C,KAAK,EAAE,cAAc;IAElD;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAab,qEAAqE;IACrE,IAAI,IAAI,IAAI;IAYZ,gFAAgF;IAChF,OAAO,CAAC,SAAS;IAQjB,+EAA+E;IAC/E,OAAO,CAAC,UAAU;CAcnB;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAoB9F"}

package/dist/src/diagnostics_watcher.js

@@ -0,0 +1,119 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { getDiagnosticsRegistry, isDiagnosticEvent, } from './diagnostics_registry.js';
+import { EntryType } from './entry.js';
+/** Telescope entry `type` produced by this watcher. */
+export const DIAGNOSTIC_ENTRY_TYPE = EntryType.Diagnostic;
+/**
+ * The ONE generic watcher behind `@adonis-agora/telescope`'s diagnostics integration. It
+ * records every event any `@adonis-agora/*` library emits through `@adonis-agora/diagnostics` —
+ * one `diagnostic` entry per `agora:<lib>:<event>` publish — without a bespoke
+ * watcher per library. This is the Agora equivalent of NestJS's
+ * `@dudousxd/nestjs-diagnostics-telescope` extension.
+ *
+ * ## Cross-repo decoupling
+ * Telescope CANNOT import `@adonis-agora/diagnostics`. Instead it reads the registry
+ * `@adonis-agora/diagnostics` publishes on `Symbol.for('@agora/diagnostics:registry')`
+ * (`{ channels, listeners }`) and subscribes to each channel via the Node builtin
+ * `node:diagnostics_channel` — no Agora import needed.
+ *
+ * ## How it auto-subscribes to current + future channels
+ * `node:diagnostics_channel` has no wildcard, so on {@link start} the watcher:
+ *  1. subscribes to every channel already in `registry.channels`, and
+ *  2. adds a listener to `registry.listeners` so any channel that appears later
+ *     (a library's first emit) is subscribed too.
+ *
+ * Subscribing also flips each producer's `channel.hasSubscribers` to `true`, which
+ * is what makes the producer build + publish envelopes at all (zero-overhead when
+ * nobody listens).
+ */
+export class DiagnosticsWatcher {
+    store;
+    type = DIAGNOSTIC_ENTRY_TYPE;
+    started = false;
+    /** The listener we added to `registry.listeners`, for exact removal on stop. */
+    registryListener = null;
+    /** name → the subscribe handler we attached, so cleanup can detach exactly. */
+    subscriptions = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Begin recording. Subscribes to every currently-registered channel and arms a
+     * listener for future ones. A no-op when `@adonis-agora/diagnostics` is not loaded
+     * (the registry slot is absent) — telescope degrades gracefully.
+     */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const registry = getDiagnosticsRegistry();
+        if (!registry)
+            return;
+        for (const name of registry.channels)
+            this.subscribe(name);
+        const listener = (name) => this.subscribe(name);
+        this.registryListener = listener;
+        registry.listeners.add(listener);
+    }
+    /** Unsubscribe from every channel and stop watching for new ones. */
+    stop() {
+        if (this.registryListener) {
+            getDiagnosticsRegistry()?.listeners.delete(this.registryListener);
+            this.registryListener = null;
+        }
+        for (const [name, handler] of this.subscriptions) {
+            diagnostics_channel.channel(name).unsubscribe(handler);
+        }
+        this.subscriptions.clear();
+        this.started = false;
+    }
+    /** Subscribe once to `name`, recording each publish as a `diagnostic` entry. */
+    subscribe(name) {
+        if (this.subscriptions.has(name))
+            return;
+        const handler = (msg) => this.safeRecord(msg);
+        this.subscriptions.set(name, handler);
+        const channel = diagnostics_channel.channel(name);
+        channel.subscribe(handler);
+    }
+    /** Validate + record, swallowing any failure so a producer can never break. */
+    safeRecord(msg) {
+        try {
+            if (!isDiagnosticEvent(msg))
+                return;
+            // This runs inside a synchronous `node:diagnostics_channel` subscriber, so we
+            // CANNOT await the now-async store. Fire-and-forget and swallow rejections —
+            // telescope must never break (or block) an emitting code path.
+            void this.store.record(buildDiagnosticEntry(msg)).catch((err) => {
+                console.error('DiagnosticsWatcher: failed to record diagnostic event:', err);
+            });
+        }
+        catch (err) {
+            // NOT rethrown — telescope must never break an emitting code path.
+            console.error('DiagnosticsWatcher: failed to record diagnostic event:', err);
+        }
+    }
+}
+/** Map a {@link DiagnosticEvent} envelope to a Telescope {@link RecordInput}. */
+export function buildDiagnosticEntry(msg) {
+    const traceId = msg.traceId ?? null;
+    const content = {
+        // Tolerate envelopes from emitters that predate schema versioning.
+        v: msg.v ?? null,
+        lib: msg.lib,
+        event: msg.event,
+        ts: msg.ts,
+        traceId,
+        payload: msg.payload,
+    };
+    return {
+        type: DIAGNOSTIC_ENTRY_TYPE,
+        // Group by lib + event so a dashboard can roll up "billing:invoice-paid".
+        familyHash: `${msg.lib}:${msg.event}`,
+        tags: [`lib:${msg.lib}`, `event:${msg.event}`, ...(traceId ? [`trace:${traceId}`] : [])],
+        content,
+        // Carry the producer-resolved trace id (it knows the emitting context best).
+        traceId,
+    };
+}
+//# sourceMappingURL=diagnostics_watcher.js.map

package/dist/src/diagnostics_watcher.js.map

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

package/dist/src/entry.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The built-in Telescope entry types shipped by `@adonis-agora/telescope`. Adapted from
+ * the NestJS `nestjs-telescope` core, trimmed to the headless slice this package
+ * actually records (request + diagnostic). The remaining values are reserved so a
+ * future watcher (a Lucid query watcher, a mailer watcher, …) can record under a
+ * stable, already-documented type without a breaking change.
+ */
+export declare const EntryType: {
+    /** An inbound HTTP request, recorded by {@link TelescopeMiddleware}. */
+    readonly Request: "request";
+    /** A single `agora:<lib>:<event>` diagnostics publish. */
+    readonly Diagnostic: "diagnostic";
+    readonly Query: "query";
+    readonly Job: "job";
+    readonly Exception: "exception";
+    readonly Mail: "mail";
+    readonly Cache: "cache";
+    readonly Redis: "redis";
+    readonly Event: "event";
+    readonly Log: "log";
+    /** An OUTBOUND HTTP call, recorded by the http-client watcher. */
+    readonly HttpClient: "http-client";
+};
+export type BuiltinEntryType = (typeof EntryType)[keyof typeof EntryType];
+/**
+ * Where a batch of entries originated. An entry recorded inside an HTTP request
+ * is `http`; one recorded by a queue worker is `queue`; a diagnostic recorded
+ * with no active request defaults to `manual`.
+ */
+declare const BATCH_ORIGINS: readonly ["http", "queue", "schedule", "cli", "manual"];
+export type BatchOrigin = (typeof BATCH_ORIGINS)[number];
+export declare function isBatchOrigin(value: unknown): value is BatchOrigin;
+/**
+ * A captured, persisted observability record. `content` is type-specific (e.g.
+ * {@link RequestEntryContent} for a `request`, {@link DiagnosticEntryContent} for
+ * a `diagnostic`).
+ */
+export interface Entry<TContent = unknown> {
+    /** Unique id of this entry. */
+    id: string;
+    /** The entry type, one of {@link EntryType} (or a custom string). */
+    type: string;
+    /**
+     * Stable grouping key — entries that share a `familyHash` are "the same kind of
+     * thing" (e.g. all `billing:invoice-paid` diagnostics). `null` when the entry
+     * is not groupable.
+     */
+    familyHash: string | null;
+    /** The type-specific payload. */
+    content: TContent;
+    /** Searchable labels, e.g. `lib:billing`, `event:invoice-paid`, `status:500`. */
+    tags: string[];
+    /** Monotonic record order within this process. */
+    sequence: number;
+    /** Wall-clock duration of the recorded operation, when known. */
+    durationMs: number | null;
+    /** Where the recording happened. */
+    origin: BatchOrigin;
+    /** The active trace id at record time, or `null` when no context. */
+    traceId: string | null;
+    /** When the entry was recorded. */
+    createdAt: Date;
+}
+/**
+ * What a watcher hands to {@link TelescopeStore.record}. The store fills in `id`,
+ * `sequence`, `createdAt`, and resolves `traceId`/`origin` from the ambient
+ * context when the caller omits them.
+ */
+export interface RecordInput<TContent = unknown> {
+    type: string;
+    content: TContent;
+    familyHash?: string | null;
+    tags?: string[];
+    durationMs?: number | null;
+    /** Override the resolved trace id; defaults to the ambient `@adonis-agora/context`. */
+    traceId?: string | null;
+    /** Override the batch origin; defaults to `http` when a request is active. */
+    origin?: BatchOrigin;
+}
+export {};
+//# sourceMappingURL=entry.d.ts.map

package/dist/src/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/entry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;IACpB,wEAAwE;;IAExE,0DAA0D;;;;;;;;;;IAW1D,kEAAkE;;CAE1D,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAE1E;;;;GAIG;AACH,QAAA,MAAM,aAAa,yDAA0D,CAAC;AAC9E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;;GAIG;AACH,MAAM,WAAW,KAAK,CAAC,QAAQ,GAAG,OAAO;IACvC,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iCAAiC;IACjC,OAAO,EAAE,QAAQ,CAAC;IAClB,iFAAiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oCAAoC;IACpC,MAAM,EAAE,WAAW,CAAC;IACpB,qEAAqE;IACrE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mCAAmC;IACnC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ,GAAG,OAAO;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/dist/src/entry.js

@@ -0,0 +1,34 @@
+/**
+ * The built-in Telescope entry types shipped by `@adonis-agora/telescope`. Adapted from
+ * the NestJS `nestjs-telescope` core, trimmed to the headless slice this package
+ * actually records (request + diagnostic). The remaining values are reserved so a
+ * future watcher (a Lucid query watcher, a mailer watcher, …) can record under a
+ * stable, already-documented type without a breaking change.
+ */
+export const EntryType = {
+    /** An inbound HTTP request, recorded by {@link TelescopeMiddleware}. */
+    Request: 'request',
+    /** A single `agora:<lib>:<event>` diagnostics publish. */
+    Diagnostic: 'diagnostic',
+    // — reserved for deferred per-tech watchers (see DESIGN.md) —
+    Query: 'query',
+    Job: 'job',
+    Exception: 'exception',
+    Mail: 'mail',
+    Cache: 'cache',
+    Redis: 'redis',
+    Event: 'event',
+    Log: 'log',
+    /** An OUTBOUND HTTP call, recorded by the http-client watcher. */
+    HttpClient: 'http-client',
+};
+/**
+ * Where a batch of entries originated. An entry recorded inside an HTTP request
+ * is `http`; one recorded by a queue worker is `queue`; a diagnostic recorded
+ * with no active request defaults to `manual`.
+ */
+const BATCH_ORIGINS = ['http', 'queue', 'schedule', 'cli', 'manual'];
+export function isBatchOrigin(value) {
+    return typeof value === 'string' && BATCH_ORIGINS.includes(value);
+}
+//# sourceMappingURL=entry.js.map

package/dist/src/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/entry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,wEAAwE;IACxE,OAAO,EAAE,SAAS;IAClB,0DAA0D;IAC1D,UAAU,EAAE,YAAY;IACxB,8DAA8D;IAC9D,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,KAAK;IACV,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,KAAK;IACV,kEAAkE;IAClE,UAAU,EAAE,aAAa;CACjB,CAAC;AAIX;;;;GAIG;AACH,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAU,CAAC;AAG9E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3F,CAAC"}

package/dist/src/exception_family_hash.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The grouping key for "the same error". Two occurrences share a family when
+ * they have the same name, the same message, AND originate at the same top stack
+ * frame — so a `TypeError: x is undefined` thrown from two unrelated call sites
+ * stays two families, while the same bug recurring stays ONE. This is what the
+ * dashboard's exception groupings and the `new-exception` alert dedup on, so it
+ * must be deterministic across processes and across recording sources.
+ *
+ * Ported from the NestJS `nestjs-telescope` core. Why include the top frame:
+ * name+message alone over-groups (the same generic message from different code
+ * paths collapses into one family) and a host that embeds ids in messages would
+ * otherwise under-group; pinning to the first frame is the pragmatic middle
+ * ground used by most error trackers.
+ */
+export interface ExceptionFamilyParts {
+    /** Error class/name (e.g. `TypeError`); empty string when unknown. */
+    name: string;
+    /** Error message; empty string when unknown. */
+    message: string;
+    /** Full stack string, or `null` — only its FIRST frame contributes. */
+    stack: string | null;
+}
+/**
+ * Build the stable family hash for an exception from its name, message and top
+ * stack frame. Pure string concatenation (no hashing) keeps it human-readable in
+ * the dashboard and trivially equal across every recording path.
+ */
+export declare function exceptionFamilyHash(parts: ExceptionFamilyParts): string;
+//# sourceMappingURL=exception_family_hash.d.ts.map

package/dist/src/exception_family_hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception_family_hash.d.ts","sourceRoot":"","sources":["../../src/exception_family_hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAsBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAGvE"}

package/dist/src/exception_family_hash.js

@@ -0,0 +1,30 @@
+/**
+ * Extract the first stack FRAME line (the deepest call site), skipping the
+ * leading `Name: message` header that V8 and most browsers prepend. Returns an
+ * empty string when no frame line is present, so the family key degrades to
+ * name+message rather than throwing.
+ */
+function topStackFrame(stack) {
+    if (stack === null)
+        return '';
+    for (const rawLine of stack.split('\n')) {
+        const line = rawLine.trim();
+        // The first line is usually the `Error: message` header (no `at `). Frame
+        // lines start with `at ` in V8; browsers vary, so also accept an `@`-form
+        // (Firefox/Safari: `fn@url:line:col`). Take the first that looks like a frame.
+        if (line.startsWith('at ') || line.includes('@')) {
+            return line;
+        }
+    }
+    return '';
+}
+/**
+ * Build the stable family hash for an exception from its name, message and top
+ * stack frame. Pure string concatenation (no hashing) keeps it human-readable in
+ * the dashboard and trivially equal across every recording path.
+ */
+export function exceptionFamilyHash(parts) {
+    const frame = topStackFrame(parts.stack);
+    return `${parts.name}:${parts.message}:${frame}`;
+}
+//# sourceMappingURL=exception_family_hash.js.map

package/dist/src/exception_family_hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception_family_hash.js","sourceRoot":"","sources":["../../src/exception_family_hash.ts"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAoB;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC9B,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,0EAA0E;QAC1E,0EAA0E;QAC1E,+EAA+E;QAC/E,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAA2B;IAC7D,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC;AACnD,CAAC"}

package/dist/src/exception_watcher.d.ts

@@ -0,0 +1,66 @@
+import { type Entry, type RecordInput } from './entry.js';
+import type { TelescopeStore } from './store.js';
+/** The recorded body of an `exception` entry. */
+export interface ExceptionEntryContent {
+    /** Error class/name (e.g. `TypeError`, `Error`). */
+    name: string;
+    /** Error message. */
+    message: string;
+    /** Full stack string, or `null` when none was captured. */
+    stack: string | null;
+    /** HTTP method, when the exception was recorded inside a request. */
+    method: string | null;
+    /** Request url (no query string), when recorded inside a request. */
+    url: string | null;
+    /** The active trace id at record time, or `null`. */
+    traceId: string | null;
+}
+/** Optional request/correlation context for {@link recordException}. */
+export interface RecordExceptionContext {
+    /** HTTP method (upper-cased by the watcher), when applicable. */
+    method?: string;
+    /** Request url; the query string is stripped. */
+    url?: string;
+    /** Override the trace id; defaults to the ambient `@adonis-agora/context`. */
+    traceId?: string | null;
+    /** Override the batch origin; defaults to the store's resolution. */
+    origin?: RecordInput['origin'];
+}
+/**
+ * Build the `exception` {@link RecordInput} for `error` + optional context. Pure
+ * and side-effect free so it is trivially unit-testable; both the middleware
+ * auto-capture and {@link recordException} build through it. The family hash
+ * groups same-signature errors (name + message + top stack frame).
+ */
+export declare function buildExceptionInput(error: unknown, context?: RecordExceptionContext): RecordInput<ExceptionEntryContent>;
+/**
+ * Record an `exception` entry into `store` from a thrown value. The pure,
+ * framework-agnostic core used by the request middleware. Resolves to the
+ * recorded {@link Entry}; backfills the content trace id from whatever the store
+ * resolved (the ambient `@adonis-agora/context`).
+ */
+export declare function recordExceptionInStore(store: TelescopeStore, error: unknown, context?: RecordExceptionContext): Promise<Entry<ExceptionEntryContent>>;
+/**
+ * Standalone exception capture for manual / non-HTTP code paths — queue workers,
+ * ace commands, and an app's `app/exceptions/handler.ts` `report()`. Reads the
+ * active store from the global telescope runtime slot (the same handle the
+ * watchers record through) so callers need no DI wiring, and is a no-op when
+ * telescope is disabled / not booted.
+ *
+ * Fire-and-forget-safe: never throws. A missing store or a failing store is
+ * swallowed (warn-logged) so capturing an exception can never mask or replace the
+ * original error in the caller's failure path.
+ *
+ * ```ts
+ * // app/exceptions/handler.ts
+ * import { recordException } from '@adonis-agora/telescope'
+ * async report(error: unknown, ctx: HttpContext) {
+ *   recordException(error, { method: ctx.request.method(), url: ctx.request.url() })
+ *   return super.report(error, ctx)
+ * }
+ * ```
+ *
+ * Resolves to the recorded {@link Entry}, or `null` when nothing was recorded.
+ */
+export declare function recordException(error: unknown, context?: RecordExceptionContext): Promise<Entry<ExceptionEntryContent> | null>;
+//# sourceMappingURL=exception_watcher.d.ts.map

package/dist/src/exception_watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception_watcher.d.ts","sourceRoot":"","sources":["../../src/exception_watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAGrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qEAAqE;IACrE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;CAChC;AAqBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,sBAA2B,GACnC,WAAW,CAAC,qBAAqB,CAAC,CAgBpC;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAIvC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,GAAG,IAAI,CAAC,CAoB9C"}

package/dist/src/exception_watcher.js

@@ -0,0 +1,94 @@
+import { EntryType } from './entry.js';
+import { exceptionFamilyHash } from './exception_family_hash.js';
+import { getTelescopeRuntime } from './registry.js';
+/** Coerce an unknown thrown value into name/message/stack. */
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name || 'Error',
+            message: error.message,
+            stack: typeof error.stack === 'string' ? error.stack : null,
+        };
+    }
+    // Non-Error throws (strings, objects) still deserve an entry.
+    return { name: 'Error', message: String(error), stack: null };
+}
+/** Drop a `?query=string` suffix from a url. */
+function stripQuery(url) {
+    const q = url.indexOf('?');
+    return q === -1 ? url : url.slice(0, q);
+}
+/**
+ * Build the `exception` {@link RecordInput} for `error` + optional context. Pure
+ * and side-effect free so it is trivially unit-testable; both the middleware
+ * auto-capture and {@link recordException} build through it. The family hash
+ * groups same-signature errors (name + message + top stack frame).
+ */
+export function buildExceptionInput(error, context = {}) {
+    const { name, message, stack } = normalizeError(error);
+    const method = context.method !== undefined ? context.method.toUpperCase() : null;
+    const url = context.url !== undefined ? stripQuery(context.url) : null;
+    const familyHash = exceptionFamilyHash({ name, message, stack });
+    const tags = [`exception:${name}`, ...(method !== null ? [`method:${method}`] : [])];
+    return {
+        type: EntryType.Exception,
+        content: { name, message, stack, method, url, traceId: context.traceId ?? null },
+        familyHash,
+        tags,
+        ...(context.traceId !== undefined ? { traceId: context.traceId } : {}),
+        ...(context.origin !== undefined ? { origin: context.origin } : {}),
+    };
+}
+/**
+ * Record an `exception` entry into `store` from a thrown value. The pure,
+ * framework-agnostic core used by the request middleware. Resolves to the
+ * recorded {@link Entry}; backfills the content trace id from whatever the store
+ * resolved (the ambient `@adonis-agora/context`).
+ */
+export async function recordExceptionInStore(store, error, context = {}) {
+    const recorded = await store.record(buildExceptionInput(error, context));
+    recorded.content.traceId = recorded.traceId;
+    return recorded;
+}
+/**
+ * Standalone exception capture for manual / non-HTTP code paths — queue workers,
+ * ace commands, and an app's `app/exceptions/handler.ts` `report()`. Reads the
+ * active store from the global telescope runtime slot (the same handle the
+ * watchers record through) so callers need no DI wiring, and is a no-op when
+ * telescope is disabled / not booted.
+ *
+ * Fire-and-forget-safe: never throws. A missing store or a failing store is
+ * swallowed (warn-logged) so capturing an exception can never mask or replace the
+ * original error in the caller's failure path.
+ *
+ * ```ts
+ * // app/exceptions/handler.ts
+ * import { recordException } from '@adonis-agora/telescope'
+ * async report(error: unknown, ctx: HttpContext) {
+ *   recordException(error, { method: ctx.request.method(), url: ctx.request.url() })
+ *   return super.report(error, ctx)
+ * }
+ * ```
+ *
+ * Resolves to the recorded {@link Entry}, or `null` when nothing was recorded.
+ */
+export async function recordException(error, context = {}) {
+    let store;
+    try {
+        store = getTelescopeRuntime().store;
+    }
+    catch {
+        return null;
+    }
+    if (store === null)
+        return null;
+    try {
+        return await recordExceptionInStore(store, error, context);
+    }
+    catch (recordError) {
+        // Observability must never break the path it observes.
+        console.warn(`Telescope: failed to record exception: ${recordError instanceof Error ? recordError.message : String(recordError)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=exception_watcher.js.map

package/dist/src/exception_watcher.js.map

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

package/dist/src/extension/registry.d.ts

@@ -0,0 +1,17 @@
+import type { DashboardSpec, DataProvider, ExtensionContext, ExtensionEntryType, TelescopeExtension } from './types.js';
+/**
+ * Eagerly validates and collects every contribution from the registered extensions at boot. Enforces
+ * uniqueness — two extensions cannot contribute the same entry-type id, dashboard id, or provider
+ * name; a collision throws at boot (fail-closed), naming both owners, so drift is a startup error
+ * rather than a confusing runtime one. Accessors return copies; `findProvider` also tracks the owning
+ * extension so the HTTP layer can validate the `/ext/:ext/data/:provider` namespace.
+ */
+export declare class ExtensionRegistry {
+    #private;
+    constructor(extensions: readonly TelescopeExtension[], ctx: ExtensionContext);
+    entryTypes(): ExtensionEntryType[];
+    dashboards(): DashboardSpec[];
+    findProvider(name: string): DataProvider | undefined;
+    providerOwner(name: string): string | undefined;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/extension/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/extension/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,qBAAa,iBAAiB;;gBAMhB,UAAU,EAAE,SAAS,kBAAkB,EAAE,EAAE,GAAG,EAAE,gBAAgB;IAwC5E,UAAU,IAAI,kBAAkB,EAAE;IAGlC,UAAU,IAAI,aAAa,EAAE;IAG7B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAGpD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAGhD"}

package/dist/src/extension/registry.js

@@ -0,0 +1,56 @@
+/**
+ * Eagerly validates and collects every contribution from the registered extensions at boot. Enforces
+ * uniqueness — two extensions cannot contribute the same entry-type id, dashboard id, or provider
+ * name; a collision throws at boot (fail-closed), naming both owners, so drift is a startup error
+ * rather than a confusing runtime one. Accessors return copies; `findProvider` also tracks the owning
+ * extension so the HTTP layer can validate the `/ext/:ext/data/:provider` namespace.
+ */
+export class ExtensionRegistry {
+    #entryTypes = [];
+    #dashboards = [];
+    #providers = new Map();
+    #providerOwners = new Map();
+    constructor(extensions, ctx) {
+        const entryOwners = new Map();
+        const dashOwners = new Map();
+        for (const ext of extensions) {
+            for (const et of ext.entryTypes?.(ctx) ?? []) {
+                const prev = entryOwners.get(et.id);
+                if (prev !== undefined) {
+                    throw new Error(`Telescope entry type "${et.id}" is contributed by both "${prev}" and "${ext.name}". Entry-type ids must be unique.`);
+                }
+                entryOwners.set(et.id, ext.name);
+                this.#entryTypes.push(et);
+            }
+            for (const d of ext.dashboards?.(ctx) ?? []) {
+                const prev = dashOwners.get(d.id);
+                if (prev !== undefined) {
+                    throw new Error(`Telescope dashboard "${d.id}" is contributed by both "${prev}" and "${ext.name}". Dashboard ids must be unique.`);
+                }
+                dashOwners.set(d.id, ext.name);
+                this.#dashboards.push(d);
+            }
+            for (const p of ext.dataProviders?.(ctx) ?? []) {
+                const prev = this.#providerOwners.get(p.name);
+                if (prev !== undefined) {
+                    throw new Error(`Telescope data provider "${p.name}" is contributed by both "${prev}" and "${ext.name}". Provider names must be unique.`);
+                }
+                this.#providerOwners.set(p.name, ext.name);
+                this.#providers.set(p.name, p);
+            }
+        }
+    }
+    entryTypes() {
+        return [...this.#entryTypes];
+    }
+    dashboards() {
+        return [...this.#dashboards];
+    }
+    findProvider(name) {
+        return this.#providers.get(name);
+    }
+    providerOwner(name) {
+        return this.#providerOwners.get(name);
+    }
+}
+//# sourceMappingURL=registry.js.map