@zintrust/core 2.4.3 → 2.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "2.4.3",
+  "version": "2.4.5",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {
@@ -202,6 +202,14 @@
       "types": "./src/socket-index.d.ts",
       "import": "./src/socket-index.js"
     },
+    "./tasks": {
+      "types": "./src/tasks.d.ts",
+      "import": "./src/tasks.js"
+    },
+    "./worker-runtime": {
+      "types": "./src/worker-runtime.d.ts",
+      "import": "./src/worker-runtime.js"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v2.4.3
+ * @zintrust/core v2.4.5
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-06-01T09:39:36.110Z
+ *   Built: 2026-06-01T13:37:05.393Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-06-01T09:39:36.070Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-06-01T13:37:05.359Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';

package/src/runtime/BackgroundTaskScheduler.d.ts

@@ -0,0 +1,39 @@
+/**
+ * BackgroundTaskScheduler — runtime-agnostic background task scheduling.
+ * Maps to ctx.waitUntil() in Cloudflare Workers, normal promises in Node.
+ */
+type ExecutionContext = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+type BackgroundTaskScheduler = {
+    schedule(task: Promise<void>): void;
+    isAvailable(): boolean;
+};
+export declare const BackgroundTaskScheduler: Readonly<{
+    /**
+     * Set the Worker execution context for waitUntil support.
+     * Call this from your Cloudflare Worker fetch handler:
+     *   BackgroundTaskScheduler.setExecutionContext(ctx);
+     */
+    setExecutionContext(ctx: ExecutionContext): void;
+    /**
+     * Get the current scheduler instance.
+     */
+    getScheduler(): BackgroundTaskScheduler;
+    /**
+     * Schedule a background task.
+     * In Workers: uses ctx.waitUntil() if context is set
+     * In Node: fire-and-forget with error suppression
+     */
+    schedule(task: Promise<void>): void;
+    /**
+     * Check if a proper scheduler is available (i.e., Workers context is set).
+     */
+    isAvailable(): boolean;
+    /**
+     * Reset the scheduler (useful for testing).
+     */
+    reset(): void;
+}>;
+export {};
+//# sourceMappingURL=BackgroundTaskScheduler.d.ts.map

package/src/runtime/BackgroundTaskScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackgroundTaskScheduler.d.ts","sourceRoot":"","sources":["../../../src/runtime/BackgroundTaskScheduler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,KAAK,gBAAgB,GAAG;IACtB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,WAAW,IAAI,OAAO,CAAC;CACxB,CAAC;AA4DF,eAAO,MAAM,uBAAuB;IAClC;;;;OAIG;6BACsB,gBAAgB,GAAG,IAAI;IAKhD;;OAEG;oBACa,uBAAuB;IAmBvC;;;;OAIG;mBACY,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAInC;;OAEG;mBACY,OAAO;IAItB;;OAEG;aACM,IAAI;EAIb,CAAC"}

package/src/runtime/BackgroundTaskScheduler.js

@@ -0,0 +1,105 @@
+/**
+ * BackgroundTaskScheduler — runtime-agnostic background task scheduling.
+ * Maps to ctx.waitUntil() in Cloudflare Workers, normal promises in Node.
+ */
+let _executionContext;
+let _scheduler;
+const isCloudflareRuntime = () => {
+    const globalRef = typeof globalThis === 'undefined' ? undefined : globalThis;
+    if (!globalRef)
+        return false;
+    // @ts-ignore - navigator is available in workers
+    if (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') {
+        return true;
+    }
+    return (globalRef.caches !== undefined ||
+        typeof globalRef.WebSocketPair === 'function' ||
+        globalRef.CF !== undefined);
+};
+const createWorkerScheduler = (ctx) => {
+    return Object.freeze({
+        schedule(task) {
+            ctx.waitUntil(task);
+        },
+        isAvailable() {
+            return true;
+        },
+    });
+};
+const createNodeScheduler = () => {
+    return Object.freeze({
+        schedule(task) {
+            // In Node, fire-and-forget is acceptable since the process doesn't terminate
+            // like Workers do. We still catch errors to prevent unhandled rejections.
+            task.catch(() => {
+                // Silently ignore background task errors to avoid noise
+                // The individual watchers handle their own error logging
+            });
+        },
+        isAvailable() {
+            return true;
+        },
+    });
+};
+const createFallbackScheduler = () => {
+    return Object.freeze({
+        schedule(task) {
+            // Fallback: fire-and-forget with error suppression
+            task.catch(() => undefined);
+        },
+        isAvailable() {
+            return false;
+        },
+    });
+};
+export const BackgroundTaskScheduler = Object.freeze({
+    /**
+     * Set the Worker execution context for waitUntil support.
+     * Call this from your Cloudflare Worker fetch handler:
+     *   BackgroundTaskScheduler.setExecutionContext(ctx);
+     */
+    setExecutionContext(ctx) {
+        _executionContext = ctx;
+        _scheduler = createWorkerScheduler(ctx);
+    },
+    /**
+     * Get the current scheduler instance.
+     */
+    getScheduler() {
+        if (_scheduler)
+            return _scheduler;
+        if (_executionContext) {
+            _scheduler = createWorkerScheduler(_executionContext);
+            return _scheduler;
+        }
+        if (isCloudflareRuntime()) {
+            // We're in Workers but no context was set - use fallback
+            _scheduler = createFallbackScheduler();
+            return _scheduler;
+        }
+        // Node.js or other runtime
+        _scheduler = createNodeScheduler();
+        return _scheduler;
+    },
+    /**
+     * Schedule a background task.
+     * In Workers: uses ctx.waitUntil() if context is set
+     * In Node: fire-and-forget with error suppression
+     */
+    schedule(task) {
+        this.getScheduler().schedule(task);
+    },
+    /**
+     * Check if a proper scheduler is available (i.e., Workers context is set).
+     */
+    isAvailable() {
+        return this.getScheduler().isAvailable();
+    },
+    /**
+     * Reset the scheduler (useful for testing).
+     */
+    reset() {
+        _executionContext = undefined;
+        _scheduler = undefined;
+    },
+});

package/src/tasks.d.ts

@@ -0,0 +1,2 @@
+export { BackgroundTaskScheduler } from './runtime/BackgroundTaskScheduler';
+//# sourceMappingURL=tasks.d.ts.map

package/src/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC"}

package/src/tasks.js

@@ -0,0 +1 @@
+export { BackgroundTaskScheduler } from './runtime/BackgroundTaskScheduler.js';

package/src/worker-runtime/drain.d.ts

@@ -0,0 +1,18 @@
+import type { WorkerModule } from './processor-registry';
+export type AppWorkerDefinition = Readonly<{
+    name: string;
+    queueName: string;
+    version: string;
+    autoStart: boolean;
+    activeStatus: boolean;
+    concurrency: number;
+    processorSpec: string;
+}>;
+/**
+ * Ensure a drain loop is running. Returns immediately. If a loop is already active this is
+ * a no-op (concurrent-PING guard). The returned promise resolves when the active loop ends
+ * and is suitable for `ctx.waitUntil`.
+ */
+export declare const ensureDraining: (appWorkerDefinitions: AppWorkerDefinition[], workerModules: ReadonlyArray<WorkerModule>) => Promise<void>;
+export declare const isDraining: () => boolean;
+//# sourceMappingURL=drain.d.ts.map

package/src/worker-runtime/drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/drain.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAgCvE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAsKH;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,sBAAsB,mBAAmB,EAAE,EAC3C,eAAe,aAAa,CAAC,YAAY,CAAC,KACzC,OAAO,CAAC,IAAI,CAUd,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,OAA+B,CAAC"}

package/src/worker-runtime/drain.js

@@ -0,0 +1,152 @@
+/**
+ * Worker drain loop.
+ *
+ * The Cloudflare Worker is not an always-on daemon, so it does not hold persistent BullMQ
+ * consumers. Instead it is woken by a PING (on enqueue, or by cron) and then drains
+ * available jobs: pull an atomically-claimed job over HTTP RPC, run the bundled processor,
+ * and ack/fail it back over RPC. The whole drain runs inside the Worker so it executes the
+ * app's real business logic with all bindings/code already bundled.
+ *
+ * A single drain loop runs at a time (guard). A PING that arrives while a loop is active is
+ * a no-op for the loop (the caller still gets an immediate ack).
+ */
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { isNullish } from '../helper/index.js';
+import { resolveProcessor } from './processor-registry.js';
+import { ackJob, failJob, isRedisRpcConfigured, listWorkers, pullJob, } from './rpc-client.js';
+let activeDrain = null;
+const sleep = async (ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms));
+const intEnv = (key, fallback) => {
+    const parsed = Number.parseInt(Env.get(key, '').trim(), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+/**
+ * Resolve which queues this Worker should drain: app manifest workers that have a bundled
+ * processor and are not disabled. The backend lifecycle registry is authoritative for
+ * start/stop — a worker explicitly `stopped` there is skipped; otherwise the manifest's
+ * `autoStart` decides.
+ */
+const resolveDrainTargets = async (appWorkerDefinitions, workerModules) => {
+    let statusByQueue = new Map();
+    try {
+        const registered = await listWorkers();
+        statusByQueue = new Map(registered
+            .filter((entry) => typeof entry.queueName === 'string' && entry.source === 'redis-rpc-registry')
+            .map((entry) => [entry.queueName, entry.status ?? 'stopped']));
+    }
+    catch (error) {
+        Logger.debug('[worker-runtime] worker registry unavailable; falling back to manifest autoStart', error);
+    }
+    const targets = [];
+    for (const definition of appWorkerDefinitions) {
+        if (definition.activeStatus === false)
+            continue;
+        if (!resolveProcessor(definition.processorSpec, workerModules))
+            continue;
+        const status = statusByQueue.get(definition.queueName);
+        const enabled = status === undefined ? definition.autoStart === true : status === 'running';
+        if (enabled) {
+            targets.push({ queueName: definition.queueName, processorSpec: definition.processorSpec });
+        }
+    }
+    return targets;
+};
+const toJob = (queueName, pulled) => {
+    return {
+        id: pulled.id,
+        name: pulled.name ?? 'default',
+        data: pulled.payload,
+        queueName,
+        attemptsMade: pulled.attempts,
+    };
+};
+const getDrainLoopConfig = () => ({
+    deadline: Date.now() + intEnv('WORKER_DRAIN_MAX_MS', 300_000),
+    idleSleepMs: intEnv('WORKER_DRAIN_IDLE_SLEEP_MS', 1_000),
+    maxIdleCycles: intEnv('WORKER_DRAIN_MAX_IDLE_CYCLES', 5),
+    visibilityTimeoutMs: intEnv('WORKER_DRAIN_VISIBILITY_MS', 30_000),
+});
+/** Pull and process a single job for a queue. Returns true if a job was handled. */
+const drainOneJob = async (target, visibilityTimeoutMs, workerModules) => {
+    const pulled = await pullJob(target.queueName, visibilityTimeoutMs);
+    if (!pulled)
+        return false;
+    const processor = resolveProcessor(target.processorSpec, workerModules);
+    if (!processor) {
+        await failJob(target.queueName, pulled.id, `No bundled processor for ${target.processorSpec}`);
+        return true;
+    }
+    try {
+        const returnValue = await processor(toJob(target.queueName, pulled));
+        await ackJob(target.queueName, pulled.id, returnValue);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        Logger.error('[worker-runtime] job processing failed', {
+            queue: target.queueName,
+            jobId: pulled.id,
+            reason,
+        });
+        await failJob(target.queueName, pulled.id, reason);
+    }
+    return true;
+};
+const drainTargetQueue = async (target, visibilityTimeoutMs, workerModules, deadline) => {
+    let handledCount = 0;
+    while (Date.now() < deadline) {
+        // eslint-disable-next-line no-await-in-loop
+        const handled = await drainOneJob(target, visibilityTimeoutMs, workerModules).catch((error) => {
+            Logger.warn('[worker-runtime] drainOneJob error', { queue: target.queueName, error });
+            return false;
+        });
+        if (!handled)
+            break;
+        handledCount += 1;
+    }
+    return handledCount;
+};
+const drainTargets = async (targets, visibilityTimeoutMs, workerModules, deadline) => {
+    const handledCounts = await Promise.all(targets.map(async (target) => drainTargetQueue(target, visibilityTimeoutMs, workerModules, deadline)));
+    return handledCounts.reduce((sum, handledCount) => sum + handledCount, 0);
+};
+const runDrainLoop = async (appWorkerDefinitions, workerModules) => {
+    if (!Env.getBool('WORKER_ENABLED', false) || !isRedisRpcConfigured()) {
+        return;
+    }
+    const { deadline, idleSleepMs, maxIdleCycles, visibilityTimeoutMs } = getDrainLoopConfig();
+    let idleCycles = 0;
+    while (Date.now() < deadline && idleCycles < maxIdleCycles) {
+        // eslint-disable-next-line no-await-in-loop
+        const targets = await resolveDrainTargets(appWorkerDefinitions, workerModules);
+        if (targets.length === 0)
+            break;
+        // eslint-disable-next-line no-await-in-loop
+        const handledThisCycle = await drainTargets(targets, visibilityTimeoutMs, workerModules, deadline);
+        if (handledThisCycle === 0) {
+            idleCycles += 1;
+            // eslint-disable-next-line no-await-in-loop
+            await sleep(idleSleepMs);
+            continue;
+        }
+        idleCycles = 0;
+    }
+};
+/**
+ * Ensure a drain loop is running. Returns immediately. If a loop is already active this is
+ * a no-op (concurrent-PING guard). The returned promise resolves when the active loop ends
+ * and is suitable for `ctx.waitUntil`.
+ */
+export const ensureDraining = async (appWorkerDefinitions, workerModules) => {
+    if (!isNullish(activeDrain))
+        return activeDrain;
+    activeDrain = runDrainLoop(appWorkerDefinitions, workerModules)
+        .catch((error) => {
+        Logger.error('[worker-runtime] drain loop crashed', error);
+    })
+        .finally(() => {
+        activeDrain = null;
+    });
+    return activeDrain;
+};
+export const isDraining = () => activeDrain !== null;

package/src/worker-runtime/install-enqueue-hook.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Registers the global post-enqueue hook that core `Queue.enqueue` invokes after a
+ * successful enqueue. Every enqueue then wakes the worker runtime (PING), so jobs are
+ * drained promptly instead of waiting for the next cron tick. `triggerWorkerPing` is itself
+ * gated (WORKER_ENABLED + Redis RPC configured) and honours `WAIT_FOR_PING`.
+ */
+import type { AppWorkerDefinition } from './drain';
+import type { WorkerModule } from './processor-registry';
+declare global {
+    var __zintrustQueueEnqueueHook: ((queue: string, jobId: unknown, driver: string) => unknown) | undefined;
+}
+/**
+ * Wire the app's bundled worker manifest and processor modules into the post-enqueue PING so
+ * the same-isolate drain loop can resolve which queues to drain and which processor to run.
+ */
+export declare const installQueueEnqueuePingHook: (appWorkerDefinitions: AppWorkerDefinition[], workerModules: ReadonlyArray<WorkerModule>) => void;
+//# sourceMappingURL=install-enqueue-hook.d.ts.map

package/src/worker-runtime/install-enqueue-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-enqueue-hook.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/install-enqueue-hook.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,0BAA0B,EAC1B,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,GAC5D,SAAS,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GACtC,sBAAsB,mBAAmB,EAAE,EAC3C,eAAe,aAAa,CAAC,YAAY,CAAC,KACzC,IAGF,CAAC"}

package/src/worker-runtime/install-enqueue-hook.js

@@ -0,0 +1,8 @@
+import { triggerWorkerPing } from './ping.js';
+/**
+ * Wire the app's bundled worker manifest and processor modules into the post-enqueue PING so
+ * the same-isolate drain loop can resolve which queues to drain and which processor to run.
+ */
+export const installQueueEnqueuePingHook = (appWorkerDefinitions, workerModules) => {
+    globalThis.__zintrustQueueEnqueueHook = async () => triggerWorkerPing(appWorkerDefinitions, workerModules);
+};

package/src/worker-runtime/ping.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Worker PING — wake + drain trigger.
+ *
+ * Producer side (`triggerWorkerPing`): called after a job is enqueued (and by cron). It
+ * wakes the worker runtime so jobs are drained promptly instead of waiting for the next
+ * cron tick.
+ *
+ * - Monolith / same isolate (no `WORKER_PING_URL`): start the local drain loop directly
+ *   via the background scheduler (`ctx.waitUntil`).
+ * - Split service (`WORKER_PING_URL` set): POST to the worker service's PING endpoint.
+ *
+ * `WAIT_FOR_PING` gates the producer: when `true` the producer awaits the PING *ack only*
+ * (worker-awake confirmation), never the job's completion; when false it is fire-and-forget.
+ *
+ * Endpoint side (`handlePing`): authenticates, schedules the drain loop on the background
+ * scheduler, and responds immediately with an awake ack. The concurrent-PING guard lives in
+ * `ensureDraining`, so overlapping pings never start duplicate loops.
+ */
+import { type AppWorkerDefinition } from './drain';
+import type { WorkerModule } from './processor-registry';
+type PingRequest = {
+    getHeader?: (name: string) => string | string[] | undefined;
+};
+type PingResponse = {
+    json: (body: unknown) => unknown;
+    setStatus: (status: number) => PingResponse;
+};
+/**
+ * Producer-side wake. Safe no-op when the worker runtime is disabled/unconfigured.
+ *
+ * `appWorkerDefinitions` / `workerModules` are the app's bundled worker manifest and
+ * statically-imported processor modules; they are only used in the same-isolate branch to
+ * start the local drain loop. In the split-service branch the wake is a remote PING and the
+ * worker service supplies its own definitions, so they are unused there.
+ */
+export declare const triggerWorkerPing: (appWorkerDefinitions: AppWorkerDefinition[], workerModules: ReadonlyArray<WorkerModule>) => Promise<void>;
+/** Endpoint-side handler: authenticate, start draining in the background, ack immediately. */
+export declare const handlePing: (req: PingRequest, res: PingResponse, appWorkerDefinitions: AppWorkerDefinition[], workerModules: ReadonlyArray<WorkerModule>) => void;
+export {};
+//# sourceMappingURL=ping.d.ts.map

package/src/worker-runtime/ping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/ping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAGvE,KAAK,WAAW,GAAG;IACjB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CAC7D,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IACjC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,YAAY,CAAC;CAC7C,CAAC;AAcF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAC5B,sBAAsB,mBAAmB,EAAE,EAC3C,eAAe,aAAa,CAAC,YAAY,CAAC,KACzC,OAAO,CAAC,IAAI,CA+Bd,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,UAAU,GACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,sBAAsB,mBAAmB,EAAE,EAC3C,eAAe,aAAa,CAAC,YAAY,CAAC,KACzC,IAaF,CAAC"}

package/src/worker-runtime/ping.js

@@ -0,0 +1,82 @@
+/**
+ * Worker PING — wake + drain trigger.
+ *
+ * Producer side (`triggerWorkerPing`): called after a job is enqueued (and by cron). It
+ * wakes the worker runtime so jobs are drained promptly instead of waiting for the next
+ * cron tick.
+ *
+ * - Monolith / same isolate (no `WORKER_PING_URL`): start the local drain loop directly
+ *   via the background scheduler (`ctx.waitUntil`).
+ * - Split service (`WORKER_PING_URL` set): POST to the worker service's PING endpoint.
+ *
+ * `WAIT_FOR_PING` gates the producer: when `true` the producer awaits the PING *ack only*
+ * (worker-awake confirmation), never the job's completion; when false it is fire-and-forget.
+ *
+ * Endpoint side (`handlePing`): authenticates, schedules the drain loop on the background
+ * scheduler, and responds immediately with an awake ack. The concurrent-PING guard lives in
+ * `ensureDraining`, so overlapping pings never start duplicate loops.
+ */
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { BackgroundTaskScheduler } from '../runtime/BackgroundTaskScheduler.js';
+import { ensureDraining, isDraining } from './drain.js';
+import { isRedisRpcConfigured } from './rpc-client.js';
+const getPingSecret = () => Env.get('WORKER_PING_SECRET', Env.get('REDIS_RPC_SECRET', Env.get('REDIS_PROXY_SECRET', Env.get('APP_KEY', '')))).trim();
+const headerValue = (req, name) => {
+    const raw = req.getHeader?.(name);
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' ? value.trim() : '';
+};
+/**
+ * Producer-side wake. Safe no-op when the worker runtime is disabled/unconfigured.
+ *
+ * `appWorkerDefinitions` / `workerModules` are the app's bundled worker manifest and
+ * statically-imported processor modules; they are only used in the same-isolate branch to
+ * start the local drain loop. In the split-service branch the wake is a remote PING and the
+ * worker service supplies its own definitions, so they are unused there.
+ */
+export const triggerWorkerPing = async (appWorkerDefinitions, workerModules) => {
+    if (!Env.getBool('WORKER_ENABLED', false) || !isRedisRpcConfigured()) {
+        return;
+    }
+    const url = Env.get('WORKER_PING_URL', '').trim();
+    if (url.length === 0) {
+        // Same isolate: wake the local drain loop in the background.
+        BackgroundTaskScheduler.schedule(ensureDraining(appWorkerDefinitions, workerModules));
+        return;
+    }
+    const secret = getPingSecret();
+    const ack = fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(secret ? { 'x-worker-ping-secret': secret } : {}),
+        },
+        body: JSON.stringify({ at: new Date().toISOString() }),
+    })
+        .then(() => undefined)
+        .catch((error) => {
+        Logger.warn('[worker-runtime] worker ping failed', error);
+    });
+    if (Env.getBool('WAIT_FOR_PING', false)) {
+        await ack; // wait for the awake ack only — never the job's completion
+    }
+    else {
+        BackgroundTaskScheduler.schedule(ack);
+    }
+};
+/** Endpoint-side handler: authenticate, start draining in the background, ack immediately. */
+export const handlePing = (req, res, appWorkerDefinitions, workerModules) => {
+    const expected = getPingSecret();
+    if (expected.length > 0 && headerValue(req, 'x-worker-ping-secret') !== expected) {
+        res.setStatus(401).json({ ok: false, error: 'Invalid worker ping secret' });
+        return;
+    }
+    if (!Env.getBool('WORKER_ENABLED', false) || !isRedisRpcConfigured()) {
+        res.json({ ok: true, status: 'disabled' });
+        return;
+    }
+    const alreadyDraining = isDraining();
+    BackgroundTaskScheduler.schedule(ensureDraining(appWorkerDefinitions, workerModules));
+    res.json({ ok: true, status: 'awake', alreadyDraining });
+};

