@hile/redis-stream-queue 3.0.1 → 3.0.4

package/AI.md

@@ -0,0 +1,303 @@
+# AI Guide For @hile/redis-stream-queue
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Persist and process background work with Redis Streams, retries, delayed jobs, pending recovery, and DLQ.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Persist and retry background jobs | `@hile/redis-stream-queue` | `packages/redis-reliability.md`, `recipes/queue-worker-idempotency.md` |
+
+
+
+# Redis Reliability
+
+Packages: `@hile/redis-lock`, `@hile/redis-idempotency`, `@hile/redis-rate-limit`, `@hile/redis-stream-queue`.
+
+## Copy-Paste Example
+
+Idempotent queue worker:
+
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { RedisIdempotency, stableHash } from '@hile/redis-idempotency'
+import { RedisStreamQueue, defineQueue } from '@hile/redis-stream-queue'
+
+type EmailJob = { tenantId: string; userId: string; template: 'welcome' }
+
+const emailQueue = defineQueue<EmailJob>('email')
+
+const redis = await loadService(redisService)
+const queue = new RedisStreamQueue(redis, { prefix: 'app:' })
+const idempotency = new RedisIdempotency(redis)
+
+queue.worker(emailQueue, async (job) => {
+  await idempotency.run(
+    `idem:email:${job.data.tenantId}:${job.jobId ?? job.id}`,
+    () => sendEmail(job.data),
+    {
+      lockTtl: 60_000,
+      resultTtl: 86_400_000,
+      fingerprint: stableHash(job.data),
+    },
+  )
+}, {
+  group: 'email-workers',
+  consumer: process.env.HOSTNAME ?? `${process.pid}`,
+  concurrency: 8,
+}).start()
+```
+
+## More Examples
+
+Distributed lock with fencing:
+
+```ts
+import { RedisLock } from '@hile/redis-lock'
+
+const locks = new RedisLock(redis, {
+  prefix: 'billing:',
+  defaultTtl: 30_000,
+})
+
+await locks.withLock('lock:account:acct_1', {
+  wait: 2_000,
+  fencing: true,
+  renew: true,
+}, async ({ fencingToken }) => {
+  await accountRepo.updateIfFencingTokenIsNewer('acct_1', changes, fencingToken!)
+})
+```
+
+Rate limit HTTP middleware:
+
+```ts
+import { defineLimit, RedisRateLimiter, rateLimitHttp } from '@hile/redis-rate-limit'
+
+const loginLimit = defineLimit('rl:login:{ip:string}', {
+  algorithm: 'sliding-window',
+  limit: 5,
+  window: 60_000,
+})
+
+const limiter = new RedisRateLimiter(redis, { prefix: 'app:' })
+
+http.use(rateLimitHttp(loginLimit, {
+  limiter,
+  key: (ctx) => ({ ip: ctx.ip }),
+}))
+```
+
+Queue add with delayed retry policy:
+
+```ts
+await queue.add(emailQueue, payload, {
+  jobId: `welcome:${payload.tenantId}:${payload.userId}`,
+  delay: 10_000,
+  maxAttempts: 5,
+  backoff: { type: 'exponential', baseMs: 1_000, maxMs: 60_000 },
+})
+```
+
+## Use When
+
+Use these packages for distributed lease locks, duplicate execution protection, shared quotas, and durable Redis Streams job processing.
+
+## Do Not Use When
+
+- Do not claim exactly-once behavior.
+- Do not use locks as a replacement for database constraints.
+- Do not use queue `jobId` as the only idempotency boundary for side effects.
+- Do not use rate limits as authorization or authentication.
+
+## Install
+
+```bash
+pnpm add @hile/redis-lock @hile/redis-idempotency @hile/redis-rate-limit @hile/redis-stream-queue
+```
+
+## Imports
+
+```ts
+import { RedisLock } from '@hile/redis-lock'
+import { RedisIdempotency, stableHash, withIdempotency, idempotent } from '@hile/redis-idempotency'
+import { RedisRateLimiter, defineLimit, rateLimitHttp, rateLimitModel } from '@hile/redis-rate-limit'
+import { RedisStreamQueue, defineQueue } from '@hile/redis-stream-queue'
+```
+
+## Compose With
+
+- Use `@hile/ioredis` for the Redis client.
+- Use `idempotent()` and `rateLimitModel()` in `@hile/model` pipelines.
+- Use `@hile/context` with queues; active context is snapshotted during enqueue and restored in handlers.
+- Use `@hile/cache` singleflight to reduce stampedes.
+
+## Runtime And Lifecycle Notes
+
+- `RedisLock.withLock()` asserts ownership before returning a successful callback result.
+- `tryLock()` returns `undefined` if the key is already locked.
+- `RedisIdempotency.run()` stores `IN_FLIGHT` and `DONE` states in Redis and uses Redis locks for ownership.
+- Idempotency requires a stable `fingerprint`.
+- `stableHash()` is for plain DTOs and rejects unsupported shapes.
+- Rate limit algorithms: `fixed-window`, `sliding-window`, `token-bucket`.
+- `dryRun` rate limit checks do not mutate Redis.
+- Queue workers use Redis Streams consumer groups, delayed sorted sets, pending claim recovery, retry backoff, and DLQ streams.
+- Queue payload schema can expose `parse()` or `safeParse()`.
+
+## Anti-Patterns
+
+- Random UUID per retry as idempotency key.
+- Returning `Date`, `BigInt`, or class instances from idempotent functions without a `resultCodec`.
+- Using `stream()` or RPC retries without idempotency around irreversible handlers.
+- Ignoring DLQ after max attempts.
+
+## Verification Checklist
+
+- Lock TTL is longer than normal critical-section time.
+- Fencing is enabled when stale owners can write to external resources.
+- Idempotency keys use business identifiers.
+- Queue handlers are idempotent or wrapped in idempotency.
+- Rate limit `Retry-After` is exposed in seconds for HTTP.
+- DLQ is monitored.
+
+
+
+# Related Recipes
+
+
+
+# Queue Worker With Idempotency
+
+## Complete Example
+
+```ts
+// src/services/email-worker.boot.ts
+import { defineService, loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { RedisIdempotency, stableHash } from '@hile/redis-idempotency'
+import { RedisStreamQueue, defineQueue } from '@hile/redis-stream-queue'
+
+type EmailPayload = {
+  tenantId: string
+  userId: string
+  template: 'welcome'
+}
+
+const emailQueue = defineQueue<EmailPayload>('email')
+
+export default defineService('email.worker', async (shutdown) => {
+  const redis = await loadService(redisService)
+  const queue = new RedisStreamQueue(redis, { prefix: 'app:' })
+  const idempotency = new RedisIdempotency(redis)
+
+  const worker = queue.worker(emailQueue, async (job) => {
+    await idempotency.run(
+      `idem:email:${job.data.tenantId}:${job.jobId ?? job.id}`,
+      () => sendEmail(job.data),
+      {
+        lockTtl: 60_000,
+        resultTtl: 86_400_000,
+        fingerprint: stableHash(job.data),
+      },
+    )
+  }, {
+    group: 'email-workers',
+    consumer: process.env.HOSTNAME ?? `${process.pid}`,
+    concurrency: 8,
+    claimIdle: 60_000,
+  })
+
+  worker.start()
+  shutdown(() => worker.stop())
+
+  return { queue, worker }
+})
+```
+
+Enqueue:
+
+```ts
+await queue.add(emailQueue, {
+  tenantId: 't1',
+  userId: 'u1',
+  template: 'welcome',
+}, {
+  jobId: 'welcome:t1:u1',
+  maxAttempts: 5,
+  backoff: { type: 'exponential', baseMs: 1_000, maxMs: 60_000 },
+})
+```
+
+## File Layout
+
+```text
+src/
+  services/email-worker.boot.ts
+  queues/email.queue.ts
+```
+
+## User Intent
+
+Use this recipe for at-least-once background work where side effects must survive retries safely.
+
+## Packages To Use
+
+- `@hile/redis-stream-queue`
+- `@hile/redis-idempotency`
+- `@hile/ioredis`
+- `@hile/core`
+
+## Implementation Steps
+
+1. Define the queue and payload type.
+2. Enqueue with a stable `jobId`.
+3. Wrap side effects with `RedisIdempotency.run()`.
+4. Use business identifiers in idempotency keys.
+5. Monitor DLQ with `readDeadLetters()`.
+
+## Failure And Cleanup Behavior
+
+- Queue delivery is at-least-once.
+- Failed attempts retry until `maxAttempts`, then move to DLQ.
+- `jobId` dedupes enqueue, not side effects.
+- Idempotency caches successful results but is not exactly-once.
+
+## Verification Checklist
+
+- Handler is idempotent.
+- Idempotency key is business-derived.
+- Worker stop is registered with `shutdown`.
+- DLQ read path exists.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,167 +1,79 @@
 # @hile/redis-stream-queue
 
-Redis Streams backed durable job queue primitives for Hile applications.
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-Use this package when work should not block the current request but still needs to be persisted, retried, recovered after worker crashes, and inspected when it finally fails.
+Persist and process background work with Redis Streams, retries, delayed jobs, pending recovery, and DLQ.
+
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
+
+## When To Use
+
+Use these packages for distributed lease locks, duplicate execution protection, shared quotas, and durable Redis Streams job processing.
 
 ## Install
 
 ```bash
-pnpm add @hile/redis-stream-queue @hile/ioredis
+pnpm add @hile/redis-stream-queue
 ```
 
-The package accepts any Redis client matching `RedisStreamQueueLike`. In Hile apps the usual client comes from `@hile/ioredis`.
+## Copy-Paste Example
 
-## Quick Start
+Idempotent queue worker:
 
-```typescript
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { RedisIdempotency, stableHash } from '@hile/redis-idempotency'
 import { RedisStreamQueue, defineQueue } from '@hile/redis-stream-queue'
 
-type EmailPayload = {
-  template: 'welcome'
-  userId: string
-}
+type EmailJob = { tenantId: string; userId: string; template: 'welcome' }
 
-const emailQueue = defineQueue<EmailPayload>('email')
-const queue = new RedisStreamQueue(redis, { prefix: 'myapp:' })
+const emailQueue = defineQueue<EmailJob>('email')
 
-await queue.add(emailQueue, {
-  template: 'welcome',
-  userId: 'user-1',
-}, {
-  jobId: 'welcome:user-1',
-  maxAttempts: 5,
-  backoff: { type: 'exponential', baseMs: 1_000 },
-})
+const redis = await loadService(redisService)
+const queue = new RedisStreamQueue(redis, { prefix: 'app:' })
+const idempotency = new RedisIdempotency(redis)
 
 queue.worker(emailQueue, async (job) => {
-  await sendEmail(job.data)
+  await idempotency.run(
+    `idem:email:${job.data.tenantId}:${job.jobId ?? job.id}`,
+    () => sendEmail(job.data),
+    {
+      lockTtl: 60_000,
+      resultTtl: 86_400_000,
+      fingerprint: stableHash(job.data),
+    },
+  )
 }, {
   group: 'email-workers',
-  consumer: 'worker-1',
+  consumer: process.env.HOSTNAME ?? `${process.pid}`,
   concurrency: 8,
 }).start()
 ```
 
-## Core Concepts
-
-### defineQueue(name, schema?)
-
-`defineQueue()` declares the queue name and optional payload schema.
-
-```typescript
-const imageQueue = defineQueue('image-resize', {
-  parse(value) {
-    if (typeof value !== 'object' || value === null) throw new Error('invalid payload')
-    return value as { imageId: string; size: 'small' | 'large' }
-  },
-})
-```
-
-The schema can expose `parse(value)` or `safeParse(value)`. Payloads are validated before enqueueing and again when workers read them.
-
-### queue.add(queue, payload, options?)
-
-Adds a durable job.
-
-```typescript
-await queue.add(emailQueue, payload, {
-  jobId: 'welcome:user-1',
-  delay: 30_000,
-  maxAttempts: 5,
-  backoff: { type: 'fixed', delay: 5_000 },
-})
-```
-
-Options:
-
-| Option | Meaning |
-|---|---|
-| `jobId` | Deduplication key. A second add with the same `jobId` returns `{ duplicate: true }`. |
-| `delay` | Milliseconds before the job becomes visible to workers. |
-| `maxAttempts` | Maximum attempts before the job goes to DLQ. Defaults to `1`. |
-| `backoff` | Retry delay. Use a number, `{ type: 'fixed', delay }`, or `{ type: 'exponential', baseMs, maxMs }`. |
-
-### queue.worker(queue, handler, options?)
-
-Creates a worker around a Redis consumer group.
-
-```typescript
-const worker = queue.worker(emailQueue, async (job) => {
-  await sendEmail(job.data)
-}, {
-  group: 'email-workers',
-  consumer: process.env.HOSTNAME ?? 'local',
-  concurrency: 4,
-  claimIdle: 60_000,
-})
-
-worker.start()
-```
-
-`runOnce()` is available for tests and controlled scripts:
-
-```typescript
-await worker.runOnce()
-await worker.stop()
-```
-
-### readDeadLetters(queue)
-
-Reads failed jobs from the dead-letter stream:
-
-```typescript
-const failed = await queue.readDeadLetters(emailQueue, { count: 20 })
-```
-
-## State Machine
-
-| State | Redis structure | Meaning |
-|---|---|---|
-| `scheduled` | sorted set `{prefix}queue:{name}:delayed` | Job has a future `runAt`. |
-| `ready` | stream `{prefix}queue:{name}:stream` | Job is visible to the consumer group. |
-| `pending` | Redis Streams PEL | A worker received the job but has not acked it yet. |
-| `retrying` | delayed sorted set | A failed job is waiting for backoff before another attempt. |
-| `done` | acked stream entry | Handler completed and the pending entry was acked. |
-| `dead-lettered` | stream `{prefix}queue:{name}:dlq` | Attempts were exhausted. |
-
-## Crash Recovery
-
-Workers use Redis consumer groups. If a worker reads a job and dies before `XACK`, the job remains in the pending entries list. Another worker can claim it after `claimIdle` milliseconds and continue processing.
-
-## Context Propagation
-
-If `@hile/context` has an active context when a job is enqueued, the queue stores a snapshot and restores it while the worker handler runs.
-
-```typescript
-await runWithContext<AppContext>({ shopId: 'shop-1' }, async () => {
-  await queue.add(emailQueue, payload)
-})
-```
-
-```typescript
-queue.worker(emailQueue, async () => {
-  const context = getContext<AppContext>()
-  console.log(context.shopId)
-})
-```
-
 ## Boundaries
 
-- This package is for background jobs, not request/response RPC.
-- It provides at-least-once delivery. Handlers must be idempotent.
-- It does not promise exactly-once execution.
-- Delayed jobs and retries are promoted when workers poll the queue.
-- Payload and context values must be JSON-serializable.
-- `jobId` prevents duplicate enqueue for the same key; it does not make the handler side effect exactly-once.
+- Do not claim exactly-once behavior.
+- Do not use locks as a replacement for database constraints.
+- Do not use queue `jobId` as the only idempotency boundary for side effects.
+- Do not use rate limits as authorization or authentication.
 
-## Testing
+- Random UUID per retry as idempotency key.
+- Returning `Date`, `BigInt`, or class instances from idempotent functions without a `resultCodec`.
+- Using `stream()` or RPC retries without idempotency around irreversible handlers.
+- Ignoring DLQ after max attempts.
 
-```bash
-pnpm --filter @hile/redis-stream-queue test
-pnpm --filter @hile/redis-stream-queue build
-```
+## Verify
+
+- Lock TTL is longer than normal critical-section time.
+- Fencing is enabled when stale owners can write to external resources.
+- Idempotency keys use business identifiers.
+- Queue handlers are idempotent or wrapped in idempotency.
+- Rate limit `Retry-After` is exposed in seconds for HTTP.
+- DLQ is monitored.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/dist/queue.d.ts

@@ -9,6 +9,7 @@ export declare class RedisStreamQueue {
     readDeadLetters<TData>(definition: QueueDefinition<TData>, options?: ReadDeadLettersOptions): Promise<Array<QueueDeadLetter<TData>>>;
     runWorkerOnce<TData>(definition: QueueDefinition<TData>, handler: QueueWorkerHandler<TData>, options: RequiredWorkerOptions): Promise<number>;
     private processEntry;
+    private acknowledge;
     private handleFailure;
     private createJob;
     private promoteDelayed;
@@ -41,7 +42,10 @@ type RequiredWorkerOptions = {
     concurrency: number;
     block: number;
     pollInterval: number;
+    errorRetryInterval: number;
     claimIdle: number;
     claimCount: number;
+    removeOnAck: boolean;
+    onError?: (err: unknown) => void | Promise<void>;
 };
 export {};

package/dist/queue.js

@@ -6,7 +6,16 @@ const DEFAULT_MAX_ATTEMPTS = 1;
 const DEFAULT_CONCURRENCY = 1;
 const DEFAULT_CLAIM_IDLE = 60_000;
 const DEFAULT_POLL_INTERVAL = 1_000;
+const DEFAULT_ERROR_RETRY_INTERVAL = 1_000;
 const DEFAULT_READ_BLOCK = 0;
+const PROMOTE_DELAYED_SCRIPT = `
+if redis.call('ZSCORE', KEYS[1], ARGV[1]) == false then
+  return 0
+end
+local streamId = redis.call('XADD', KEYS[2], '*', 'job', ARGV[1])
+redis.call('ZREM', KEYS[1], ARGV[1])
+return streamId
+`;
 export class RedisStreamQueue {
     redis;
     prefix;
@@ -128,13 +137,20 @@ export class RedisStreamQueue {
             else {
                 await run();
             }
-            await this.redis.xack(this.streamKey(definition), options.group, streamId);
         }
         catch (err) {
-            await this.handleFailure(definition, stored, streamId, attempt, options.group, err);
+            await this.handleFailure(definition, stored, streamId, attempt, options, err);
+            return;
         }
+        await this.acknowledge(definition, options, streamId);
     }
-    async handleFailure(definition, stored, streamId, attempt, group, err) {
+    async acknowledge(definition, options, streamId) {
+        await this.redis.xack(this.streamKey(definition), options.group, streamId);
+        if (options.removeOnAck) {
+            await this.redis.xdel(this.streamKey(definition), streamId);
+        }
+    }
+    async handleFailure(definition, stored, streamId, attempt, options, err) {
         const reason = errorReason(err);
         const failed = {
             ...stored,
@@ -150,7 +166,7 @@ export class RedisStreamQueue {
         else {
             await this.redis.xadd(this.deadLetterKey(definition), '*', 'job', this.encodeJob(definition, failed));
         }
-        await this.redis.xack(this.streamKey(definition), group, streamId);
+        await this.acknowledge(definition, options, streamId);
     }
     createJob(definition, stored, streamId, attempt) {
         return {
@@ -170,11 +186,9 @@ export class RedisStreamQueue {
         const members = await this.redis.zrangebyscore(this.delayedKey(definition), '-inf', this.now(), 'LIMIT', 0, limit);
         let promoted = 0;
         for (const member of members) {
-            const removed = await this.redis.zrem(this.delayedKey(definition), member);
-            if (removed === 0)
-                continue;
-            await this.redis.xadd(this.streamKey(definition), '*', 'job', member);
-            promoted++;
+            const streamId = await this.redis.eval(PROMOTE_DELAYED_SCRIPT, 2, this.delayedKey(definition), this.streamKey(definition), member);
+            if (streamId !== 0)
+                promoted++;
         }
         return promoted;
     }
@@ -276,9 +290,22 @@ export class RedisStreamQueueWorker {
     }
     async runLoop() {
         while (this.running) {
-            const processed = await this.runOnce();
-            if (processed === 0) {
-                await sleep(this.options.pollInterval);
+            try {
+                const processed = await this.runOnce();
+                if (processed === 0) {
+                    await sleep(this.options.pollInterval);
+                }
+            }
+            catch (err) {
+                try {
+                    await this.options.onError?.(err);
+                }
+                catch {
+                    // Error observers must not stop a worker that is already recovering.
+                }
+                if (this.running) {
+                    await sleep(this.options.errorRetryInterval);
+                }
             }
         }
     }
@@ -291,8 +318,11 @@ function normalizeWorkerOptions(definition, options) {
         concurrency,
         block: assertNonNegativeInteger(options.block ?? DEFAULT_READ_BLOCK, 'block'),
         pollInterval: assertNonNegativeInteger(options.pollInterval ?? DEFAULT_POLL_INTERVAL, 'pollInterval'),
+        errorRetryInterval: assertNonNegativeInteger(options.errorRetryInterval ?? DEFAULT_ERROR_RETRY_INTERVAL, 'errorRetryInterval'),
         claimIdle: assertNonNegativeInteger(options.claimIdle ?? DEFAULT_CLAIM_IDLE, 'claimIdle'),
         claimCount: assertPositiveInteger(options.claimCount ?? concurrency, 'claimCount'),
+        removeOnAck: options.removeOnAck ?? false,
+        onError: options.onError,
     };
 }
 function normalizeBackoff(backoff) {

package/dist/types.d.ts

@@ -66,8 +66,11 @@ export type QueueWorkerOptions = {
     concurrency?: number;
     block?: number;
     pollInterval?: number;
+    errorRetryInterval?: number;
     claimIdle?: number;
     claimCount?: number;
+    removeOnAck?: boolean;
+    onError?: (err: unknown) => void | Promise<void>;
 };
 export type RedisStreamEntry = [id: string, fields: string[]];
 export type RedisStreamReadResult = Array<[stream: string, entries: RedisStreamEntry[]]> | null;
@@ -79,10 +82,12 @@ export interface RedisStreamQueueLike {
     xpending(...args: any[]): Promise<any>;
     xclaim(...args: any[]): Promise<any>;
     xack(...args: any[]): Promise<any>;
+    xdel(...args: any[]): Promise<any>;
     xrange(...args: any[]): Promise<any>;
     zadd(...args: any[]): Promise<any>;
     zrangebyscore(...args: any[]): Promise<any>;
     zrem(...args: any[]): Promise<any>;
+    eval(...args: any[]): Promise<any>;
     set(...args: any[]): Promise<any>;
     get(...args: any[]): Promise<any>;
     del(...args: any[]): Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/redis-stream-queue",
-  "version": "3.0.1",
+  "version": "3.0.4",
   "description": "Redis Streams backed durable job queue primitives for Hile applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,7 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -24,7 +24,7 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/context": "^3.0.1"
+    "@hile/context": "^3.0.2"
   },
-  "gitHead": "762f9476b1b53f91899b985fe5bf437b618bb224"
+  "gitHead": "f5d5970c964440047dda973d3f4eda92116ca809"
 }

package/SKILL.md

@@ -1,45 +0,0 @@
----
-name: redis-stream-queue
-description: Use when implementing Redis Streams backed durable job queues, background workers, retry/backoff, delayed jobs, consumer-group pending recovery, DLQ handling, or Hile queue context propagation.
----
-
-# Redis Stream Queue
-
-Use `@hile/redis-stream-queue` when work should be persisted and processed asynchronously by background workers.
-
-## Core Rule
-
-This package provides at-least-once background job execution. Handlers must be idempotent; do not claim exactly-once delivery.
-
-```typescript
-const emailQueue = defineQueue<EmailPayload>('email')
-
-await queue.add(emailQueue, payload, {
-  jobId: `welcome:${payload.userId}`,
-  maxAttempts: 5,
-  backoff: { type: 'exponential', baseMs: 1_000 },
-})
-
-queue.worker(emailQueue, async (job) => {
-  await sendEmail(job.data)
-}, { concurrency: 8 }).start()
-```
-
-## Design Boundaries
-
-- Use Redis Streams consumer groups for ready jobs.
-- Use the pending entries list plus `XCLAIM` for worker crash recovery.
-- Use a delayed sorted set for delayed jobs and retry backoff.
-- Move exhausted jobs to `{prefix}queue:{name}:dlq`.
-- Store job attempts, first/last failure reason, and context metadata.
-- Validate payloads through the queue schema before enqueueing and before handling.
-- `jobId` is enqueue dedupe only; side effects still need idempotency.
-
-## Testing Priorities
-
-- Pending job claimed by another worker after `claimIdle`.
-- Failed job retries with configured backoff.
-- Exhausted job appears in DLQ.
-- Duplicate `jobId` enqueues only one job.
-- Worker concurrency caps simultaneous handlers.
-- Active `@hile/context` is restored inside handlers.