queasy 0.2.0 → 0.3.0

package/fuzztest/handlers/cascade-b.js

@@ -0,0 +1,72 @@
+/**
+ * cascade-b handler — terminal handler, dispatches no further jobs.
+ * Subject to all chaos behaviors.
+ */
+
+import { BroadcastChannel } from 'node:worker_threads';
+import { createClient } from 'redis';
+import { PermanentError } from '../../src/index.js';
+import { pickChaos } from '../shared/chaos.js';
+import { emitEvent } from '../shared/stream.js';
+
+const eventRedis = createClient();
+await eventRedis.connect();
+
+const crashChannel = new BroadcastChannel('fuzz-crash');
+
+/**
+ * @param {any} data
+ * @param {import('../../src/types.js').Job} job
+ */
+export async function handle(_data, job) {
+    const startedAt = Date.now();
+    await emitEvent(eventRedis, {
+        type: 'start',
+        queue: '{fuzz}:cascade-b',
+        id: job.id,
+        pid: String(process.pid),
+        runAt: String(job.runAt),
+        startedAt: String(startedAt),
+    });
+
+    const chaos = pickChaos();
+    await emitEvent(eventRedis, {
+        type: 'chaos',
+        queue: '{fuzz}:cascade-b',
+        id: job.id,
+        chaos,
+    });
+
+    if (chaos === 'crash') {
+        crashChannel.postMessage({ type: 'crash' });
+        // Stall so the process exits before we return
+        await new Promise(() => {});
+    }
+
+    if (chaos === 'stall') {
+        await new Promise(() => {});
+    }
+
+    if (chaos === 'spin') {
+        const end = Date.now() + 10_000;
+        while (Date.now() < end) {
+            /* busy wait */
+        }
+    }
+
+    if (chaos === 'permanent') {
+        throw new PermanentError('cascade-b: permanent chaos');
+    }
+
+    if (chaos === 'retriable') {
+        throw new Error('cascade-b: retriable chaos');
+    }
+
+    // Normal completion
+    await emitEvent(eventRedis, {
+        type: 'finish',
+        queue: '{fuzz}:cascade-b',
+        id: job.id,
+        finishedAt: String(Date.now()),
+    });
+}

package/fuzztest/handlers/fail-handler.js

@@ -0,0 +1,52 @@
+/**
+ * Fail handler — invoked for every job that exhausts retries/stalls on any queue.
+ *
+ * Received data: [originalJobId, originalData, errorObject]
+ *
+ * For periodic jobs (id starts with 'fuzz-periodic-'), re-dispatches the job
+ * so that periodic jobs keep running indefinitely even after permanent failure.
+ * For cascade jobs, simply records the failure.
+ */
+
+import { createClient } from 'redis';
+import { Client } from '../../src/index.js';
+import { emitEvent } from '../shared/stream.js';
+
+const redis = createClient();
+const eventRedis = createClient();
+
+await redis.connect();
+await eventRedis.connect();
+
+// Dispatch-only queasy client (await ready to avoid Function not found race)
+const client = await new Promise((resolve) => new Client(redis, 0, resolve));
+
+// Queue references (keys already include braces)
+const periodicQueue = client.queue('{fuzz}:periodic', true);
+
+/**
+ * @param {[string, any, {message: string}]} data
+ * @param {import('../../src/types.js').Job} job
+ */
+export async function handle(data, job) {
+    const [originalId, originalData, error] = data;
+
+    await emitEvent(eventRedis, {
+        type: 'fail',
+        queue: 'fail',
+        id: originalId,
+        failJobId: job.id,
+        error: error?.message ?? String(error),
+    });
+
+    // Re-dispatch periodic jobs so they continue indefinitely.
+    if (originalId.startsWith('fuzz-periodic-')) {
+        const delay = 1000 + Math.random() * 4000;
+        await periodicQueue.dispatch(originalData, {
+            id: originalId,
+            runAt: Date.now() + delay,
+            updateRunAt: true,
+            updateData: true,
+        });
+    }
+}

