@c9up/bay 0.1.12 → 0.1.13

package/README.md

@@ -11,9 +11,14 @@ pnpm add @c9up/bay
 ream configure @c9up/bay
 ```
 
+`ream add @c9up/bay` installs it, registers the provider and writes
+`config/queue.ts`. The rest of this page assumes that has run.
+
 ## Usage
 
-Register the provider in your app, then configure it under `config/queue.ts` — the provider reads `config.get('queue')`, so a `config/bay.ts` would be loaded under the key `bay` and never seen:
+Register the provider, then name the queue backend in `config/queue.ts` — the
+provider reads `config.get('queue')`, so a `config/bay.ts` would be loaded under
+the key `bay` and never seen:
 
 ```ts
 // reamrc.ts
@@ -22,6 +27,66 @@ providers: [
 ]
 ```
 
+```ts
+// config/queue.ts
+import { defineConfig, stores } from '@c9up/bay'
+import env from '#start/env'
+
+export default defineConfig({
+  default: env.get('QUEUE_STORE'),
+  stores: {
+    memory: stores.memory(),
+    redis:  stores.redis({ connection: 'main' }),
+  },
+})
+```
+
+```ts
+// start/queue.ts
+import queue from '@c9up/bay/services/main'
+
+queue.register('send-email', new SendEmailJob())
+await queue.dispatch('send-email', { to: 'user@example.com' })
+```
+
+| Store | Keeps jobs | Use it when |
+| --- | --- | --- |
+| `stores.memory()` | until the process exits | tests, and local work |
+| `stores.redis({ connection })` | in Redis | anything that must survive a restart |
+
+Factories are lazy: only the store actually selected is built, so naming a Redis
+queue in a config that runs in memory opens no connection. A `default` that
+names nothing throws, listing what exists — falling back to memory would look
+like it worked until a restart dropped every pending job.
+
+`stores.redis` takes a `@c9up/quasar` connection name, resolved at first use so
+bay never imports quasar, which stays an optional peer. Pass an ioredis-shaped
+client (or a function answering one) to use any other.
+
+## Delivery guarantee, and the one way to lose it
+
+A job the queue accepted gets run: `pop()` moves it from pending to processing
+in a single `LMOVE`, so a worker that dies mid-job leaves the job recoverable
+rather than gone.
+
+`LMOVE` needs **Redis 6.2 or later**. Without it the move is `lpop` then
+`rpush`, and a crash between the two deletes the job from pending before it
+reaches processing — nothing recovers it, because nothing knows it existed.
+That turns at-least-once delivery into at-most-once.
+
+So on an older Redis the driver **refuses to start in production**, and says
+which two ways out there are:
+
+```ts
+// Either upgrade the server, or state that losing a job is acceptable here:
+stores.redis({ connection: 'jobs', allowNonAtomicPop: true })
+```
+
+The opt-in is honoured and still logs a warning on every process that starts
+with it, naming production — agreeing once in a config file is not the same as
+being reminded, in the logs of an incident, that this is how the process was
+running. Outside production the fallback simply warns.
+
 ## Entry points
 
 - `@c9up/bay` — main API

package/dist/BayProvider.d.ts

@@ -1,3 +1,4 @@
+import type { QueueStoreFactory } from "./stores.js";
 /**
  * Slim, duck-typed host context — bay stays publishable without
  * importing `@c9up/ream`. Any framework that exposes a Container with
@@ -17,44 +18,37 @@ export interface BayAppContext {
 }
 export interface BayProviderConfig {
     /**
-     * Driver to bind by default. The provider only auto-wires `"memory"`
-     * (the default) — it has no Redis connection to build a `RedisDriver`
-     * from. For Redis, a custom driver, or a pre-built instance, wire
-     * `QueueManager` directly in your app's startup and skip the provider;
-     * the `services/main` singleton resolves whatever is registered.
-     * Passing anything other than `"memory"` throws at boot.
-     *
-     * Default `"memory"`.
+     * Which named store to use — a key of {@link stores}. Read from the
+     * environment in the generated config, so a deployment picks its queue
+     * backend without editing a file.
+     */
+    default?: string;
+    /**
+     * The queue stores this application can use, by name. Each is a factory
+     * from `stores.*`, built only when it is the one selected.
+     */
+    stores?: Record<string, QueueStoreFactory>;
+    /**
+     * The single-store form, kept for configs written against it: only
+     * `"memory"` was ever accepted. Prefer `default` + `stores`, which is how a
+     * pluggable backend is configured everywhere else and what lets the
+     * environment choose.
      */
     driver?: "memory";
 }
-/**
- * BayProvider — registers a default in-memory `QueueManager` in the
- * host container so apps that don't need custom driver wiring can
- * `import queue from '@c9up/bay/services/main'` and dispatch
- * straight away. Job handlers are still registered manually via
- * `queue.register(name, handler)` — that's intrinsic to the queue
- * design (handlers are app-defined, not config-driven).
- *
- * Apps with non-trivial wiring (Redis driver, custom queue config)
- * can ignore this provider and bind their own `QueueManager` instance
- * in the container; the `services/main` proxy resolves whatever is
- * registered.
- *
- *   // reamrc.ts
- *   providers: [() => import('@c9up/bay/provider')]
- *
- *   // start/queue.ts
- *   import queue from '@c9up/bay/services/main'
- *
- *   queue.register('send-email', new SendEmailJob())
- *   await queue.dispatch('send-email', { to: 'user@example.com' })
- */
 export default class BayProvider {
+    #private;
     protected app: BayAppContext;
     constructor(app: BayAppContext);
     register(): void;
     boot(): Promise<void>;
+    /**
+     * Stop the worker the app started, and let the job in flight finish.
+     *
+     * A worker polls on a timer. Left running, it survives a dev reload, a test
+     * teardown and a SIGTERM — so the old process keeps pulling jobs the new
+     * one is also pulling, and the same job runs twice.
+     */
     shutdown(): Promise<void>;
 }
 export {};

package/dist/BayProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BayProvider.d.ts","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,UAAU,YAAY;IACrB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AACD,UAAU,cAAc;IACvB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AACD,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;IACnB,SAAS,CAAC,GAAG,EAAE,aAAa;gBAAlB,GAAG,EAAE,aAAa;IAExC,QAAQ,IAAI,IAAI;IAiBV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAC/B"}
+{"version":3,"file":"BayProvider.d.ts","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;GAKG;AACH,UAAU,YAAY;IACrB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AACD,UAAU,cAAc;IACvB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AACD,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CAClB;AAoED,MAAM,CAAC,OAAO,OAAO,WAAW;;IACnB,SAAS,CAAC,GAAG,EAAE,aAAa;gBAAlB,GAAG,EAAE,aAAa;IAExC,QAAQ,IAAI,IAAI;IAaV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}

package/dist/BayProvider.js

@@ -1,6 +1,6 @@
 import { MemoryDriver } from "./drivers/MemoryDriver.js";
 import { QueueManager } from "./QueueManager.js";
-import { setQueue } from "./services/main.js";
+import { clearQueue, getQueue, setQueue } from "./services/main.js";
 /**
  * BayProvider — registers a default in-memory `QueueManager` in the
  * host container so apps that don't need custom driver wiring can
@@ -23,6 +23,40 @@ import { setQueue } from "./services/main.js";
  *   queue.register('send-email', new SendEmailJob())
  *   await queue.dispatch('send-email', { to: 'user@example.com' })
  */
+/**
+ * The driver the config asks for.
+ *
+ * `default` + `stores` first — the form an environment variable can steer. The
+ * `driver` key is the single-store form kept for configs written against it.
+ * Naming a store that does not exist throws rather than falling back to memory:
+ * an application that meant to queue in Redis and silently got an in-process
+ * queue would only find out when a restart dropped every pending job.
+ */
+function buildDriver(config) {
+    const stores = config?.stores;
+    const name = config?.default;
+    if (stores && name !== undefined) {
+        const selected = stores[name];
+        if (!selected) {
+            const known = Object.keys(stores);
+            throw new Error(`[bay] config.queue names the store '${name}', which is not in \`stores\`. ` +
+                (known.length > 0
+                    ? `Declared: ${known.join(", ")}.`
+                    : "`stores` is empty — declare one with stores.memory() or stores.redis()."));
+        }
+        return selected();
+    }
+    if (stores && name === undefined) {
+        throw new Error("[bay] config.queue declares `stores` but no `default` naming which one to use. " +
+            `Set default to one of: ${Object.keys(stores).join(", ")}.`);
+    }
+    const driverName = config?.driver ?? "memory";
+    if (driverName !== "memory") {
+        throw new Error(`[bay] Unsupported driver '${driverName}' — name it under \`stores\` instead: ` +
+            "stores: { redis: stores.redis({ connection: 'main' }) }.");
+    }
+    return new MemoryDriver();
+}
 export default class BayProvider {
     app;
     constructor(app) {
@@ -31,20 +65,35 @@ export default class BayProvider {
     register() {
         this.app.container.singleton(QueueManager, () => {
             const config = this.app.config.get("queue");
-            const driverName = config?.driver ?? "memory";
-            if (driverName !== "memory") {
-                throw new Error(`[bay] Unsupported driver '${driverName}' for default provider — ` +
-                    "wire QueueManager yourself in start/queue.ts for non-memory drivers.");
-            }
-            return new QueueManager(new MemoryDriver());
+            return new QueueManager(buildDriver(config));
         });
         this.app.container.singleton("queue", () => this.app.container.resolve(QueueManager));
     }
+    /** The queue THIS provider booted — not whatever the module singleton holds. */
+    #queue;
     async boot() {
         // Populate the `@c9up/bay/services/main` singleton so apps can
         // `import queue from '@c9up/bay/services/main'` from anywhere.
-        setQueue(await this.app.container.resolve(QueueManager));
+        this.#queue = await this.app.container.resolve(QueueManager);
+        setQueue(this.#queue);
+    }
+    /**
+     * Stop the worker the app started, and let the job in flight finish.
+     *
+     * A worker polls on a timer. Left running, it survives a dev reload, a test
+     * teardown and a SIGTERM — so the old process keeps pulling jobs the new
+     * one is also pulling, and the same job runs twice.
+     */
+    async shutdown() {
+        if (!this.#queue)
+            return;
+        await this.#queue.stop();
+        // Two applications can share a process — parallel tests, a hot reload.
+        // The module singleton holds whichever booted last, so it is only ours
+        // to clear while it still points at the queue this provider booted.
+        if (getQueue() === this.#queue)
+            clearQueue();
+        this.#queue = undefined;
     }
-    async shutdown() { }
 }
 //# sourceMappingURL=BayProvider.js.map

package/dist/BayProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"BayProvider.js","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAkC9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;IACT;IAAtB,YAAsB,GAAkB;QAAlB,QAAG,GAAH,GAAG,CAAe;IAAG,CAAC;IAE5C,QAAQ;QACP,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,EAAE;YAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,OAAO,CAAC,CAAC;YAC/D,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,IAAI,QAAQ,CAAC;YAC9C,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACd,6BAA6B,UAAU,2BAA2B;oBACjE,sEAAsE,CACvE,CAAC;YACH,CAAC;YACD,OAAO,IAAI,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAC1C,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CACtD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACT,+DAA+D;QAC/D,+DAA+D;QAC/D,QAAQ,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,QAAQ,KAAmB,CAAC;CAClC"}
+{"version":3,"file":"BayProvider.js","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA0CpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,MAAqC;IACzD,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,EAAE,OAAO,CAAC;IAE7B,IAAI,MAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAClC,MAAM,IAAI,KAAK,CACd,uCAAuC,IAAI,iCAAiC;gBAC3E,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;oBAChB,CAAC,CAAC,aAAa,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBAClC,CAAC,CAAC,yEAAyE,CAAC,CAC9E,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,EAAE,CAAC;IACnB,CAAC;IAED,IAAI,MAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACd,iFAAiF;YAChF,0BAA0B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC5D,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,IAAI,QAAQ,CAAC;IAC9C,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACd,6BAA6B,UAAU,wCAAwC;YAC9E,0DAA0D,CAC3D,CAAC;IACH,CAAC;IACD,OAAO,IAAI,YAAY,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,OAAO,OAAO,WAAW;IACT;IAAtB,YAAsB,GAAkB;QAAlB,QAAG,GAAH,GAAG,CAAe;IAAG,CAAC;IAE5C,QAAQ;QACP,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,EAAE;YAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,OAAO,CAAC,CAAC;YAC/D,OAAO,IAAI,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAC1C,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CACtD,CAAC;IACH,CAAC;IAED,gFAAgF;IAChF,MAAM,CAA2B;IAEjC,KAAK,CAAC,IAAI;QACT,+DAA+D;QAC/D,+DAA+D;QAC/D,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CAAC;QAC3E,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ;QACb,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACzB,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,IAAI,QAAQ,EAAE,KAAK,IAAI,CAAC,MAAM;YAAE,UAAU,EAAE,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IACzB,CAAC;CACD"}

package/dist/QueueManager.d.ts

@@ -62,7 +62,13 @@ export declare class QueueManager {
     recoverStale(): Promise<number>;
     /** Await the currently in-flight processOne, if any. */
     drain(): Promise<void>;
-    /** Stop the worker. */
+    /**
+     * Stop the worker and wait for it to actually be gone.
+     *
+     * Awaits the LOOP, not just the job in flight: a stop that returns while
+     * the loop is still sleeping leaves a worker running past the teardown that
+     * asked it to stop.
+     */
     stop(): Promise<void>;
     /** Get failed jobs. */
     failedJobs(): Promise<Job[]>;

package/dist/QueueManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"QueueManager.d.ts","sourceRoot":"","sources":["../src/QueueManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,qBAAa,YAAY;;gBAMZ,MAAM,EAAE,WAAW;IAI/B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,CAAC,UAAU,UAAU,CAAC,GAAG,IAAI;IAI1E,mCAAmC;IAC7B,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,CAAC;IAkBlB,yCAAyC;IACnC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IA2CpC;;;;;OAKG;IACG,IAAI,CAAC,cAAc,SAAO,EAAE,cAAc,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CzE;;;;;OAKG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAIrC,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,uBAAuB;IACjB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,uBAAuB;IACjB,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAIlC,sBAAsB;IAChB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG7B"}
+{"version":3,"file":"QueueManager.d.ts","sourceRoot":"","sources":["../src/QueueManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,qBAAa,YAAY;;gBAUZ,MAAM,EAAE,WAAW;IAI/B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,CAAC,UAAU,UAAU,CAAC,GAAG,IAAI;IAI1E,mCAAmC;IAC7B,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,CAAC;IAkBlB,yCAAyC;IACnC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IA2CpC;;;;;OAKG;IACG,IAAI,CAAC,cAAc,SAAO,EAAE,cAAc,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA6EzE;;;;;OAKG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAIrC,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,uBAAuB;IACjB,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAIlC,sBAAsB;IAChB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG7B"}

package/dist/QueueManager.js

@@ -10,6 +10,10 @@ export class QueueManager {
     #driver;
     #handlers = new Map();
     #running = false;
+    /** The running loop, so `stop()` can wait for it to finish. */
+    #loopPromise;
+    /** Cuts the sleep between polls short. */
+    #wake;
     #inflightPromise = null;
     constructor(driver) {
         this.#driver = driver;
@@ -89,19 +93,36 @@ export class QueueManager {
             throw new Error("QueueManager is already running");
         }
         this.#running = true;
+        const loop = this.#loop(pollIntervalMs, recoverStaleMs);
+        this.#loopPromise = loop;
+        try {
+            await loop;
+        }
+        finally {
+            this.#loopPromise = undefined;
+        }
+    }
+    /**
+     * The polling loop itself.
+     *
+     * Between jobs it sleeps, and that sleep is CANCELLABLE: `stop()` wakes it
+     * rather than waiting out the interval. Without that, stopping returned
+     * while the loop was still pending — up to a full poll interval of a worker
+     * that was supposed to be gone, and a timer holding the process open.
+     */
+    async #loop(pollIntervalMs, recoverStaleMs) {
         await this.#tryRecoverStale();
         let lastRecover = Date.now();
         while (this.#running) {
             try {
                 this.#inflightPromise = this.processOne();
                 const processed = await this.#inflightPromise;
-                if (!processed) {
-                    await new Promise((r) => setTimeout(r, pollIntervalMs));
-                }
+                if (!processed)
+                    await this.#sleep(pollIntervalMs);
             }
             catch (err) {
                 process.stderr.write(`QueueManager processOne error: ${err instanceof Error ? err.message : String(err)}\n`);
-                await new Promise((r) => setTimeout(r, pollIntervalMs));
+                await this.#sleep(pollIntervalMs);
             }
             finally {
                 this.#inflightPromise = null;
@@ -112,6 +133,20 @@ export class QueueManager {
             }
         }
     }
+    /** Wait, unless `stop()` says otherwise first. */
+    #sleep(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#wake = undefined;
+                resolve();
+            }, ms);
+            this.#wake = () => {
+                clearTimeout(timer);
+                this.#wake = undefined;
+                resolve();
+            };
+        });
+    }
     /** recoverStale() wrapper that swallows driver errors — used by the work loop. */
     async #tryRecoverStale() {
         try {
@@ -136,10 +171,19 @@ export class QueueManager {
             await this.#inflightPromise.catch(() => { });
         }
     }
-    /** Stop the worker. */
+    /**
+     * Stop the worker and wait for it to actually be gone.
+     *
+     * Awaits the LOOP, not just the job in flight: a stop that returns while
+     * the loop is still sleeping leaves a worker running past the teardown that
+     * asked it to stop.
+     */
     async stop() {
         this.#running = false;
+        this.#wake?.();
         await this.drain();
+        if (this.#loopPromise)
+            await this.#loopPromise.catch(() => { });
     }
     /** Get failed jobs. */
     async failedJobs() {

package/dist/QueueManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"QueueManager.js","sourceRoot":"","sources":["../src/QueueManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"QueueManager.js","sourceRoot":"","sources":["../src/QueueManager.ts"],"names":[],"mappings":"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"}

package/dist/configure.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `ream configure @c9up/bay` — wire the job queue in one command.
+ *
+ * The provider alone is not enough: it reads `config/queue.ts`, and a package
+ * registered without one falls back to a default that is rarely the one an
+ * application wants. Writing both together is what makes `ream add` mean
+ * installed AND working.
+ */
+interface Codemods {
+    addProvider(importPath: string): Promise<void>;
+    addEnvVars(vars: Record<string, string>): Promise<void>;
+    writeFile(filePath: string, content: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+}
+export declare function configure(codemods: Codemods): Promise<void>;
+export {};
+//# sourceMappingURL=configure.d.ts.map

package/dist/configure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,UAAU,QAAQ;IACjB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;CACjB;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBjE"}

package/dist/configure.js

@@ -0,0 +1,31 @@
+/**
+ * `ream configure @c9up/bay` — wire the job queue in one command.
+ *
+ * The provider alone is not enough: it reads `config/queue.ts`, and a package
+ * registered without one falls back to a default that is rarely the one an
+ * application wants. Writing both together is what makes `ream add` mean
+ * installed AND working.
+ */
+export async function configure(codemods) {
+    // The config below reads these, so they are declared here. Writing the file
+    // without them leaves an application whose config asks the environment for
+    // something nothing ever put there.
+    await codemods.addEnvVars({
+        QUEUE_STORE: "memory",
+    });
+    await codemods.addProvider("@c9up/bay/provider");
+    await codemods.writeFile("config/queue.ts", `import { defineConfig, stores } from '@c9up/bay'
+import env from '#start/env'
+
+export default defineConfig({
+  // Which store to run on. Memory forgets everything on restart, which is
+  // what a single process in development wants and nothing else does.
+  default: env.get('QUEUE_STORE', 'memory'),
+
+  stores: {
+    memory: stores.memory(),
+    redis: stores.redis({ connection: 'main' }),
+  },
+})`);
+}
+//# sourceMappingURL=configure.js.map

package/dist/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAkB;IACjD,4EAA4E;IAC5E,2EAA2E;IAC3E,oCAAoC;IACpC,MAAM,QAAQ,CAAC,UAAU,CAAC;QACzB,WAAW,EAAE,QAAQ;KACrB,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,WAAW,CAAC,oBAAoB,CAAC,CAAC;IACjD,MAAM,QAAQ,CAAC,SAAS,CACvB,iBAAiB,EACjB;;;;;;;;;;;;GAYC,CACD,CAAC;AACH,CAAC"}

package/dist/drivers/RedisDriver.d.ts

@@ -41,6 +41,12 @@ export declare class RedisDriver implements QueueDriver {
     constructor(source: RedisClientSource, options?: {
         prefix?: string;
         visibilityTimeoutMs?: number;
+        /**
+         * Accept the non-atomic pop on a Redis older than 6.2, in
+         * production. Off by default: losing an accepted job is a choice a
+         * deployment makes, not one a version check makes for it.
+         */
+        allowNonAtomicPop?: boolean;
     });
     push(job: Job): Promise<void>;
     pop(): Promise<Job | null>;

package/dist/drivers/RedisDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,CACL,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,OAAO,EACtB,EAAE,EAAE,MAAM,GAAG,OAAO,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACzC;AAcD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAC1B,WAAW,GACX,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AA6B9C,qBAAa,WAAY,YAAW,WAAW;;gBAsC7C,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE;IA8BtD,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7B,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAuC1B,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IA8D/B,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAexB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI7B"}
+{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,CACL,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,OAAO,EACtB,EAAE,EAAE,MAAM,GAAG,OAAO,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACzC;AAcD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAC1B,WAAW,GACX,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AAmD9C,qBAAa,WAAY,YAAW,WAAW;;gBAsC7C,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B;;;;WAIG;QACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC5B;IAkCI,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7B,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAkD1B,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IA8D/B,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAexB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI7B"}

package/dist/drivers/RedisDriver.js

@@ -17,6 +17,7 @@
  * { PX: ms }) does NOT satisfy this interface and would drop the lease TTL — it
  * needs a thin adapter.
  */
+import { inProduction } from "../nodeEnv.js";
 function isValidJob(obj) {
     if (typeof obj !== "object" || obj === null)
         return false;
@@ -33,13 +34,32 @@ function isValidJob(obj) {
  * has no client to inspect yet.
  */
 const warned = new WeakSet();
-function warnWithoutLmove(client) {
-    if (typeof client.lmove === "function" || warned.has(client))
+function checkLmove(client, allowNonAtomicPop) {
+    if (typeof client.lmove === "function")
+        return;
+    // A queue's whole promise is that a job it accepted gets run. Without LMOVE
+    // the pop is `lpop` then `rpush`, and a crash between the two deletes the
+    // job from pending before it reaches processing: nothing recovers it,
+    // because nothing knows it existed. That is a different product, and in
+    // production it must be asked for rather than fallen into.
+    if (inProduction() && !allowNonAtomicPop) {
+        throw new Error("[bay] this Redis client has no LMOVE (Redis < 6.2), so pop() would be a non-atomic lpop+rpush — " +
+            "a crash between the two loses the in-flight job, turning at-least-once delivery into at-most-once.\n" +
+            "  Upgrade to Redis 6.2 or later, or pass `allowNonAtomicPop: true` to state that losing a job is acceptable here.");
+    }
+    if (warned.has(client))
         return;
     warned.add(client);
+    // Said even when the deployment opted in: agreeing to lose a job once, in a
+    // config file, is not the same as being reminded that this process is
+    // running that way. The line has to be in the logs of the incident.
+    const optedIn = inProduction() && allowNonAtomicPop;
     console.warn("[bay] RedisDriver: client lacks LMOVE (Redis <6.2). pop() falls back to " +
         "a non-atomic lpop+rpush, downgrading delivery from at-least-once to " +
-        "at-most-once — a crash between the two commands loses the in-flight job.");
+        "at-most-once — a crash between the two commands loses the in-flight job." +
+        (optedIn
+            ? "\n  Running this way in PRODUCTION because allowNonAtomicPop was set."
+            : ""));
 }
 /**
  * A key prefix that ends in a separator.
@@ -67,7 +87,7 @@ export class RedisDriver {
             return this.#resolved;
         if (typeof this.#source !== "function") {
             this.#resolved = this.#source;
-            warnWithoutLmove(this.#resolved);
+            checkLmove(this.#resolved, this.#allowNonAtomicPop);
             return this.#resolved;
         }
         if (!this.#pending) {
@@ -75,7 +95,7 @@ export class RedisDriver {
             this.#pending = Promise.resolve(resolver())
                 .then((client) => {
                 this.#resolved = client;
-                warnWithoutLmove(client);
+                checkLmove(client, this.#allowNonAtomicPop);
                 return client;
             })
                 // Cleared on failure too. Clearing only on success left the
@@ -93,13 +113,15 @@ export class RedisDriver {
         // A client handed in directly can be checked now, so the warning keeps
         // landing at construction as it always did. A named connection has no
         // client yet — it is checked when the connection resolves.
-        if (typeof source !== "function")
-            warnWithoutLmove(source);
+        if (typeof source !== "function") {
+            checkLmove(source, options?.allowNonAtomicPop ?? false);
+        }
         // Normalised rather than documented: every key is built by concatenation
         // (`${prefix}pending`), so a prefix without a trailing separator yields
         // "myapppending" — unreadable, and able to collide with a neighbouring
         // prefix. Nothing warned, because nothing failed.
         this.#prefix = withSeparator(options?.prefix ?? "queue:");
+        this.#allowNonAtomicPop = options?.allowNonAtomicPop ?? false;
         const visibilityTimeout = options?.visibilityTimeoutMs ?? 30_000;
         // A non-positive / non-integer timeout makes pop()'s `SET … PX <ms>` fail
         // on a real Redis; the catch then removes the job from `processing` and
@@ -112,6 +134,7 @@ export class RedisDriver {
     }
     #pendingKey = () => `${this.#prefix}pending`;
     #processingKey = () => `${this.#prefix}processing`;
+    #allowNonAtomicPop = false;
     #failedKey = () => `${this.#prefix}failed`;
     #leaseKey = (jobId) => `${this.#prefix}lease:${jobId}`;
     async push(job) {
@@ -131,22 +154,31 @@ export class RedisDriver {
         }
         if (!raw)
             return null;
+        // Only a payload that can never be run is purged. Everything past this
+        // point is a REAL job that already sits in `processing`, and deleting
+        // it there is the one thing that loses it for good: it is gone from
+        // pending too, and recoverStale() scans processing, so nothing would
+        // ever find it again.
+        let parsed;
         try {
-            const parsed = JSON.parse(raw);
-            if (!isValidJob(parsed)) {
-                // Malformed payload — purge from `processing` so it can't sit
-                // there indefinitely as a poison pill. recoverStale() also
-                // catches survivors but pop()'s own move is the primary path.
-                await client.lrem(this.#processingKey(), 1, raw);
-                return null;
-            }
-            await client.set(this.#leaseKey(parsed.id), raw, "PX", String(this.#visibilityTimeout));
-            return parsed;
+            parsed = JSON.parse(raw);
         }
         catch {
+            // A poison pill: unparseable, and it would sit in processing
+            // forever blocking nothing but wasting every recovery pass.
+            await client.lrem(this.#processingKey(), 1, raw);
+            return null;
+        }
+        if (!isValidJob(parsed)) {
             await client.lrem(this.#processingKey(), 1, raw);
             return null;
         }
+        // A lease that cannot be written is a transient Redis failure, not a
+        // bad job. The error propagates and the job STAYS in processing with
+        // no lease, which is precisely the state recoverStale() puts back in
+        // pending — so the delivery guarantee survives the blip.
+        await client.set(this.#leaseKey(parsed.id), raw, "PX", String(this.#visibilityTimeout));
+        return parsed;
     }
     async complete(job) {
         const client = await this.#client();