@pikku/queue-nats 0.12.1

package/dist/nats-queue-service.js

@@ -0,0 +1,84 @@
+import { headers } from '@nats-io/nats-core';
+import { ATTEMPTS_HEADER, BACKOFF_DELAY_HEADER, BACKOFF_TYPE_HEADER, NATS_MSG_ID_HEADER, PIKKU_USER_ID_HEADER, attemptsHeaderValue, subjectForQueue, } from './utils.js';
+/**
+ * JetStream queue service for publishing jobs.
+ *
+ * Deliberately narrower than the pg-boss and bullmq services in two ways, both
+ * forced by the broker rather than by choice — see `supportsResults` and
+ * `getJob` below.
+ */
+export class NatsQueueService {
+    js;
+    subjectPrefix;
+    /**
+     * A work-queue stream deletes a message the moment it is acked, so there is
+     * nowhere for a result to live and nothing to read it back from. Producers
+     * that need a return value should use an RPC, not a queue.
+     */
+    supportsResults = false;
+    delayedPublisher;
+    constructor(js, subjectPrefix, delayedPublisher) {
+        this.js = js;
+        this.subjectPrefix = subjectPrefix;
+        this.delayedPublisher = delayedPublisher;
+    }
+    /**
+     * Attach the delayed publisher after construction. Needed because the pg-boss
+     * publisher republishes *through* this service, so the two reference each
+     * other and one of them has to be wired second.
+     */
+    setDelayedPublisher(publisher) {
+        this.delayedPublisher = publisher;
+    }
+    async add(queueName, data, options) {
+        const hdrs = headers();
+        if (options?.pikkuUserId) {
+            hdrs.set(PIKKU_USER_ID_HEADER, options.pikkuUserId);
+        }
+        // JetStream dedupes on this header within the stream's duplicate window,
+        // which is the closest equivalent to pg-boss's singleton `jobId`.
+        if (options?.jobId) {
+            hdrs.set(NATS_MSG_ID_HEADER, options.jobId);
+        }
+        // Retry policy travels with the job — see ATTEMPTS_HEADER. The worker
+        // enforces it; JetStream itself has no per-message equivalent.
+        if (options?.attempts !== undefined) {
+            hdrs.set(ATTEMPTS_HEADER, attemptsHeaderValue(options.attempts, queueName));
+        }
+        if (options?.backoff !== undefined) {
+            const backoff = typeof options.backoff === 'string'
+                ? { type: options.backoff }
+                : options.backoff;
+            hdrs.set(BACKOFF_TYPE_HEADER, backoff.type);
+            if (backoff.delay !== undefined) {
+                hdrs.set(BACKOFF_DELAY_HEADER, String(backoff.delay));
+            }
+        }
+        if (options?.delay) {
+            // Silently dropping this is not an option: `delay` is what backs
+            // workflow.sleep() and orchestrator backoff, so ignoring it turns a
+            // one-hour sleep into a zero-second one and an exponential backoff into a
+            // hot retry loop. `NatsServiceFactory` always wires a publisher, so this
+            // only fires for a hand-built service.
+            if (!this.delayedPublisher) {
+                throw new Error(`Queue "${queueName}" was given delay=${options.delay}ms but no delayedPublisher is configured. Construct NatsQueueService with a NatsDelayedPublisher (NatsServiceFactory does this for you) or enqueue without a delay.`);
+            }
+            return await this.delayedPublisher.publishAfter(queueName, data, options.delay, options);
+        }
+        const ack = await this.js.publish(subjectForQueue(this.subjectPrefix, queueName), JSON.stringify(data), { headers: hdrs });
+        // The stream sequence is the only broker-assigned identity a message has.
+        // It is unique per stream and monotonic, which is enough to correlate logs
+        // and telemetry — but note it is NOT the `jobId` the caller may have passed.
+        return String(ack.seq);
+    }
+    /**
+     * Not supported. A message in a work-queue stream is only reachable through a
+     * consumer, and only while it is being delivered — there is no lookup by id,
+     * and an acked message no longer exists. Returning null (rather than throwing)
+     * keeps callers that poll for optional status working; callers that genuinely
+     * need per-job state should read it from telemetry.
+     */
+    async getJob(_queueName, _jobId) {
+        return null;
+    }
+}

