@fluojs/queue 1.0.0-beta.4 → 1.0.0

package/README.ko.md

@@ -59,23 +59,23 @@ import { Module, Inject } from '@fluojs/core';
 import { QueueModule, QueueLifecycleService } from '@fluojs/queue';
 import { RedisModule } from '@fluojs/redis';
 
+@Inject(QueueLifecycleService)
+export class OrderService {
+  constructor(private readonly queue: QueueLifecycleService) {}
+
+  async placeOrder(id: string) {
+    await this.queue.enqueue(new ProcessOrderJob(id));
+  }
+}
+
 @Module({
   imports: [
     RedisModule.forRoot({ host: 'localhost', port: 6379 }),
     QueueModule.forRoot(),
   ],
-  providers: [OrderWorker],
+  providers: [OrderService, OrderWorker],
 })
 export class AppModule {}
-
-export class OrderService {
-  @Inject(QueueLifecycleService)
-  private readonly queue: QueueLifecycleService;
-
-  async placeOrder(id: string) {
-    await this.queue.enqueue(new ProcessOrderJob(id));
-  }
-}
 ```
 
 ## 일반적인 패턴
@@ -90,6 +90,12 @@ QueueModule.forRoot({ clientName: 'jobs' })
 
 `@fluojs/queue`는 애플리케이션 부트스트랩 중 해당 Redis 클라이언트를 조회한 뒤 BullMQ용으로 큐가 소유하는 duplicate 연결을 만듭니다. 공유 `@fluojs/redis` 클라이언트의 소유권은 `RedisModule`에 남아 있으며, Queue는 자신이 만든 BullMQ duplicate 연결만 닫습니다. 이 duplicate 연결은 BullMQ Worker가 요구하는 `maxRetriesPerRequest: null` 설정으로 구성되어 시작 동작이 BullMQ의 실제 런타임 제약과 일치합니다.
 
+### 부트스트랩 및 종료 수명 주기
+
+Queue는 애플리케이션 부트스트랩 중 worker를 탐색하고 Queue가 소유하는 BullMQ 리소스를 만들지만, BullMQ worker processor는 runtime이 전체 애플리케이션 bootstrap/readiness sequence 완료를 표시한 뒤에만 시작합니다. 다른 `onApplicationBootstrap()` hook에서 enqueue한 job은 Queue 서비스가 초기화된 뒤에는 받을 수 있으며, processor는 뒤에 실행되는 async bootstrap hook이나 애플리케이션 readiness보다 앞서 실행되지 않고 bootstrap-ready handoff 이후 실행됩니다.
+
+애플리케이션 종료가 시작되면 Queue는 상태를 `stopping`으로 바꾸고 새 enqueue를 거부한 다음 Queue 소유 worker/queue/connection을 닫고 pending dead-letter write를 drain합니다. Worker 종료는 `workerShutdownTimeoutMs`로 bounded wait를 적용하므로 끝나지 않는 active processor가 애플리케이션 종료를 무기한 막을 수 없습니다. Timeout이 지나면 Queue는 로그를 남기고 BullMQ worker에 force-close를 요청한 뒤 나머지 리소스 정리를 계속합니다.
+
 ### 분산 재시도 (Distributed Retries)
 
 워커 설정에서 최대 시도 횟수와 백오프 전략을 지정하여 일시적인 실패를 자동으로 처리할 수 있습니다.
@@ -127,7 +133,14 @@ Job은 JSON으로 직렬화 가능한 plain object여야 합니다. Queue는 enq
 - `QueueWorkerOptions`: 개별 작업 설정(시도 횟수, 백오프, 동시성, jobName, 전송률 제한 등)을 위한 타입입니다.
 - `QueueBackoffOptions`: 재시도 백오프 설정(`type`, `delayMs`)을 위한 타입입니다.
 
-`QueueModuleOptions`에는 `defaultDeadLetterMaxEntries` 같은 dead-letter retention 설정도 포함됩니다.
+`QueueModuleOptions`에는 `workerShutdownTimeoutMs`, `defaultDeadLetterMaxEntries` 같은 lifecycle 및 dead-letter retention 설정도 포함됩니다.
+
+`QueueModuleOptions` 수명 주기/status 설정:
+
+- `workerShutdownTimeoutMs`: 종료 중 active worker processor를 기다리는 최대 시간입니다. 시간이 지나면 BullMQ worker를 force-close합니다. 기본값은 `30_000`입니다.
+- `defaultDeadLetterMaxEntries`: job별로 유지할 dead-letter record의 최대 개수이며, trimming을 끄려면 `false`를 지정합니다. 기본값은 `1_000`입니다.
+
+`createQueuePlatformStatusSnapshot(...)`은 Queue가 `started`에 도달한 뒤에만 readiness를 `ready`로 보고합니다. `starting`은 degraded readiness, `stopping`/`stopped`는 not-ready로 보고합니다. Snapshot details에는 Redis dependency id, lifecycle state, ready/discovered worker 수, pending dead-letter write 수, dead-letter drain timeout, `workerShutdownTimeoutMs`가 포함됩니다.
 
 singleton `@QueueWorker()` provider/controller만 등록됩니다. request/transient worker는 discovery 중 건너뜁니다.
 

package/README.md

@@ -59,23 +59,23 @@ import { Module, Inject } from '@fluojs/core';
 import { QueueModule, QueueLifecycleService } from '@fluojs/queue';
 import { RedisModule } from '@fluojs/redis';
 
+@Inject(QueueLifecycleService)
+export class OrderService {
+  constructor(private readonly queue: QueueLifecycleService) {}
+
+  async placeOrder(id: string) {
+    await this.queue.enqueue(new ProcessOrderJob(id));
+  }
+}
+
 @Module({
   imports: [
     RedisModule.forRoot({ host: 'localhost', port: 6379 }),
     QueueModule.forRoot(),
   ],
-  providers: [OrderWorker],
+  providers: [OrderService, OrderWorker],
 })
 export class AppModule {}
-
-export class OrderService {
-  @Inject(QueueLifecycleService)
-  private readonly queue: QueueLifecycleService;
-
-  async placeOrder(id: string) {
-    await this.queue.enqueue(new ProcessOrderJob(id));
-  }
-}
 ```
 
 ## Common Patterns
