@zizq-labs/zizq 0.1.0

package/dist/worker.js

@@ -0,0 +1,396 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * In-process worker that takes jobs from the Zizq server and dispatches
+ * them to a single handler function.
+ *
+ * The handler can either route jobs manually (e.g. via a `switch` on
+ * `job.type`) or use `buildHandler([...])` to build a dispatcher
+ * from an array of named `JobFunction`s.
+ *
+ * @example Function-based dispatch
+ * ```ts
+ * import { Client, Worker, buildHandler } from "@zizq-labs/zizq";
+ *
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = { queue: "emails" };
+ *
+ * async function generateReport(payload) { ... }
+ * generateReport.zizqOptions = { queue: "reports" };
+ *
+ * const client = new Client({ url: "http://localhost:7890" });
+ * const worker = new Worker({
+ *   client,
+ *   concurrency: 10,
+ *   handler: buildHandler([sendEmail, generateReport]),
+ * });
+ *
+ * // Blocks until stopped.
+ * await worker.run();
+ * ```
+ *
+ * @example Manual dispatch (low-level / cross-language)
+ * ```ts
+ * const worker = new Worker({
+ *   client,
+ *   queues: ["payments"],
+ *   concurrency: 5,
+ *   handler: async (job) => {
+ *     switch (job.type) {
+ *       case "charge_card": return chargeCard(job.payload);
+ *       case "send_receipt": return sendReceipt(job.payload);
+ *       default: throw new Error(`Unknown job type: ${job.type}`);
+ *     }
+ *   },
+ * });
+ *
+ * await worker.run();
+ * ```
+ *
+ * @example Graceful shutdown
+ * ```ts
+ * process.on("SIGTERM", () => worker.stop());
+ * ```
+ *
+ * @module
+ */
+import { ClientError, } from "./client.js";
+/**
+ * In-process worker that takes jobs from the Zizq server and dispatches them
+ * to registered handlers.
+ *
+ * Manages concurrency via a prefetch-based flow control model: the server
+ * sends up to `prefetch` unacknowledged jobs, and the worker processes
+ * up to `concurrency` of them concurrently using `Promise.race` to stay
+ * within the limit.
+ *
+ * Jobs that complete successfully are acknowledged automatically. Jobs that
+ * throw are reported as failures (with error message, type, and stack trace),
+ * and the server handles retry scheduling based on the backoff policy.
+ */
+export class Worker {
+    client;
+    concurrency;
+    prefetch;
+    queues;
+    logger;
+    retryInitialDelay;
+    retryMaxDelay;
+    retryMultiplier;
+    handler;
+    // Two abort controllers for a coordinated two-phase shutdown:
+    //   - `abortController` is the user-facing signal, fired by `stop()`.
+    //     When it fires, the worker begins draining in-flight jobs and
+    //     flushing acks while the take stream is still alive.
+    //   - `streamController` is the internal signal passed to the take
+    //     request. It is only aborted *after* the drain + flush completes,
+    //     so the server keeps jobs as in-flight during the drain and
+    //     accepts the acks before the connection closes.
+    //
+    // Reassigned fresh on every `run()` via `resetRuntimeState()`.
+    abortController = new AbortController();
+    streamController = new AbortController();
+    // Set of promises for currently in-flight `processJob` tasks. Exposed
+    // as an instance field so the shutdown listener can drain them.
+    inFlight = new Set();
+    // Promise representing the drain + flush + stream-abort sequence
+    // initiated by the shutdown listener. `run()` awaits this before
+    // returning so callers can observe any errors from the shutdown path.
+    shutdownPromise = Promise.resolve();
+    // Set to `true` when `kill()` is called. The drain loop in
+    // `startShutdown` checks this to bail out early, and `kill()` itself
+    // aborts `streamController` directly so the take loop exits without
+    // waiting for the drain.
+    //
+    // `killDeferred` is a promise that resolves when `kill()` is called.
+    // The drain loop races against it so it wakes up immediately on kill,
+    // otherwise a slow in-flight job could keep the drain loop blocked
+    // on `Promise.allSettled` for an unbounded amount of time.
+    killing = false;
+    killDeferred = Promise.withResolvers();
+    // Bulk ack batching buffer.
+    // Success acks are buffered and flushed in a single bulk request.
+    // The bulk ack is scheduled via queueMicrotask and only one bulk ack runs at
+    // a time. While a bulk ack request is in flight, new acks accumulate and
+    // are sent in the next batch.
+    pendingAcks = [];
+    ackFlushInFlight = false;
+    ackFlushPromise = Promise.resolve();
+    constructor(options) {
+        this.client = options.client;
+        this.handler = options.handler;
+        this.concurrency = options.concurrency ?? 1;
+        this.prefetch = options.prefetch ?? this.concurrency;
+        this.logger = options.logger ?? console;
+        this.retryInitialDelay = options.requestRetry?.initialDelay ?? 500;
+        this.retryMaxDelay = options.requestRetry?.maxDelay ?? 30_000;
+        this.retryMultiplier = options.requestRetry?.multiplier ?? 2;
+        this.queues = options.queues ?? [];
+    }
+    /**
+     * Start processing jobs. Blocks until {@link stop} is called.
+     *
+     * Opens a streaming connection to the server's take endpoint and
+     * dispatches incoming jobs to the registered handlers concurrently.
+     *
+     * Automatically reconnects with exponential backoff if the connection
+     * drops or the server is unreachable. The backoff is reset after a
+     * successful connection. Uses the `requestRetry` configuration.
+     *
+     * On shutdown, waits for all in-flight jobs to complete and flushes
+     * pending acks before returning.
+     *
+     * @example
+     * ```ts
+     * const worker = new Worker({ client, jobs: [sendEmail] });
+     *
+     * // In another context (e.g. signal handler):
+     * process.on("SIGTERM", () => worker.stop());
+     *
+     * // Blocks here until stopped.
+     * await worker.run();
+     * ```
+     */
+    async run() {
+        this.resetRuntimeState();
+        // When the user calls stop(), begin an async shutdown sequence:
+        // drain in-flight jobs, flush acks, then abort the stream. The
+        // stream stays alive during the drain so the server keeps jobs
+        // marked in-flight and accepts the acks.
+        this.abortController.signal.addEventListener("abort", () => this.startShutdown(), { once: true });
+        let attempt = 0;
+        while (!this.abortController.signal.aborted) {
+            this.streamController = new AbortController();
+            try {
+                const takeOpts = {
+                    prefetch: this.prefetch,
+                    queues: this.queues.length > 0 ? this.queues : undefined,
+                    signal: this.streamController.signal,
+                };
+                const stream = await this.client.take(takeOpts);
+                if (attempt > 0) {
+                    this.logger.info(`[zizq] reconnected to ${this.client.url}`);
+                }
+                else {
+                    this.logger.info(`[zizq] connected to ${this.client.url}`);
+                }
+                attempt = 0;
+                for await (const job of stream) {
+                    // Once stop() has been called, don't dispatch any more jobs.
+                    // The shutdown listener is draining in-flight and will abort
+                    // the stream when done. Keep reading so heartbeats flow and
+                    // the connection stays alive during the drain.
+                    if (this.abortController.signal.aborted)
+                        continue;
+                    const task = this.processJob(job).finally(() => {
+                        this.inFlight.delete(task);
+                    });
+                    this.inFlight.add(task);
+                    // If we've hit concurrency limit, wait for one to finish.
+                    if (this.inFlight.size >= this.concurrency) {
+                        await Promise.race(this.inFlight);
+                    }
+                }
+            }
+            catch (err) {
+                if (this.abortController.signal.aborted) {
+                    // Expected — stream aborted by the shutdown listener.
+                }
+                else if (err instanceof ClientError) {
+                    throw err;
+                }
+                else {
+                    attempt++;
+                    const delay = Math.min(this.retryInitialDelay * Math.pow(this.retryMultiplier, attempt - 1), this.retryMaxDelay);
+                    this.logger.error(`[zizq] disconnected from ${this.client.url} (attempt ${attempt}, reconnecting in ${delay}ms):`, err instanceof Error ? err.message : err);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+            }
+        }
+        // Wait for the shutdown sequence initiated by the listener to
+        // complete (drain + flush + stream abort).
+        await this.shutdownPromise;
+        this.logger.info("[zizq] worker stopped");
+    }
+    /**
+     * Reset all mutable runtime state so {@link run} can be called
+     * multiple times on the same Worker instance. Called from the top of
+     * {@link run}. Config (client, handler, concurrency, etc.) is
+     * preserved; only per-run state is wiped.
+     */
+    resetRuntimeState() {
+        this.abortController = new AbortController();
+        this.streamController = new AbortController();
+        this.inFlight = new Set();
+        this.shutdownPromise = Promise.resolve();
+        this.killing = false;
+        this.killDeferred = Promise.withResolvers();
+        this.pendingAcks = [];
+        this.ackFlushInFlight = false;
+        this.ackFlushPromise = Promise.resolve();
+    }
+    /**
+     * Async sequence triggered by the shutdown listener when `stop()` or
+     * `kill()` is called. On a graceful stop, drains in-flight jobs and
+     * flushes pending acks before aborting the take stream. On kill, the
+     * drain loop bails out early via the `killing` flag, any pending
+     * acks are dropped, and the stream is (already) aborted by `kill()`
+     * itself.
+     *
+     * The drain loop races `Promise.allSettled(inFlight)` against
+     * `killDeferred.promise` so that a `kill()` call mid-drain wakes the
+     * loop immediately, rather than having to wait for an in-flight
+     * handler to finish before noticing.
+     */
+    startShutdown() {
+        this.shutdownPromise = (async () => {
+            try {
+                // Drain in-flight jobs, bailing out early if kill() is called.
+                while (this.inFlight.size > 0 && !this.killing) {
+                    await Promise.race([
+                        Promise.allSettled([...this.inFlight]),
+                        this.killDeferred.promise,
+                    ]);
+                }
+                if (!this.killing) {
+                    // Graceful path: flush any pending acks while the stream is
+                    // still alive.
+                    await this.ackFlushPromise;
+                    await this.flushAcks();
+                }
+            }
+            finally {
+                // Abort the take stream. Idempotent — if kill() already aborted
+                // it, this call is a no-op.
+                this.streamController.abort();
+            }
+        })();
+    }
+    /**
+     * Request a graceful shutdown.
+     *
+     * Stops dispatching new jobs, waits for all in-flight job handlers to
+     * finish, flushes any pending acks, and then aborts the take stream.
+     * {@link run} returns once all of that has drained. `stop` is patient
+     * — there is no internal deadline. If you need to bound how long
+     * shutdown can take, use {@link kill} as an escalation.
+     *
+     * Callable any number of times; subsequent calls are no-ops.
+     */
+    stop() {
+        this.logger.info("[zizq] stopping worker...");
+        if (!this.abortController.signal.aborted) {
+            this.abortController.abort();
+        }
+    }
+    /**
+     * Force an immediate shutdown.
+     *
+     * Aborts the take stream right away and skips the drain + flush
+     * steps. Any in-flight job handlers that are already running will
+     * continue to completion. JavaScript can't cancel promises, but
+     * their acks will not be flushed, so the server will re-queue the
+     * corresponding jobs once the worker disconnects.
+     *
+     * Safe to call after `stop()` has already been called; this is the
+     * deadline-escalation path. A `stop()` drain that's been running too
+     * long will wake up immediately once `kill()` is called, and
+     * {@link run} returns shortly after.
+     */
+    kill() {
+        this.logger.info("[zizq] killing worker...");
+        this.killing = true;
+        // Wake the drain loop in startShutdown() if it's blocked on
+        // Promise.allSettled.
+        this.killDeferred.resolve();
+        // Close the stream immediately so the take loop exits.
+        this.streamController.abort();
+        // Trigger startShutdown if stop() hasn't been called yet.
+        if (!this.abortController.signal.aborted) {
+            this.abortController.abort();
+        }
+    }
+    /**
+     * Process a single job: dispatch to the handler, then ack or fail.
+     *
+     * Success acks are batched — the job ID is buffered and a flush is
+     * scheduled via `setImmediate`. This means the worker moves on to
+     * the next job immediately without waiting for the ack round-trip.
+     *
+     * Failures are reported individually (they carry per-job error details)
+     * and are retried on transient errors.
+     */
+    async processJob(job) {
+        try {
+            await this.handler(job);
+            this.scheduleAck(job.id);
+        }
+        catch (err) {
+            const failure = {
+                message: err instanceof Error ? err.message : String(err),
+                errorType: err instanceof Error ? err.constructor.name : undefined,
+                backtrace: err instanceof Error ? err.stack : undefined,
+            };
+            await this.withRetry(() => this.client.reportFailure(job.id, failure));
+        }
+    }
+    /**
+     * Buffer a success ack and schedule a flush.
+     *
+     * If a flush is already in flight, the ack simply accumulates in the
+     * buffer; it will be picked up when the current flush completes and
+     * schedules the next one.
+     */
+    scheduleAck(id) {
+        this.pendingAcks.push(id);
+        if (!this.ackFlushInFlight) {
+            this.ackFlushInFlight = true;
+            this.ackFlushPromise = new Promise((resolve) => {
+                setImmediate(() => this.flushAcks().then(resolve));
+            });
+        }
+    }
+    /**
+     * Send all buffered acks in a single bulk request.
+     *
+     * After the request completes (or fails with retry), if more acks have
+     * accumulated during the flush, schedule another flush immediately.
+     */
+    async flushAcks() {
+        while (this.pendingAcks.length > 0) {
+            const batch = this.pendingAcks;
+            this.pendingAcks = [];
+            await this.withRetry(() => this.client.reportSuccessBulk(batch));
+        }
+        this.ackFlushInFlight = false;
+    }
+    /**
+     * Retry an async operation with exponential backoff for transient errors.
+     *
+     * Client errors (4xx) are not retried — they indicate a permanent problem
+     * with the request. Connection errors and server errors (5xx) are retried
+     * indefinitely with exponential backoff. Retry timing is configured via
+     * `requestRetry` in `WorkerOptions`.
+     */
+    async withRetry(fn) {
+        let attempt = 0;
+        while (true) {
+            try {
+                await fn();
+                return;
+            }
+            catch (err) {
+                // Client errors (4xx) are not transient — don't retry.
+                if (err instanceof ClientError) {
+                    this.logger.error("[zizq] ack/nack rejected:", err.message);
+                    return;
+                }
+                attempt++;
+                const delay = Math.min(this.retryInitialDelay * Math.pow(this.retryMultiplier, attempt - 1), this.retryMaxDelay);
+                this.logger.error(`[zizq] ack/nack failed (attempt ${attempt}, retrying in ${delay}ms):`, err instanceof Error ? err.message : err);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@zizq-labs/zizq",
+  "version": "0.1.0",
+  "description": "Node.js client for the Zizq job queue server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types 'src/**/*.test.ts'"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "undici": "^8.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.8.0"
+  }
+}