package/dist/nats-queue-worker.d.ts

@@ -0,0 +1,46 @@
+import type { ConsumerConfig, JetStreamClient, JetStreamManager } from '@nats-io/jetstream';
+import type { ConfigValidationResult, PikkuWorkerConfig, QueueConfigMapping, QueueWorkers } from '@pikku/core/queue';
+import type { Logger } from '@pikku/core/services';
+/**
+ * Map a pikku worker config onto a JetStream consumer config.
+ *
+ * The important line is `max_ack_pending`. It is the number of messages the
+ * server will let this consumer hold unacked at once — i.e. real per-message
+ * concurrency, where a slow message occupies exactly one of the N slots. It is
+ * NOT a batch size: nothing here ever hands several messages to one handler and
+ * waits for all of them, which is the shape that produces head-of-line blocking
+ * on a shared queue. Keep it that way.
+ */
+export declare const mapPikkuWorkerToNats: (workerConfig?: PikkuWorkerConfig) => Partial<ConsumerConfig>;
+/**
+ * JetStream queue worker implementation.
+ *
+ * Cron and delayed work are handled by `NatsSchedulerService`, which uses the
+ * server's own message scheduler (2.14+) rather than a database.
+ */
+export declare class NatsQueueWorkers implements QueueWorkers {
+    private readonly js;
+    private readonly jsm;
+    private readonly streamName;
+    private readonly subjectPrefix;
+    private readonly defaultConsumerConfig;
+    readonly name = "nats";
+    readonly supportsResults = false;
+    readonly configMappings: QueueConfigMapping;
+    private readonly activeConsumers;
+    constructor(js: JetStreamClient, jsm: JetStreamManager, streamName: string, subjectPrefix: string, defaultConsumerConfig?: Partial<ConsumerConfig>);
+    registerQueues(logger?: Logger): Promise<Record<string, ConfigValidationResult[]>>;
+    private handleMessage;
+    /** Stop consuming. In-flight handlers are left to settle their own acks. */
+    stop(): Promise<void>;
+    /**
+     * Stop consuming and wait for in-flight jobs to settle, up to `timeoutMs`
+     * across all queues. Returns the queues that did NOT finish in time.
+     *
+     * Use this on shutdown in preference to `stop()`. Without it a redeploy kills
+     * handlers mid-job, and every unacked message waits out `ack_wait` before
+     * being redelivered — safe, but slow, and it re-runs whatever side effects the
+     * handler had already performed.
+     */
+    drain(timeoutMs: number): Promise<string[]>;
+}

package/dist/nats-queue-worker.js