package/fuzztest/handlers/periodic.js

@@ -0,0 +1,93 @@
+/**
+ * periodic handler — re-queues itself with the same job ID so it fires indefinitely.
+ * Also dispatches cascade-a jobs on normal completion.
+ * Subject to all chaos behaviors.
+ */
+
+import { BroadcastChannel } from 'node:worker_threads';
+import { createClient } from 'redis';
+import { Client, PermanentError } from '../../src/index.js';
+import { pickChaos } from '../shared/chaos.js';
+import { emitEvent } from '../shared/stream.js';
+
+const redis = createClient();
+const eventRedis = createClient();
+
+await redis.connect();
+await eventRedis.connect();
+
+// Dispatch-only queasy client (await ready to avoid Function not found race)
+const client = await new Promise((resolve) => new Client(redis, 0, resolve));
+const periodicQueue = client.queue('{fuzz}:periodic', true);
+const cascadeAQueue = client.queue('{fuzz}:cascade-a', true);
+
+const crashChannel = new BroadcastChannel('fuzz-crash');
+
+/**
+ * @param {any} data
+ * @param {import('../../src/types.js').Job} job
+ */
+export async function handle(data, job) {
+    const startedAt = Date.now();
+    await emitEvent(eventRedis, {
+        type: 'start',
+        queue: '{fuzz}:periodic',
+        id: job.id,
+        pid: String(process.pid),
+        runAt: String(job.runAt),
+        startedAt: String(startedAt),
+    });
+
+    const chaos = pickChaos();
+    await emitEvent(eventRedis, {
+        type: 'chaos',
+        queue: '{fuzz}:periodic',
+        id: job.id,
+        chaos,
+    });
+
+    if (chaos === 'crash') {
+        crashChannel.postMessage({ type: 'crash' });
+        await new Promise(() => {});
+    }
+
+    if (chaos === 'stall') {
+        await new Promise(() => {});
+    }
+
+    if (chaos === 'spin') {
+        const end = Date.now() + 10_000;
+        while (Date.now() < end) {
+            /* busy wait */
+        }
+    }
+
+    if (chaos === 'permanent') {
+        throw new PermanentError('periodic: permanent chaos');
+    }
+
+    if (chaos === 'retriable') {
+        throw new Error('periodic: retriable chaos');
+    }
+
+    // Normal completion: dispatch a cascade-a job and re-queue self
+    const cascadeRunAt = Date.now() + Math.random() * 2000;
+    const selfDelay = 1000 + Math.random() * 4000;
+
+    const [cascadeId] = await Promise.all([
+        cascadeAQueue.dispatch({ from: job.id }, { runAt: cascadeRunAt }),
+        periodicQueue.dispatch(data, {
+            id: job.id,
+            runAt: Date.now() + selfDelay,
+            updateRunAt: true,
+        }),
+    ]);
+
+    await emitEvent(eventRedis, {
+        type: 'finish',
+        queue: '{fuzz}:periodic',
+        id: job.id,
+        finishedAt: String(Date.now()),
+        dispatched: cascadeId,
+    });
+}

package/fuzztest/process.js

