@dudousxd/nestjs-diagnostics 0.8.1 → 0.9.0

package/dist/nestjs/transports.js

@@ -0,0 +1,127 @@
+import { createDiagnosticsRedisRelay } from '../redis-relay.js';
+export const DURABLE_DELIVERY_MODULE = '@dudousxd/nestjs-durable-diagnostics/delivery';
+const DURABLE_PACKAGE = '@dudousxd/nestjs-durable-diagnostics';
+export const DURABLE_NOT_INSTALLED = `\`transports.durable()\` requires ${DURABLE_PACKAGE}. Install it and import DurableModule in your app, or pick another transport.`;
+export const DURABLE_OUTDATED = `\`transports.durable()\` requires a version of ${DURABLE_PACKAGE} that exports \`${DURABLE_DELIVERY_MODULE}\`. Upgrade it, or pick another transport.`;
+export const DURABLE_NOT_CONFIGURED = '`transports.durable()` requires durable to be configured: no durable engine resolves in this app. Import DurableModule, or pick another transport.';
+export const BULLMQ_NOT_INSTALLED = '`transports.queue()` requires bullmq. Install it (`pnpm add bullmq`), or pick another transport.';
+const importDurable = () => import(/* @vite-ignore */ DURABLE_DELIVERY_MODULE);
+const importBullmq = () => import(/* @vite-ignore */ 'bullmq');
+const loaders = { durable: importDurable, bullmq: importBullmq };
+/** Replace how optional modules are imported. Internal, for tests. */
+export function setTransportModuleLoader(name, loader) {
+    if (name === 'durable') {
+        loaders.durable = loader ?? importDurable;
+    }
+    else {
+        loaders.bullmq = loader ?? importBullmq;
+    }
+}
+/** `'missing'` when `pkg` is not installed, `'outdated'` when it lacks the subpath, else `null`. */
+function classifyImportError(error, pkg) {
+    const { code, message } = (error ?? {});
+    const text = typeof message === 'string' ? message : '';
+    if (!text.includes(pkg))
+        return null;
+    if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+        return 'outdated';
+    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND')
+        return 'missing';
+    return null;
+}
+/**
+ * The transport factories for `DiagnosticsModule.forRoot({ default, transports })`:
+ *
+ * ```ts
+ * DiagnosticsModule.forRoot({
+ *   default: 'queue',
+ *   transports: {
+ *     redis: transports.redis({ pub, sub }),
+ *     queue: transports.queue({ connection: { host: 'localhost', port: 6379 } }),
+ *     durable: transports.durable({ retries: 5 }),
+ *   },
+ * })
+ * ```
+ *
+ * Each factory returns a lazy {@link TransportProvider}: only the selected `default` starts, and
+ * only it imports its optional dependency.
+ */
+export const transports = {
+    /**
+     * Broadcast over Redis pub/sub, best-effort: listeners run in every process the event reaches.
+     * Events of libs with listeners are forwarded automatically; `libs`/`channels`/`all` forward more.
+     */
+    redis(config) {
+        return async (ctx) => {
+            const libs = [...new Set([...(config.libs ?? []), ...ctx.listenerLibs])];
+            const receive = ctx.role !== 'api';
+            const stop = createDiagnosticsRedisRelay({
+                pub: config.pub,
+                ...(receive ? (config.sub !== undefined ? { sub: config.sub } : {}) : { receive: false }),
+                libs,
+                ...(config.channels !== undefined ? { channels: config.channels } : {}),
+                ...(config.all !== undefined ? { all: config.all } : {}),
+                ...(config.redisChannel !== undefined ? { redisChannel: config.redisChannel } : {}),
+                nodeId: ctx.nodeId,
+            });
+            return { stop };
+        };
+    },
+    /**
+     * Run listeners through BullMQ: one job per `(listener, event)`, retried when the handler throws
+     * (at-least-once). Every process that is not `role: 'api'` runs a worker for the queue.
+     * Requires the optional peer `bullmq`.
+     */
+    queue(config) {
+        return async (ctx) => {
+            let bullmq;
+            try {
+                bullmq = await loaders.bullmq();
+            }
+            catch (error) {
+                if (classifyImportError(error, 'bullmq') === 'missing') {
+                    throw new Error(BULLMQ_NOT_INSTALLED, { cause: error });
+                }
+                throw error;
+            }
+            const { createQueueTransport } = await import('./queue-transport.js');
+            return createQueueTransport(bullmq, config, ctx);
+        };
+    },
+    /**
+     * Run listeners as durable runs: one run per `(listener, event)`, retried with backoff and
+     * idempotent per event id. Imports `@dudousxd/nestjs-durable-diagnostics/delivery` only when this
+     * transport is the selected `default`; bootstrap fails with a clear error when it is missing or
+     * durable is not configured.
+     */
+    durable(config = {}) {
+        return async (ctx) => {
+            let durable;
+            try {
+                durable = await loaders.durable();
+            }
+            catch (error) {
+                const kind = classifyImportError(error, DURABLE_PACKAGE);
+                if (kind === 'missing')
+                    throw new Error(DURABLE_NOT_INSTALLED, { cause: error });
+                if (kind === 'outdated')
+                    throw new Error(DURABLE_OUTDATED, { cause: error });
+                throw error;
+            }
+            if (typeof durable?.isConfigured !== 'function' ||
+                typeof durable.createDeliveryTransport !== 'function') {
+                throw new Error(DURABLE_OUTDATED);
+            }
+            if (!(await durable.isConfigured(ctx.moduleRef)))
+                throw new Error(DURABLE_NOT_CONFIGURED);
+            return durable.createDeliveryTransport({
+                moduleRef: ctx.moduleRef,
+                nodeId: ctx.nodeId,
+                role: ctx.role,
+                invoke: ctx.invoke,
+                listenerIds: ctx.listenerIds,
+            }, config);
+        };
+    },
+};
+//# sourceMappingURL=transports.js.map