@@ -0,0 +1,199 @@
+import { AckPolicy, DeliverPolicy } from '@nats-io/jetstream';
+import { QueueJobDiscardedError, QueueJobFailedError, registerQueueWorkers, runQueueJob, } from '@pikku/core/queue';
+import { pikkuState } from '@pikku/core/state';
+import { attemptsFor, backoffFor, mapJsMsgToQueueJob } from './utils.js';
+import { consumeQueue } from './consume.js';
+const MS_TO_NS = 1_000_000;
+/**
+ * Default abandonment timeout, used when a worker declares no `lockDuration`.
+ *
+ * Matches pg-boss's `expire_seconds` default of 900s. This MUST be set
+ * explicitly: JetStream's own default `ack_wait` is 30s, so leaving it unset
+ * silently shortens the abandonment timeout 30x versus pg-boss, and any job
+ * running longer than 30s — a workflow orchestrator that polls, say — is
+ * redelivered while it is still running and executed a second time.
+ */
+const DEFAULT_ACK_WAIT_MS = 900_000;
+/**
+ * Map a pikku worker config onto a JetStream consumer config.
+ *
+ * The important line is `max_ack_pending`. It is the number of messages the
+ * server will let this consumer hold unacked at once — i.e. real per-message
+ * concurrency, where a slow message occupies exactly one of the N slots. It is
+ * NOT a batch size: nothing here ever hands several messages to one handler and
+ * waits for all of them, which is the shape that produces head-of-line blocking
+ * on a shared queue. Keep it that way.
+ */
+export const mapPikkuWorkerToNats = (workerConfig) => {
+    const config = {
+        ack_policy: AckPolicy.Explicit,
+        deliver_policy: DeliverPolicy.All,
+        max_ack_pending: workerConfig?.batchSize ?? 10,
+    };
+    // Unlike pg-boss (where expiry is a fixed ceiling from job start), JetStream
+    // redelivers purely on ack_wait — so this doubles as the abandonment timeout.
+    // It must exceed the longest a handler can legitimately run, or a still-running
+    // job gets redelivered and executed twice. Always set, never left to the
+    // server default — see DEFAULT_ACK_WAIT_MS.
+    config.ack_wait =
+        (workerConfig?.lockDuration ?? DEFAULT_ACK_WAIT_MS) * MS_TO_NS;
+    return config;
+};
+/**
+ * JetStream queue worker implementation.
+ *
+ * Cron and delayed work are handled by `NatsSchedulerService`, which uses the
+ * server's own message scheduler (2.14+) rather than a database.
+ */
+export class NatsQueueWorkers {
+    js;
+    jsm;
+    streamName;
+    subjectPrefix;
+    defaultConsumerConfig;
+    name = 'nats';
+    supportsResults = false;
+    configMappings = {
+        supported: {
+            batchSize: {
+                queueProperty: 'max_ack_pending',
+                description: 'Number of messages this consumer may hold unacked at once — per-message concurrency',
+            },
+            lockDuration: {
+                queueProperty: 'ack_wait',
+                transform: (value) => value * MS_TO_NS,
+                description: 'How long the server waits for an ack before redelivering (converted from ms to ns)',
+            },
+        },
+        unsupported: {
+            name: {
+                reason: 'Worker names are not supported in JetStream',
+                explanation: 'Consumers are identified by their durable name, which is derived from the queue name',
+            },
+            autorun: {
+                reason: 'Autorun is not configurable',
+                explanation: 'Consumers begin pulling as soon as they are registered',
+            },
+            drainDelay: {
+                reason: 'Drain delay is not configurable in JetStream',
+                explanation: 'Shutdown is handled by stopping consumption and letting in-flight acks settle',
+            },
+            pollInterval: {
+                reason: 'Pull consumers are not timer-driven',
+                explanation: 'The server pushes messages to a waiting pull request as they arrive, so there is no poll interval to tune',
+            },
+            groupConcurrency: {
+                reason: 'JetStream has no per-group fairness primitive',
+                explanation: 'Fairness across groups would need either a stream per group or application-side accounting',
+            },
+        },
+        fallbacks: {
+            removeOnComplete: {
+                reason: 'Work-queue streams delete messages on ack',
+                explanation: 'A completed message is removed from the stream immediately, so there is no retention to configure',
+                fallbackValue: 'Always removed on ack',
+            },
+            removeOnFail: {
+                reason: 'Exhausted messages leave via max_deliver, not retention',
+                explanation: 'A message that exceeds max_deliver raises a MAX_DELIVERIES advisory and is dropped from the stream',
+                fallbackValue: 'Managed by max_deliver',
+            },
+        },
+    };
+    activeConsumers = new Map();
+    constructor(js, jsm, streamName, subjectPrefix, defaultConsumerConfig = {}) {
+        this.js = js;
+        this.jsm = jsm;
+        this.streamName = streamName;
+        this.subjectPrefix = subjectPrefix;
+        this.defaultConsumerConfig = defaultConsumerConfig;
+    }
+    async registerQueues(logger) {
+        if (!logger) {
+            logger = pikkuState(null, 'package', 'singletonServices')?.logger;
+        }
+        if (!logger) {
+            throw new Error('Logger is required for registerQueues — pass it explicitly or ensure singleton services are initialized first');
+        }
+        const log = logger;
+        return await registerQueueWorkers(this.configMappings, log, async (queueName, processor) => {
+            const handle = await consumeQueue({
+                js: this.js,
+                jsm: this.jsm,
+                streamName: this.streamName,
+                subjectPrefix: this.subjectPrefix,
+                queueName,
+                config: {
+                    ...this.defaultConsumerConfig,
+                    ...mapPikkuWorkerToNats(processor.config),
+                },
+                handler: (msg) => this.handleMessage(queueName, msg, log),
+                logger: log,
+            });
+            this.activeConsumers.set(queueName, handle);
+        });
+    }
+    async handleMessage(queueName, msg, logger) {
+        try {
+            await runQueueJob({ job: mapJsMsgToQueueJob(queueName, msg) });
+            msg.ack();
+        }
+        catch (error) {
+            if (error instanceof QueueJobDiscardedError) {
+                // Permanently done, do not redeliver — the JetStream equivalent of
+                // pg-boss completing a job in order to discard it.
+                logger.info(`NATS message ${msg.seq} on ${queueName} discarded: ${error.message}`);
+                msg.term();
+                return;
+            }
+            const message = error instanceof QueueJobFailedError || error instanceof Error
+                ? error.message
+                : 'Unknown error';
+            // Enforce the job's own retry policy. This CANNOT be left to the consumer:
+            // `attempts` is per-job (the workflow engine sets it per step, and uses 1
+            // to mean "never retry"), while max_deliver is per-consumer — and an unset
+            // max_deliver means unlimited, so without this a step marked no-retry
+            // would be redelivered forever.
+            const attempts = attemptsFor(msg);
+            if (attempts !== undefined && msg.info.deliveryCount >= attempts) {
+                logger.error(`NATS message ${msg.seq} on ${queueName} failed after ${msg.info.deliveryCount}/${attempts} attempts, giving up: ${message}`);
+                msg.term();
+                return;
+            }
+            const delayMs = backoffFor(msg);
+            logger.error(`NATS message ${msg.seq} on ${queueName} failed (attempt ${msg.info.deliveryCount}${attempts ? `/${attempts}` : ''}), retrying in ${delayMs}ms: ${message}`);
+            // nak(delay) is what makes backoff real. A bare nak() redelivers as fast
+            // as the server can, which turns an exponential-backoff policy into a hot
+            // loop against whatever is already failing.
+            msg.nak(delayMs);
+        }
+    }
+    /** Stop consuming. In-flight handlers are left to settle their own acks. */
+    async stop() {
+        for (const handle of this.activeConsumers.values()) {
+            handle.stop();
+        }
+        this.activeConsumers.clear();
+    }
+    /**
+     * Stop consuming and wait for in-flight jobs to settle, up to `timeoutMs`
+     * across all queues. Returns the queues that did NOT finish in time.
+     *
+     * Use this on shutdown in preference to `stop()`. Without it a redeploy kills
+     * handlers mid-job, and every unacked message waits out `ack_wait` before
+     * being redelivered — safe, but slow, and it re-runs whatever side effects the
+     * handler had already performed.
+     */
+    async drain(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        const entries = [...this.activeConsumers.entries()];
+        this.activeConsumers.clear();
+        // Drained concurrently, not in sequence: one slow queue must not eat the
+        // whole budget and leave the rest no time at all.
+        const results = await Promise.all(entries.map(async ([queueName, handle]) => {
+            const drained = await handle.drain(Math.max(0, deadline - Date.now()));
+            return drained ? null : queueName;
+        }));
+        return results.filter((name) => name !== null);
+    }
+}

