@dudousxd/nestjs-diagnostics 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.9.0
+
+### Minor Changes
+
+- [#81](https://github.com/DavideCarvalho/nestjs-diagnostics/pull/81) [`ebdacd0`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/ebdacd09676892eca5bf2d359b6edd8079600015) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Listeners with delivery transports and `role`.
+
+  - Every envelope from `emit` and `trace` carries a unique `id` (a UUID). Relays keep it, so the same event has the same `id` in every process.
+  - `@OnDiagnostic(lib, event?)` accepts a `RegExp` for `event`, and checks the handler's parameter against the `ChannelRegistry` payload for registered channels. Each listener has a stable id, `<ClassName>#<method>`; two listener classes with the same name fail the bootstrap.
+  - `DiagnosticsModule.forRoot({ default, transports, role, nodeId })` and `forRootAsync(...)` select how listeners run across processes, with the `transports` factory:
+    - `transports.redis({ pub, sub })`: broadcast over Redis pub/sub, best-effort.
+    - `transports.queue({ connection })`: one BullMQ job per `(listener, event)`, retried when the handler throws (optional peer `bullmq`).
+    - `transports.durable(options)`: one durable run per `(listener, event)` through `@dudousxd/nestjs-durable-diagnostics/delivery`, imported only when selected; bootstrap fails with a clear message when it is missing or durable is not configured.
+      With `queue` and `durable`, delivery happens once, from the emitting process.
+  - `role: 'all' | 'api' | 'worker'`: `'api'` emits and hands work to the transport but never consumes or runs listeners. `'api'`/`'worker'` without a `default` transport fail the bootstrap.
+  - The Redis relay now lives in `@dudousxd/nestjs-diagnostics` (`createDiagnosticsRedisRelay`); `@dudousxd/nestjs-diagnostics-redis` re-exports it. It takes `receive: false` for a publish-only relay (then `sub` is optional), and marks re-emitted copies (`isRelayed`).
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -184,6 +184,35 @@ handler that throws or rejects is logged and swallowed — it can never break th
 code that emitted. `@nestjs/common` + `@nestjs/core` are optional peers; the main
 barrel stays framework-agnostic.
 
+`event` also takes a `RegExp`. Each listener has a stable id, `<ClassName>#<method>`.
+
+### Across processes: transports and `role`
+
+Pick a `default` transport to run listeners across processes:
+
+```ts
+import { DiagnosticsModule, transports } from '@dudousxd/nestjs-diagnostics/nestjs';
+
+DiagnosticsModule.forRoot({
+  role: 'api', // 'all' (default) | 'api' | 'worker'
+  default: 'queue',
+  transports: {
+    redis: transports.redis({ pub: redis, sub: redis.duplicate() }), // broadcast, best-effort
+    queue: transports.queue({ connection: { host: 'localhost', port: 6379 } }), // BullMQ, retried
+    durable: transports.durable({ retries: 5 }), // durable runs (@dudousxd/nestjs-durable-diagnostics)
+  },
+});
+```
+
+| transport | where the listener runs | lost if the process dies? | if the handler throws |
+|---|---|---|---|
+| none (local) | in the emitting process | yes | logged, dropped |
+| `redis` | in every process (broadcast) | yes | logged, dropped |
+| `queue` | in one worker | no | BullMQ retries the job (at-least-once) |
+| `durable` | in one durable worker | no | durable retries with backoff; idempotent per event id |
+
+See the [Listeners and transports](https://davidecarvalho.github.io/aviary/docs/diagnostics/listeners) docs.
+
 ## License
 
 MIT

package/dist/channel.d.ts

@@ -38,7 +38,7 @@ export declare function getChannel(lib: string, event: string): Channel;
  * - When `opts.sample` is given, it is consulted AFTER the `hasSubscribers` gate
  *   and BEFORE the envelope is built: a falsy result sheds this event without
  *   allocating anything. Default (no `sample`) always publishes when subscribed.
- * - The envelope carries the current {@link SCHEMA_VERSION} as `v`.
+ * - The envelope carries the current {@link SCHEMA_VERSION} as `v` and a fresh UUID as `id`.
  * - Never throws: emitting observability must not break the caller.
  *
  * ```ts

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAA4B,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EAAmB,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1F,gEAAgE;AAChE,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAc9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EACnE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAChC,IAAI,CAAC,EAAE,WAAW,GACjB,IAAI,CAuBN"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AACA,OAA4B,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EAAmB,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1F,gEAAgE;AAChE,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAc9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EACnE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAChC,IAAI,CAAC,EAAE,WAAW,GACjB,IAAI,CAwBN"}

package/dist/channel.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import diagnostics_channel from 'node:diagnostics_channel';
 import { resolveTraceId } from './context-accessor.js';
 import { onRegistryReset, registerChannel } from './registry.js';
@@ -74,7 +75,7 @@ export function getChannel(lib, event) {
  * - When `opts.sample` is given, it is consulted AFTER the `hasSubscribers` gate
  *   and BEFORE the envelope is built: a falsy result sheds this event without
  *   allocating anything. Default (no `sample`) always publishes when subscribed.
- * - The envelope carries the current {@link SCHEMA_VERSION} as `v`.
+ * - The envelope carries the current {@link SCHEMA_VERSION} as `v` and a fresh UUID as `id`.
  * - Never throws: emitting observability must not break the caller.
  *
  * ```ts
@@ -100,6 +101,7 @@ export function emit(lib, event, payload, opts) {
         const traceId = opts?.traceId ?? resolveTraceId();
         const envelope = {
             v: SCHEMA_VERSION,
+            id: randomUUID(),
             ts: Date.now(),
             lib,
             event,

package/dist/channel.js.map

@@ -1 +1 @@
-{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAqC,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,OAAO,GAAG,cAAc,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE7D,8EAA8E;AAC9E,6EAA6E;AAC7E,eAAe,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAa;IACnD,IAAI,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;QACrC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,IAAI,CAClB,GAAS,EACT,KAAa,EACb,OAAgC,EAChC,IAAkB;IAElB,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,cAAc;QAAE,OAAO;IACpC,IAAI,CAAC;QACH,6EAA6E;QAC7E,4EAA4E;QAC5E,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO;QACzD,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAoB;YAChC,CAAC,EAAE,cAAc;YACjB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;YACd,GAAG;YACH,KAAK;YACL,OAAO;YACP,OAAO;YACP,wEAAwE;YACxE,yEAAyE;YACzE,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;SACvE,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,mBAAqC,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,OAAO,GAAG,cAAc,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE7D,8EAA8E;AAC9E,6EAA6E;AAC7E,eAAe,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAa;IACnD,IAAI,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;QACrC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,IAAI,CAClB,GAAS,EACT,KAAa,EACb,OAAgC,EAChC,IAAkB;IAElB,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,cAAc;QAAE,OAAO;IACpC,IAAI,CAAC;QACH,6EAA6E;QAC7E,4EAA4E;QAC5E,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO;QACzD,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAoB;YAChC,CAAC,EAAE,cAAc;YACjB,EAAE,EAAE,UAAU,EAAE;YAChB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;YACd,GAAG;YACH,KAAK;YACL,OAAO;YACP,OAAO;YACP,wEAAwE;YACxE,yEAAyE;YACzE,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;SACvE,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
 export { assertCapabilityNaming } from './conformance.js';
 export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, getContextAccessor, resolveTraceId, setContextAccessor, type UserRef, } from './context-accessor.js';
 export { NESTJS_AUTHENTICATION_CHANNELS, NESTJS_AUTHORIZATION_CHANNELS, NESTJS_MAIL_CHANNELS, NESTJS_RESILIENCE_CHANNELS, NESTJS_WORKFLOWS_CHANNELS, OFFICIAL_CHANNEL_PREFIX, OFFICIAL_CHANNELS, OFFICIAL_PACKAGE_VERSIONS, type OfficialChannelName, type OfficialDiagnosticEvent, type OfficialLib, type OfficialListener, type OfficialType, officialChannelNames, subscribeOfficial, } from './official.js';
+export { type ChannelRef, createDiagnosticsRedisRelay, type DiagnosticsRedisRelayOptions, type RedisLike, type RedisPipelineLike, } from './redis-relay.js';
+export { isRelayed, publishRelayed } from './relayed.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
 export { SPAN_SCHEMA_VERSION, trace, type TraceChannelNames, traceChannelNames, type TracingChannel, tracingChannel, } from './trace.js';
 export type { ChannelRegistry, DiagnosticEvent, EmitOptions, EventOf, LibOf, PayloadOf, SpanEvent, SpanPhase, TraceOptions, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,UAAU,EACf,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,SAAS,EACd,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -4,6 +4,8 @@ export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
 export { assertCapabilityNaming } from './conformance.js';
 export { CONTEXT_ACCESSOR, getContextAccessor, resolveTraceId, setContextAccessor, } from './context-accessor.js';
 export { NESTJS_AUTHENTICATION_CHANNELS, NESTJS_AUTHORIZATION_CHANNELS, NESTJS_MAIL_CHANNELS, NESTJS_RESILIENCE_CHANNELS, NESTJS_WORKFLOWS_CHANNELS, OFFICIAL_CHANNEL_PREFIX, OFFICIAL_CHANNELS, OFFICIAL_PACKAGE_VERSIONS, officialChannelNames, subscribeOfficial, } from './official.js';
+export { createDiagnosticsRedisRelay, } from './redis-relay.js';
+export { isRelayed, publishRelayed } from './relayed.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
 export { SPAN_SCHEMA_VERSION, trace, traceChannelNames, tracingChannel, } from './trace.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EAMzB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EAMzB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,2BAA2B,GAI5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/nestjs/delivery.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The listener delivery contract. Types only: a transport package (such as
+ * `@dudousxd/nestjs-durable-diagnostics`) implements it with `import type` and never loads
+ * diagnostics at runtime.
+ *
+ * Lifecycle, in every process that boots `DiagnosticsModule` with a delivering transport selected:
+ *
+ * 1. At bootstrap, after listeners are discovered, the transport is created with a
+ *    {@link DeliveryTransportContext}. Unless `role` is `'api'`, it must also set up whatever runs
+ *    deliveries (a worker, a workflow) in THIS process, because any process may run them.
+ * 2. When a process emits an event that matches listeners, diagnostics calls
+ *    {@link ListenerDeliveryTransport.deliver} in that process only, once per matching listener,
+ *    off the emitter's call stack, batched per event loop turn, in emit order. Copies of the event
+ *    that reached other processes through a relay are never delivered again.
+ * 3. Wherever the transport runs a delivery, it calls {@link DeliveryTransportContext.invoke}
+ *    `(listenerId, envelope)`. The promise settles when the handler finishes and rejects with the
+ *    handler's own error, so the transport can retry.
+ * 4. On application shutdown, diagnostics awaits {@link ListenerDeliveryTransport.stop}.
+ */
+import type { ModuleRef } from '@nestjs/core';
+import type { DiagnosticEvent } from '../types.js';
+import type { DiagnosticsRole } from './role.js';
+/** An envelope handed to a delivering transport: `id` is always set. */
+export type DeliveredEvent<TPayload = unknown> = DiagnosticEvent<TPayload> & {
+    id: string;
+};
+/** One unit of work: run listener `listenerId` for `envelope`. */
+export interface ListenerDelivery {
+    /** Stable listener id, `<ClassName>#<method>`. The same in every process running the same app. */
+    listenerId: string;
+    /**
+     * The event, as emitted. `diag:<envelope.id>:<listenerId>` identifies this delivery uniquely:
+     * use it as the idempotency key.
+     */
+    envelope: DeliveredEvent;
+}
+/**
+ * Run listener `listenerId` for `envelope` in this process. Resolves when the handler finishes;
+ * rejects with the handler's error (retry it), or with an `UnknownDiagnosticListenerError`
+ * (`code: 'E_UNKNOWN_DIAGNOSTICS_LISTENER'`) when this process has no listener with that id.
+ */
+export type ListenerInvoker = (listenerId: string, envelope: DiagnosticEvent) => Promise<void>;
+/** What a delivering transport receives when diagnostics creates it at bootstrap. */
+export interface DeliveryTransportContext {
+    /** The application's module ref, to resolve providers. */
+    moduleRef: ModuleRef;
+    /** Id of this process (`nodeId` in the diagnostics options, or a random one). */
+    nodeId: string;
+    /** Which half of a split deployment this process is. On `'api'`, never run deliveries here. */
+    role: DiagnosticsRole;
+    /** Runs a listener in this process. See {@link ListenerInvoker}. */
+    invoke: ListenerInvoker;
+    /** Ids of the listeners registered in this process. */
+    listenerIds: readonly string[];
+}
+/** A transport that owns listener execution (`queue`, `durable`). */
+export interface ListenerDeliveryTransport {
+    /**
+     * Take ownership of these deliveries. Called only in the emitting process. Return (or resolve)
+     * once they are safely stored; a throw or rejection is logged and those deliveries are lost.
+     */
+    deliver(deliveries: readonly ListenerDelivery[]): void | Promise<void>;
+    /** Release resources on shutdown. Awaited. */
+    stop?(): void | Promise<void>;
+}
+/** Options of `transports.durable()`, passed to the durable step that runs each listener. */
+export interface DurableTransportConfig {
+    /** Max attempts of a listener before its run fails. */
+    retries?: number;
+    /** How the delay between attempts grows: constant (`fixed`) or doubling (`exp`). */
+    backoff?: 'fixed' | 'exp';
+    /** Base delay between attempts, in ms. */
+    backoffMs?: number;
+    /** Upper bound of the exponential delay, in ms. */
+    backoffMaxMs?: number;
+    /** Add random jitter to the delay. */
+    jitter?: boolean;
+}
+/**
+ * What `@dudousxd/nestjs-durable-diagnostics/delivery` must export (as named exports) for
+ * `transports.durable()`. Diagnostics imports it only when durable is the selected transport.
+ */
+export interface DurableDiagnosticsDeliveryModule {
+    /**
+     * Whether durable is set up in this app (its engine resolves from `moduleRef`). Called at
+     * bootstrap, before {@link createDeliveryTransport}; `false` fails the bootstrap.
+     */
+    isConfigured(moduleRef: ModuleRef): boolean | Promise<boolean>;
+    /** Create the delivering transport. Called once per process, at bootstrap. */
+    createDeliveryTransport(context: DeliveryTransportContext, config: DurableTransportConfig): ListenerDeliveryTransport | Promise<ListenerDeliveryTransport>;
+}
+//# sourceMappingURL=delivery.d.ts.map

package/dist/nestjs/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/nestjs/delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,wEAAwE;AACxE,MAAM,MAAM,cAAc,CAAC,QAAQ,GAAG,OAAO,IAAI,eAAe,CAAC,QAAQ,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/F,qFAAqF;AACrF,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,SAAS,EAAE,SAAS,CAAC;IACrB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,IAAI,EAAE,eAAe,CAAC;IACtB,oEAAoE;IACpE,MAAM,EAAE,eAAe,CAAC;IACxB,uDAAuD;IACvD,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,qEAAqE;AACrE,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,8CAA8C;IAC9C,IAAI,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC1B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,8EAA8E;IAC9E,uBAAuB,CACrB,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,sBAAsB,GAC7B,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACnE"}

package/dist/nestjs/delivery.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=delivery.js.map

package/dist/nestjs/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../../src/nestjs/delivery.ts"],"names":[],"mappings":""}

package/dist/nestjs/diagnostics.explorer.d.ts

@@ -1,20 +1,60 @@
 import { type OnApplicationBootstrap, type OnApplicationShutdown } from '@nestjs/common';
-import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { DiscoveryService, MetadataScanner, ModuleRef } from '@nestjs/core';
+import type { ListenerInvoker } from './delivery.js';
+import { type DiagnosticsModuleOptions } from './diagnostics.options.js';
+import { type OnDiagnosticMeta } from './on-diagnostic.decorator.js';
+/** Thrown by the listener invoker for a listener id this process does not know. */
+export declare class UnknownDiagnosticListenerError extends Error {
+    readonly listenerId: string;
+    readonly code = "E_UNKNOWN_DIAGNOSTICS_LISTENER";
+    constructor(listenerId: string);
+}
+/** A discovered `@OnDiagnostic` method. */
+export interface RegisteredListener {
+    /** Stable id, `<ClassName>#<method>`. */
+    readonly id: string;
+    /** Where it listens (one entry per stacked decorator). */
+    readonly matchers: readonly OnDiagnosticMeta[];
+    readonly instance: Record<string, unknown>;
+    readonly method: string;
+}
+/**
+ * Discovers `@OnDiagnostic` methods, starts the `default` transport and routes every matching
+ * event: to the delivering transport (only in the emitting process), or straight to the handler.
+ */
 export declare class DiagnosticsExplorer implements OnApplicationBootstrap, OnApplicationShutdown {
     private readonly discovery;
     private readonly scanner;
+    private readonly moduleRef;
     private readonly logger;
-    private readonly subscriptions;
-    private readonly wildcards;
+    private readonly listeners;
+    private readonly matchCache;
+    private readonly subscribed;
+    private readonly wildcardLibs;
+    private readonly pending;
+    private scheduled;
     private offChannelRegistered;
-    constructor(discovery: DiscoveryService, scanner: MetadataScanner);
-    onApplicationBootstrap(): void;
-    onApplicationShutdown(): void;
-    /** Subscribe once to `name`; the listener fans the envelope into `invoke`. */
+    private transport;
+    private deliver;
+    private role;
+    private readonly options;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, moduleRef: ModuleRef, options?: DiagnosticsModuleOptions);
+    /**
+     * Run listener `listenerId` for `envelope` in this process. The handler is called synchronously;
+     * the promise rejects with its error.
+     */
+    readonly invoke: ListenerInvoker;
+    /** Every listener discovered in this process. */
+    registeredListeners(): RegisteredListener[];
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    private discover;
+    /** The listeners that receive an event on `aviary:<lib>:<event>`. */
+    private listenersFor;
+    private subscribeListeners;
     private subscribe;
-    /** Invoke a handler, swallowing sync throws and async rejections so a buggy
-     *  reaction can never break the synchronous `emit()` that triggered it. */
-    private safeInvoke;
-    private logError;
+    private readonly onEvent;
+    /** Hand this turn's deliveries to the transport, in emit order. Settles once they are handed over. */
+    private flush;
 }
 //# sourceMappingURL=diagnostics.explorer.d.ts.map

package/dist/nestjs/diagnostics.explorer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.explorer.d.ts","sourceRoot":"","sources":["../../src/nestjs/diagnostics.explorer.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAQjE,qBACa,mBAAoB,YAAW,sBAAsB,EAAE,qBAAqB;IAO3D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiE;IAC/F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,OAAO,CAAC,oBAAoB,CAA6B;gBAGZ,SAAS,EAAE,gBAAgB,EAC5B,OAAO,EAAE,eAAe;IAGpE,sBAAsB,IAAI,IAAI;IA+B9B,qBAAqB,IAAI,IAAI;IAU7B,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAMjB;+EAC2E;IAC3E,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,QAAQ;CAIjB"}
+{"version":3,"file":"diagnostics.explorer.d.ts","sourceRoot":"","sources":["../../src/nestjs/diagnostics.explorer.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAE3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK5E,OAAO,KAAK,EAAoC,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAuB,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIzF,mFAAmF;AACnF,qBAAa,8BAA+B,SAAQ,KAAK;IAE3C,QAAQ,CAAC,UAAU,EAAE,MAAM;IADvC,QAAQ,CAAC,IAAI,oCAAoC;gBAC5B,UAAU,EAAE,MAAM;CAKxC;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AA0BD;;;GAGG;AACH,qBACa,mBAAoB,YAAW,sBAAsB,EAAE,qBAAqB;IAe3D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAhB/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2C;IACtE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,SAAS,CAAgD;IACjE,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAGN,SAAS,EAAE,gBAAgB,EAC5B,OAAO,EAAE,eAAe,EAC9B,SAAS,EAAE,SAAS,EACf,OAAO,CAAC,EAAE,wBAAwB;IAK7E;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAS9B;IAEF,iDAAiD;IACjD,mBAAmB,IAAI,kBAAkB,EAAE;IAIrC,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5C,OAAO,CAAC,QAAQ;IAwBhB,qEAAqE;IACrE,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAmBtB;IAEF,sGAAsG;YACxF,KAAK;CAiBpB"}

package/dist/nestjs/diagnostics.explorer.js

@@ -10,96 +10,252 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { randomUUID } from 'node:crypto';
 import diagnostics_channel from 'node:diagnostics_channel';
-import { Inject, Injectable, Logger, } from '@nestjs/common';
-import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { Inject, Injectable, Logger, Optional, } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner, ModuleRef } from '@nestjs/core';
 import { CHANNEL_PREFIX, channelName } from '../channel.js';
 import { onChannelRegistered, registeredChannels } from '../registry.js';
+import { isRelayed } from '../relayed.js';
+import { DIAGNOSTICS_OPTIONS } from './diagnostics.options.js';
 import { ON_DIAGNOSTIC_META } from './on-diagnostic.decorator.js';
+import { resolveRole } from './role.js';
+/** Thrown by the listener invoker for a listener id this process does not know. */
+export class UnknownDiagnosticListenerError extends Error {
+    listenerId;
+    code = 'E_UNKNOWN_DIAGNOSTICS_LISTENER';
+    constructor(listenerId) {
+        super(`@dudousxd/nestjs-diagnostics: no listener "${listenerId}" is registered in this process. Every process that runs deliveries must register the same listeners.`);
+        this.listenerId = listenerId;
+    }
+}
+function matches(meta, lib, event) {
+    if (meta.lib !== lib)
+        return false;
+    const matcher = meta.event;
+    if (matcher === undefined)
+        return true;
+    if (typeof matcher === 'string')
+        return matcher === event;
+    matcher.lastIndex = 0;
+    return matcher.test(event);
+}
+/** A diagnostics POINT event (from `emit`). Span phase events from `trace` are never dispatched. */
+function isPointEvent(msg) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const env = msg;
+    if (typeof env.lib !== 'string' || typeof env.event !== 'string')
+        return false;
+    return env.phase === undefined || env.spanId === undefined;
+}
+function libOf(name) {
+    if (!name.startsWith(`${CHANNEL_PREFIX}:`))
+        return undefined;
+    const rest = name.slice(CHANNEL_PREFIX.length + 1);
+    const idx = rest.indexOf(':');
+    return idx > 0 ? rest.slice(0, idx) : undefined;
+}
+/**
+ * Discovers `@OnDiagnostic` methods, starts the `default` transport and routes every matching
+ * event: to the delivering transport (only in the emitting process), or straight to the handler.
+ */
 let DiagnosticsExplorer = class DiagnosticsExplorer {
     discovery;
     scanner;
+    moduleRef;
     logger = new Logger('DiagnosticsExplorer');
-    subscriptions = [];
-    wildcards = [];
+    listeners = new Map();
+    matchCache = new Map();
+    subscribed = new Set();
+    wildcardLibs = new Set();
+    pending = [];
+    scheduled = null;
     offChannelRegistered = null;
-    constructor(discovery, scanner) {
+    transport = null;
+    deliver = null;
+    role = 'all';
+    options;
+    constructor(discovery, scanner, moduleRef, options) {
         this.discovery = discovery;
         this.scanner = scanner;
+        this.moduleRef = moduleRef;
+        this.options = options ?? {};
+    }
+    /**
+     * Run listener `listenerId` for `envelope` in this process. The handler is called synchronously;
+     * the promise rejects with its error.
+     */
+    invoke = (listenerId, envelope) => {
+        const listener = this.listeners.get(listenerId);
+        if (!listener)
+            return Promise.reject(new UnknownDiagnosticListenerError(listenerId));
+        try {
+            const fn = listener.instance[listener.method];
+            return Promise.resolve(fn.call(listener.instance, envelope)).then(() => undefined);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    };
+    /** Every listener discovered in this process. */
+    registeredListeners() {
+        return [...this.listeners.values()];
+    }
+    async onApplicationBootstrap() {
+        this.role = resolveRole(this.options.role, this.options.default);
+        this.discover();
+        const name = this.options.default;
+        if (name) {
+            const provider = this.options.transports?.[name];
+            if (!provider) {
+                throw new Error(`@dudousxd/nestjs-diagnostics: default is "${name}", but transports.${name} is not defined`);
+            }
+            const listeners = this.registeredListeners();
+            this.transport = await provider({
+                moduleRef: this.moduleRef,
+                role: this.role,
+                nodeId: this.options.nodeId ?? randomUUID(),
+                listenerLibs: [...new Set(listeners.flatMap((l) => l.matchers.map((m) => m.lib)))],
+                listenerIds: listeners.map((l) => l.id),
+                invoke: this.invoke,
+                logger: this.logger,
+            });
+            this.deliver = this.transport.deliver?.bind(this.transport) ?? null;
+        }
+        // An 'api' process without a delivering transport has nothing to do with its listeners.
+        if (this.role === 'api' && !this.deliver)
+            return;
+        this.subscribeListeners();
     }
-    onApplicationBootstrap() {
+    async onApplicationShutdown() {
+        await this.flush();
+        this.offChannelRegistered?.();
+        this.offChannelRegistered = null;
+        for (const name of this.subscribed)
+            diagnostics_channel.channel(name).unsubscribe(this.onEvent);
+        this.subscribed.clear();
+        this.wildcardLibs.clear();
+        const transport = this.transport;
+        this.transport = null;
+        this.deliver = null;
+        try {
+            await transport?.stop?.();
+        }
+        catch (error) {
+            this.logger.error(`failed to stop the diagnostics transport: ${messageOf(error)}`);
+        }
+    }
+    discover() {
         for (const wrapper of this.discovery.getProviders()) {
             const instance = wrapper.instance;
             if (!instance || typeof instance !== 'object')
                 continue;
             const proto = Object.getPrototypeOf(instance);
-            for (const methodName of this.scanner.getAllMethodNames(proto)) {
-                const metas = Reflect.getMetadata(ON_DIAGNOSTIC_META, proto, methodName);
+            for (const method of this.scanner.getAllMethodNames(proto)) {
+                const metas = Reflect.getMetadata(ON_DIAGNOSTIC_META, proto, method);
                 if (!metas?.length)
                     continue;
-                for (const meta of metas) {
-                    const invoke = (event) => this.safeInvoke(instance, methodName, event);
-                    if (meta.event !== undefined) {
-                        this.subscribe(channelName(meta.lib, meta.event), invoke);
-                    }
-                    else {
-                        const prefix = `${CHANNEL_PREFIX}:${meta.lib}:`;
-                        this.wildcards.push({ prefix, invoke });
-                        for (const name of registeredChannels()) {
-                            if (name.startsWith(prefix))
-                                this.subscribe(name, invoke);
-                        }
+                const id = `${instance.constructor.name}#${method}`;
+                const existing = this.listeners.get(id);
+                if (existing) {
+                    if (existing.instance.constructor === instance.constructor)
+                        continue;
+                    throw new Error(`@dudousxd/nestjs-diagnostics: two listeners share the id "${id}". Listener ids are <ClassName>#<method> and must be unique; rename one class.`);
+                }
+                this.listeners.set(id, { id, matchers: metas, instance, method });
+            }
+        }
+        this.matchCache.clear();
+    }
+    /** The listeners that receive an event on `aviary:<lib>:<event>`. */
+    listenersFor(lib, event) {
+        const key = `${lib}\0${event}`;
+        let hit = this.matchCache.get(key);
+        if (hit === undefined) {
+            hit = this.registeredListeners().filter((l) => l.matchers.some((m) => matches(m, lib, event)));
+            this.matchCache.set(key, hit);
+        }
+        return hit;
+    }
+    subscribeListeners() {
+        for (const listener of this.listeners.values()) {
+            for (const meta of listener.matchers) {
+                if (typeof meta.event === 'string') {
+                    this.subscribe(channelName(meta.lib, meta.event));
+                }
+                else if (!this.wildcardLibs.has(meta.lib)) {
+                    this.wildcardLibs.add(meta.lib);
+                    for (const name of registeredChannels()) {
+                        if (libOf(name) === meta.lib)
+                            this.subscribe(name);
                     }
                 }
             }
         }
         this.offChannelRegistered = onChannelRegistered((name) => {
-            for (const w of this.wildcards) {
-                if (name.startsWith(w.prefix))
-                    this.subscribe(name, w.invoke);
-            }
+            const lib = libOf(name);
+            if (lib !== undefined && this.wildcardLibs.has(lib))
+                this.subscribe(name);
         });
     }
-    onApplicationShutdown() {
-        this.offChannelRegistered?.();
-        this.offChannelRegistered = null;
-        for (const { name, listener } of this.subscriptions) {
-            diagnostics_channel.channel(name).unsubscribe(listener);
-        }
-        this.subscriptions.length = 0;
-        this.wildcards.length = 0;
-    }
-    /** Subscribe once to `name`; the listener fans the envelope into `invoke`. */
-    subscribe(name, invoke) {
-        const listener = (msg) => invoke(msg);
-        diagnostics_channel.channel(name).subscribe(listener);
-        this.subscriptions.push({ name, listener });
+    subscribe(name) {
+        if (this.subscribed.has(name))
+            return;
+        diagnostics_channel.channel(name).subscribe(this.onEvent);
+        this.subscribed.add(name);
     }
-    /** Invoke a handler, swallowing sync throws and async rejections so a buggy
-     *  reaction can never break the synchronous `emit()` that triggered it. */
-    safeInvoke(instance, methodName, event) {
+    onEvent = (msg) => {
+        if (!isPointEvent(msg))
+            return;
+        const matched = this.listenersFor(msg.lib, msg.event);
+        if (matched.length === 0)
+            return;
+        if (this.deliver) {
+            // Delivery happens once, at the origin. A relayed copy was already handed over there.
+            if (isRelayed(msg))
+                return;
+            const envelope = (typeof msg.id === 'string' ? msg : { ...msg, id: randomUUID() });
+            for (const listener of matched)
+                this.pending.push({ listenerId: listener.id, envelope });
+            this.scheduled ??= setImmediate(() => void this.flush());
+            return;
+        }
+        for (const listener of matched) {
+            this.invoke(listener.id, msg).catch((error) => this.logger.error(`@OnDiagnostic ${listener.id} handler failed: ${messageOf(error)}`));
+        }
+    };
+    /** Hand this turn's deliveries to the transport, in emit order. Settles once they are handed over. */
+    async flush() {
+        if (this.scheduled !== null) {
+            clearImmediate(this.scheduled);
+            this.scheduled = null;
+        }
+        if (this.pending.length === 0 || !this.deliver)
+            return;
+        const deliveries = this.pending.splice(0);
+        const report = (error) => this.logger.error(`failed to hand ${deliveries.length} diagnostics deliveries to the transport: ${messageOf(error)}`);
         try {
-            const fn = instance[methodName];
-            const result = fn.call(instance, event);
-            if (result != null && typeof result.then === 'function') {
-                result.catch((err) => this.logError(methodName, err));
-            }
+            await this.deliver(deliveries);
         }
-        catch (err) {
-            this.logError(methodName, err);
+        catch (error) {
+            report(error);
         }
     }
-    logError(methodName, err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.logger.error(`@OnDiagnostic ${methodName} handler failed: ${message}`);
-    }
 };
 DiagnosticsExplorer = __decorate([
     Injectable(),
     __param(0, Inject(DiscoveryService)),
     __param(1, Inject(MetadataScanner)),
+    __param(2, Inject(ModuleRef)),
+    __param(3, Optional()),
+    __param(3, Inject(DIAGNOSTICS_OPTIONS)),
     __metadata("design:paramtypes", [DiscoveryService,
-        MetadataScanner])
+        MetadataScanner,
+        ModuleRef, Object])
 ], DiagnosticsExplorer);
 export { DiagnosticsExplorer };
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 //# sourceMappingURL=diagnostics.explorer.js.map