package/src/worker-runtime/processor-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bundled processor registry.
+ *
+ * Cloudflare Workers cannot dynamically `import()` a file path at runtime — the module
+ * graph is frozen at build time. So the worker processor functions are statically
+ * imported here and exposed as a `processorSpec -> ZinTrustProcessor` map. The Redis RPC
+ * backend only stores the `processorSpec` string as metadata; this runtime resolves that
+ * string to the already-bundled function when it pulls a job.
+ */
+import type { Job } from 'bullmq';
+export type WorkerProcessor = (job: Job) => Promise<unknown>;
+export type WorkerModule = {
+    workerDefinition: {
+        processorSpec: string;
+    };
+    ZinTrustProcessor?: WorkerProcessor;
+    default?: WorkerProcessor;
+};
+export declare const resolveProcessor: (processorSpec: string, workerModules: ReadonlyArray<WorkerModule>) => WorkerProcessor | undefined;
+export declare const hasProcessor: (processorSpec: string, workerModules: ReadonlyArray<WorkerModule>) => boolean;
+export declare const listProcessorSpecs: (workerModules: ReadonlyArray<WorkerModule>) => string[];
+//# sourceMappingURL=processor-registry.d.ts.map

package/src/worker-runtime/processor-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor-registry.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/processor-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAElC,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7D,MAAM,MAAM,YAAY,GAAG;IACzB,gBAAgB,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B,CAAC;AAoBF,eAAO,MAAM,gBAAgB,GAC3B,eAAe,MAAM,EACrB,eAAe,aAAa,CAAC,YAAY,CAAC,KACzC,eAAe,GAAG,SAAgE,CAAC;AAEtF,eAAO,MAAM,YAAY,GACvB,eAAe,MAAM,EACrB,eAAe,aAAa,CAAC,YAAY,CAAC,KACzC,OAA8D,CAAC;AAElE,eAAO,MAAM,kBAAkB,GAAI,eAAe,aAAa,CAAC,YAAY,CAAC,KAAG,MAAM,EACjC,CAAC"}

