@fluojs/event-bus 1.0.0-beta.5 → 1.0.0-beta.7

package/README.ko.md

@@ -58,24 +58,24 @@ export class NotificationService {
 import { Module, Inject } from '@fluojs/core';
 import { EventBusModule, EventBusLifecycleService } from '@fluojs/event-bus';
 
-@Module({
-  imports: [EventBusModule.forRoot()],
-  providers: [NotificationService],
-})
-export class AppModule {}
-
+@Inject(EventBusLifecycleService)
 export class UserService {
-  @Inject(EventBusLifecycleService)
-  private readonly eventBus: EventBusLifecycleService;
+  constructor(private readonly eventBus: EventBusLifecycleService) {}
 
   async signUp(email: string) {
     // 사용자 저장 로직...
     await this.eventBus.publish(new UserSignedUpEvent(email));
   }
 }
+
+@Module({
+  imports: [EventBusModule.forRoot()],
+  providers: [NotificationService, UserService],
+})
+export class AppModule {}
 ```
 
-`publish(event, options?)`는 `signal`, `timeoutMs`, `waitForHandlers`를 지원합니다. `waitForHandlers`의 기본값은 `true`이며, `false`로 설정하면 publish가 즉시 반환되고 timeout bound를 적용하지 않습니다.
+`publish(event, options?)`는 `signal`, `timeoutMs`, `waitForHandlers`를 지원합니다. `waitForHandlers`의 기본값은 `true`이며, 기다리는 로컬 핸들러와 기다리는 트랜스포트 publish는 동일한 timeout 및 cancellation bound를 공유합니다. `waitForHandlers`를 `false`로 설정하면 publish가 즉시 반환되고 timeout bound를 적용하지 않습니다. Shutdown 중에는 이벤트 버스가 진행 중인 awaited publish 및 inbound transport handler 작업을 drain한 뒤 트랜스포트를 닫고, lifecycle이 stopping에 진입한 뒤의 새 publish 호출과 shutdown 시작 뒤 도착한 inbound transport callback은 무시합니다. Shutdown drain은 기본값이 5000ms인 `EventBusModule.forRoot({ shutdown: { drainTimeoutMs } })`로 제한됩니다. 활성 dispatch 작업이 이 bound 이후에도 멈춰 있으면 bus는 degraded status diagnostic을 기록하고 경고를 남긴 뒤, 애플리케이션 close를 무기한 hang시키지 않고 transport cleanup을 계속합니다.
 
 ## 일반적인 패턴
 
@@ -104,7 +104,7 @@ class UserRegisteredEvent {
 }
 ```
 
-핸들러는 imported module의 singleton provider와 controller에서 발견됩니다. 각 핸들러는 격리된 clone payload를 받으며, class inheritance는 `instanceof` 매칭으로 지원됩니다.
+핸들러는 imported module의 singleton provider와 controller에서 발견됩니다. 각 핸들러는 격리된 clone payload를 받으며, class inheritance는 `instanceof` 매칭으로 지원됩니다. 외부 트랜스포트를 구성하면 subclass event publish는 publisher process에 해당 타입의 local handler가 없더라도 subclass channel과 prototype chain의 모든 inherited event channel로 fan-out됩니다. Subclass가 직접 `static eventKey`를 선언한 경우에만 그 값을 사용하며, 그렇지 않으면 subclass channel은 class name을 유지하고 base class는 자신의 stable key를 유지합니다.
 
 ## 공개 API 개요
 
@@ -120,7 +120,7 @@ class UserRegisteredEvent {
 - `EventBus`, `EventPublishOptions`, `EventBusModuleOptions`, `EventType`: 발행, 기본값, 트랜스포트, 안정적인 이벤트 키를 위한 타입 전용 계약입니다.
 - `EventBusLifecycleState`, `EventBusStatusAdapterInput`, `EventBusPlatformStatusSnapshot`: status snapshot 계약입니다.
 
-Transport bootstrap은 unique event channel마다 한 번만 subscribe합니다. `eventKey`가 있으면 transport channel 이름을 제어합니다. 잘못된 JSON transport message는 무시됩니다.
+Transport bootstrap은 unique event channel마다 한 번만 subscribe합니다. `eventKey`가 있으면 transport channel 이름을 제어합니다. 잘못된 JSON transport message는 무시되며, shutdown 시작 뒤 도착한 inbound transport message는 local handler dispatch 전에 무시됩니다.
 
 ## 런타임별 및 통합 서브패스
 

package/README.md

@@ -58,24 +58,24 @@ Use `EventBusModule.forRoot(...)` to wire the in-process event bus.
 import { Module, Inject } from '@fluojs/core';
 import { EventBusModule, EventBusLifecycleService } from '@fluojs/event-bus';
 
-@Module({
-  imports: [EventBusModule.forRoot()],
-  providers: [NotificationService],
-})
-export class AppModule {}
-
+@Inject(EventBusLifecycleService)
 export class UserService {
-  @Inject(EventBusLifecycleService)
-  private readonly eventBus: EventBusLifecycleService;
+  constructor(private readonly eventBus: EventBusLifecycleService) {}
 
   async signUp(email: string) {
     // Logic to save user...
     await this.eventBus.publish(new UserSignedUpEvent(email));
   }
 }
+
+@Module({
+  imports: [EventBusModule.forRoot()],
+  providers: [NotificationService, UserService],
+})
+export class AppModule {}
 ```
 
-`publish(event, options?)` supports `signal`, `timeoutMs`, and `waitForHandlers`. `waitForHandlers` defaults to `true`; when set to `false`, publishing returns immediately and skips timeout bounds.
+`publish(event, options?)` supports `signal`, `timeoutMs`, and `waitForHandlers`. `waitForHandlers` defaults to `true`; awaited local handlers and awaited transport publishes share the same timeout and cancellation bounds. When `waitForHandlers` is set to `false`, publishing returns immediately and skips timeout bounds. During shutdown, the event bus drains in-flight awaited publish and inbound transport handler work before closing the transport, ignores new publish calls after the lifecycle has started stopping, and ignores inbound transport callbacks that arrive after shutdown begins. Shutdown drain is bounded by `EventBusModule.forRoot({ shutdown: { drainTimeoutMs } })`, which defaults to 5000ms; if active dispatch work is still stuck after the bound, the bus records a degraded status diagnostic, logs a warning, and continues transport cleanup instead of hanging application close indefinitely.
 
 ## Common Patterns
 
@@ -104,7 +104,7 @@ class UserRegisteredEvent {
 }
 ```
 
-Handlers are discovered from singleton providers and controllers across imported modules. Each handler receives an isolated cloned payload, and class inheritance is supported through `instanceof` matching.
+Handlers are discovered from singleton providers and controllers across imported modules. Each handler receives an isolated cloned payload, and class inheritance is supported through `instanceof` matching. With an external transport configured, publishing a subclass event fans out to the subclass channel and every inherited event channel in its prototype chain, even when the publisher process has no matching local handlers for those types. A subclass uses its own `static eventKey` only when it declares one directly; otherwise its class name remains the subclass channel while base classes keep their own stable keys.
 
 ## Public API Overview
 
@@ -120,7 +120,7 @@ Handlers are discovered from singleton providers and controllers across imported
 - `EventBus`, `EventPublishOptions`, `EventBusModuleOptions`, `EventType`: Type-only contracts for publishing, defaults, transports, and stable event keys.
 - `EventBusLifecycleState`, `EventBusStatusAdapterInput`, `EventBusPlatformStatusSnapshot`: Status snapshot contracts.
 
-Transport bootstrap subscribes once per unique event channel. `eventKey` controls the transport channel name when present. Invalid JSON transport messages are ignored.
+Transport bootstrap subscribes once per unique event channel. `eventKey` controls the transport channel name when present. Invalid JSON transport messages are ignored, and inbound transport messages that arrive after shutdown starts are ignored before local handler dispatch.
 
 ## Runtime-Specific and Integration Subpaths
 

package/dist/service.d.ts

@@ -21,6 +21,8 @@ export declare class EventBusLifecycleService implements EventBus, OnApplication
     private transportCloseFailures;
     private transportPublishFailures;
     private transportSubscribeFailures;
+    private shutdownDrainTimeouts;
+    private readonly activeDispatches;
     private readonly transport;
     constructor(runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, moduleOptions: EventBusModuleOptions);
     onApplicationBootstrap(): Promise<void>;
@@ -39,6 +41,12 @@ export declare class EventBusLifecycleService implements EventBus, OnApplication
      * @returns A promise that resolves once the configured local/transport publication completes.
      */
     publish(event: object, options?: EventPublishOptions): Promise<void>;
+    private executePublish;
+    private canPublishInCurrentLifecycle;
+    private drainActiveDispatches;
+    private trackActiveDispatch;
+    private awaitShutdownDrain;
+    private resolveShutdownDrainTimeoutMs;
     private matchEventDescriptors;
     private createInvocationTasks;
     private createBackgroundInvocationTasks;
@@ -50,9 +58,14 @@ export declare class EventBusLifecycleService implements EventBus, OnApplication
     private discoverHandlers;
     private channelFromEventType;
     private channelsForTransportPublish;
+    private eventTypeLineage;
     private publishToTransport;
+    private logTransportPublishCancelledBeforeDispatch;
+    private logBoundedTransportPublishError;
     private subscribeTransportChannels;
     private subscribeTransportChannel;
+    private canDispatchIncomingTransportMessage;
+    private dispatchIncomingTransportMessage;
     private preloadHandlerInstances;
     private invokeHandlerWithBounds;
     private logPublishCancelledBeforeDispatch;

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EACV,QAAQ,EACR,qBAAqB,EAGrB,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AA8DpB;;;;;GAKG;AACH,qBACa,wBAAyB,YAAW,QAAQ,EAAE,sBAAsB,EAAE,qBAAqB;IAapG,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAfhC,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,wBAAwB,CAAK;IACrC,OAAO,CAAC,0BAA0B,CAAK;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;gBAGvC,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,qBAAqB;IAKjD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAavC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5C;;;;OAIG;IACH,4BAA4B;IAa5B;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B1E,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,+BAA+B;IAWvC,OAAO,CAAC,8BAA8B;YAMxB,yBAAyB;YAazB,gBAAgB;IAqB9B,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,kBAAkB;YAQZ,gBAAgB;IAW9B,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,2BAA2B;YAcrB,kBAAkB;YAyBlB,0BAA0B;YAmB1B,yBAAyB;YAqCzB,uBAAuB;YAUvB,uBAAuB;IAmBrC,OAAO,CAAC,iCAAiC;IAOzC,OAAO,CAAC,yBAAyB;YAwBnB,qBAAqB;IAuBnC,OAAO,CAAC,sBAAsB;IAqB9B,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,0BAA0B;IAyBlC,OAAO,CAAC,+BAA+B;IAevC,OAAO,CAAC,8BAA8B;IA4BtC,OAAO,CAAC,uBAAuB;IAe/B,OAAO,CAAC,mBAAmB;YAsCb,aAAa;YA4Bb,sBAAsB;CAsBrC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EACV,QAAQ,EACR,qBAAqB,EAGrB,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAgEpB;;;;;GAKG;AACH,qBACa,wBAAyB,YAAW,QAAQ,EAAE,sBAAsB,EAAE,qBAAqB;IAepG,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAjBhC,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,wBAAwB,CAAK;IACrC,OAAO,CAAC,0BAA0B,CAAK;IACvC,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4B;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;gBAGvC,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,qBAAqB;IAKjD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAavC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB5C;;;;OAIG;IACH,4BAA4B;IAe5B;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YAY5D,cAAc;IA+B5B,OAAO,CAAC,4BAA4B;YAItB,qBAAqB;YAcrB,mBAAmB;YAUnB,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,+BAA+B;IAWvC,OAAO,CAAC,8BAA8B;YAMxB,yBAAyB;YAazB,gBAAgB;IAqB9B,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,kBAAkB;YAQZ,gBAAgB;IAW9B,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,gBAAgB;YAiBV,kBAAkB;IA8BhC,OAAO,CAAC,0CAA0C;IAOlD,OAAO,CAAC,+BAA+B;YAwBzB,0BAA0B;YAmB1B,yBAAyB;IAiCvC,OAAO,CAAC,mCAAmC;YAI7B,gCAAgC;YAmBhC,uBAAuB;YAUvB,uBAAuB;IAmBrC,OAAO,CAAC,iCAAiC;IAOzC,OAAO,CAAC,yBAAyB;YAwBnB,qBAAqB;IAuBnC,OAAO,CAAC,sBAAsB;IAqB9B,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,0BAA0B;IAyBlC,OAAO,CAAC,+BAA+B;IAevC,OAAO,CAAC,8BAA8B;IA4BtC,OAAO,CAAC,uBAAuB;IAe/B,OAAO,CAAC,mBAAmB;YAsCb,aAAa;YA4Bb,sBAAsB;CAsBrC"}

package/dist/service.js

@@ -10,6 +10,7 @@ import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs
 import { getEventHandlerMetadataEntries } from './metadata.js';
 import { createEventBusPlatformStatusSnapshot } from './status.js';
 import { EVENT_BUS_OPTIONS } from './tokens.js';
+const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 function createIsolatedEvent(eventType, source) {
   const clonedPayload = cloneWithFallback(source);
   if (typeof clonedPayload !== 'object' || clonedPayload === null) {
@@ -64,6 +65,8 @@ class EventBusLifecycleService {
   transportCloseFailures = 0;
   transportPublishFailures = 0;
   transportSubscribeFailures = 0;
+  shutdownDrainTimeouts = 0;
+  activeDispatches = new Set();
   transport;
   constructor(runtimeContainer, compiledModules, logger, moduleOptions) {
     this.runtimeContainer = runtimeContainer;
@@ -85,6 +88,9 @@ class EventBusLifecycleService {
   }
   async onApplicationShutdown() {
     this.lifecycleState = 'stopping';
+    if (this.activeDispatches.size > 0) {
+      await this.drainActiveDispatches();
+    }
     if (this.transport) {
       try {
         await this.transport.close();
@@ -108,6 +114,8 @@ class EventBusLifecycleService {
     return createEventBusPlatformStatusSnapshot({
       handlersDiscovered: this.descriptors.length,
       lifecycleState: this.lifecycleState,
+      shutdownDrainTimeoutMs: this.resolveShutdownDrainTimeoutMs(),
+      shutdownDrainTimeouts: this.shutdownDrainTimeouts,
       subscribedChannels: this.subscribedChannels.size,
       transportCloseFailures: this.transportCloseFailures,
       transportConfigured: this.transport !== undefined,
@@ -125,16 +133,27 @@ class EventBusLifecycleService {
    * @returns A promise that resolves once the configured local/transport publication completes.
    */
   async publish(event, options) {
+    if (!this.canPublishInCurrentLifecycle()) {
+      this.logger.warn(`EventBus.publish() was ignored because the event bus is ${this.lifecycleState}.`, 'EventBusLifecycleService');
+      return;
+    }
+    await this.trackActiveDispatch(this.executePublish(event, options));
+  }
+  async executePublish(event, options) {
     await this.ensureDiscovered();
     const matchingDescriptors = this.matchEventDescriptors(event);
     const publishOptions = this.resolvePublishOptions(options);
     const transportPayload = createIsolatedEvent(event.constructor, event);
-    const transportPublish = this.publishToTransport(transportPayload, matchingDescriptors);
     if (!publishOptions.waitForHandlers) {
+      const transportPublish = this.publishToTransport(transportPayload, matchingDescriptors, {
+        ...publishOptions,
+        timeoutMs: undefined
+      });
       const backgroundTasks = this.createBackgroundInvocationTasks(matchingDescriptors, event, publishOptions.signal);
       this.runInvocationTasksInBackground([...backgroundTasks, transportPublish]);
       return;
     }
+    const transportPublish = this.publishToTransport(transportPayload, matchingDescriptors, publishOptions);
     if (matchingDescriptors.length === 0) {
       await transportPublish;
       return;
@@ -142,6 +161,43 @@ class EventBusLifecycleService {
     const invocationTasks = this.createInvocationTasks(matchingDescriptors, event, publishOptions);
     await Promise.allSettled([...invocationTasks, transportPublish]);
   }
+  canPublishInCurrentLifecycle() {
+    return !['failed', 'stopped', 'stopping'].includes(this.lifecycleState);
+  }
+  async drainActiveDispatches() {
+    const activeDispatches = Array.from(this.activeDispatches);
+    const timeoutMs = this.resolveShutdownDrainTimeoutMs();
+    const drained = await this.awaitShutdownDrain(activeDispatches, timeoutMs);
+    if (!drained) {
+      this.shutdownDrainTimeouts += 1;
+      this.logger.warn(`Event bus shutdown drain exceeded ${String(timeoutMs)}ms with ${String(activeDispatches.length)} active dispatch workflow(s); continuing shutdown.`, 'EventBusLifecycleService');
+    }
+  }
+  async trackActiveDispatch(dispatchWorkflow) {
+    this.activeDispatches.add(dispatchWorkflow);
+    try {
+      await dispatchWorkflow;
+    } finally {
+      this.activeDispatches.delete(dispatchWorkflow);
+    }
+  }
+  async awaitShutdownDrain(activePublishes, timeoutMs) {
+    let timeoutId;
+    const timeout = new Promise(resolve => {
+      timeoutId = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const drain = Promise.allSettled(activePublishes).then(() => true);
+    try {
+      return await Promise.race([drain, timeout]);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+  resolveShutdownDrainTimeoutMs() {
+    return this.normalizeTimeoutMs(this.moduleOptions.shutdown?.drainTimeoutMs) ?? DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
+  }
   matchEventDescriptors(event) {
     return this.descriptors.filter(descriptor => event instanceof descriptor.eventType);
   }
@@ -210,7 +266,7 @@ class EventBusLifecycleService {
     }
   }
   channelFromEventType(eventType) {
-    if (typeof eventType.eventKey === 'string') {
+    if (Object.hasOwn(eventType, 'eventKey') && typeof eventType.eventKey === 'string') {
       const eventKey = eventType.eventKey.trim();
       if (eventKey.length > 0) {
         return eventKey;
@@ -220,6 +276,9 @@ class EventBusLifecycleService {
   }
   channelsForTransportPublish(event, descriptors) {
     const channels = new Set();
+    for (const eventType of this.eventTypeLineage(event)) {
+      channels.add(this.channelFromEventType(eventType));
+    }
     for (const descriptor of descriptors) {
       channels.add(this.channelFromEventType(descriptor.eventType));
     }
@@ -228,22 +287,52 @@ class EventBusLifecycleService {
     }
     return Array.from(channels);
   }
-  async publishToTransport(event, descriptors) {
+  eventTypeLineage(event) {
+    const eventTypes = [];
+    let prototype = Object.getPrototypeOf(event);
+    while (prototype && prototype !== Object.prototype) {
+      const constructor = prototype.constructor;
+      if (typeof constructor === 'function') {
+        eventTypes.push(constructor);
+      }
+      prototype = Object.getPrototypeOf(prototype);
+    }
+    return eventTypes;
+  }
+  async publishToTransport(event, descriptors, publishOptions) {
     if (!this.transport) {
       return;
     }
     const channels = this.channelsForTransportPublish(event, descriptors);
     const publishTasks = channels.map(async channel => {
       const payload = createIsolatedEvent(event.constructor, event);
+      if (publishOptions.signal?.aborted) {
+        this.logTransportPublishCancelledBeforeDispatch(channel);
+        return;
+      }
       try {
-        await this.transport.publish(channel, payload);
+        await this.awaitInvocationBounds(this.transport.publish(channel, payload), publishOptions);
       } catch (error) {
         this.transportPublishFailures += 1;
-        this.logger.error(`EventBusTransport failed to publish to channel "${channel}".`, error, 'EventBusLifecycleService');
+        this.logBoundedTransportPublishError(channel, error);
       }
     });
     await Promise.allSettled(publishTasks);
   }
+  logTransportPublishCancelledBeforeDispatch(channel) {
+    this.logger.warn(`Event publish was cancelled before publishing transport channel "${channel}".`, 'EventBusLifecycleService');
+  }
+  logBoundedTransportPublishError(channel, error) {
+    if (error instanceof EventPublishTimeoutError) {
+      this.logger.warn(`EventBusTransport publish to channel "${channel}" exceeded publish timeout of ${String(error.timeoutMs)}ms.`, 'EventBusLifecycleService');
+      return;
+    }
+    if (error instanceof EventPublishAbortError) {
+      this.logger.warn(`Event publish was cancelled while waiting for transport channel "${channel}".`, 'EventBusLifecycleService');
+      return;
+    }
+    this.logger.error(`EventBusTransport failed to publish to channel "${channel}".`, error, 'EventBusLifecycleService');
+  }
   async subscribeTransportChannels() {
     if (!this.transport) {
       return;
@@ -262,15 +351,14 @@ class EventBusLifecycleService {
   async subscribeTransportChannel(channel, channelDescriptors) {
     try {
       await this.transport.subscribe(channel, async payload => {
+        if (!this.canDispatchIncomingTransportMessage()) {
+          this.logger.warn(`EventBusTransport message on channel "${channel}" was ignored because the event bus is ${this.lifecycleState}.`, 'EventBusLifecycleService');
+          return;
+        }
         if (channelDescriptors.length === 0) {
           return;
         }
-        const invocationTasks = channelDescriptors.map(descriptor => this.invokeHandlerWithBounds(descriptor, createIsolatedEvent(descriptor.eventType, payload), {
-          signal: undefined,
-          timeoutMs: this.normalizeTimeoutMs(this.moduleOptions.publish?.timeoutMs),
-          waitForHandlers: this.moduleOptions.publish?.waitForHandlers ?? true
-        }));
-        await Promise.allSettled(invocationTasks);
+        await this.trackActiveDispatch(this.dispatchIncomingTransportMessage(channelDescriptors, payload));
       });
       this.subscribedChannels.add(channel);
     } catch (error) {
@@ -279,6 +367,17 @@ class EventBusLifecycleService {
       throw error;
     }
   }
+  canDispatchIncomingTransportMessage() {
+    return this.lifecycleState === 'ready';
+  }
+  async dispatchIncomingTransportMessage(channelDescriptors, payload) {
+    const invocationTasks = channelDescriptors.map(descriptor => this.invokeHandlerWithBounds(descriptor, createIsolatedEvent(descriptor.eventType, payload), {
+      signal: undefined,
+      timeoutMs: this.normalizeTimeoutMs(this.moduleOptions.publish?.timeoutMs),
+      waitForHandlers: this.moduleOptions.publish?.waitForHandlers ?? true
+    }));
+    await Promise.allSettled(invocationTasks);
+  }
   async preloadHandlerInstances(descriptors) {
     for (const descriptor of descriptors) {
       if (this.handlerInstances.has(descriptor.token)) {

package/dist/status.d.ts

@@ -9,6 +9,8 @@ export type EventBusLifecycleState = 'created' | 'discovering' | 'ready' | 'stop
 export interface EventBusStatusAdapterInput {
     handlersDiscovered: number;
     lifecycleState: EventBusLifecycleState;
+    shutdownDrainTimeoutMs: number;
+    shutdownDrainTimeouts: number;
     subscribedChannels: number;
     transportCloseFailures: number;
     transportConfigured: boolean;

package/dist/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7G;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,sBAAsB,CAAC;IACvC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAwFD;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,0BAA0B,GAAG,8BAA8B,CAqBtH"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7G;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,sBAAsB,CAAC;IACvC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AA6FD;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,0BAA0B,GAAG,8BAA8B,CAuBtH"}

package/dist/status.js

@@ -71,9 +71,9 @@ function createHealth(input) {
       status: 'degraded'
     };
   }
-  if (input.transportPublishFailures > 0 || input.transportSubscribeFailures > 0 || input.transportCloseFailures > 0) {
+  if (input.shutdownDrainTimeouts > 0 || input.transportPublishFailures > 0 || input.transportSubscribeFailures > 0 || input.transportCloseFailures > 0) {
     return {
-      reason: 'Event bus transport reported recoverable runtime failures.',
+      reason: 'Event bus reported recoverable runtime failures.',
       status: 'degraded'
     };
   }
@@ -98,6 +98,8 @@ export function createEventBusPlatformStatusSnapshot(input) {
       handlersDiscovered: input.handlersDiscovered,
       lifecycleState: input.lifecycleState,
       operationMode: resolveOperationMode(input),
+      shutdownDrainTimeoutMs: input.shutdownDrainTimeoutMs,
+      shutdownDrainTimeouts: input.shutdownDrainTimeouts,
       subscribedChannels: input.subscribedChannels,
       transportCloseFailures: input.transportCloseFailures,
       transportConfigured: input.transportConfigured,

package/dist/types.d.ts

@@ -32,8 +32,8 @@ export interface EventBusTransport {
     publish(channel: string, payload: unknown): Promise<void>;
     /**
      * Subscribe to incoming messages on the given channel from the external transport.
-     * The event bus calls this once per discovered local handler during bootstrap.
-     * Received messages are deserialized and dispatched to matching local handlers.
+     * The event bus calls this once per unique event channel during bootstrap.
+     * Received messages are dispatched to every matching local handler for that channel.
      */
     subscribe(channel: string, handler: (payload: unknown) => Promise<void>): Promise<void>;
     /**
@@ -49,6 +49,10 @@ export interface EventBusModuleOptions {
         timeoutMs?: number;
         waitForHandlers?: boolean;
     };
+    /** Shutdown drain policy. `drainTimeoutMs` defaults to 5000ms. */
+    shutdown?: {
+        drainTimeoutMs?: number;
+    };
     /**
      * Optional external transport adapter (e.g. Redis Pub/Sub).
      * When provided, `publish()` fans out to the transport in addition to local handlers,

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE/D,qGAAqG;AACrG,MAAM,WAAW,SAAS,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IACvD,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExF;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE/D,qGAAqG;AACrG,MAAM,WAAW,SAAS,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IACvD,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExF;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF,kEAAkE;IAClE,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE"}

package/package.json

@@ -8,7 +8,7 @@
     "pubsub",
     "in-process"
   ],
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -39,9 +39,9 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.4",
-    "@fluojs/di": "^1.0.0-beta.6",
-    "@fluojs/runtime": "^1.0.0-beta.11"
+    "@fluojs/core": "^1.0.0-beta.6",
+    "@fluojs/di": "^1.0.0-beta.8",
+    "@fluojs/runtime": "^1.0.0-beta.12"
   },
   "peerDependencies": {
     "ioredis": "^5.0.0"