package/dist/nestjs/transports.js.map

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

package/dist/redis-relay.d.ts

@@ -0,0 +1,60 @@
+/** The minimal Redis pub/sub surface the relay uses. An ioredis instance satisfies it structurally. */
+export interface RedisLike {
+    publish(channel: string, message: string): unknown;
+    /** When present, a tick's forwarded events go out as one pipeline instead of one round trip each. */
+    pipeline?(): RedisPipelineLike;
+    subscribe(channel: string, callback?: (err: Error | null, count: number) => void): unknown;
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    removeListener(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    unsubscribe(channel: string): unknown;
+}
+/** The slice of an ioredis pipeline the relay uses to batch publishes. */
+export interface RedisPipelineLike {
+    publish(channel: string, message: string): unknown;
+    exec(): unknown;
+}
+export interface ChannelRef {
+    lib: string;
+    event: string;
+}
+export interface DiagnosticsRedisRelayOptions {
+    /** Publisher connection. */
+    pub: RedisLike;
+    /**
+     * Subscriber connection (separate from `pub`). For ioredis: `const sub = pub.duplicate()`.
+     * Required unless `receive` is `false`.
+     */
+    sub?: RedisLike;
+    /**
+     * Re-emit events other processes forward onto this process's bus. Default `true`; `false` makes
+     * a publish-only relay that never subscribes (a `role: 'api'` process).
+     */
+    receive?: boolean;
+    /** Forward every event of these libs (current + future channels). */
+    libs?: string[];
+    /** Forward these exact channels, in addition to `libs`. */
+    channels?: ChannelRef[];
+    /** Forward EVERY aviary channel (current + future). Overrides `libs`/`channels`. Default false. */
+    all?: boolean;
+    /** Redis channel to relay on. Default 'aviary:diagnostics:relay'. */
+    redisChannel?: string;
+    /** Unique id for THIS process, for echo suppression. Default a random id. */
+    nodeId?: string;
+}
+/**
+ * Relay diagnostics events across processes over Redis pub/sub. The envelope crosses as JSON with
+ * its `id` intact, and the re-emitted copy is marked as relayed (see {@link publishRelayed}). Forwards selected local
+ * `aviary:<lib>:<event>` channels to Redis and re-emits Redis-received events onto the local bus, so
+ * `@OnDiagnostic` handlers / `getChannel(...).subscribe(...)` fire cross-process. Loop-safe via nodeId
+ * echo suppression and a re-emit guard. Never throws into `emit()` or the Redis handler. Does NOT
+ * close the `pub`/`sub` connections — the caller owns them.
+ *
+ * Forwarding happens off the emitter's call stack: selected events are queued and, once per event
+ * loop turn, serialized and published in emit order (one Redis message per event, sent as a single
+ * pipeline when `pub` supports it).
+ *
+ * @returns a teardown that publishes any queued events, then removes all local subscriptions and
+ *   the Redis message handler.
+ */
+export declare function createDiagnosticsRedisRelay(options: DiagnosticsRedisRelayOptions): () => void;
+//# sourceMappingURL=redis-relay.d.ts.map

package/dist/redis-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-relay.d.ts","sourceRoot":"","sources":["../src/redis-relay.ts"],"names":[],"mappings":"AAMA,uGAAuG;AACvG,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACnD,qGAAqG;IACrG,QAAQ,CAAC,IAAI,iBAAiB,CAAC;IAC/B,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;IAC3F,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;IACpF,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;IAChG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACvC;AAED,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACnD,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,4BAA4B;IAC3C,4BAA4B;IAC5B,GAAG,EAAE,SAAS,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,mGAAmG;IACnG,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,IAAI,CAmI7F"}

package/dist/redis-relay.js

@@ -0,0 +1,170 @@
+import { randomUUID } from 'node:crypto';
+import { CHANNEL_PREFIX, channelName, getChannel } from './channel.js';
+import { onChannelRegistered, registeredChannels } from './registry.js';
+import { publishRelayed } from './relayed.js';
+const DEFAULT_REDIS_CHANNEL = 'aviary:diagnostics:relay';
+/** Strip the `aviary:` prefix and split on the FIRST colon — the event segment may contain dots
+ *  (e.g. `durable:run.failed`), but the lib/event boundary is the first colon after the prefix. */
+function parseChannelName(name) {
+    const prefix = `${CHANNEL_PREFIX}:`;
+    if (!name.startsWith(prefix))
+        return null;
+    const rest = name.slice(prefix.length);
+    const idx = rest.indexOf(':');
+    if (idx <= 0 || idx === rest.length - 1)
+        return null;
+    return { lib: rest.slice(0, idx), event: rest.slice(idx + 1) };
+}
+/**
+ * Relay diagnostics events across processes over Redis pub/sub. The envelope crosses as JSON with
+ * its `id` intact, and the re-emitted copy is marked as relayed (see {@link publishRelayed}). Forwards selected local
+ * `aviary:<lib>:<event>` channels to Redis and re-emits Redis-received events onto the local bus, so
+ * `@OnDiagnostic` handlers / `getChannel(...).subscribe(...)` fire cross-process. Loop-safe via nodeId
+ * echo suppression and a re-emit guard. Never throws into `emit()` or the Redis handler. Does NOT
+ * close the `pub`/`sub` connections — the caller owns them.
+ *
+ * Forwarding happens off the emitter's call stack: selected events are queued and, once per event
+ * loop turn, serialized and published in emit order (one Redis message per event, sent as a single
+ * pipeline when `pub` supports it).
+ *
+ * @returns a teardown that publishes any queued events, then removes all local subscriptions and
+ *   the Redis message handler.
+ */
+export function createDiagnosticsRedisRelay(options) {
+    const { pub } = options;
+    const sub = options.receive === false ? undefined : options.sub;
+    if (options.receive !== false && sub === undefined) {
+        throw new Error('@dudousxd/nestjs-diagnostics: the Redis relay needs a `sub` connection, or `receive: false` for a publish-only relay');
+    }
+    const redisChannel = options.redisChannel ?? DEFAULT_REDIS_CHANNEL;
+    const nodeId = options.nodeId ?? randomUUID();
+    const forwardAll = options.all === true;
+    const libs = options.libs ?? [];
+    const exact = options.channels ?? [];
+    const subscriptions = [];
+    const subscribed = new Set();
+    const reEmitting = new WeakSet();
+    const pending = [];
+    let scheduled = null;
+    const publishOne = (message) => {
+        try {
+            pub.publish(redisChannel, message);
+        }
+        catch {
+            // a failing publish drops only its own event
+        }
+    };
+    const flush = () => {
+        if (scheduled !== null) {
+            clearImmediate(scheduled);
+            scheduled = null;
+        }
+        if (pending.length === 0)
+            return;
+        const messages = [];
+        for (const env of pending.splice(0)) {
+            try {
+                messages.push(JSON.stringify({ node: nodeId, env }));
+            }
+            catch {
+                // an unserializable event is dropped without affecting the rest of the batch
+            }
+        }
+        if (messages.length > 1 && typeof pub.pipeline === 'function') {
+            try {
+                const pipeline = pub.pipeline();
+                for (const message of messages)
+                    pipeline.publish(redisChannel, message);
+                pipeline.exec();
+            }
+            catch {
+                // never throw out of the flush
+            }
+            return;
+        }
+        for (const message of messages)
+            publishOne(message);
+    };
+    const forward = (msg) => {
+        if (typeof msg !== 'object' || msg === null)
+            return;
+        if (reEmitting.has(msg))
+            return; // a re-emitted remote event — do not send it back
+        pending.push(msg);
+        scheduled ??= setImmediate(flush);
+    };
+    const subscribeRef = (ref) => {
+        const name = channelName(ref.lib, ref.event);
+        if (subscribed.has(name))
+            return;
+        getChannel(ref.lib, ref.event).subscribe(forward);
+        subscribed.add(name);
+        subscriptions.push({ ref, listener: forward });
+    };
+    const wildcardMatches = (name) => {
+        if (forwardAll)
+            return name.startsWith(`${CHANNEL_PREFIX}:`);
+        return libs.some((lib) => name.startsWith(`${CHANNEL_PREFIX}:${lib}:`));
+    };
+    for (const ref of exact)
+        subscribeRef(ref);
+    const hasWildcard = forwardAll || libs.length > 0;
+    if (hasWildcard) {
+        for (const name of registeredChannels()) {
+            if (wildcardMatches(name)) {
+                const ref = parseChannelName(name);
+                if (ref)
+                    subscribeRef(ref);
+            }
+        }
+    }
+    const offRegistered = hasWildcard
+        ? onChannelRegistered((name) => {
+            if (wildcardMatches(name)) {
+                const ref = parseChannelName(name);
+                if (ref)
+                    subscribeRef(ref);
+            }
+        })
+        : null;
+    const onMessage = (channel, raw) => {
+        if (channel !== redisChannel)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return; // ignore malformed
+        }
+        if (parsed.node === nodeId)
+            return; // our own echo
+        const env = parsed.env;
+        if (!env || typeof env.lib !== 'string' || typeof env.event !== 'string')
+            return;
+        reEmitting.add(env);
+        try {
+            publishRelayed(env, () => getChannel(env.lib, env.event).publish(env));
+        }
+        catch {
+            // a local subscriber threw — never propagate into the message handler
+        }
+        finally {
+            reEmitting.delete(env);
+        }
+    };
+    sub?.subscribe(redisChannel);
+    sub?.on('message', onMessage);
+    return () => {
+        flush();
+        for (const { ref, listener } of subscriptions) {
+            getChannel(ref.lib, ref.event).unsubscribe(listener);
+        }
+        subscriptions.length = 0;
+        subscribed.clear();
+        offRegistered?.();
+        sub?.removeListener('message', onMessage);
+        sub?.unsubscribe(redisChannel);
+    };
+}
+//# sourceMappingURL=redis-relay.js.map