package/src/worker-runtime/processor-registry.js

@@ -0,0 +1,24 @@
+/**
+ * Bundled processor registry.
+ *
+ * Cloudflare Workers cannot dynamically `import()` a file path at runtime — the module
+ * graph is frozen at build time. So the worker processor functions are statically
+ * imported here and exposed as a `processorSpec -> ZinTrustProcessor` map. The Redis RPC
+ * backend only stores the `processorSpec` string as metadata; this runtime resolves that
+ * string to the already-bundled function when it pulls a job.
+ */
+const buildRegistry = (workerModules) => {
+    const registry = new Map();
+    for (const mod of workerModules) {
+        const spec = mod.workerDefinition?.processorSpec;
+        const processor = mod.ZinTrustProcessor ?? mod.default;
+        if (typeof spec === 'string' && spec.trim().length > 0 && typeof processor === 'function') {
+            registry.set(spec, processor);
+        }
+    }
+    return registry;
+};
+const processorRegistry = (workerModules) => buildRegistry(workerModules);
+export const resolveProcessor = (processorSpec, workerModules) => processorRegistry(workerModules).get(processorSpec);
+export const hasProcessor = (processorSpec, workerModules) => processorRegistry(workerModules).has(processorSpec);
+export const listProcessorSpecs = (workerModules) => Array.from(processorRegistry(workerModules).keys());