@@ -0,0 +1,100 @@
+/**
+ * Fuzz test child process entry point.
+ *
+ * Each child process creates one queasy Client (with worker threads) and
+ * calls listen() on all three queues. Handlers run inside queasy's internal
+ * worker threads and communicate crash signals via BroadcastChannel.
+ */
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BroadcastChannel } from 'node:worker_threads';
+import { Client } from '../src/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Configuration ─────────────────────────────────────────────────────────────
+
+const WORKER_THREADS = 2; // worker threads per child process
+
+const BASE_OPTIONS = {
+    maxRetries: 3,
+    maxStalls: 2,
+    minBackoff: 200,
+    maxBackoff: 2000,
+    timeout: 3000,
+    size: 10,
+};
+
+const FAIL_RETRY_OPTIONS = {
+    maxRetries: 5,
+    minBackoff: 200,
+};
+
+// ── Handler paths ──────────────────────────────────────────────────────────────
+
+const failHandlerPath = join(__dirname, 'handlers', 'fail-handler.js');
+const periodicPath = join(__dirname, 'handlers', 'periodic.js');
+const cascadeAPath = join(__dirname, 'handlers', 'cascade-a.js');
+const cascadeBPath = join(__dirname, 'handlers', 'cascade-b.js');
+
+// ── Crash signal ───────────────────────────────────────────────────────────────
+
+// Handlers running in worker threads post to this channel to trigger a crash.
+const crashChannel = new BroadcastChannel('fuzz-crash');
+crashChannel.onmessage = () => {
+    process.exit(1);
+};
+
+// ── Redis + queasy client ──────────────────────────────────────────────────────
+
+const client = await new Promise((resolve) => new Client({}, WORKER_THREADS, resolve));
+
+client.on('disconnected', (reason) => {
+    console.error(`[process ${process.pid}] Client disconnected: ${reason}`);
+    process.exit(1);
+});
+
+// Forward client lifecycle events to the orchestrator via IPC.
+// The orchestrator uses these to authoritatively track active jobs.
+client.on('dequeue', (queue, job) => {
+    process.send({ type: 'dequeue', queue, jobId: job.id, runAt: job.runAt });
+});
+client.on('finish', (queue, jobId) => {
+    process.send({ type: 'finish', queue, jobId });
+});
+client.on('retry', (queue, jobId) => {
+    process.send({ type: 'retry', queue, jobId });
+});
+client.on('fail', (queue, jobId) => {
+    process.send({ type: 'fail', queue, jobId });
+});
+
+// ── Queue setup ────────────────────────────────────────────────────────────────
+
+const periodicQueue = client.queue('{fuzz}:periodic', true);
+const cascadeAQueue = client.queue('{fuzz}:cascade-a', true);
+const cascadeBQueue = client.queue('{fuzz}:cascade-b', true);
+
+await Promise.all([
+    periodicQueue.listen(periodicPath, {
+        ...BASE_OPTIONS,
+        priority: 300,
+        failHandler: failHandlerPath,
+        failRetryOptions: FAIL_RETRY_OPTIONS,
+    }),
+    cascadeAQueue.listen(cascadeAPath, {
+        ...BASE_OPTIONS,
+        priority: 200,
+        failHandler: failHandlerPath,
+        failRetryOptions: FAIL_RETRY_OPTIONS,
+    }),
+    cascadeBQueue.listen(cascadeBPath, {
+        ...BASE_OPTIONS,
+        priority: 100,
+        failHandler: failHandlerPath,
+        failRetryOptions: FAIL_RETRY_OPTIONS,
+    }),
+]);
+
+console.log(`[process ${process.pid}] Ready`);

package/fuzztest/shared/chaos.js

@@ -0,0 +1,28 @@
+/**
+ * Weighted random chaos behavior picker.
+ * All handlers apply the same set of chaos behaviors.
+ */
+
+const BEHAVIORS = [
+    { action: 'normal', weight: 65 },
+    { action: 'retriable', weight: 15 },
+    { action: 'permanent', weight: 5 },
+    { action: 'stall', weight: 10 },
+    { action: 'spin', weight: 3 },
+    { action: 'crash', weight: 2 },
+];
+
+const TOTAL_WEIGHT = BEHAVIORS.reduce((sum, b) => sum + b.weight, 0);
+
+/**
+ * Pick a chaos action based on weighted probability.
+ * @returns {'normal' | 'retriable' | 'permanent' | 'stall' | 'spin' | 'crash'}
+ */
+export function pickChaos() {
+    let r = Math.random() * TOTAL_WEIGHT;
+    for (const { action, weight } of BEHAVIORS) {
+        r -= weight;
+        if (r <= 0) return /** @type {any} */ (action);
+    }
+    return 'normal';
+}

package/fuzztest/shared/stream.js