@@ -90,6 +90,12 @@ QueueModule.forRoot({ clientName: 'jobs' })
 
 `@fluojs/queue` resolves that Redis client during application bootstrap, then creates queue-owned duplicate connections for BullMQ. The shared `@fluojs/redis` client remains owned by `RedisModule`; Queue closes only the duplicate BullMQ connections it creates. Those duplicate connections are configured with BullMQ's required `maxRetriesPerRequest: null` worker setting so startup behavior matches BullMQ's runtime constraints.
 
+### Bootstrap and Shutdown Lifecycle
+
+Queue discovers workers and creates queue-owned BullMQ resources during application bootstrap, but BullMQ worker processors are started only after the runtime marks the full application bootstrap/readiness sequence complete. Jobs enqueued by other `onApplicationBootstrap()` hooks can be accepted once the Queue service is initialized, and their processors run after the bootstrap-ready handoff instead of racing ahead of later async bootstrap hooks or application readiness.
+
+Application shutdown marks Queue as `stopping`, rejects new enqueue attempts, closes queue-owned workers/queues/connections, and drains pending dead-letter writes. Worker shutdown is bounded by `workerShutdownTimeoutMs` so an active processor that never settles cannot block application shutdown indefinitely. When the timeout elapses, Queue logs the timeout and asks BullMQ to force-close the worker before continuing resource cleanup.
+
 ### Distributed Retries
 
 Workers can be configured with a maximum number of attempts and backoff strategies to handle transient failures automatically.
@@ -127,7 +133,14 @@ Treat low-level provider assembly as an internal implementation detail: low-leve
 - `QueueWorkerOptions`: Per-job settings (attempts, backoff, concurrency, jobName, rate limiting).
 - `QueueBackoffOptions`: Retry backoff settings (`type`, `delayMs`).
 