package/src/worker-runtime/rpc-client.d.ts

@@ -0,0 +1,23 @@
+export type PulledJob = {
+    id: string;
+    name?: string;
+    payload: unknown;
+    attempts: number;
+};
+export declare const isRedisRpcConfigured: () => boolean;
+/** Atomically claim and pull the next waiting job for a queue, or undefined if none. */
+export declare const pullJob: (queueName: string, visibilityTimeoutMs: number) => Promise<PulledJob | undefined>;
+/** Mark a pulled job completed. */
+export declare const ackJob: (queueName: string, jobId: string, returnValue?: unknown) => Promise<void>;
+/** Mark a pulled job failed. */
+export declare const failJob: (queueName: string, jobId: string, reason: string) => Promise<void>;
+export type RegisteredWorker = {
+    workerName: string;
+    queueName: string;
+    status?: string;
+    processorSpec?: string | null;
+    source?: string;
+};
+/** List worker lifecycle records the backend holds (status running/stopped). */
+export declare const listWorkers: () => Promise<RegisteredWorker[]>;
+//# sourceMappingURL=rpc-client.d.ts.map

package/src/worker-runtime/rpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-client.d.ts","sourceRoot":"","sources":["../../../src/worker-runtime/rpc-client.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAOF,eAAO,MAAM,oBAAoB,QAAO,OAAkC,CAAC;AA6B3E,wFAAwF;AACxF,eAAO,MAAM,OAAO,GAClB,WAAW,MAAM,EACjB,qBAAqB,MAAM,KAC1B,OAAO,CAAC,SAAS,GAAG,SAAS,CAM/B,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,MAAM,GACjB,WAAW,MAAM,EACjB,OAAO,MAAM,EACb,cAAc,OAAO,KACpB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,OAAO,GAAU,WAAW,MAAM,EAAE,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAM5F,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,WAAW,QAAa,OAAO,CAAC,gBAAgB,EAAE,CAG9D,CAAC"}