@@ -0,0 +1,40 @@
+/**
+ * Redis stream helpers for the fuzz test event log.
+ * All events are written to the 'fuzz:events' stream.
+ */
+
+export const STREAM_KEY = 'fuzz:events';
+
+/**
+ * Emit a structured event to the fuzz:events stream.
+ * @param {import('redis').RedisClientType} redis
+ * @param {Record<string, string>} fields
+ */
+export async function emitEvent(redis, fields) {
+    try {
+        await redis.xAdd(STREAM_KEY, '*', fields);
+    } catch {
+        // Never let event emission crash a handler
+    }
+}
+
+/**
+ * Async generator that yields parsed event objects from the fuzz:events stream.
+ * Blocks for up to 1 second waiting for new events, then yields control back.
+ * @param {import('redis').RedisClientType} redis
+ * @param {string} [lastId='0'] - Stream ID to start reading from ('0' = from beginning, '$' = new only)
+ * @yields {Record<string, string>}
+ */
+export async function* readEvents(redis, lastId = '0') {
+    let id = lastId;
+    while (true) {
+        const results = await redis.xRead({ key: STREAM_KEY, id }, { BLOCK: 1000, COUNT: 100 });
+        if (!results) continue;
+        for (const { messages } of results) {
+            for (const { id: msgId, message } of messages) {
+                id = msgId;
+                yield message;
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "queasy",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "A simple Redis-backed queue library for Node.js",
     "main": "src/index.js",
     "type": "module",
@@ -29,13 +29,12 @@
     ],
     "author": "",
     "license": "ISC",
-    "peerDependencies": {
+    "dependencies": {
         "redis": "^5.10.0"
     },
     "devDependencies": {
         "@biomejs/biome": "^2.3.14",
         "@types/node": "^25.2.0",
-        "redis": "^5.10.0",
         "typescript": "^5.9.3"
     }
 }

package/plans/redis-options.md

@@ -0,0 +1,279 @@
+# Plan: Client constructs its own Redis connection
+
+## Goal
+
+Change the `Client` constructor so that instead of accepting a pre-built node-redis
+connection as its first argument, it accepts an options object and constructs the
+connection itself (calling either `createClient` or `createCluster` from the `redis`
+package). This gives Queasy full control over connection lifecycle.
+
+---
+
+## 1. Options object design
+
+The first argument changes from `RedisClient` to a `RedisOptions` object:
+
+```ts
+import type { RedisClientOptions, RedisClusterOptions } from 'redis';
+
+type SingleNodeOptions = Pick<RedisClientOptions, 'url' | 'socket' | 'username' | 'password' | 'database'>;
+
+type RedisOptions =
+  | SingleNodeOptions
+  | {
+      rootNodes: SingleNodeOptions[];
+      defaults?: Partial<SingleNodeOptions>;
+      nodeAddressMap?: RedisClusterOptions['nodeAddressMap'];
+    }
+```
+
+`RedisClientOptions` and `RedisClusterOptions` are both exported from the top-level
+`redis` package and can be imported directly. `RedisClusterClientOptions` (the type
+node-redis uses for `rootNodes` elements and `defaults`) is **not** exported at the
+top level, so we define the cluster form inline, reusing `SingleNodeOptions` to
+constrain both `rootNodes` elements and `defaults` to the same permitted fields as
+the single-node case. `nodeAddressMap` is taken via an index type from
+`RedisClusterOptions` directly to avoid depending on the unexported `NodeAddressMap`
+type.
+
+The dispatch rule: **if `options.rootNodes` exists, use `createCluster`; otherwise
+use `createClient`.**
+
+- If `options.rootNodes` is present: call `createCluster(options)`, passing the
+  object through directly. The caller may also provide `defaults` (shared auth/TLS
+  for all nodes) and `nodeAddressMap` — all standard `createCluster` options,
+  named consistently with the node-redis API.
+- Otherwise: call `createClient(options)`, passing the object through directly.
+- The constructed connection is stored as `this.redis`.
+- `connect()` is called internally in the constructor.
+- `close()` calls `this.redis.destroy()` to disconnect.
+
+### Constructor signature
+
+All three arguments default so that `new Client()` works (connects to `localhost:6379`):
+
+```js
+constructor(options = {}, workerCount = os.cpus().length, callback = undefined)
+```
+
+---
+
+## 2. Changes to `src/client.js`
+
+1. Add imports:
+   ```js
+   import { createClient, createCluster } from 'redis';
+   ```
+
+2. Add a helper at module level:
+   ```js
+   function buildRedisConnection(options) {
+     if (options.rootNodes) {
+       return createCluster(options);
+     }
+     return createClient(options);
+   }
+   ```
+
+3. Update constructor:
+   - Parameter `redis` → `options` (with JSDoc type `RedisOptions`)
+   - Replace `this.redis = redis;` with:
+     ```js
+     this.redis = buildRedisConnection(options);
+     ```
+   - Replace the bare `installLuaFunctions(this.redis).then(...)` call with:
+     ```js
+     this.redis.connect()
+       .then(() => installLuaFunctions(this.redis))
+       .then((disconnect) => { ... })
+       .catch((err) => {
+         this.disconnected = true;
+         this.emit('disconnected', err.message);
+       });
+     ```
+   - Apply defaults to all parameters:
+     ```js
+     constructor(options = {}, workerCount = os.cpus().length, callback)
+     ```
+     Add `import os from 'node:os';` (check if already imported; if so, reuse).
+
+4. Update `close()`:
+   - After `this.disconnected = true;`, add:
+     ```js
+     await this.redis.destroy().catch(() => {});
+     ```
+     `destroy()` is the documented disconnect method for both `RedisClientType`
+     and `RedisClusterType` in node-redis v5.
+
+5. Update JSDoc typedef:
+   ```js
+   /** @typedef {import('./types').RedisOptions} RedisOptions */
+   ```
+   Point to `types.ts` rather than duplicating the type inline in JS, since the
+   full `Pick<>` construction is cleaner to express in TypeScript. Remove the old
+   `RedisClient` typedef.
+
+---
+
+## 3. Changes to `src/types.ts`
+
+Import the relevant node-redis types and define `RedisOptions` using `Pick<>` and
+an inline cluster shape:
+
+```ts
+import type { RedisClientOptions, RedisClusterOptions } from 'redis';
+
+type SingleNodeOptions = Pick<RedisClientOptions, 'url' | 'socket' | 'username' | 'password' | 'database'>;
+
+export type RedisOptions =
+  | SingleNodeOptions
+  | {
+      rootNodes: SingleNodeOptions[];
+      defaults?: Partial<SingleNodeOptions>;
+      nodeAddressMap?: RedisClusterOptions['nodeAddressMap'];
+    }
+```
+
+`SingleNodeOptions` is not exported — it's an internal building block. Only
+`RedisOptions` is exported. Update the `Client` constructor signature to accept
+`RedisOptions` instead of `RedisClientType`.
+
+---
+
+## 4. Changes to `package.json`
+
+- Move `redis` from `peerDependencies` + `devDependencies` to **`dependencies`**
+  (queasy now owns the connection; callers no longer need to install it themselves).
+- Remove the `peerDependencies` section entirely.
+
+Before:
+```json
+"peerDependencies": { "redis": "^5.10.0" },
+"devDependencies": { "redis": "^5.10.0", ... }
+```
+
+After:
+```json
+"dependencies": { "redis": "^5.10.0" },
+"devDependencies": { ... }
+```
+
+---
+
+## 5. Changes to `test/queue.test.js`
+
+Currently each `beforeEach` creates and connects a Redis client, passes it to
+`Client`, and each `afterEach` calls `redis.quit()`.
+
+Changes:
+- Remove the `createClient` import and the `redis` variable.
+- Change `new Client(redis, 1)` → `new Client({}, 1)`.
+- Remove `await redis.quit()` — `client.close()` now handles disconnection.
+- Any direct Redis inspection calls (`redis.zScore`, `redis.hGetAll`, `redis.keys`,
+  `redis.del`) still need a Redis connection. Add a dedicated `redisInspect` client
+  used only for test-side assertions:
+  ```js
+  // beforeEach
+  redisInspect = createClient();
+  await redisInspect.connect();
+  // afterEach
+  await redisInspect.quit();
+  ```
+
+---
+
+## 6. Changes to `test/client.test.js`
+
+Same pattern as `queue.test.js`:
+- Remove `createClient` import and `redis` variable.
+- `new Client(redis, 1)` → `new Client({}, 1)`.
+- Direct Redis calls (`redis.zScore`, `redis.keys`, `redis.del`) move to a
+  separate `redisInspect` client.
+- Remove `await redis.quit()` from `afterEach`; `client.close()` handles it.
+
+---
+
+## 7. Changes to `test/redis-functions.test.js`
+
+This test file does **not** use the `Client` class — it builds its own `redis`
+connection to test Lua functions directly. **No changes needed.**
+
+---
+
+## 8. Changes to `fuzztest/process.js`
+
+Currently:
+```js
+import { createClient } from 'redis';
+const redis = createClient();
+await redis.connect();
+const client = await new Promise((resolve) => new Client(redis, WORKER_THREADS, resolve));
+```
+
+Change to:
+```js
+const client = await new Promise((resolve) => new Client({}, WORKER_THREADS, resolve));
+```
+
+Remove the `import { createClient } from 'redis'` line and the three lines that
+create and connect `redis`.
+
+---
+
+## 9. Changes to `Readme.md`
+
+Update the `client()` API section:
+
+**Before:**
+```
+### `client(redisConnection, workerCount)`
+Returns a Queasy client.
+- `redisConnection`: a node-redis connection object.
+- `workerCount`: number; Size of the worker pool. ...
+```
+
+**After:**
+```
+### `new Client(options, workerCount)`
+Returns a Queasy client. Queasy creates and manages its own Redis connection internally.
+- `options`: connection options. Two forms are accepted:
+  - **Single node** (plain object): passed to node-redis `createClient`. Accepts
+    `url`, `socket`, `username`, `password`, and `database`. Defaults to `{}`
+    (connects to `localhost:6379`).
+  - **Cluster** (object with `rootNodes`): passed to node-redis `createCluster`.
+    Accepts `rootNodes` (required — array of per-node connection options, at least
+    three recommended), `defaults` (options shared across all nodes, e.g. auth and
+    TLS), and `nodeAddressMap` (for address translation in NAT environments).
+- `workerCount`: number; size of the worker pool. Defaults to number of CPUs.
+```
+
+Also update the terminology section to reflect that the client manages its own
+connection rather than accepting one from the caller.
+
+---
+
+## 10. Changes to `CLAUDE.md`
+
+In the Architecture section, update the JS layer description:
+- "On construction, it calls `createClient` or `createCluster` (based on whether
+  `options.rootNodes` is present), connects, then uploads the Lua script via
+  `FUNCTION LOAD REPLACE`."
+- Remove the mention of `WeakSet (initializedClients)` tracking which Redis clients
+  have had functions loaded (no longer relevant since the connection is internal and
+  only created once per `Client` instance).
+
+---
+
+## Summary of file changes
+
+| File | Change |
+|---|---|
+| `src/client.js` | Accept `RedisOptions`; call `createClient`/`createCluster`; connect in constructor; `destroy()` in `close()`; emit `'disconnected'` on connect error; default all args |
+| `src/types.ts` | Add `RedisOptions` type using `Pick<RedisClientOptions, ...> \| Pick<RedisClusterOptions, ...>`; remove `RedisClientType` reference |
+| `package.json` | Move `redis` from `peerDependencies`+`devDependencies` to `dependencies` |
+| `test/queue.test.js` | Remove external `redis` client; pass `{}` to `Client`; add `redisInspect` for assertions |
+| `test/client.test.js` | Same as above |
+| `test/redis-functions.test.js` | No changes |
+| `fuzztest/process.js` | Remove `createClient`/`redis`; pass `{}` to `Client` |
+| `Readme.md` | Update `client()` API docs |
+| `CLAUDE.md` | Update architecture description |