-`QueueModuleOptions` also includes dead-letter retention controls such as `defaultDeadLetterMaxEntries`.
+`QueueModuleOptions` also includes lifecycle and dead-letter retention controls such as `workerShutdownTimeoutMs` and `defaultDeadLetterMaxEntries`.
+
+`QueueModuleOptions` lifecycle/status controls:
+
+- `workerShutdownTimeoutMs`: maximum time to wait for active worker processors during shutdown before force-closing the BullMQ worker. Defaults to `30_000`.
+- `defaultDeadLetterMaxEntries`: maximum retained dead-letter records per job, or `false` to disable trimming. Defaults to `1_000`.
+
+`createQueuePlatformStatusSnapshot(...)` reports readiness as `ready` only after Queue reaches `started`; `starting` reports degraded readiness, and `stopping`/`stopped` report not-ready. Snapshot details include the Redis dependency id, lifecycle state, ready/discovered worker counts, pending dead-letter writes, the dead-letter drain timeout, and `workerShutdownTimeoutMs`.
 
 Only singleton `@QueueWorker()` providers/controllers are registered. Request/transient workers are skipped during discovery.
 

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAAgC,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAqCnF;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU;CAS7D"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAAgC,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAsCnF;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU;CAS7D"}

package/dist/module.js

@@ -13,7 +13,8 @@ function normalizeQueueModuleOptions(options = {}) {
     } : undefined,
     defaultConcurrency: normalizePositiveInteger(options.defaultConcurrency, 1),
     defaultDeadLetterMaxEntries: normalizePositiveIntegerOrFalse(options.defaultDeadLetterMaxEntries, 1_000),