package/src/worker-runtime/rpc-client.js

@@ -0,0 +1,59 @@
+/**
+ * Worker-native Redis RPC client.
+ *
+ * The Cloudflare Worker cannot open a raw TCP/ioredis connection reliably, so all Redis
+ * access goes over HTTP to the Redis RPC backend (`REDIS_RPC_URL`). This is the same
+ * `/rpc` envelope used by the worker dashboard.
+ */
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const getBaseUrl = () => Env.get('REDIS_RPC_URL', '').trim();
+const getSecret = () => Env.get('REDIS_RPC_SECRET', Env.get('REDIS_PROXY_SECRET', Env.get('APP_KEY', ''))).trim();
+export const isRedisRpcConfigured = () => getBaseUrl().length > 0;
+const call = async (service, method, payload = {}) => {
+    const baseUrl = getBaseUrl();
+    if (baseUrl.length === 0) {
+        throw ErrorFactory.createConfigError('REDIS_RPC_URL is not configured');
+    }
+    const secret = getSecret();
+    const response = await fetch(new URL('/rpc', baseUrl), {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(secret ? { 'x-redis-rpc-secret': secret } : {}),
+        },
+        body: JSON.stringify({ requestId: crypto.randomUUID(), service, method, payload }),
+    });
+    const parsed = (await response.json());
+    if (!response.ok || parsed.ok !== true) {
+        throw ErrorFactory.createConfigError(parsed.error?.message ?? `Redis RPC ${service}.${method} failed (${response.status})`);
+    }
+    return parsed.result;
+};
+/** Atomically claim and pull the next waiting job for a queue, or undefined if none. */
+export const pullJob = async (queueName, visibilityTimeoutMs) => {
+    const result = await call('queue', 'dequeue', {
+        queueName,
+        visibilityTimeoutMs,
+    });
+    return result ?? undefined;
+};
+/** Mark a pulled job completed. */
+export const ackJob = async (queueName, jobId, returnValue) => {
+    await call('queue', 'ack', { queueName, jobId, returnValue });
+};
+/** Mark a pulled job failed. */
+export const failJob = async (queueName, jobId, reason) => {
+    try {
+        await call('queue', 'fail', { queueName, jobId, reason });
+    }
+    catch (error) {
+        Logger.warn('[worker-runtime] failJob RPC failed', { queueName, jobId, error });
+    }
+};
+/** List worker lifecycle records the backend holds (status running/stopped). */
+export const listWorkers = async () => {
+    const result = await call('worker', 'list', {});
+    return Array.isArray(result) ? result : [];
+};

package/src/worker-runtime.d.ts

@@ -0,0 +1,5 @@
+export type { AppWorkerDefinition } from './worker-runtime/drain';
+export { installQueueEnqueuePingHook } from './worker-runtime/install-enqueue-hook';
+export { handlePing, triggerWorkerPing } from './worker-runtime/ping';
+export { hasProcessor, listProcessorSpecs, type WorkerModule, type WorkerProcessor, } from './worker-runtime/processor-registry';
+//# sourceMappingURL=worker-runtime.d.ts.map

package/src/worker-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-runtime.d.ts","sourceRoot":"","sources":["../../src/worker-runtime.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,oCAAoC,CAAC"}

package/src/worker-runtime.js

@@ -0,0 +1,3 @@
+export { installQueueEnqueuePingHook } from './worker-runtime/install-enqueue-hook.js';
+export { handlePing, triggerWorkerPing } from './worker-runtime/ping.js';
+export { hasProcessor, listProcessorSpecs, } from './worker-runtime/processor-registry.js';