package/dist/redis-relay.js.map

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

package/dist/relayed.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Run `publish` with `env` marked as a relayed copy. Call it from a relay that re-emits an event
+ * received from another process onto the local bus.
+ */
+export declare function publishRelayed(env: object, publish: () => void): void;
+/** Whether `env` is a relayed copy being re-emitted right now (it was emitted in another process). */
+export declare function isRelayed(env: object): boolean;
+//# sourceMappingURL=relayed.d.ts.map

package/dist/relayed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayed.d.ts","sourceRoot":"","sources":["../src/relayed.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAOrE;AAED,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C"}

package/dist/relayed.js

@@ -0,0 +1,31 @@
+/**
+ * Envelopes a relay is re-emitting right now: copies of an event that was emitted in ANOTHER
+ * process. Listener dispatch reads it to deliver only at the origin. With a delivering transport
+ * (`queue`, `durable`), the process that called `emit` hands each `(listener, event)` pair over
+ * once, and a relayed copy of the same event is never handed over again.
+ *
+ * Held on a `Symbol.for` slot of `globalThis`, so relays and dispatch agree even when more than
+ * one copy of this package is loaded.
+ */
+const RELAYED_KEY = Symbol.for('@dudousxd/nestjs-diagnostics:relayed');
+const slots = globalThis;
+const relayed = slots[RELAYED_KEY] ?? new WeakSet();
+slots[RELAYED_KEY] = relayed;
+/**
+ * Run `publish` with `env` marked as a relayed copy. Call it from a relay that re-emits an event
+ * received from another process onto the local bus.
+ */
+export function publishRelayed(env, publish) {
+    relayed.add(env);
+    try {
+        publish();
+    }
+    finally {
+        relayed.delete(env);
+    }
+}
+/** Whether `env` is a relayed copy being re-emitted right now (it was emitted in another process). */
+export function isRelayed(env) {
+    return relayed.has(env);
+}
+//# sourceMappingURL=relayed.js.map

