@dudousxd/nestjs-diagnostics 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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
+
+- [#77](https://github.com/DavideCarvalho/nestjs-diagnostics/pull/77) [`5730846`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/5730846a07b685effba58b344004722dc4d7f08c) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Docs: `OfficialDiagnosticEvent` TSDoc no longer says Telescope's `DiagnosticWatcher` records `nestjs:*`; READMEs note the removed-channel test and the Telescope peer range.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -119,7 +119,8 @@ off();
 
 The channel lists are exported per lib in one file, pinned to the official
 versions they were verified against (`OFFICIAL_PACKAGE_VERSIONS`). A test
-re-reads the installed packages and fails if a channel is added or renamed.
+re-reads the installed packages and fails if a channel is added, renamed or
+removed.
 
 | Lib | Constant | Channels |
 | --- | --- | --- |
@@ -183,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"}