nestworker 2.1.5 → 2.1.7

package/dist/core/worker.interfaces.d.ts

@@ -6,8 +6,13 @@ export interface WorkerJob {
     methodName: string;
     args: unknown[];
     proxyServices?: ProxyServiceDescriptor[];
-    /** ALS context snapshot — restored in worker before task runs */
-    alsContext?: Record<string, unknown>;
+    /**
+     * ALS context snapshot. Index `i` corresponds to the i-th storage in
+     * `WorkerModuleOptions.asyncLocalStorages`. Encoded as an array — smaller
+     * structuredClone payload than an object, and survives >10 storages
+     * (the old string-keyed encoding broke past 9).
+     */
+    alsContext?: unknown[];
     /** OTEL trace context — W3C traceparent/tracestate headers */
     traceContext?: Record<string, string>;
     /** AbortSignal is non-transferable; we send the signal ID instead */
@@ -43,6 +48,13 @@ export interface IpcInvokeRequest {
     propertyKey: string;
     methodName: string;
     args: unknown[];
+    /**
+     * If the originating worker task was invoked with an AbortSignal, the
+     * worker forwards its abortSignalId here so the main thread can wire the
+     * proxy call to the same signal — preventing proxy methods from running
+     * past their parent task's cancellation.
+     */
+    abortSignalId?: number;
 }
 export interface IpcInvokeResponse {
     type: 'ipc:result';
@@ -79,7 +91,8 @@ export interface DiscoveredTask {
     priority: TaskPriority;
     timeout?: number;
     retry?: number;
-    retryDelay?: number;
+    /** Number or function — functions are evaluated main-thread per attempt. */
+    retryDelay?: number | ((attempt: number) => number);
     fn: (...args: unknown[]) => unknown;
     metatype: new (...args: unknown[]) => unknown;
     instance: unknown;
@@ -111,11 +124,29 @@ export interface WorkerModuleOptions {
      * workers on application shutdown. Defaults to 30_000.
      */
     shutdownTimeout?: number;
+    /**
+     * Maximum number of pending tasks allowed in the queue. When the queue is
+     * full, `WorkerService.run()` rejects with a `QueueFullError` instead of
+     * enqueuing — gives callers a chance to apply backpressure. Defaults to
+     * `Infinity` (unbounded, legacy behaviour).
+     */
+    maxQueueDepth?: number;
     /**
      * AsyncLocalStorage instances whose current store should be propagated
      * into worker tasks. Pass the same ALS instances you use in your app.
      */
     asyncLocalStorages?: AsyncLocalStorage<unknown>[];
+    /**
+     * Optional logger sink. Defaults to `@nestjs/common`'s `Logger`. Pass any
+     * object with `error`/`warn`/`debug` methods to integrate pino, winston,
+     * bunyan, etc.
+     */
+    logger?: WorkerLogger;
+}
+export interface WorkerLogger {
+    error(message: string, trace?: string): void;
+    warn(message: string): void;
+    debug?(message: string): void;
 }
 export interface WorkerModuleAsyncOptions {
     inject?: unknown[];
@@ -127,4 +158,8 @@ export interface PoolStats {
     busy: number;
     queued: number;
     warmingUp: number;
+    /** Queue depth as a fraction of `maxQueueDepth` (0..1). 0 when unbounded. */
+    saturation: number;
+    /** Configured `maxQueueDepth` (Infinity when unbounded). */
+    maxQueueDepth: number;
 }

package/dist/core/worker.module.js

@@ -55,11 +55,7 @@ let WorkerModule = WorkerModule_1 = class WorkerModule {
             module: WorkerModule_1,
             global: true,
             imports: [core_1.DiscoveryModule],
-            providers: [
-                optionsProvider,
-                discovery_service_1.WorkerDiscoveryService,
-                worker_service_1.WorkerService,
-            ],
+            providers: [optionsProvider, discovery_service_1.WorkerDiscoveryService, worker_service_1.WorkerService],
             exports: [worker_service_1.WorkerService],
         };
     }

package/dist/core/worker.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker.module.js","sourceRoot":"","sources":["../../src/core/worker.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAiE;AACjE,uCAA+C;AAC/C,qDAAiD;AACjD,sEAAwE;AAIjE,IAAM,YAAY,oBAAlB,MAAM,YAAY;IACvB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,UAA+B,EAAE;QAC9C,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBAChD,0CAAsB;gBACtB,8BAAa;aACd;YACD,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,YAAsC;QACxD,MAAM,eAAe,GAAa;YAChC,OAAO,EAAE,gBAAgB;YACzB,MAAM,EAAE,CAAC,YAAY,CAAC,MAAM,IAAI,EAAE,CAAY;YAC9C,UAAU,EAAE,YAAY,CAAC,UAAU;SACpC,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,eAAe;gBACf,0CAAsB;gBACtB,8BAAa;aACd;YACD,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;CACF,CAAA;AArDY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,YAAY,CAqDxB"}
+{"version":3,"file":"worker.module.js","sourceRoot":"","sources":["../../src/core/worker.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAiE;AACjE,uCAA+C;AAC/C,qDAAiD;AACjD,sEAAwE;AAOjE,IAAM,YAAY,oBAAlB,MAAM,YAAY;IACvB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,UAA+B,EAAE;QAC9C,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBAChD,0CAAsB;gBACtB,8BAAa;aACd;YACD,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,YAAsC;QACxD,MAAM,eAAe,GAAa;YAChC,OAAO,EAAE,gBAAgB;YACzB,MAAM,EAAE,CAAC,YAAY,CAAC,MAAM,IAAI,EAAE,CAAY;YAC9C,UAAU,EAAE,YAAY,CAAC,UAAU;SACpC,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,cAAY;YACpB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,sBAAe,CAAC;YAC1B,SAAS,EAAE,CAAC,eAAe,EAAE,0CAAsB,EAAE,8BAAa,CAAC;YACnE,OAAO,EAAE,CAAC,8BAAa,CAAC;SACzB,CAAC;IACJ,CAAC;CACF,CAAA;AAjDY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,YAAY,CAiDxB"}

package/dist/core/worker.pool.d.ts

@@ -1,6 +1,9 @@
 import { EventEmitter } from 'node:events';
 import type { WorkerJob, TaskPriority, ProxyInstance, DeadLetterEvent, SerializedError, PoolStats } from './worker.interfaces';
 import type { SerializedService } from '../di/worker-container';
+export declare class QueueFullError extends Error {
+    constructor(depth: number);
+}
 export declare interface WorkerPool {
     on(event: 'dead', listener: (event: DeadLetterEvent) => void): this;
     on(event: 'error', listener: (err: Error, job: WorkerJob) => void): this;
@@ -26,8 +29,13 @@ export declare class WorkerPool extends EventEmitter {
      */
     private readonly idle;
     private readonly warmingUp;
-    private readonly queue;
-    private queueHead;
+    private readonly queueHigh;
+    private readonly queueNormal;
+    private readonly queueLow;
+    private queueHighHead;
+    private queueNormalHead;
+    private queueLowHead;
+    private queuedCount;
     private destroyed;
     private activeCount;
     /**
@@ -39,36 +47,65 @@ export declare class WorkerPool extends EventEmitter {
      * coalesced into a single postMessage per worker.
      */
     private scheduleQueued;
-    /** Maps abortSignalId → worker currently running that job */
-    private readonly signalWorkerMap;
     private readonly concurrency;
+    private readonly maxQueueDepth;
     private readonly proxyMap;
-    constructor(services: SerializedService[], proxyInstances: ProxyInstance[], size?: number, shutdownTimeout?: number, concurrency?: number);
+    constructor(services: SerializedService[], proxyInstances: ProxyInstance[], size?: number, shutdownTimeout?: number, concurrency?: number, maxQueueDepth?: number);
     execute<T = unknown>(job: WorkerJob, meta: {
         priority: TaskPriority;
         timeout?: number;
         retry?: number;
-        retryDelay?: number;
+        retryDelay?: number | ((attempt: number) => number);
     }, signal?: AbortSignal): Promise<T>;
+    /** Remove the abort listener installed in `execute()` (idempotent). */
+    private detachAbort;
     stats(): PoolStats;
     private spawnWorker;
     private handleIpcInvoke;
+    /**
+     * Look up the original caller's AbortSignal by abortSignalId. Used by
+     * `handleIpcInvoke` to forward cancellation into proxy methods.
+     * Scan is bounded by `concurrency * poolSize` and only happens on proxy
+     * calls from signal-bearing tasks, so we don't bother with a side index.
+     */
+    private findSignalById;
     private enqueue;
-    private schedule;
     /**
-     * Synchronous drain used on the COMPLETION path — when a worker becomes
-     * idle as a result of a result message arriving, we want to hand it the
-     * next queued job in the SAME tick. The microtask-deferred `schedule()`
-     * adds a full microtask hop per round-trip, which dominates throughput
-     * for short tasks with concurrency=1.
+     * Pop the next ready task in priority order (HIGH > NORMAL > LOW). Skips
+     * tombstoned entries (aborted-while-queued) and lazily compacts each
+     * bucket once its head pointer wastes >1024 slots.
      *
-     * Initial-burst dispatch still goes through the deferred `schedule()` so
-     * synchronous floods of `execute()` calls get coalesced into per-worker
-     * batches.
+     * Returns `undefined` when all buckets are empty or contain only
+     * tombstones — caller must check.
+     */
+    private dequeue;
+    private maybeCompact;
+    /** True iff at least one bucket has a non-tombstone entry remaining. */
+    private hasQueued;
+    private schedule;
+    /**
+     * Synchronous drain used on the COMPLETION path. Initial-burst dispatch
+     * still goes through the deferred `schedule()` so synchronous floods of
+     * `execute()` calls get coalesced into per-worker batches.
      */
     private dispatchNow;
     /** Pre-bound for queueMicrotask — avoids closure allocation per schedule. */
     private readonly drain;
+    /**
+     * Common dispatch loop shared by `dispatchNow` (synchronous, post-result)
+     * and `drain` (microtask, post-burst). Pops idle slots and ships jobs as
+     * either bare `WorkerJob` (single) or `WorkerJobBatch` envelopes.
+     *
+     * @param fastSingle When true, take a fast path for "exactly one job to
+     *   exactly one idle worker" that skips the per-worker Map allocation.
+     */
+    private flushDispatch;
+    /**
+     * Post a single job; on serialization failure synthesise a failure result
+     * so the caller's promise rejects instead of hanging on the active map.
+     */
+    private safePostJob;
+    private safePostBatch;
     private prepareDispatch;
     /** Called from the persistent message listener when a job result arrives. */
     private completeJob;