package/dist/nats-scheduler-service.d.ts

@@ -0,0 +1,156 @@
+import type { JetStreamClient, JetStreamManager } from '@nats-io/jetstream';
+import type { CoreUserSession } from '@pikku/core/types';
+import type { ScheduledTaskInfo, ScheduledTaskSummary } from '@pikku/core/services';
+import { SchedulerService } from '@pikku/core/services';
+/**
+ * Split a crontab expression into the schedule NATS wants and the timezone it
+ * was written in.
+ *
+ * The timezone has to come out of the expression because pikku's
+ * `CoreScheduledTask` has no timezone field — the cron string is the only place
+ * an author can say what zone they meant, and `TZ=`/`CRON_TZ=` is how crontab
+ * has always said it. It cannot be left in place either: NATS carries the zone
+ * in a header, and a prefix left in the expression lands in the seconds field,
+ * where it is rejected outright (`TZ=... 0 3 * * *`) or, from a 4-field
+ * expression, silently shifts every field along.
+ */
+export declare const parseNatsSchedule: (cronExpr: string) => {
+    schedule: string;
+    timezone?: string;
+};
+/**
+ * Translate a 5-field crontab expression into the 6-field form NATS requires.
+ *
+ * NATS cron is seconds-first and rejects anything that is not exactly 6 fields.
+ * Pikku's `wireScheduler` schedules are ordinary 5-field crontab, so the
+ * leading `0` is added here rather than pushed onto every task definition.
+ *
+ * A `TZ=`/`CRON_TZ=` prefix is stripped, since it belongs in a header rather
+ * than in the expression — use `parseNatsSchedule` to get the zone as well.
+ */
+export declare const toNatsCron: (cronExpr: string) => string;
+/**
+ * Scheduler backed by JetStream's own message scheduler (server 2.14+).
+ *
+ * Mirrors `PgBossSchedulerService`, with the schedules living in the broker
+ * instead of a `pgboss.schedule` table. A schedule *is* a retained message on a
+ * reserved subject: publishing registers it, republishing to the same subject
+ * replaces it, and purging the subject cancels it. The server then produces the
+ * message body onto `Nats-Schedule-Target` on each occurrence, where an
+ * ordinary consumer picks it up.
+ *
+ * Two behaviours differ from a database-backed scheduler, both deliberate:
+ *
+ *  - A missed occurrence is skipped, not caught up. This matches pg-boss, whose
+ *    cron monitor only fires a schedule whose previous occurrence is under a
+ *    minute old — so an instance that was down over an occurrence has always
+ *    dropped it rather than replaying it.
+ *  - There is no job history. A WorkQueue stream deletes a message on ack, so
+ *    "did this task run" comes from telemetry, not from the broker.
+ */
+export declare class NatsSchedulerService extends SchedulerService {
+    private readonly js;
+    private readonly jsm;
+    private readonly streamName;
+    private readonly subjectPrefix;
+    /**
+     * Zone for tasks that do not name one themselves. Applies to every task
+     * without a `TZ=` prefix; absent means the server's own zone, which is UTC
+     * unless it was configured otherwise.
+     */
+    private readonly defaultTimezone?;
+    private consumer?;
+    /**
+     * Tasks whose schedule could not be registered on the last `start()`, by name.
+     *
+     * A schedule that fails to register is the worst failure this service has:
+     * every other task keeps firing, so the service and the process both look
+     * healthy while one task silently never runs. Kept so a caller can assert on
+     * it — a health check, or a boot that would rather fail than run degraded.
+     */
+    readonly failedSchedules: Map<string, string>;
+    constructor(js: JetStreamClient, jsm: JetStreamManager, streamName: string, subjectPrefix: string, 
+    /**
+     * Zone for tasks that do not name one themselves. Applies to every task
+     * without a `TZ=` prefix; absent means the server's own zone, which is UTC
+     * unless it was configured otherwise.
+     */
+    defaultTimezone?: string | undefined);
+    /** No-op: the connection and stream are owned by NatsServiceFactory. */
+    init(): Promise<void>;
+    /**
+     * Schedule a one-off delayed RPC.
+     *
+     * The returned task id is the schedule's own subject, which is what makes
+     * `unschedule` and `getTask` exact — there is no id to look up, the subject
+     * *is* the handle. `@at` schedules are purged by the server once they fire,
+     * so a fired task simply stops being findable.
+     */
+    scheduleRPC(delay: number | string, rpcName: string, data?: any, session?: CoreUserSession): Promise<string>;
+    /**
+     * Cancel a scheduled task. Idempotent — purging a subject that holds no
+     * message is not an error, so cancelling a task that already fired returns
+     * false rather than throwing.
+     */
+    unschedule(taskId: string): Promise<boolean>;
+    getTask(taskId: string): Promise<ScheduledTaskInfo | null>;
+    /**
+     * List every schedule this service owns.
+     *
+     * Unlike the pg-boss implementation — which returned an empty array because
+     * pg-boss has no cheap way to enumerate pending jobs — this is exact: the
+     * stream's subject list *is* the set of live schedules, so one
+     * `subjects_filter` call answers it. That listing is also what prunes
+     * orphans in `start()`.
+     */
+    getAllTasks(): Promise<ScheduledTaskSummary[]>;
+    /** No-op: the connection is owned by NatsServiceFactory. */
+    close(): Promise<void>;
+    /**
+     * Register every code-declared recurring task with the broker and start
+     * consuming their fires.
+     *
+     * Rewriting all schedules on every boot is the point, not waste: a schedule
+     * lives in the broker and the code is the only source of truth for what
+     * should exist, so republishing reconciles a changed cron expression, and the
+     * prune below reconciles a deleted task. Without the prune a task removed
+     * from code would keep firing forever onto a queue whose handler no longer
+     * recognises it — the NATS-side version of the pg-boss bug where a removed
+     * task flooded a queue with stuck jobs.
+     */
+    start(): Promise<void>;
+    /**
+     * Deregister every recurring schedule and drop the fires already queued.
+     *
+     * A runner that drives crons some other way has to call this, because a
+     * schedule lives in the broker rather than in the process: one left behind by
+     * an earlier deployment keeps firing on time into a queue nothing consumes,
+     * and on a work-queue stream those fires are never reclaimed. `start()`
+     * re-registers everything it owns, so a runner that does drive crons here can
+     * call this first at no cost.
+     */
+    pruneAll(): Promise<number>;
+    /**
+     * Stop consuming fires, leaving the schedules registered.
+     *
+     * Deliberately not symmetric with `start()`: the pg-boss implementation
+     * unscheduled everything on stop, which meant a rolling deploy briefly had no
+     * schedules at all and any occurrence in that window was lost. Schedules are
+     * shared state that outlive one instance; only the consumer is per-instance.
+     */
+    stop(): Promise<void>;
+    /** Run one recurring fire. Owns the message's terminal call — `consumeQueue`
+     *  launches handlers without awaiting them, so it cannot ack on their behalf. */
+    private runFire;
+    /** Stable schedule subject for a code-declared recurring task. */
+    private recurringSubjectFor;
+    /** Guards against a caller passing an id from some other scheduler, which
+     *  would otherwise purge an arbitrary subject in this stream. */
+    private ownsSubject;
+    /**
+     * Subjects currently holding a schedule, optionally narrowed to one queue.
+     * `subjects_filter` makes the server return its per-subject message counts,
+     * which for schedule subjects is exactly the live schedule set.
+     */
+    private scheduleSubjects;
+}