@dudousxd/nestjs-diagnostics 0.8.1 → 0.9.0

package/skills/react-with-on-diagnostic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react-with-on-diagnostic
-description: React to diagnostics events inside a NestJS app with @OnDiagnostic(lib, event?) from @dudousxd/nestjs-diagnostics/nestjs, wired by DiagnosticsModule.forRoot(). Decorate provider methods to handle one exact aviary:<lib>:<event> channel or every aviary:<lib>:* channel (current and future). Handlers run on the DI-resolved instance; sync throws and async rejections are logged and swallowed so a reaction can never break the synchronous emit() that triggered it.
+description: React to diagnostics events inside a NestJS app with @OnDiagnostic(lib, event?) from @dudousxd/nestjs-diagnostics/nestjs, wired by DiagnosticsModule.forRoot()/forRootAsync({ default, transports, role, nodeId }). Decorate provider methods to handle one exact aviary:<lib>:<event> channel, a RegExp match, or every aviary:<lib>:* channel (current and future). The handler parameter is checked against the ChannelRegistry payload for registered channels; each listener has a stable <ClassName>#<method> id. Handlers run on the DI-resolved instance; without a delivering transport sync throws and async rejections are logged and swallowed, while queue/durable transports propagate the handler error for retry with delivery once from the emitting process. role 'api' never consumes or runs listeners.
 license: MIT
 metadata:
   type: core
@@ -44,21 +44,37 @@ export class Reactions {
   @OnDiagnostic('resilience', 'circuit-opened') // one exact channel
   onCircuitOpen(e: DiagnosticEvent) { /* … */ }
 
+  @OnDiagnostic('durable', /^run\./)            // every event of the lib whose name matches
+  onRun(e: DiagnosticEvent) { /* … */ }
+
   @OnDiagnostic('resilience')                   // every aviary:resilience:* channel
   onAnyResilience(e: DiagnosticEvent) { /* … */ }
 }
 ```
 
+For a channel declared in the `ChannelRegistry`, the handler's parameter is
+checked against the declared payload (see `DiagnosticEventOf`); untyped
+channels accept any annotation. Each listener has a stable id,
+`<ClassName>#<method>`; two listener classes with the same name fail the
+bootstrap. To run listeners across processes, pass
+`{ default, transports, role, nodeId }` to `forRoot()` (or `forRootAsync()`):
+`transports.redis()`, `transports.queue()`, or `transports.durable()` select
+the delivery, and `role: 'api'` emits and hands work to the transport but
+never consumes or runs listeners (`'api'`/`'worker'` without a `default`
+transport fail the bootstrap).
+
 Source: `packages/core/src/nestjs/diagnostics.module.ts`,
 `packages/core/src/nestjs/on-diagnostic.decorator.ts`,
 `packages/core/src/nestjs/diagnostics.explorer.ts`.
 
 ## Core patterns
 
-### 1. Exact channel vs library wildcard
+### 1. Exact channel, RegExp match, or library wildcard
 
 - `@OnDiagnostic('resilience', 'circuit-opened')` subscribes to the exact
   `aviary:resilience:circuit-opened` channel.
+- `@OnDiagnostic('durable', /^run\./)` subscribes to every
+  `aviary:durable:*` channel whose event name matches the `RegExp`.
 - `@OnDiagnostic('resilience')` (no `event`) subscribes to **every**
   `aviary:resilience:*` channel — both those already registered at bootstrap and
   any that appear later (a library's first `emit('resilience', 'newevent', …)`).
@@ -69,6 +85,12 @@ automatically.
 
 Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`onApplicationBootstrap`).
 
+Each discovered method gets a stable listener id, `<ClassName>#<method>`,
+which delivering transports (`queue`, `durable`) use to route work; keep it
+stable while deliveries may be pending. Two listener classes with the same
+name fail the bootstrap. `role: 'api'` never consumes or runs listeners —
+it emits and hands work to the transport.
+
 ### 2. Handlers run on the DI-resolved instance
 
 The decorated method is invoked on the real provider instance, so injected
@@ -86,17 +108,21 @@ export class AlertReactions {
 }
 ```
 
-Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`safeInvoke` calls `fn.call(instance, event)`).
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`invoke` calls `fn.call(instance, event)`).
 
-### 3. Never-throw isolation
+### 3. Never-throw isolation without a delivering transport
 
 `diagnostics_channel.publish` is **synchronous**, so a subscriber that throws
-would propagate into the emitter's call stack. The explorer's `safeInvoke`
+would propagate into the emitter's call stack. Without a delivering transport,
+the explorer's `invoke` path
 catches synchronous throws and attaches a `.catch` to rejected promises, logging
 both — a reaction can never break the `emit()` that triggered it. Async handlers
-are therefore fire-and-forget (publish cannot await).
+are therefore fire-and-forget (publish cannot await). With a delivering
+transport (`queue`, `durable`), delivery happens once, from the emitting
+process, and the handler's error rejects `invoke` so the transport can retry
+instead of being swallowed.
 
-Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`safeInvoke`, `logError`).
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`invoke`, `onEvent`, `deliver`).
 
 ## Common mistakes
 
@@ -143,21 +169,23 @@ Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`discovery.getProvid
 ### Throwing in a handler expecting the framework to retry
 
 ```ts
-// Wrong — assuming a throw bubbles up or triggers a retry.
+// Wrong — assuming a throw bubbles up or triggers a retry (without a delivering transport it will NOT — it is logged and swallowed).
 @OnDiagnostic('billing', 'invoice-paid')
 onPaid(e: DiagnosticEvent) {
-  throw new Error('will be retried'); // it will NOT — it is logged and swallowed
+  throw new Error('will be retried'); // only retried with transports.queue()/durable()
 }
 ```
 
 ```ts
-// Correct — handle failures inside the reaction; it is fire-and-forget.
+// Correct — handle failures inside the reaction when running without a delivering transport; it is fire-and-forget.
 @OnDiagnostic('billing', 'invoice-paid')
 async onPaid(e: DiagnosticEvent) {
   try { await this.work(e); } catch (err) { this.logger.warn(err); }
 }
 ```
 
-`safeInvoke` swallows throws/rejections by design, so emission stays safe — there
-is no delivery guarantee, retry, or replay.
-Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`safeInvoke`).
+Without a delivering transport, the explorer swallows throws/rejections by design, so emission stays safe — there
+is no delivery guarantee, retry, or replay. With `transports.queue()` or
+`transports.durable()`, the handler error propagates to the transport and is
+retried (delivery happens once, from the emitting process).
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`invoke`, `onEvent`).

package/skills/trace-spans/SKILL.md

@@ -42,7 +42,8 @@ export class AuthzService {
 ```
 
 Span events ride `aviary:<lib>:<event>:<phase>`; the base `aviary:<lib>:<event>`
-name is what gets registered for discovery. A `SpanEvent` carries `v`, `ts`,
+name is what gets registered for discovery. A `SpanEvent` carries `v`, a unique
+`id` (a UUID stamped by `trace`; correlate phases with `spanId`), `ts`,
 `lib`, `event`, `phase`, a per-span `spanId`, optional `traceId`, and
 `payload` / `result` / `error` / `durationMs` depending on the phase.