-    defaultRateLimiter
+    defaultRateLimiter,
+    workerShutdownTimeoutMs: normalizePositiveInteger(options.workerShutdownTimeoutMs, 30_000)
   };
 }
 function createQueueProviders(options = {}) {

package/dist/service.d.ts

@@ -1,5 +1,6 @@
 import type { Container } from '@fluojs/di';
-import { type ApplicationLogger, type CompiledModule, type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleDestroy } from '@fluojs/runtime';
+import type { ApplicationLogger, CompiledModule, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy } from '@fluojs/runtime';
+import { type BootstrapReadySignal } from '@fluojs/runtime/internal';
 import type { NormalizedQueueModuleOptions, Queue } from './types.js';
 /**
  * Lifecycle-managed queue runtime for worker discovery and job dispatch.
@@ -12,16 +13,18 @@ export declare class QueueLifecycleService implements Queue, OnApplicationBootst
     private readonly runtimeContainer;
     private readonly compiledModules;
     private readonly logger;
+    private readonly bootstrapReadySignal;
     private readonly descriptorsByJobType;
     private readonly queuesByJobName;
     private readonly workersByJobName;
     private readonly ownedConnections;
     private readonly deadLetterManager;
+    private readonly readyWorkers;
     private lifecycleState;
     private redisClient;
     private startPromise;
     private shutdownPromise;
-    constructor(options: NormalizedQueueModuleOptions, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger);
+    constructor(options: NormalizedQueueModuleOptions, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, bootstrapReadySignal?: BootstrapReadySignal);
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     onModuleDestroy(): Promise<void>;
@@ -53,12 +56,15 @@ export declare class QueueLifecycleService implements Queue, OnApplicationBootst
     private createWorkerLimiterOptions;
     private attachWorkerFailureHandler;
     private registerInitializedWorker;
+    private scheduleReadyWorkers;
+    private runWorker;
     private cleanupWorkerInitializationFailure;
     private createOwnedConnection;
     private executeWorker;
     private resolveWorkerHandler;
     private rehydrateWorkerPayload;
     private shutdown;
+    private waitForInFlightStartup;
     private closeInitializedResources;
     private tryCloseWorker;
     private tryCloseQueue;

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,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EACV,4BAA4B,EAC5B,KAAK,EAIN,MAAM,YAAY,CAAC;AAkGpB;;;;;GAKG;AACH,qBACa,qBAAsB,YAAW,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe;IAY/G,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdzB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAkD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA8B;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,eAAe,CAA4B;gBAGhC,OAAO,EAAE,4BAA4B,EACrC,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB;IAKtC,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB9D;;;;OAIG;IACH,4BAA4B;YAWd,aAAa;YAwBb,cAAc;YAad,oBAAoB;YAOpB,kBAAkB;IAgBhC,OAAO,CAAC,cAAc;YAQR,iBAAiB;YAOjB,yBAAyB;IAyBvC,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,mBAAmB;IAkB3B,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,yBAAyB;YASnB,kCAAkC;YAkBlC,qBAAqB;YAiBrB,aAAa;YAOb,oBAAoB;IAyBlC,OAAO,CAAC,sBAAsB;YAQhB,QAAQ;YAsBR,yBAAyB;YAqBzB,cAAc;YAQd,aAAa;YAQb,uBAAuB;CAOtC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EACV,4BAA4B,EAC5B,KAAK,EAIN,MAAM,YAAY,CAAC;AAqHpB;;;;;GAKG;AACH,qBACa,qBAAsB,YAAW,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe;IAa/G,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAhBvC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAkD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA8B;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,eAAe,CAA4B;gBAGhC,OAAO,EAAE,4BAA4B,EACrC,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,oBAAoB,GAAE,oBAAuD;IAK1F,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B9D;;;;OAIG;IACH,4BAA4B;YAYd,aAAa;YAwBb,cAAc;YAgBd,oBAAoB;YASpB,kBAAkB;IAgBhC,OAAO,CAAC,cAAc;YAQR,iBAAiB;YAOjB,yBAAyB;IAyBvC,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,yBAAyB;IAUjC,OAAO,CAAC,oBAAoB;IAwB5B,OAAO,CAAC,SAAS;YAgBH,kCAAkC;YAkBlC,qBAAqB;YAiBrB,aAAa;YAOb,oBAAoB;IAyBlC,OAAO,CAAC,sBAAsB;YAQhB,QAAQ;YAyBR,sBAAsB;YAgBtB,yBAAyB;YAsBzB,cAAc;YAkBd,aAAa;YAQb,uBAAuB;CAOtC"}

package/dist/service.js

@@ -7,13 +7,16 @@ function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side
 import { Inject } from '@fluojs/core';
 import { cloneWithFallback } from '@fluojs/core/internal';
 import { getRedisClientToken, getRedisComponentId } from '@fluojs/redis';
-import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { APPLICATION_LOGGER, BOOTSTRAP_READY_SIGNAL, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { Queue as BullQueue, Worker as BullWorker } from 'bullmq';
 import { QueueDeadLetterManager } from './dead-letter-manager.js';
-import { normalizePositiveInteger } from './helpers.js';
+import { normalizePositiveInteger, withTimeout } from './helpers.js';
 import { createQueuePlatformStatusSnapshot } from './status.js';
 import { QUEUE_OPTIONS } from './tokens.js';
 import { discoverQueueWorkerDescriptors } from './worker-discovery.js';
+const IMMEDIATE_BOOTSTRAP_READY_SIGNAL = {
+  wait: () => Promise.resolve()
+};
 function hasQueueRedisClient(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -66,22 +69,24 @@ async function closeConnection(connection) {
 let _QueueLifecycleServic;
 class QueueLifecycleService {
   static {
-    [_QueueLifecycleServic, _initClass] = _applyDecs(this, [Inject(QUEUE_OPTIONS, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], []).c;
+    [_QueueLifecycleServic, _initClass] = _applyDecs(this, [Inject(QUEUE_OPTIONS, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, BOOTSTRAP_READY_SIGNAL)], []).c;
   }
   descriptorsByJobType = new Map();
   queuesByJobName = new Map();
   workersByJobName = new Map();
   ownedConnections = [];
   deadLetterManager;
+  readyWorkers = [];
   lifecycleState = 'idle';
   redisClient;
   startPromise;
   shutdownPromise;
-  constructor(options, runtimeContainer, compiledModules, logger) {
+  constructor(options, runtimeContainer, compiledModules, logger, bootstrapReadySignal = IMMEDIATE_BOOTSTRAP_READY_SIGNAL) {
     this.options = options;
     this.runtimeContainer = runtimeContainer;
     this.compiledModules = compiledModules;
     this.logger = logger;
+    this.bootstrapReadySignal = bootstrapReadySignal;
     this.deadLetterManager = new QueueDeadLetterManager(this.options, this.logger, () => this.getRedisClient());
   }
   async onApplicationBootstrap() {
@@ -104,6 +109,9 @@ class QueueLifecycleService {
    */
   async enqueue(job) {
     await this.ensureStarted();
+    if (this.lifecycleState !== 'started') {
+      throw new Error(`Queue lifecycle state is ${this.lifecycleState}.`);
+    }
     const descriptor = this.descriptorsByJobType.get(job.constructor);
     if (!descriptor) {
       throw new Error(`No @QueueWorker() registered for job type ${job.constructor.name}.`);
@@ -130,6 +138,7 @@ class QueueLifecycleService {
       lifecycleState: this.lifecycleState,
       pendingDeadLetterWrites: this.deadLetterManager.pendingWriteCount,
       queuesReady: this.queuesByJobName.size,
+      workerShutdownTimeoutMs: this.options.workerShutdownTimeoutMs,
       workersDiscovered: this.descriptorsByJobType.size,
       workersReady: this.workersByJobName.size
     });
@@ -161,11 +170,16 @@ class QueueLifecycleService {
       this.descriptorsByJobType.set(jobType, descriptor);
     }
     await this.initializeWorkers(redis);
-    this.lifecycleState = 'started';
+    if (this.lifecycleState === 'starting') {
+      this.lifecycleState = 'started';
+      this.scheduleReadyWorkers();
+    }
   }
   async handleStartupFailure() {
     await this.closeInitializedResources();
-    this.lifecycleState = 'idle';
+    if (this.lifecycleState === 'starting') {
+      this.lifecycleState = 'idle';
+    }
     this.redisClient = undefined;
     this.startPromise = undefined;
   }
@@ -223,6 +237,7 @@ class QueueLifecycleService {
   }
   createWorkerOptions(descriptor, workerConnection) {
     return {
+      autorun: false,
       concurrency: descriptor.concurrency,
       connection: workerConnection,
       ...this.createWorkerLimiterOptions(descriptor)
@@ -248,6 +263,38 @@ class QueueLifecycleService {
     this.queuesByJobName.set(descriptor.jobName, resources.queue);
     this.workersByJobName.set(descriptor.jobName, resources.worker);
     this.ownedConnections.push(resources.queueConnection, resources.workerConnection);
+    this.readyWorkers.push({
+      descriptor,
+      worker: resources.worker
+    });
+  }
+  scheduleReadyWorkers() {
+    const workers = this.readyWorkers.splice(0);
+    void this.bootstrapReadySignal.wait().then(() => {
+      if (this.lifecycleState !== 'started') {
+        return;
+      }
+      for (const {
+        descriptor,
+        worker
+      } of workers) {
+        this.runWorker(descriptor, worker);
+      }
+    }).catch(error => {
+      if (this.lifecycleState !== 'started') {
+        return;
+      }
+      this.logger.error('Failed to start queue workers after application bootstrap readiness.', error, 'QueueLifecycleService');
+    });
+  }
+  runWorker(descriptor, worker) {
+    const runnableWorker = worker;
+    if (typeof runnableWorker.run !== 'function') {
+      return;
+    }
+    void Promise.resolve(runnableWorker.run()).catch(error => {
+      this.logger.error(`Failed to start queue worker ${descriptor.workerName} after application bootstrap.`, error, 'QueueLifecycleService');
+    });
   }
   async cleanupWorkerInitializationFailure(resources) {
     if (resources.worker) {
@@ -314,19 +361,35 @@ class QueueLifecycleService {
     }
     this.lifecycleState = 'stopping';
     this.shutdownPromise = (async () => {
+      await this.waitForInFlightStartup();
       await this.closeInitializedResources();
       await this.deadLetterManager.drainPendingWrites();
       this.lifecycleState = 'stopped';
+      this.redisClient = undefined;
       this.startPromise = undefined;
     })();
     await this.shutdownPromise;
   }
+  async waitForInFlightStartup() {
+    const startup = this.startPromise;
+    if (!startup) {
+      return;
+    }
+    try {
+      await startup;
+    } catch {
+      // ensureStarted() owns startup rollback and preserves the original
+      // bootstrap error. Shutdown still continues so partially registered
+      // resources cannot outlive the application lifecycle.
+    }
+  }
   async closeInitializedResources() {
     const workers = Array.from(this.workersByJobName.values());
     const queues = Array.from(this.queuesByJobName.values());
     const ownedConnections = this.ownedConnections.splice(0);
     this.workersByJobName.clear();
     this.queuesByJobName.clear();
+    this.readyWorkers.splice(0);
     for (const worker of workers) {
       await this.tryCloseWorker(worker);
     }
@@ -339,9 +402,14 @@ class QueueLifecycleService {
   }
   async tryCloseWorker(worker) {
     try {
-      await worker.close();
+      await withTimeout(worker.close(), this.options.workerShutdownTimeoutMs, () => new Error('queue worker shutdown timed out'));
     } catch (error) {
-      this.logger.error('Failed to close queue worker during shutdown.', error, 'QueueLifecycleService');
+      this.logger.error('Failed to close queue worker within shutdown timeout.', error, 'QueueLifecycleService');
+      try {
+        await worker.close(true);
+      } catch (forceCloseError) {
+        this.logger.error('Failed to force close queue worker during shutdown.', forceCloseError, 'QueueLifecycleService');
+      }
     }
   }
   async tryCloseQueue(queue) {

package/dist/status.d.ts

@@ -7,6 +7,7 @@ export interface QueueStatusAdapterInput {
     lifecycleState: QueueLifecycleState;
     pendingDeadLetterWrites: number;
     queuesReady: number;
+    workerShutdownTimeoutMs: number;
     workersDiscovered: number;
     workersReady: number;
 }

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,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3F,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,mBAAmB,CAAC;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,2BAA2B;IAC1C,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;AAkFD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,uBAAuB,GAAG,2BAA2B,CAkB7G"}
+{"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,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3F,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,mBAAmB,CAAC;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,2BAA2B;IAC1C,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;AAkFD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,uBAAuB,GAAG,2BAA2B,CAmB7G"}

package/dist/status.js

@@ -88,6 +88,7 @@ export function createQueuePlatformStatusSnapshot(input) {
       lifecycleState: input.lifecycleState,
       pendingDeadLetterWrites: input.pendingDeadLetterWrites,
       queuesReady: input.queuesReady,
+      workerShutdownTimeoutMs: input.workerShutdownTimeoutMs,
       workersDiscovered: input.workersDiscovered,
       workersReady: input.workersReady
     },

package/dist/types.d.ts

@@ -38,6 +38,8 @@ export interface QueueModuleOptions {
     defaultConcurrency?: number;
     defaultDeadLetterMaxEntries?: number | false;
     defaultRateLimiter?: QueueRateLimiterOptions;
+    /** Maximum time shutdown waits for active worker processors before forcing worker close. Defaults to `30_000`. */
+    workerShutdownTimeoutMs?: number;
 }
 /** Normalized queue options resolved once during module registration. */
 export interface NormalizedQueueModuleOptions {
@@ -47,6 +49,7 @@ export interface NormalizedQueueModuleOptions {
     defaultConcurrency: number;
     defaultDeadLetterMaxEntries: number | false;
     defaultRateLimiter?: QueueRateLimiterOptions;
+    workerShutdownTimeoutMs: number;
 }
 /** Metadata captured by {@link QueueWorker} during decorator evaluation. */
 export interface QueueWorkerMetadata {

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,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,oFAAoF;AACpF,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACxD,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;CAC9B;AAED,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,aAAa,CAAC;AAEvD,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACvC;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2BAA2B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7C,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,yEAAyE;AACzE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5C,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,oFAAoF;AACpF,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACxD,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;CAC9B;AAED,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,aAAa,CAAC;AAEvD,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACvC;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2BAA2B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7C,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAC7C,kHAAkH;IAClH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,yEAAyE;AACzE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5C,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAC7C,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D"}

package/package.json

@@ -10,7 +10,7 @@
     "redis",
     "dlq"
   ],
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -38,10 +38,10 @@
   ],
   "dependencies": {
     "bullmq": "^5.58.0",
-    "@fluojs/core": "^1.0.0-beta.4",
-    "@fluojs/di": "^1.0.0-beta.6",
-    "@fluojs/redis": "^1.0.0-beta.3",
-    "@fluojs/runtime": "^1.0.0-beta.11"
+    "@fluojs/core": "^1.0.0",
+    "@fluojs/redis": "^1.0.0",
+    "@fluojs/runtime": "^1.0.0",
+    "@fluojs/di": "^1.0.0"
   },
   "devDependencies": {
     "vitest": "^3.2.4"