package/dist/relayed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayed.js","sourceRoot":"","sources":["../src/relayed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;AACvE,MAAM,KAAK,GAAG,UAAqE,CAAC;AACpF,MAAM,OAAO,GAAoB,KAAK,CAAC,WAAW,CAAC,IAAI,IAAI,OAAO,EAAU,CAAC;AAC7E,KAAK,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,OAAmB;IAC7D,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC"}

package/dist/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAwB,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAS/E;AA0GD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EACvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,CAAC,CAyDH;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,2EAA2E;IAC3E,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC;CACnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EAC7E,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GACZ,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAMzC"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAwB,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAS/E;AA2GD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EACvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,CAAC,CAyDH;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,2EAA2E;IAC3E,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC;CACnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EAC7E,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GACZ,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAMzC"}

package/dist/trace.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import diagnostics_channel from 'node:diagnostics_channel';
 import { channelName } from './channel.js';
 import { resolveTraceId } from './context-accessor.js';
@@ -77,6 +78,7 @@ function publishPhase(channel, phase, lib, event, spanId, traceId, extra) {
     try {
         const envelope = {
             v: SPAN_SCHEMA_VERSION,
+            id: randomUUID(),
             ts: Date.now(),
             lib,
             event,

package/dist/trace.js.map

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

package/dist/types.d.ts

@@ -14,6 +14,13 @@ export interface DiagnosticEvent<TPayload = unknown> {
      * versioning existed (treat an absent `v` as the original, unversioned shape).
      */
     v?: number;
+    /**
+     * Unique id of this envelope (a UUID), stamped by `emit`. Relays carry it unchanged, so the
+     * same event has the same `id` in every process it reaches. Delivering transports use it as
+     * the idempotency key: one delivery per `(listener, id)`. Optional on the type so observers
+     * stay tolerant of envelopes published before ids existed.
+     */
+    id?: string;
     /** Epoch millis when the event was emitted (`Date.now()` at publish time). */
     ts: number;
     /** The emitting library, e.g. `'billing'` — the `<lib>` in `aviary:<lib>:<event>`. */
@@ -116,6 +123,8 @@ export interface SpanEvent<TPayload = unknown, TResult = unknown> {
      * so observers stay tolerant of legacy/untagged envelopes.
      */
     v?: number;
+    /** Unique id of this phase envelope (a UUID), stamped by `trace`. Correlate phases with `spanId`. */
+    id?: string;
     /** Epoch millis when this phase event was published (`Date.now()`). */
     ts: number;
     /** The emitting library — the `<lib>` in `aviary:<lib>:<event>`. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO;IACjD;;;;;;OAMG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,QAAQ,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;CAAG;AAEnC;;;;;GAKG;AACH,KAAK,WAAW,GAAG,MAAM,GAAG,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,WAAW,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,MAAM,eAAe,GACzE,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,WAAW,GACpD,MAAM,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CACnB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,IACnB,IAAI,SAAS,MAAM,eAAe,GAClC,MAAM,SAAS,MAAM,eAAe,CAAC,IAAI,CAAC,GACxC,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAC7B,OAAO,GACT,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D;;;;;OAKG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iEAAiE;IACjE,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO;IACjD;;;;;;OAMG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,QAAQ,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;CAAG;AAEnC;;;;;GAKG;AACH,KAAK,WAAW,GAAG,MAAM,GAAG,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,WAAW,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,MAAM,eAAe,GACzE,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,WAAW,GACpD,MAAM,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CACnB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,IACnB,IAAI,SAAS,MAAM,eAAe,GAClC,MAAM,SAAS,MAAM,eAAe,CAAC,IAAI,CAAC,GACxC,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAC7B,OAAO,GACT,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D;;;;;OAKG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iEAAiE;IACjE,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,8 @@
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11 || ^12",
     "@nestjs/core": "^10 || ^11 || ^12",
-    "reflect-metadata": "^0.2"
+    "reflect-metadata": "^0.2",
+    "bullmq": "^5"
   },
   "peerDependenciesMeta": {
     "@nestjs/common": {
@@ -51,6 +52,9 @@
     },
     "reflect-metadata": {
       "optional": true
+    },
+    "bullmq": {
+      "optional": true
     }
   },
   "files": [
@@ -68,18 +72,22 @@
     "**/channel.js",
     "**/channel.ts",
     "**/trace.js",
-    "**/trace.ts"
+    "**/trace.ts",
+    "**/relayed.js",
+    "**/relayed.ts"
   ],
   "devDependencies": {
     "@nestjs/authentication": "0.1.5",
     "@nestjs/authorization": "0.1.3",
-    "@nestjs/common": "12.0.4",
-    "@nestjs/core": "12.0.4",
+    "@nestjs/common": "12.3.3",
+    "@nestjs/core": "12.3.3",
     "@nestjs/mail": "0.0.2",
     "@nestjs/resilience": "0.0.3",
-    "@nestjs/testing": "12.0.4",
+    "@nestjs/testing": "12.3.3",
     "@nestjs/workflows": "0.0.5",
     "@types/node": "20.19.43",
+    "bullmq": "5.81.5",
+    "ioredis": "5.11.1",
     "reflect-metadata": "0.2.2",
     "typescript": "5.9.3",
     "unplugin-swc": "1.6.0",

package/skills/emit-diagnostics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: emit-diagnostics
-description: Emit observability events from @dudousxd/nestjs-diagnostics with emit(lib, event, payload, opts) over node:diagnostics_channel on aviary:<lib>:<event>. Covers the DiagnosticEvent envelope (v, ts, lib, event, traceId, payload, durationMs), zero-overhead hasSubscribers gating, EmitOptions sampling and durationMs, typed ChannelRegistry declaration merging, and trace correlation via setContextAccessor / CONTEXT_ACCESSOR. No module to register; the core barrel is framework-agnostic.
+description: Emit observability events from @dudousxd/nestjs-diagnostics with emit(lib, event, payload, opts) over node:diagnostics_channel on aviary:<lib>:<event>. Covers the DiagnosticEvent envelope (v, id, ts, lib, event, traceId, payload, durationMs), zero-overhead hasSubscribers gating, EmitOptions sampling and durationMs, typed ChannelRegistry declaration merging, and trace correlation via setContextAccessor / CONTEXT_ACCESSOR. No module to register; the core barrel is framework-agnostic.
 license: MIT
 metadata:
   type: core
@@ -47,6 +47,7 @@ standard `DiagnosticEvent` envelope:
 ```ts
 interface DiagnosticEvent<TPayload = unknown> {
   v?: number;        // SCHEMA_VERSION stamped by emit (currently 1)
+  id?: string;       // unique UUID stamped by emit; relays keep it so the same event has the same id in every process
   ts: number;        // Date.now() at publish time
   lib: string;       // the <lib>, e.g. "billing"
   event: string;     // the <event>, e.g. "invoice-paid"
@@ -189,7 +190,9 @@ emit('billing', 'invoice-paid', payload);
 ```
 
 `emit` returns `void` and swallows every internal error so a broken observer can
-never break the producer. There is no delivery guarantee, ordering, or replay.
+never break the producer. `emit` itself offers no ack, ordering, or replay;
+`@OnDiagnostic` delivery guarantees (retry, run-once) depend on the selected
+transport (see the `react-with-on-diagnostic` skill).
 Source: `packages/core/src/channel.ts` (`emit` `try/catch`).
 
 ### Putting the prefix or colons into lib/event yourself