ingenium-redis 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+import { SessionStore, IdempotencyStore, CachedResponse, RateLimitStore, QueueStore } from 'ingenium';
+
+/**
+ * Minimal Redis-client surface the stores rely on.
+ *
+ * Intentionally duck-typed against node-redis v4+ (`@redis/client`) so users
+ * can pass their existing `createClient()` instance directly without an extra
+ * type adapter. ioredis users can shim it in a few lines if they prefer that
+ * client.
+ *
+ * The surface is intentionally tiny — only the commands the three stores
+ * actually call. Adding methods here means tightening what a custom client
+ * must implement, so resist.
+ */
+interface RedisSetOptions {
+    /** Set TTL in seconds. Mutually exclusive with `PX`. */
+    EX?: number;
+    /** Set TTL in milliseconds. Mutually exclusive with `EX`. */
+    PX?: number;
+    /** Only set if the key does not already exist. */
+    NX?: boolean;
+}
+interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: RedisSetOptions): Promise<string | null>;
+    del(key: string | readonly string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean | number>;
+    /**
+     * Run a Lua script server-side. node-redis v4 uses the `{ keys, arguments }`
+     * options bag — ioredis uses positional args, so ioredis adopters need to
+     * shim this method.
+     */
+    eval(script: string, options: {
+        keys: readonly string[];
+        arguments: readonly string[];
+    }): Promise<unknown>;
+}
+
+interface RedisSessionStoreOptions {
+    /** Connected Redis client. Caller owns lifecycle. */
+    client: RedisClientLike;
+    /** Key prefix for every entry. Default `'ingenium:sess:'`. */
+    prefix?: string;
+}
+/**
+ * Redis-backed {@link SessionStore}. JSON-encodes session data and uses
+ * `SET ... EX` so Redis owns TTL expiry — no sweeper, no clock drift between
+ * the cookie expiry and the stored value.
+ *
+ * The store does NOT manage the client connection. Create + `.connect()` your
+ * `createClient(...)` before constructing the store; close it during your
+ * graceful shutdown hook.
+ */
+declare class RedisSessionStore implements SessionStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(opts: RedisSessionStoreOptions);
+    get(id: string): Promise<Record<string, unknown> | null>;
+    set(id: string, data: Record<string, unknown>, ttlSeconds: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+    touch(id: string, ttlSeconds: number): Promise<void>;
+}
+
+interface RedisIdempotencyStoreOptions {
+    /** Connected Redis client. Caller owns lifecycle. */
+    client: RedisClientLike;
+    /** Key prefix for every entry. Default `'ingenium:idem:'`. */
+    prefix?: string;
+}
+/**
+ * Redis-backed {@link IdempotencyStore}. Cached responses are JSON-serialized
+ * (with Buffer bodies base64-encoded) and stored with `SET ... PX` so Redis
+ * owns expiry. Suitable for multi-replica deployments where the replica that
+ * served the original request may not be the one handling the retry.
+ */
+declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(opts: RedisIdempotencyStoreOptions);
+    get(key: string): Promise<CachedResponse | null>;
+    set(key: string, value: CachedResponse, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+
+interface RedisRateLimitStoreOptions {
+    /** Connected Redis client. Caller owns lifecycle. */
+    client: RedisClientLike;
+    /** Key prefix for every entry. Default `'ingenium:rl:'`. */
+    prefix?: string;
+}
+/**
+ * Redis-backed {@link RateLimitStore}. Uses a single Lua call per hit so the
+ * INCR + PEXPIRE + PTTL trio is atomic — no race where two replicas both see
+ * `count == 1` and each set their own expiry, and no race where the counter
+ * exists without a TTL because the expire happened in a separate round-trip
+ * that lost.
+ *
+ * `resetAt` is computed from `PTTL` on the server side, so the value is
+ * consistent across replicas even if their clocks drift. We add `Date.now()`
+ * locally only to produce the absolute timestamp the rest of Ingenium
+ * works with; a small clock skew there affects header reporting only, not
+ * the actual rate-limit decision (which Redis owns).
+ */
+declare class RedisRateLimitStore implements RateLimitStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(opts: RedisRateLimitStoreOptions);
+    hit(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+}
+
+interface RedisQueueStoreOptions {
+    /** Connected Redis client. Caller owns lifecycle. */
+    client: RedisClientLike;
+    /**
+     * Key prefix for every structure owned by this queue instance. Default
+     * `'ingenium:queue:'`. Two queues that must not share work need distinct
+     * prefixes (e.g. `'ingenium:queue:emails:'`).
+     */
+    prefix?: string;
+    /**
+     * Clock used to stamp ready-times (ZSET scores). Defaults to `Date.now`.
+     * Overridable so tests can drive virtual time; production code never sets it.
+     */
+    now?: () => number;
+}
+/**
+ * Redis-backed {@link QueueStore}. A FIFO job queue with delayed retries and a
+ * dead-letter list, sharing state across replicas so any worker on any pod can
+ * pick up any job.
+ *
+ * Atomicity: every operation that touches more than one key (`next`, `retry`,
+ * `fail`, and—for uniformity and to keep {@link RedisClientLike} tiny—`enqueue`,
+ * `ack`, `size`, `failedCount`) runs as a single Lua `EVAL`. This is what keeps
+ * the client surface unchanged: we never need MULTI/WATCH or any command beyond
+ * `eval`. Redis runs each script to completion atomically, so concurrent workers
+ * can't double-deliver a job or lose a payload between the ZREM and the
+ * in-flight SADD.
+ *
+ * Delivery guarantee: at-least-once. A job that is `next()`-ed but whose worker
+ * crashes before `ack`/`retry`/`fail` stays in the `inflight` set and in the
+ * `jobs` hash, but NOT in `pending` — it will not be re-delivered automatically
+ * by this store (there is no visibility-timeout sweeper). That matches
+ * {@link MemoryQueueStore}, which also leaves crashed jobs stuck in its
+ * in-flight map. Add a reaper that re-enqueues stale inflight ids if you need
+ * crash recovery; the data model (inflight SET + jobs HASH) supports it.
+ *
+ * `size()` returns the pending count INCLUDING delayed (not-yet-ready) jobs,
+ * mirroring `MemoryQueueStore.size()` which returns `pending.length`. Delayed
+ * jobs live in the same ZSET with a future score, so `ZCARD` counts them.
+ */
+declare class RedisQueueStore<TData> implements QueueStore<TData> {
+    private readonly client;
+    private readonly now;
+    /** KEYS passed to every script, in fixed order: pending, jobs, inflight, failed, seq. */
+    private readonly keys;
+    constructor(opts: RedisQueueStoreOptions);
+    enqueue(data: TData): Promise<{
+        id: string;
+    }>;
+    next(): Promise<{
+        id: string;
+        data: TData;
+        attempt: number;
+    } | null>;
+    ack(id: string): Promise<void>;
+    retry(id: string, delayMs: number): Promise<void>;
+    fail(id: string): Promise<void>;
+    size(): Promise<number>;
+    failedCount(): Promise<number>;
+}
+
+export { type RedisClientLike, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, RedisQueueStore, type RedisQueueStoreOptions, RedisRateLimitStore, type RedisRateLimitStoreOptions, RedisSessionStore, type RedisSessionStoreOptions, type RedisSetOptions };

package/dist/index.js

@@ -0,0 +1,228 @@
+import { Buffer } from 'buffer';
+
+// src/session.ts
+var RedisSessionStore = class {
+  client;
+  prefix;
+  constructor(opts) {
+    this.client = opts.client;
+    this.prefix = opts.prefix ?? "ingenium:sess:";
+  }
+  async get(id) {
+    const raw = await this.client.get(this.prefix + id);
+    if (raw === null) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  async set(id, data, ttlSeconds) {
+    await this.client.set(this.prefix + id, JSON.stringify(data), { EX: ttlSeconds });
+  }
+  async destroy(id) {
+    await this.client.del(this.prefix + id);
+  }
+  async touch(id, ttlSeconds) {
+    await this.client.expire(this.prefix + id, ttlSeconds);
+  }
+};
+function encode(value) {
+  let body = null;
+  if (Buffer.isBuffer(value.body)) {
+    body = { t: "b", v: value.body.toString("base64") };
+  } else if (typeof value.body === "string") {
+    body = { t: "s", v: value.body };
+  }
+  const env = { s: value.statusCode, h: value.headers, b: body };
+  return JSON.stringify(env);
+}
+function decode(raw) {
+  let env;
+  try {
+    env = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (env === null || typeof env !== "object") return null;
+  let body = null;
+  if (env.b !== null) {
+    body = env.b.t === "b" ? Buffer.from(env.b.v, "base64") : env.b.v;
+  }
+  return { statusCode: env.s, headers: env.h, body };
+}
+var RedisIdempotencyStore = class {
+  client;
+  prefix;
+  constructor(opts) {
+    this.client = opts.client;
+    this.prefix = opts.prefix ?? "ingenium:idem:";
+  }
+  async get(key) {
+    const raw = await this.client.get(this.prefix + key);
+    if (raw === null) return null;
+    return decode(raw);
+  }
+  async set(key, value, ttlMs) {
+    await this.client.set(this.prefix + key, encode(value), { PX: ttlMs });
+  }
+  async delete(key) {
+    await this.client.del(this.prefix + key);
+  }
+};
+
+// src/rate-limit.ts
+var HIT_SCRIPT = `-- INGENIUM_RATELIMIT_HIT v1
+local current = redis.call('INCR', KEYS[1])
+if current == 1 then
+  redis.call('PEXPIRE', KEYS[1], ARGV[1])
+end
+local ttl = redis.call('PTTL', KEYS[1])
+return {current, ttl}`;
+var RedisRateLimitStore = class {
+  client;
+  prefix;
+  constructor(opts) {
+    this.client = opts.client;
+    this.prefix = opts.prefix ?? "ingenium:rl:";
+  }
+  async hit(key, windowMs) {
+    const result = await this.client.eval(HIT_SCRIPT, {
+      keys: [this.prefix + key],
+      arguments: [String(windowMs)]
+    });
+    if (!Array.isArray(result) || result.length !== 2) {
+      throw new Error(
+        `RedisRateLimitStore: unexpected EVAL result shape: ${JSON.stringify(result)}`
+      );
+    }
+    const [count, ttlMs] = result;
+    return { count, resetAt: Date.now() + Math.max(0, ttlMs) };
+  }
+  async reset(key) {
+    await this.client.del(this.prefix + key);
+  }
+};
+
+// src/queue.ts
+var ENQUEUE_SCRIPT = `-- INGENIUM_QUEUE_ENQUEUE v1
+local id = tostring(redis.call('INCR', KEYS[5]))
+redis.call('HSET', KEYS[2], id, ARGV[2])
+redis.call('HSET', KEYS[2], id .. ':a', '1')
+redis.call('ZADD', KEYS[1], ARGV[1], id)
+return id`;
+var NEXT_SCRIPT = `-- INGENIUM_QUEUE_NEXT v1
+local ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, 1)
+if not ids[1] then
+  return nil
+end
+local id = ids[1]
+redis.call('ZREM', KEYS[1], id)
+redis.call('SADD', KEYS[3], id)
+local payload = redis.call('HGET', KEYS[2], id)
+local attempt = redis.call('HGET', KEYS[2], id .. ':a')
+return {id, payload, attempt}`;
+var ACK_SCRIPT = `-- INGENIUM_QUEUE_ACK v1
+redis.call('SREM', KEYS[3], ARGV[1])
+redis.call('HDEL', KEYS[2], ARGV[1], ARGV[1] .. ':a')
+return 1`;
+var RETRY_SCRIPT = `-- INGENIUM_QUEUE_RETRY v1
+if redis.call('SREM', KEYS[3], ARGV[1]) == 0 then
+  return 0
+end
+if redis.call('HEXISTS', KEYS[2], ARGV[1]) == 0 then
+  return 0
+end
+redis.call('HINCRBY', KEYS[2], ARGV[1] .. ':a', 1)
+redis.call('ZADD', KEYS[1], ARGV[2], ARGV[1])
+return 1`;
+var FAIL_SCRIPT = `-- INGENIUM_QUEUE_FAIL v1
+if redis.call('SREM', KEYS[3], ARGV[1]) == 0 then
+  return 0
+end
+local payload = redis.call('HGET', KEYS[2], ARGV[1])
+if payload then
+  local attempt = redis.call('HGET', KEYS[2], ARGV[1] .. ':a') or '1'
+  local envelope = '{"id":"' .. ARGV[1] .. '","d":' .. payload .. ',"a":' .. attempt .. '}'
+  redis.call('RPUSH', KEYS[4], envelope)
+  redis.call('HDEL', KEYS[2], ARGV[1], ARGV[1] .. ':a')
+end
+return 1`;
+var SIZE_SCRIPT = `-- INGENIUM_QUEUE_SIZE v1
+return redis.call('ZCARD', KEYS[1])`;
+var FAILED_COUNT_SCRIPT = `-- INGENIUM_QUEUE_FAILED_COUNT v1
+return redis.call('LLEN', KEYS[4])`;
+var RedisQueueStore = class {
+  client;
+  now;
+  /** KEYS passed to every script, in fixed order: pending, jobs, inflight, failed, seq. */
+  keys;
+  constructor(opts) {
+    this.client = opts.client;
+    this.now = opts.now ?? Date.now;
+    const prefix = opts.prefix ?? "ingenium:queue:";
+    this.keys = [
+      prefix + "pending",
+      prefix + "jobs",
+      prefix + "inflight",
+      prefix + "failed",
+      prefix + "seq"
+    ];
+  }
+  async enqueue(data) {
+    const id = await this.client.eval(ENQUEUE_SCRIPT, {
+      keys: this.keys,
+      arguments: [String(this.now()), JSON.stringify(data)]
+    });
+    return { id: String(id) };
+  }
+  async next() {
+    const result = await this.client.eval(NEXT_SCRIPT, {
+      keys: this.keys,
+      arguments: [String(this.now())]
+    });
+    if (result == null || !Array.isArray(result)) return null;
+    const [id, payload, attempt] = result;
+    if (id == null || payload == null) return null;
+    let data;
+    try {
+      data = JSON.parse(payload);
+    } catch {
+      return null;
+    }
+    return { id: String(id), data, attempt: Number(attempt) || 1 };
+  }
+  async ack(id) {
+    await this.client.eval(ACK_SCRIPT, { keys: this.keys, arguments: [id] });
+  }
+  async retry(id, delayMs) {
+    const readyAt = this.now() + Math.max(0, delayMs);
+    await this.client.eval(RETRY_SCRIPT, {
+      keys: this.keys,
+      arguments: [id, String(readyAt)]
+    });
+  }
+  async fail(id) {
+    await this.client.eval(FAIL_SCRIPT, { keys: this.keys, arguments: [id] });
+  }
+  async size() {
+    const n = await this.client.eval(SIZE_SCRIPT, {
+      keys: this.keys,
+      arguments: []
+    });
+    return Number(n) || 0;
+  }
+  async failedCount() {
+    const n = await this.client.eval(FAILED_COUNT_SCRIPT, {
+      keys: this.keys,
+      arguments: []
+    });
+    return Number(n) || 0;
+  }
+};
+
+export { RedisIdempotencyStore, RedisQueueStore, RedisRateLimitStore, RedisSessionStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session.ts","../src/idempotency.ts","../src/rate-limit.ts","../src/queue.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { SessionStore } from 'ingenium'\nimport type { RedisClientLike } from './client.ts'\n\nexport interface RedisSessionStoreOptions {\n  /** Connected Redis client. Caller owns lifecycle. */\n  client: RedisClientLike\n  /** Key prefix for every entry. Default `'ingenium:sess:'`. */\n  prefix?: string\n}\n\n/**\n * Redis-backed {@link SessionStore}. JSON-encodes session data and uses\n * `SET ... EX` so Redis owns TTL expiry — no sweeper, no clock drift between\n * the cookie expiry and the stored value.\n *\n * The store does NOT manage the client connection. Create + `.connect()` your\n * `createClient(...)` before constructing the store; close it during your\n * graceful shutdown hook.\n */\nexport class RedisSessionStore implements SessionStore {\n  private readonly client: RedisClientLike\n  private readonly prefix: string\n\n  constructor(opts: RedisSessionStoreOptions) {\n    this.client = opts.client\n    this.prefix = opts.prefix ?? 'ingenium:sess:'\n  }\n\n  async get(id: string): Promise<Record<string, unknown> | null> {\n    const raw = await this.client.get(this.prefix + id)\n    if (raw === null) return null\n    try {\n      const parsed = JSON.parse(raw)\n      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null\n      return parsed as Record<string, unknown>\n    } catch {\n      return null\n    }\n  }\n\n  async set(id: string, data: Record<string, unknown>, ttlSeconds: number): Promise<void> {\n    await this.client.set(this.prefix + id, JSON.stringify(data), { EX: ttlSeconds })\n  }\n\n  async destroy(id: string): Promise<void> {\n    await this.client.del(this.prefix + id)\n  }\n\n  async touch(id: string, ttlSeconds: number): Promise<void> {\n    await this.client.expire(this.prefix + id, ttlSeconds)\n  }\n}\n","import { Buffer } from 'node:buffer'\nimport type { CachedResponse, IdempotencyStore } from 'ingenium'\nimport type { RedisClientLike } from './client.ts'\n\n/**\n * Wire-format envelope used to JSON-encode a {@link CachedResponse} for\n * storage. Buffers are base64-encoded with a tag so we can faithfully restore\n * them on read — JSON.stringify of a Buffer would otherwise serialize as\n * `{ type: 'Buffer', data: [...] }`, which we'd have to special-case anyway.\n */\ninterface Envelope {\n  /** statusCode */\n  s: number\n  /** headers */\n  h: Record<string, string | string[]>\n  /** body: null | string | base64-Buffer */\n  b: null | { t: 's'; v: string } | { t: 'b'; v: string }\n}\n\nfunction encode(value: CachedResponse): string {\n  let body: Envelope['b'] = null\n  if (Buffer.isBuffer(value.body)) {\n    body = { t: 'b', v: value.body.toString('base64') }\n  } else if (typeof value.body === 'string') {\n    body = { t: 's', v: value.body }\n  }\n  const env: Envelope = { s: value.statusCode, h: value.headers, b: body }\n  return JSON.stringify(env)\n}\n\nfunction decode(raw: string): CachedResponse | null {\n  let env: Envelope\n  try {\n    env = JSON.parse(raw) as Envelope\n  } catch {\n    return null\n  }\n  if (env === null || typeof env !== 'object') return null\n  let body: CachedResponse['body'] = null\n  if (env.b !== null) {\n    body = env.b.t === 'b' ? Buffer.from(env.b.v, 'base64') : env.b.v\n  }\n  return { statusCode: env.s, headers: env.h, body }\n}\n\nexport interface RedisIdempotencyStoreOptions {\n  /** Connected Redis client. Caller owns lifecycle. */\n  client: RedisClientLike\n  /** Key prefix for every entry. Default `'ingenium:idem:'`. */\n  prefix?: string\n}\n\n/**\n * Redis-backed {@link IdempotencyStore}. Cached responses are JSON-serialized\n * (with Buffer bodies base64-encoded) and stored with `SET ... PX` so Redis\n * owns expiry. Suitable for multi-replica deployments where the replica that\n * served the original request may not be the one handling the retry.\n */\nexport class RedisIdempotencyStore implements IdempotencyStore {\n  private readonly client: RedisClientLike\n  private readonly prefix: string\n\n  constructor(opts: RedisIdempotencyStoreOptions) {\n    this.client = opts.client\n    this.prefix = opts.prefix ?? 'ingenium:idem:'\n  }\n\n  async get(key: string): Promise<CachedResponse | null> {\n    const raw = await this.client.get(this.prefix + key)\n    if (raw === null) return null\n    return decode(raw)\n  }\n\n  async set(key: string, value: CachedResponse, ttlMs: number): Promise<void> {\n    await this.client.set(this.prefix + key, encode(value), { PX: ttlMs })\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del(this.prefix + key)\n  }\n}\n","import type { RateLimitStore } from 'ingenium'\nimport type { RedisClientLike } from './client.ts'\n\n/**\n * Atomic fixed-window counter. INCR is atomic on its own; the `PEXPIRE`\n * piggybacks on the first hit so the window starts the moment the counter is\n * created. The trailing `PTTL` gives us the precise reset time without a\n * second round-trip and without trusting the caller's clock.\n *\n * The comment marker on line 1 is load-bearing for the in-memory fake used\n * by the test suite — see test/fake-client.ts. Real Redis ignores it.\n */\nconst HIT_SCRIPT = `-- INGENIUM_RATELIMIT_HIT v1\nlocal current = redis.call('INCR', KEYS[1])\nif current == 1 then\n  redis.call('PEXPIRE', KEYS[1], ARGV[1])\nend\nlocal ttl = redis.call('PTTL', KEYS[1])\nreturn {current, ttl}`\n\nexport interface RedisRateLimitStoreOptions {\n  /** Connected Redis client. Caller owns lifecycle. */\n  client: RedisClientLike\n  /** Key prefix for every entry. Default `'ingenium:rl:'`. */\n  prefix?: string\n}\n\n/**\n * Redis-backed {@link RateLimitStore}. Uses a single Lua call per hit so the\n * INCR + PEXPIRE + PTTL trio is atomic — no race where two replicas both see\n * `count == 1` and each set their own expiry, and no race where the counter\n * exists without a TTL because the expire happened in a separate round-trip\n * that lost.\n *\n * `resetAt` is computed from `PTTL` on the server side, so the value is\n * consistent across replicas even if their clocks drift. We add `Date.now()`\n * locally only to produce the absolute timestamp the rest of Ingenium\n * works with; a small clock skew there affects header reporting only, not\n * the actual rate-limit decision (which Redis owns).\n */\nexport class RedisRateLimitStore implements RateLimitStore {\n  private readonly client: RedisClientLike\n  private readonly prefix: string\n\n  constructor(opts: RedisRateLimitStoreOptions) {\n    this.client = opts.client\n    this.prefix = opts.prefix ?? 'ingenium:rl:'\n  }\n\n  async hit(key: string, windowMs: number): Promise<{ count: number; resetAt: number }> {\n    const result = (await this.client.eval(HIT_SCRIPT, {\n      keys: [this.prefix + key],\n      arguments: [String(windowMs)],\n    })) as [number, number]\n\n    if (!Array.isArray(result) || result.length !== 2) {\n      throw new Error(\n        `RedisRateLimitStore: unexpected EVAL result shape: ${JSON.stringify(result)}`,\n      )\n    }\n    const [count, ttlMs] = result\n    return { count, resetAt: Date.now() + Math.max(0, ttlMs) }\n  }\n\n  async reset(key: string): Promise<void> {\n    await this.client.del(this.prefix + key)\n  }\n}\n","import type { QueueStore } from 'ingenium'\nimport type { RedisClientLike } from './client.ts'\n\n/**\n * Lua scripts backing {@link RedisQueueStore}. Every multi-step operation runs\n * server-side in a single `EVAL` so the steps are atomic against concurrent\n * workers on other replicas — Redis executes a script to completion before\n * servicing any other command, so there is no window where (e.g.) two workers\n * both ZREM the same id, or where a job is removed from `pending` but not yet\n * recorded in-flight.\n *\n * The marker comment on line 1 of each script is load-bearing for the\n * in-memory fake used by the test suite — see test/fake-client.ts, which\n * dispatches on it. Real Redis ignores the comment.\n *\n * Key layout (KEYS, in the order every script receives them):\n *   1. pending  — ZSET, score = ready-time ms (notBefore), member = id.\n *                 Picking the lowest score <= now gives FIFO with delay support.\n *   2. jobs     — HASH. Two fields per job: `<id>` holds the raw JSON payload,\n *                 `<id>:a` holds the attempt count as a plain integer. Splitting\n *                 the count into its own field lets `retry` use `HINCRBY` —\n *                 no parsing of the (arbitrary, possibly `}`-containing) payload\n *                 JSON inside Lua, which a single-regex envelope can't do safely.\n *   3. inflight — SET of ids currently delivered but not yet acked/retried/failed.\n *   4. failed   — LIST (dead-letter); RPUSH on fail, LLEN for the count.\n *   5. seq      — STRING counter; INCR yields monotonic ids.\n *\n * The `:a` field suffix is an ARGV (not hard-coded in the script) only for the\n * fake's benefit; in real Lua it's concatenated. Both store + fake build it the\n * same way: `id .. ':a'`.\n */\n\n/**\n * Append a job to the tail. `now` (ARGV[1]) is the score so a freshly enqueued\n * job is immediately ready and ordered after everything already pending —\n * equal scores tie-break by member, and ids are monotonic via INCR, so equal\n * scores still resolve to enqueue order. attempt starts at 1, mirroring\n * MemoryQueueStore.\n */\nconst ENQUEUE_SCRIPT = `-- INGENIUM_QUEUE_ENQUEUE v1\nlocal id = tostring(redis.call('INCR', KEYS[5]))\nredis.call('HSET', KEYS[2], id, ARGV[2])\nredis.call('HSET', KEYS[2], id .. ':a', '1')\nredis.call('ZADD', KEYS[1], ARGV[1], id)\nreturn id`\n\n/**\n * Atomically pop the next ready job. ZRANGEBYSCORE with `-inf`..now and\n * `LIMIT 0 1` yields the lowest-score member whose delay has elapsed; if none\n * is ready (queue empty, or every pending job is still delayed) we return nil\n * — matching MemoryQueueStore returning `null`. The chosen id is ZREM'd from\n * pending and SADD'd to inflight in the same script so it can never be picked\n * twice. Returns `{id, payloadJson, attempt}`.\n */\nconst NEXT_SCRIPT = `-- INGENIUM_QUEUE_NEXT v1\nlocal ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, 1)\nif not ids[1] then\n  return nil\nend\nlocal id = ids[1]\nredis.call('ZREM', KEYS[1], id)\nredis.call('SADD', KEYS[3], id)\nlocal payload = redis.call('HGET', KEYS[2], id)\nlocal attempt = redis.call('HGET', KEYS[2], id .. ':a')\nreturn {id, payload, attempt}`\n\n/**\n * Remove a completed in-flight job entirely. SREM + HDEL (both the payload and\n * the attempt field) clears all trace; a no-op if the id is unknown (already\n * acked), so ack is idempotent.\n */\nconst ACK_SCRIPT = `-- INGENIUM_QUEUE_ACK v1\nredis.call('SREM', KEYS[3], ARGV[1])\nredis.call('HDEL', KEYS[2], ARGV[1], ARGV[1] .. ':a')\nreturn 1`\n\n/**\n * Re-enqueue an in-flight job after a delay, incrementing its attempt counter\n * (the MUST-increment contract from QueueStore). `HINCRBY` on the `<id>:a`\n * field is atomic and needs no payload parsing. ZADD back into pending at score\n * `readyAt` (ARGV[2] = now + delayMs). If the id is not in-flight we do nothing\n * — a job already acked/failed can't be retried.\n */\nconst RETRY_SCRIPT = `-- INGENIUM_QUEUE_RETRY v1\nif redis.call('SREM', KEYS[3], ARGV[1]) == 0 then\n  return 0\nend\nif redis.call('HEXISTS', KEYS[2], ARGV[1]) == 0 then\n  return 0\nend\nredis.call('HINCRBY', KEYS[2], ARGV[1] .. ':a', 1)\nredis.call('ZADD', KEYS[1], ARGV[2], ARGV[1])\nreturn 1`\n\n/**\n * Move an in-flight job to the dead-letter list. We RPUSH a self-contained\n * envelope `{\"d\":<payload>,\"a\":<attempt>}` onto `failed` (built by concatenating\n * the raw payload JSON and the integer attempt — no re-encode of the payload),\n * then drop the in-flight marker and both hash fields. No-op if the id is not\n * in-flight, so fail is idempotent.\n */\nconst FAIL_SCRIPT = `-- INGENIUM_QUEUE_FAIL v1\nif redis.call('SREM', KEYS[3], ARGV[1]) == 0 then\n  return 0\nend\nlocal payload = redis.call('HGET', KEYS[2], ARGV[1])\nif payload then\n  local attempt = redis.call('HGET', KEYS[2], ARGV[1] .. ':a') or '1'\n  local envelope = '{\"id\":\"' .. ARGV[1] .. '\",\"d\":' .. payload .. ',\"a\":' .. attempt .. '}'\n  redis.call('RPUSH', KEYS[4], envelope)\n  redis.call('HDEL', KEYS[2], ARGV[1], ARGV[1] .. ':a')\nend\nreturn 1`\n\n/** `size()` = ZCARD pending (includes delayed jobs). */\nconst SIZE_SCRIPT = `-- INGENIUM_QUEUE_SIZE v1\nreturn redis.call('ZCARD', KEYS[1])`\n\n/** `failedCount()` = LLEN of the dead-letter list. */\nconst FAILED_COUNT_SCRIPT = `-- INGENIUM_QUEUE_FAILED_COUNT v1\nreturn redis.call('LLEN', KEYS[4])`\n\nexport interface RedisQueueStoreOptions {\n  /** Connected Redis client. Caller owns lifecycle. */\n  client: RedisClientLike\n  /**\n   * Key prefix for every structure owned by this queue instance. Default\n   * `'ingenium:queue:'`. Two queues that must not share work need distinct\n   * prefixes (e.g. `'ingenium:queue:emails:'`).\n   */\n  prefix?: string\n  /**\n   * Clock used to stamp ready-times (ZSET scores). Defaults to `Date.now`.\n   * Overridable so tests can drive virtual time; production code never sets it.\n   */\n  now?: () => number\n}\n\n/**\n * Redis-backed {@link QueueStore}. A FIFO job queue with delayed retries and a\n * dead-letter list, sharing state across replicas so any worker on any pod can\n * pick up any job.\n *\n * Atomicity: every operation that touches more than one key (`next`, `retry`,\n * `fail`, and—for uniformity and to keep {@link RedisClientLike} tiny—`enqueue`,\n * `ack`, `size`, `failedCount`) runs as a single Lua `EVAL`. This is what keeps\n * the client surface unchanged: we never need MULTI/WATCH or any command beyond\n * `eval`. Redis runs each script to completion atomically, so concurrent workers\n * can't double-deliver a job or lose a payload between the ZREM and the\n * in-flight SADD.\n *\n * Delivery guarantee: at-least-once. A job that is `next()`-ed but whose worker\n * crashes before `ack`/`retry`/`fail` stays in the `inflight` set and in the\n * `jobs` hash, but NOT in `pending` — it will not be re-delivered automatically\n * by this store (there is no visibility-timeout sweeper). That matches\n * {@link MemoryQueueStore}, which also leaves crashed jobs stuck in its\n * in-flight map. Add a reaper that re-enqueues stale inflight ids if you need\n * crash recovery; the data model (inflight SET + jobs HASH) supports it.\n *\n * `size()` returns the pending count INCLUDING delayed (not-yet-ready) jobs,\n * mirroring `MemoryQueueStore.size()` which returns `pending.length`. Delayed\n * jobs live in the same ZSET with a future score, so `ZCARD` counts them.\n */\nexport class RedisQueueStore<TData> implements QueueStore<TData> {\n  private readonly client: RedisClientLike\n  private readonly now: () => number\n  /** KEYS passed to every script, in fixed order: pending, jobs, inflight, failed, seq. */\n  private readonly keys: readonly [string, string, string, string, string]\n\n  constructor(opts: RedisQueueStoreOptions) {\n    this.client = opts.client\n    this.now = opts.now ?? Date.now\n    const prefix = opts.prefix ?? 'ingenium:queue:'\n    this.keys = [\n      prefix + 'pending',\n      prefix + 'jobs',\n      prefix + 'inflight',\n      prefix + 'failed',\n      prefix + 'seq',\n    ]\n  }\n\n  async enqueue(data: TData): Promise<{ id: string }> {\n    const id = (await this.client.eval(ENQUEUE_SCRIPT, {\n      keys: this.keys,\n      arguments: [String(this.now()), JSON.stringify(data)],\n    })) as string\n    return { id: String(id) }\n  }\n\n  async next(): Promise<{ id: string; data: TData; attempt: number } | null> {\n    const result = (await this.client.eval(NEXT_SCRIPT, {\n      keys: this.keys,\n      arguments: [String(this.now())],\n    })) as [string, string | null, string | null] | null\n\n    if (result == null || !Array.isArray(result)) return null\n    const [id, payload, attempt] = result\n    if (id == null || payload == null) return null\n    let data: TData\n    try {\n      data = JSON.parse(payload) as TData\n    } catch {\n      return null\n    }\n    return { id: String(id), data, attempt: Number(attempt) || 1 }\n  }\n\n  async ack(id: string): Promise<void> {\n    await this.client.eval(ACK_SCRIPT, { keys: this.keys, arguments: [id] })\n  }\n\n  async retry(id: string, delayMs: number): Promise<void> {\n    const readyAt = this.now() + Math.max(0, delayMs)\n    await this.client.eval(RETRY_SCRIPT, {\n      keys: this.keys,\n      arguments: [id, String(readyAt)],\n    })\n  }\n\n  async fail(id: string): Promise<void> {\n    await this.client.eval(FAIL_SCRIPT, { keys: this.keys, arguments: [id] })\n  }\n\n  async size(): Promise<number> {\n    const n = (await this.client.eval(SIZE_SCRIPT, {\n      keys: this.keys,\n      arguments: [],\n    })) as number\n    return Number(n) || 0\n  }\n\n  async failedCount(): Promise<number> {\n    const n = (await this.client.eval(FAILED_COUNT_SCRIPT, {\n      keys: this.keys,\n      arguments: [],\n    })) as number\n    return Number(n) || 0\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ingenium-redis",
+  "version": "0.0.1",
+  "description": "Redis-backed session, idempotency, rate-limit, and background-job queue stores for Ingenium. Drop-in replacements for the in-memory defaults; required for multi-instance deployments.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "redis",
+    "session",
+    "idempotency",
+    "rate-limit",
+    "queue",
+    "jobs",
+    "background-jobs",
+    "ingenium",
+    "multi-instance"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "ingenium": "*"
+  },
+  "peerDependenciesMeta": {
+    "ingenium": { "optional": false }
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal Redis-client surface the stores rely on.
+ *
+ * Intentionally duck-typed against node-redis v4+ (`@redis/client`) so users
+ * can pass their existing `createClient()` instance directly without an extra
+ * type adapter. ioredis users can shim it in a few lines if they prefer that
+ * client.
+ *
+ * The surface is intentionally tiny — only the commands the three stores
+ * actually call. Adding methods here means tightening what a custom client
+ * must implement, so resist.
+ */
+
+export interface RedisSetOptions {
+  /** Set TTL in seconds. Mutually exclusive with `PX`. */
+  EX?: number
+  /** Set TTL in milliseconds. Mutually exclusive with `EX`. */
+  PX?: number
+  /** Only set if the key does not already exist. */
+  NX?: boolean
+}
+
+export interface RedisClientLike {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string, options?: RedisSetOptions): Promise<string | null>
+  del(key: string | readonly string[]): Promise<number>
+  expire(key: string, seconds: number): Promise<boolean | number>
+  /**
+   * Run a Lua script server-side. node-redis v4 uses the `{ keys, arguments }`
+   * options bag — ioredis uses positional args, so ioredis adopters need to
+   * shim this method.
+   */
+  eval(
+    script: string,
+    options: { keys: readonly string[]; arguments: readonly string[] },
+  ): Promise<unknown>
+}

package/src/idempotency.ts

@@ -0,0 +1,81 @@
+import { Buffer } from 'node:buffer'
+import type { CachedResponse, IdempotencyStore } from 'ingenium'
+import type { RedisClientLike } from './client.ts'
+
+/**
+ * Wire-format envelope used to JSON-encode a {@link CachedResponse} for
+ * storage. Buffers are base64-encoded with a tag so we can faithfully restore
+ * them on read — JSON.stringify of a Buffer would otherwise serialize as
+ * `{ type: 'Buffer', data: [...] }`, which we'd have to special-case anyway.
+ */
+interface Envelope {
+  /** statusCode */
+  s: number
+  /** headers */
+  h: Record<string, string | string[]>
+  /** body: null | string | base64-Buffer */
+  b: null | { t: 's'; v: string } | { t: 'b'; v: string }
+}
+
+function encode(value: CachedResponse): string {
+  let body: Envelope['b'] = null
+  if (Buffer.isBuffer(value.body)) {
+    body = { t: 'b', v: value.body.toString('base64') }
+  } else if (typeof value.body === 'string') {
+    body = { t: 's', v: value.body }
+  }
+  const env: Envelope = { s: value.statusCode, h: value.headers, b: body }
+  return JSON.stringify(env)
+}
+
+function decode(raw: string): CachedResponse | null {
+  let env: Envelope
+  try {
+    env = JSON.parse(raw) as Envelope
+  } catch {
+    return null
+  }
+  if (env === null || typeof env !== 'object') return null
+  let body: CachedResponse['body'] = null
+  if (env.b !== null) {
+    body = env.b.t === 'b' ? Buffer.from(env.b.v, 'base64') : env.b.v
+  }
+  return { statusCode: env.s, headers: env.h, body }
+}
+
+export interface RedisIdempotencyStoreOptions {
+  /** Connected Redis client. Caller owns lifecycle. */
+  client: RedisClientLike
+  /** Key prefix for every entry. Default `'ingenium:idem:'`. */
+  prefix?: string
+}
+
+/**
+ * Redis-backed {@link IdempotencyStore}. Cached responses are JSON-serialized
+ * (with Buffer bodies base64-encoded) and stored with `SET ... PX` so Redis
+ * owns expiry. Suitable for multi-replica deployments where the replica that
+ * served the original request may not be the one handling the retry.
+ */
+export class RedisIdempotencyStore implements IdempotencyStore {
+  private readonly client: RedisClientLike
+  private readonly prefix: string
+
+  constructor(opts: RedisIdempotencyStoreOptions) {
+    this.client = opts.client
+    this.prefix = opts.prefix ?? 'ingenium:idem:'
+  }
+
+  async get(key: string): Promise<CachedResponse | null> {
+    const raw = await this.client.get(this.prefix + key)
+    if (raw === null) return null
+    return decode(raw)
+  }
+
+  async set(key: string, value: CachedResponse, ttlMs: number): Promise<void> {
+    await this.client.set(this.prefix + key, encode(value), { PX: ttlMs })
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.del(this.prefix + key)
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Redis-backed stores for Ingenium. Drop-in replacements for the in-memory
+ * defaults shipped in the core package — required for multi-instance
+ * deployments where sessions, idempotency replays, rate-limit counters, and
+ * background-job queues must share state across replicas.
+ *
+ * Bring your own connected client (node-redis v4+ recommended). The package
+ * intentionally does not own connection lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'redis'
+ * import { ingenium, sessionMiddleware, IdempotencyMemoryStore } from 'ingenium'
+ * import {
+ *   RedisSessionStore,
+ *   RedisIdempotencyStore,
+ *   RedisRateLimitStore,
+ *   RedisQueueStore,
+ * } from 'ingenium-redis'
+ *
+ * const client = createClient({ url: process.env.REDIS_URL })
+ * await client.connect()
+ *
+ * const app = ingenium()
+ * app.use(sessionMiddleware({
+ *   secret: [process.env.SESSION_SECRET!],
+ *   store: new RedisSessionStore({ client }),
+ * }))
+ * app.use(ingenium.idempotency({ store: new RedisIdempotencyStore({ client }) }))
+ * app.use(ingenium.rateLimit({
+ *   windowMs: 60_000,
+ *   limit: 100,
+ *   store: new RedisRateLimitStore({ client }),
+ * }))
+ *
+ * // Background jobs shared across replicas:
+ * app.queue('emails', {
+ *   store: new RedisQueueStore({ client }),
+ * }, async (job) => { await sendEmail(job.data) })
+ * ```
+ */
+
+export { RedisSessionStore, type RedisSessionStoreOptions } from './session.ts'
+export {
+  RedisIdempotencyStore,
+  type RedisIdempotencyStoreOptions,
+} from './idempotency.ts'
+export {
+  RedisRateLimitStore,
+  type RedisRateLimitStoreOptions,
+} from './rate-limit.ts'
+export { RedisQueueStore, type RedisQueueStoreOptions } from './queue.ts'
+export type { RedisClientLike, RedisSetOptions } from './client.ts'