Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,92 @@
/**
* Options accepted by `SharedStoreAdapter.set`.
*
* - `ttlSeconds`: when set, the key expires after the given number of
* seconds. Mirrors Redis `EX`.
* - `nx`: when true, the call only succeeds if the key does not yet
* exist. Mirrors Redis `NX`.
*/
export interface SharedStoreSetOptions {
ttlSeconds?: number;
nx?: boolean;
}
/**
* Options for the streaming SCAN cursor.
*
* `count` is a hint to the underlying store; adapters are free to use it
* for pagination or to ignore it. The default is 100.
*/
export interface SharedStoreScanOptions {
count?: number;
}
/**
* Minimal Redis-compatible adapter surface. Higher-level helpers in
* `src/helpers/` rely only on these primitives so they keep working
* against the in-process `MemoryAdapter` used in dev/test.
*
* Implementations MUST keep operations atomic at the level expected by
* Redis (e.g. `set NX`, `incr`, sorted-set ops). Pub/Sub `subscribe`
* must return a disposer that fully unwires the handler.
*/
export interface SharedStoreAdapter {
/** Read a string value. Returns `null` for missing or expired keys. */
get(key: string): Promise<string | null>;
/**
* Write a string value. Returns `true` when the key was written and
* `false` when an `nx` constraint blocked the write. Always returns
* `true` when `nx` is not set.
*/
set(key: string, value: string, opts?: SharedStoreSetOptions): Promise<boolean>;
/** Delete a key. Returns the number of keys removed (0 or 1). */
del(key: string): Promise<number>;
/**
* Increment a numeric counter by `by` (default 1). The key is created
* as `0` if it does not yet exist and the increment is then applied.
*/
incr(key: string, by?: number): Promise<number>;
/**
* Set a TTL on an existing key. Returns `true` when the key existed
* and the TTL was applied, `false` when the key was missing.
*/
expire(key: string, ttlSeconds: number): Promise<boolean>;
/** Read multiple keys in one round trip. */
mget(keys: string[]): Promise<(string | null)[]>;
/** Async iterator over keys matching a glob pattern. */
scan(pattern: string, opts?: SharedStoreScanOptions): AsyncIterable<string>;
/** Publish a message to a channel. Returns the number of receivers. */
publish(channel: string, message: string): Promise<number>;
/**
* Subscribe to a channel. The returned disposer must be awaited to
* guarantee the underlying listener was torn down.
*/
subscribe(channel: string, handler: (message: string) => void | Promise<void>): Promise<() => Promise<void>>;
/** Sorted-set add. Returns the number of elements actually added. */
zAdd(key: string, score: number, member: string): Promise<number>;
/** Remove sorted-set members whose score lies in [min, max]. */
zRemRangeByScore(key: string, min: number, max: number): Promise<number>;
/** Cardinality of a sorted set. Returns 0 for missing keys. */
zCard(key: string): Promise<number>;
/**
* Execute a Lua-like atomic compound operation. In the Redis adapter
* this is real `EVAL`. In the memory adapter, the script body is
* matched against a registered TypeScript equivalent.
*/
eval(script: string, keys: string[], args: string[]): Promise<unknown>;
/**
* Register a handler that fires every time the backing connection is
* re-established AFTER it has been lost (i.e. NOT the very first
* connect). Used by L1-holding helpers to flush their local caches
* because pub/sub has no persistence and invalidations published
* during the disconnect window are silently dropped.
*
* Returns a disposer that removes the listener. Adapters without a
* disconnect concept (e.g. the memory adapter) MUST still implement
* this as a no-op returning a noop disposer so callers do not need
* to feature-detect.
*/
onReconnect(handler: () => void | Promise<void>): () => void;
/** Release any backing connections or timers. Idempotent. */
close(): Promise<void>;
}
@@ -0,0 +1 @@
export type { SharedStoreAdapter, SharedStoreSetOptions, SharedStoreScanOptions } from "./adapter.js";
@@ -0,0 +1,223 @@
import { afterEach, describe, expect, test, vi } from "vitest";
import { MemoryAdapter } from "./memory.js";
afterEach(() => {
vi.useRealTimers();
});
describe("MemoryAdapter — kv operations", () => {
test("set then get returns the stored value", async () => {
const adapter = new MemoryAdapter();
await adapter.set("a", "1");
expect(await adapter.get("a")).toBe("1");
await adapter.close();
});
test("get returns null for unknown keys", async () => {
const adapter = new MemoryAdapter();
expect(await adapter.get("missing")).toBeNull();
await adapter.close();
});
test("set NX rejects writes when the key exists", async () => {
const adapter = new MemoryAdapter();
expect(await adapter.set("k", "first", { nx: true })).toBe(true);
expect(await adapter.set("k", "second", { nx: true })).toBe(false);
expect(await adapter.get("k")).toBe("first");
await adapter.close();
});
test("set NX succeeds again once the previous key has expired", async () => {
let now = 1_000;
const adapter = new MemoryAdapter({ now: () => now });
expect(await adapter.set("k", "first", { nx: true, ttlSeconds: 1 })).toBe(true);
now += 2_000;
expect(await adapter.set("k", "second", { nx: true })).toBe(true);
expect(await adapter.get("k")).toBe("second");
await adapter.close();
});
test("TTL expiry is observed lazily on get", async () => {
let now = 0;
const adapter = new MemoryAdapter({ now: () => now });
await adapter.set("k", "v", { ttlSeconds: 1 });
expect(await adapter.get("k")).toBe("v");
now = 1_500;
expect(await adapter.get("k")).toBeNull();
await adapter.close();
});
test("del returns 1 for existing keys and 0 otherwise", async () => {
const adapter = new MemoryAdapter();
await adapter.set("k", "v");
expect(await adapter.del("k")).toBe(1);
expect(await adapter.del("k")).toBe(0);
await adapter.close();
});
test("incr creates the key and increments existing values", async () => {
const adapter = new MemoryAdapter();
expect(await adapter.incr("c")).toBe(1);
expect(await adapter.incr("c", 4)).toBe(5);
await adapter.close();
});
test("incr preserves the existing expiry", async () => {
let now = 0;
const adapter = new MemoryAdapter({ now: () => now });
await adapter.set("c", "0", { ttlSeconds: 1 });
await adapter.incr("c");
now = 2_000;
expect(await adapter.get("c")).toBeNull();
await adapter.close();
});
test("incr rejects non-numeric keys", async () => {
const adapter = new MemoryAdapter();
await adapter.set("c", "abc");
await expect(adapter.incr("c")).rejects.toThrow(/non-numeric/);
await adapter.close();
});
test("expire sets ttl on existing keys and returns false for missing ones", async () => {
let now = 0;
const adapter = new MemoryAdapter({ now: () => now });
await adapter.set("k", "v");
expect(await adapter.expire("k", 1)).toBe(true);
expect(await adapter.expire("missing", 5)).toBe(false);
now = 2_000;
expect(await adapter.get("k")).toBeNull();
await adapter.close();
});
test("mget preserves order and reports nulls for missing keys", async () => {
const adapter = new MemoryAdapter();
await adapter.set("a", "1");
await adapter.set("c", "3");
expect(await adapter.mget(["a", "b", "c"])).toEqual(["1", null, "3"]);
await adapter.close();
});
});
describe("MemoryAdapter — scan", () => {
test("yields keys matching a glob pattern", async () => {
const adapter = new MemoryAdapter();
await adapter.set("user:1", "x");
await adapter.set("user:2", "y");
await adapter.set("other:3", "z");
const collected: string[] = [];
for await (const key of adapter.scan("user:*")) {
collected.push(key);
}
expect(collected.sort()).toEqual(["user:1", "user:2"]);
await adapter.close();
});
test("skips expired keys", async () => {
let now = 0;
const adapter = new MemoryAdapter({ now: () => now });
await adapter.set("temp:1", "x", { ttlSeconds: 1 });
await adapter.set("temp:2", "y");
now = 2_000;
const collected: string[] = [];
for await (const key of adapter.scan("temp:*")) {
collected.push(key);
}
expect(collected).toEqual(["temp:2"]);
await adapter.close();
});
});
describe("MemoryAdapter — pub/sub", () => {
test("publish triggers subscribers and returns the listener count", async () => {
const adapter = new MemoryAdapter();
const received: string[] = [];
const unsubscribe = await adapter.subscribe("c", (msg) => {
received.push(msg);
});
expect(await adapter.publish("c", "hello")).toBe(1);
await new Promise((resolve) => setTimeout(resolve, 0));
expect(received).toEqual(["hello"]);
await unsubscribe();
expect(await adapter.publish("c", "ignored")).toBe(0);
await adapter.close();
});
test("subscriber errors do not break other subscribers", async () => {
const adapter = new MemoryAdapter();
const calls: string[] = [];
await adapter.subscribe("c", () => {
throw new Error("boom");
});
await adapter.subscribe("c", (msg) => {
calls.push(msg);
});
await adapter.publish("c", "a");
await new Promise((resolve) => setTimeout(resolve, 0));
expect(calls).toEqual(["a"]);
await adapter.close();
});
});
describe("MemoryAdapter — sorted sets", () => {
test("zAdd inserts and updates scores", async () => {
const adapter = new MemoryAdapter();
expect(await adapter.zAdd("k", 1, "a")).toBe(1);
expect(await adapter.zAdd("k", 2, "a")).toBe(0);
expect(await adapter.zCard("k")).toBe(1);
await adapter.close();
});
test("zRemRangeByScore removes the matching window", async () => {
const adapter = new MemoryAdapter();
await adapter.zAdd("k", 1, "a");
await adapter.zAdd("k", 5, "b");
await adapter.zAdd("k", 10, "c");
expect(await adapter.zRemRangeByScore("k", 0, 5)).toBe(2);
expect(await adapter.zCard("k")).toBe(1);
await adapter.close();
});
test("zCard returns 0 for unknown keys", async () => {
const adapter = new MemoryAdapter();
expect(await adapter.zCard("missing")).toBe(0);
await adapter.close();
});
test("del also clears sorted sets", async () => {
const adapter = new MemoryAdapter();
await adapter.zAdd("k", 1, "a");
expect(await adapter.del("k")).toBe(1);
expect(await adapter.zCard("k")).toBe(0);
await adapter.close();
});
});
describe("MemoryAdapter — eval / scripts", () => {
test("unknown scripts reject", async () => {
const adapter = new MemoryAdapter();
await expect(adapter.eval("unknown-script", [], [])).rejects.toThrow(/unknown eval script/);
await adapter.close();
});
test("registered scripts execute against the adapter", async () => {
MemoryAdapter.registerScript("test-script", async (instance, keys, args) => {
await instance.set(keys[0], args[0]);
return `${keys[0]}=${args[0]}`;
});
const adapter = new MemoryAdapter();
const result = await adapter.eval("test-script", ["x"], ["1"]);
expect(result).toBe("x=1");
expect(await adapter.get("x")).toBe("1");
expect(MemoryAdapter.hasRegisteredScript("test-script")).toBe(true);
await adapter.close();
});
});
describe("MemoryAdapter — lifecycle", () => {
test("close prevents further operations", async () => {
const adapter = new MemoryAdapter();
await adapter.close();
await expect(adapter.get("k")).rejects.toThrow(/closed/);
});
});
@@ -0,0 +1,265 @@
import { EventEmitter } from "node:events";
import type { SharedStoreAdapter, SharedStoreScanOptions, SharedStoreSetOptions } from "./adapter.js";
interface KvEntry {
value: string;
expiresAt: number | null;
}
interface SortedSetMember {
score: number;
member: string;
}
/**
* Registry for `eval` scripts. The memory adapter cannot run real Lua,
* so it matches the script body against a TypeScript equivalent that
* mirrors the Redis behavior. New helpers register their script via
* `MemoryAdapter.registerScript` so the same script string can be sent
* through `eval` against either backend.
*/
export type MemoryScriptHandler = (
adapter: MemoryAdapter,
keys: string[],
args: string[],
) => Promise<unknown> | unknown;
const scriptRegistry = new Map<string, MemoryScriptHandler>();
/**
* In-process implementation of `SharedStoreAdapter` for dev, tests, and
* single-instance deployments. TTLs are evaluated lazily on read; no
* background timers are used so tests can exit cleanly.
*/
export class MemoryAdapter implements SharedStoreAdapter {
private readonly kv = new Map<string, KvEntry>();
private readonly sortedSets = new Map<string, SortedSetMember[]>();
private readonly emitter = new EventEmitter();
private readonly clock: () => number;
private closed = false;
constructor(options: { now?: () => number } = {}) {
this.clock = options.now ?? (() => Date.now());
this.emitter.setMaxListeners(0);
}
/**
* Register a TypeScript equivalent of a Redis Lua script so that the
* same `eval(script, keys, args)` call works against both adapters.
*/
static registerScript(script: string, handler: MemoryScriptHandler): void {
scriptRegistry.set(script, handler);
}
static hasRegisteredScript(script: string): boolean {
return scriptRegistry.has(script);
}
async get(key: string): Promise<string | null> {
this.assertOpen();
const entry = this.kv.get(key);
if (!entry) {
return null;
}
if (this.isExpired(entry)) {
this.kv.delete(key);
return null;
}
return entry.value;
}
async set(key: string, value: string, opts: SharedStoreSetOptions = {}): Promise<boolean> {
this.assertOpen();
if (opts.nx) {
const existing = this.kv.get(key);
if (existing && !this.isExpired(existing)) {
return false;
}
}
const expiresAt =
typeof opts.ttlSeconds === "number" && opts.ttlSeconds > 0 ? this.clock() + opts.ttlSeconds * 1000 : null;
this.kv.set(key, { value, expiresAt });
return true;
}
async del(key: string): Promise<number> {
this.assertOpen();
const existed = this.kv.delete(key);
const setExisted = this.sortedSets.delete(key);
return existed || setExisted ? 1 : 0;
}
async incr(key: string, by = 1): Promise<number> {
this.assertOpen();
const entry = this.kv.get(key);
let current = 0;
let expiresAt: number | null = null;
if (entry && !this.isExpired(entry)) {
const parsed = Number.parseInt(entry.value, 10);
if (Number.isNaN(parsed)) {
throw new Error(`incr called on non-numeric key: ${key}`);
}
current = parsed;
expiresAt = entry.expiresAt;
}
const next = current + by;
this.kv.set(key, { value: String(next), expiresAt });
return next;
}
async expire(key: string, ttlSeconds: number): Promise<boolean> {
this.assertOpen();
const entry = this.kv.get(key);
if (!entry || this.isExpired(entry)) {
if (entry) this.kv.delete(key);
return false;
}
entry.expiresAt = ttlSeconds > 0 ? this.clock() + ttlSeconds * 1000 : null;
return true;
}
async mget(keys: string[]): Promise<(string | null)[]> {
this.assertOpen();
return Promise.all(keys.map((key) => this.get(key)));
}
scan(pattern: string, opts: SharedStoreScanOptions = {}): AsyncIterable<string> {
this.assertOpen();
const regex = patternToRegExp(pattern);
const snapshot: string[] = [];
for (const [key, entry] of this.kv.entries()) {
if (!this.isExpired(entry) && regex.test(key)) {
snapshot.push(key);
}
}
const batchSize = Math.max(1, opts.count ?? 100);
let index = 0;
return {
[Symbol.asyncIterator]: () => ({
async next() {
if (index >= snapshot.length) {
return { value: undefined as unknown as string, done: true };
}
const value = snapshot[index];
index += 1;
// batchSize is honored implicitly by sequential iteration; the
// counter exists so callers can reason about it in logs.
void batchSize;
return { value, done: false };
},
}),
};
}
async publish(channel: string, message: string): Promise<number> {
this.assertOpen();
const listeners = this.emitter.listenerCount(channel);
this.emitter.emit(channel, message);
return listeners;
}
async subscribe(channel: string, handler: (message: string) => void | Promise<void>): Promise<() => Promise<void>> {
this.assertOpen();
const wrapped = (message: string) => {
// Defer handler errors to the next tick so other subscribers still run.
Promise.resolve()
.then(() => handler(message))
.catch(() => {
/* swallowed; consumers handle their own errors */
});
};
this.emitter.on(channel, wrapped);
return async () => {
this.emitter.off(channel, wrapped);
};
}
async zAdd(key: string, score: number, member: string): Promise<number> {
this.assertOpen();
const set = this.sortedSets.get(key) ?? [];
const existingIndex = set.findIndex((entry) => entry.member === member);
if (existingIndex >= 0) {
set[existingIndex].score = score;
this.sortedSets.set(key, set);
return 0;
}
set.push({ score, member });
this.sortedSets.set(key, set);
return 1;
}
async zRemRangeByScore(key: string, min: number, max: number): Promise<number> {
this.assertOpen();
const set = this.sortedSets.get(key);
if (!set) return 0;
const before = set.length;
const remaining = set.filter((entry) => entry.score < min || entry.score > max);
if (remaining.length === 0) {
this.sortedSets.delete(key);
} else {
this.sortedSets.set(key, remaining);
}
return before - remaining.length;
}
async zCard(key: string): Promise<number> {
this.assertOpen();
return this.sortedSets.get(key)?.length ?? 0;
}
async eval(script: string, keys: string[], args: string[]): Promise<unknown> {
this.assertOpen();
const handler = scriptRegistry.get(script);
if (!handler) {
throw new Error("shared-store memory adapter: unknown eval script (use MemoryAdapter.registerScript)");
}
return handler(this, keys, args);
}
onReconnect(_handler: () => void | Promise<void>): () => void {
// The in-process memory adapter has no connection that can drop, so
// there is nothing to wire. Returning a noop disposer keeps callers
// adapter-agnostic.
void _handler;
return () => {
/* no-op */
};
}
async close(): Promise<void> {
this.closed = true;
this.kv.clear();
this.sortedSets.clear();
this.emitter.removeAllListeners();
}
private assertOpen(): void {
if (this.closed) {
throw new Error("shared-store memory adapter is closed");
}
}
private isExpired(entry: KvEntry): boolean {
return entry.expiresAt !== null && entry.expiresAt <= this.clock();
}
}
function patternToRegExp(pattern: string): RegExp {
// Translate a tiny subset of glob (`*`, `?`) into a regex, escaping
// everything else. This mirrors how Redis SCAN MATCH works for the
// patterns used in this codebase.
let regex = "^";
for (const ch of pattern) {
if (ch === "*") {
regex += ".*";
} else if (ch === "?") {
regex += ".";
} else if (/[\\^$.+()|[\]{}]/.test(ch)) {
regex += `\\${ch}`;
} else {
regex += ch;
}
}
regex += "$";
return new RegExp(regex);
}
@@ -0,0 +1,348 @@
// RedisAdapter unit tests use `ioredis-mock` as a stand-in for a real
// Redis server. The mock implements every command exercised here (GET,
// SET with EX/NX, INCR/INCRBY, EXPIRE, MGET, SCAN, ZADD, ZREMRANGEBYSCORE,
// ZCARD, PUBSUB, EVAL/EVALSHA). Integration against a real Redis is
// covered by the manual smoke test recipe in README.md and will be wired
// into CI alongside task #38.
import { EventEmitter } from "node:events";
import RedisMock from "ioredis-mock";
import { afterEach, beforeEach, describe, expect, test } from "vitest";
import { RedisAdapter } from "./redis.js";
type RedisClient = import("ioredis").Redis;
function buildAdapter() {
const adapter = new RedisAdapter({
clientFactory: () => new RedisMock() as unknown as RedisClient,
});
return adapter;
}
class RedisClientDouble extends EventEmitter {
readonly subscribedChannels = new Set<string>();
status = "wait";
closed = false;
constructor(private readonly broker?: { subscriber: RedisClientDouble }) {
super();
}
async publish(channel: string, message: string): Promise<number> {
const subscriber = this.broker?.subscriber;
if (!subscriber || subscriber.closed || !subscriber.subscribedChannels.has(channel)) {
return 0;
}
subscriber.emit("message", channel, message);
return 1;
}
async subscribe(channel: string): Promise<"OK"> {
this.subscribedChannels.add(channel);
return "OK";
}
async unsubscribe(channel: string): Promise<number> {
const removed = this.subscribedChannels.delete(channel);
return removed ? 1 : 0;
}
async quit(): Promise<"OK"> {
this.closed = true;
this.subscribedChannels.clear();
return "OK";
}
disconnect(): void {
this.closed = true;
this.subscribedChannels.clear();
}
}
function buildLifecycleHarness(primaryStatus = "wait") {
const primary = new RedisClientDouble();
const subscriber = new RedisClientDouble();
const publisher = new RedisClientDouble({ subscriber });
primary.status = primaryStatus;
const adapter = new RedisAdapter({
clientFactory: (role) => {
if (role === "primary") return primary as unknown as RedisClient;
if (role === "subscriber") return subscriber as unknown as RedisClient;
return publisher as unknown as RedisClient;
},
});
return { adapter, primary, subscriber };
}
const adapters: RedisAdapter[] = [];
beforeEach(async () => {
// ioredis-mock shares a process-wide keyspace across `new RedisMock()`
// instances; flush before each test so we start with a clean slate.
const flush = new RedisMock() as unknown as { flushall: () => Promise<unknown>; quit: () => Promise<void> };
await flush.flushall();
await flush.quit();
});
afterEach(async () => {
while (adapters.length > 0) {
const adapter = adapters.pop();
if (adapter) {
await adapter.close().catch(() => undefined);
}
}
});
function track(adapter: RedisAdapter): RedisAdapter {
adapters.push(adapter);
return adapter;
}
async function waitForFanout(): Promise<void> {
await new Promise((resolve) => setTimeout(resolve, 0));
}
describe("RedisAdapter — kv operations", () => {
test("set and get round-trip a value", async () => {
const adapter = track(buildAdapter());
await adapter.set("k", "v");
expect(await adapter.get("k")).toBe("v");
});
test("set NX rejects when the key already exists", async () => {
const adapter = track(buildAdapter());
expect(await adapter.set("k", "first", { nx: true })).toBe(true);
expect(await adapter.set("k", "second", { nx: true })).toBe(false);
expect(await adapter.get("k")).toBe("first");
});
test("set with TTL expires the key", async () => {
const adapter = track(buildAdapter());
await adapter.set("k", "v", { ttlSeconds: 1 });
await new Promise((resolve) => setTimeout(resolve, 1_100));
expect(await adapter.get("k")).toBeNull();
});
test("incr creates and increments the counter", async () => {
const adapter = track(buildAdapter());
expect(await adapter.incr("c")).toBe(1);
expect(await adapter.incr("c", 5)).toBe(6);
});
test("expire applies a ttl to an existing key", async () => {
const adapter = track(buildAdapter());
await adapter.set("k", "v");
expect(await adapter.expire("k", 1)).toBe(true);
expect(await adapter.expire("missing", 1)).toBe(false);
});
test("mget returns values in input order", async () => {
const adapter = track(buildAdapter());
await adapter.set("a", "1");
await adapter.set("c", "3");
expect(await adapter.mget(["a", "b", "c"])).toEqual(["1", null, "3"]);
});
test("mget with an empty list short-circuits", async () => {
const adapter = track(buildAdapter());
expect(await adapter.mget([])).toEqual([]);
});
test("del removes the key and returns the count", async () => {
const adapter = track(buildAdapter());
await adapter.set("k", "v");
expect(await adapter.del("k")).toBe(1);
expect(await adapter.del("k")).toBe(0);
});
});
describe("RedisAdapter — scan", () => {
test("yields keys matching the pattern across multiple cursor pages", async () => {
const adapter = track(buildAdapter());
for (let i = 0; i < 25; i += 1) {
await adapter.set(`user:${i}`, String(i));
}
await adapter.set("other:1", "n");
const collected: string[] = [];
for await (const key of adapter.scan("user:*", { count: 5 })) {
collected.push(key);
}
expect(collected.length).toBe(25);
expect(collected.every((key) => key.startsWith("user:"))).toBe(true);
});
});
describe("RedisAdapter — sorted sets", () => {
test("zAdd reports new vs updated members and zCard counts them", async () => {
const adapter = track(buildAdapter());
expect(await adapter.zAdd("k", 1, "a")).toBe(1);
expect(await adapter.zAdd("k", 2, "a")).toBe(0);
expect(await adapter.zAdd("k", 5, "b")).toBe(1);
expect(await adapter.zCard("k")).toBe(2);
});
test("zRemRangeByScore trims the window", async () => {
const adapter = track(buildAdapter());
await adapter.zAdd("k", 1, "a");
await adapter.zAdd("k", 2, "b");
await adapter.zAdd("k", 10, "c");
expect(await adapter.zRemRangeByScore("k", 0, 5)).toBe(2);
expect(await adapter.zCard("k")).toBe(1);
});
});
describe("RedisAdapter — pub/sub", () => {
test("publish delivers to subscribers and unsubscribe stops further delivery", async () => {
const adapter = track(buildAdapter());
const received: string[] = [];
const unsubscribe = await adapter.subscribe("ch", (msg) => {
received.push(msg);
});
await adapter.publish("ch", "hi");
await new Promise((resolve) => setTimeout(resolve, 25));
expect(received).toContain("hi");
await unsubscribe();
await adapter.publish("ch", "ignored");
await new Promise((resolve) => setTimeout(resolve, 25));
expect(received).not.toContain("ignored");
});
test("multiple handlers on a single channel all fire and tear down independently", async () => {
const adapter = track(buildAdapter());
const a: string[] = [];
const b: string[] = [];
const stopA = await adapter.subscribe("ch", (m) => {
a.push(m);
});
await adapter.subscribe("ch", (m) => {
b.push(m);
});
await adapter.publish("ch", "m1");
await new Promise((resolve) => setTimeout(resolve, 25));
expect(a).toEqual(["m1"]);
expect(b).toEqual(["m1"]);
await stopA();
await adapter.publish("ch", "m2");
await new Promise((resolve) => setTimeout(resolve, 25));
expect(a).toEqual(["m1"]);
expect(b).toEqual(["m1", "m2"]);
});
test("handler errors are swallowed so remaining subscribers still receive the message", async () => {
const { adapter } = buildLifecycleHarness();
track(adapter);
const received: string[] = [];
await adapter.subscribe("ch", () => {
throw new Error("subscriber failed");
});
await adapter.subscribe("ch", async () => {
throw new Error("async subscriber failed");
});
await adapter.subscribe("ch", (message) => {
received.push(message);
});
expect(await adapter.publish("ch", "still-delivered")).toBe(1);
await waitForFanout();
expect(received).toEqual(["still-delivered"]);
});
});
describe("RedisAdapter — eval", () => {
test("runs and caches lua scripts", async () => {
const adapter = track(buildAdapter());
const script = "return ARGV[1]";
const result = await adapter.eval(script, [], ["hello"]);
expect(String(result)).toBe("hello");
// Second invocation hits the SHA cache.
const cached = await adapter.eval(script, [], ["world"]);
expect(String(cached)).toBe("world");
});
});
describe("RedisAdapter — lifecycle", () => {
test("close blocks further operations", async () => {
const adapter = buildAdapter();
await adapter.close();
await expect(adapter.get("k")).rejects.toThrow(/closed/);
});
test("ping returns true when the client is healthy", async () => {
const adapter = track(buildAdapter());
expect(await adapter.ping()).toBe(true);
});
test("onReconnect ignores the initial ready event and fires on later ready events", async () => {
const { adapter, primary } = buildLifecycleHarness();
track(adapter);
const reconnects: string[] = [];
adapter.onReconnect(() => {
reconnects.push("reconnected");
});
primary.emit("ready");
await waitForFanout();
expect(reconnects).toEqual([]);
primary.emit("ready");
await waitForFanout();
expect(reconnects).toEqual(["reconnected"]);
});
test("onReconnect treats an already-ready client as connected when registered", async () => {
const { adapter, primary } = buildLifecycleHarness("ready");
track(adapter);
let reconnects = 0;
adapter.onReconnect(() => {
reconnects += 1;
});
primary.emit("ready");
await waitForFanout();
expect(reconnects).toBe(1);
});
test("onReconnect swallows handler errors and continues fanout", async () => {
const { adapter, primary } = buildLifecycleHarness("ready");
track(adapter);
const calls: string[] = [];
adapter.onReconnect(() => {
calls.push("bad");
throw new Error("reconnect handler failed");
});
adapter.onReconnect(async () => {
calls.push("async-bad");
throw new Error("async reconnect handler failed");
});
adapter.onReconnect(() => {
calls.push("good");
});
primary.emit("ready");
await waitForFanout();
expect(calls).toEqual(["bad", "async-bad", "good"]);
});
test("close prevents later subscriber events and reconnect events from fanning out", async () => {
const { adapter, primary, subscriber } = buildLifecycleHarness("ready");
const received: string[] = [];
let reconnects = 0;
await adapter.subscribe("ch", (message) => {
received.push(message);
});
adapter.onReconnect(() => {
reconnects += 1;
});
await adapter.close();
subscriber.emit("message", "ch", "ignored");
primary.emit("ready");
await waitForFanout();
expect(received).toEqual([]);
expect(reconnects).toBe(0);
});
});
@@ -0,0 +1,307 @@
import { Redis, type RedisOptions } from "ioredis";
import type { SharedStoreAdapter, SharedStoreScanOptions, SharedStoreSetOptions } from "./adapter.js";
export interface RedisAdapterOptions {
/** Redis connection URL, e.g. `redis://host:6379`. */
redisUrl?: string;
/** Pre-built ioredis options (test injection or advanced TLS setups). */
redisOptions?: RedisOptions;
/** Logical DB index for KV state. Defaults to 1 to stay clear of BullMQ (0). */
db?: number;
/** Optional factory that returns a Redis client. Used by tests with ioredis-mock. */
clientFactory?: (role: "primary" | "subscriber" | "publisher") => Redis;
/** Connection-establish timeout in ms. */
connectionTimeout?: number;
/** Per-command timeout in ms. */
commandTimeout?: number;
}
const DEFAULT_CONNECTION_TIMEOUT_MS = 5_000;
const DEFAULT_COMMAND_TIMEOUT_MS = 2_000;
/**
* Redis-backed implementation of `SharedStoreAdapter`. Owns three
* ioredis clients:
* - `primary` — commands and reads
* - `subscriber` — receives pub/sub messages (ioredis forbids issuing
* other commands on a subscribed client)
* - `publisher` — sends pub/sub messages; reused from `primary` when
* no custom factory is supplied, otherwise a dedicated client so
* mocks behave predictably.
*/
export class RedisAdapter implements SharedStoreAdapter {
private readonly primary: Redis;
private readonly subscriber: Redis;
private readonly publisher: Redis;
private readonly handlers = new Map<string, Set<(message: string) => void | Promise<void>>>();
private readonly scriptShaCache = new Map<string, string>();
private readonly reconnectHandlers = new Set<() => void | Promise<void>>();
private subscriberWired = false;
private reconnectWired = false;
private hasConnectedOnce = false;
private closed = false;
constructor(options: RedisAdapterOptions = {}) {
const factory = options.clientFactory ?? ((role) => buildClient(role, options));
this.primary = factory("primary");
this.subscriber = factory("subscriber");
this.publisher = factory("publisher");
}
async get(key: string): Promise<string | null> {
this.assertOpen();
return this.primary.get(key);
}
async set(key: string, value: string, opts: SharedStoreSetOptions = {}): Promise<boolean> {
this.assertOpen();
const args: (string | number)[] = [key, value];
if (typeof opts.ttlSeconds === "number" && opts.ttlSeconds > 0) {
args.push("EX", opts.ttlSeconds);
}
if (opts.nx) {
args.push("NX");
}
// ioredis returns null when NX prevents the write, "OK" otherwise.
const result = await (this.primary as unknown as { set: (...a: unknown[]) => Promise<string | null> }).set(...args);
return result === "OK";
}
async del(key: string): Promise<number> {
this.assertOpen();
return this.primary.del(key);
}
async incr(key: string, by = 1): Promise<number> {
this.assertOpen();
if (by === 1) {
return this.primary.incr(key);
}
return this.primary.incrby(key, by);
}
async expire(key: string, ttlSeconds: number): Promise<boolean> {
this.assertOpen();
const result = await this.primary.expire(key, ttlSeconds);
return result === 1;
}
async mget(keys: string[]): Promise<(string | null)[]> {
this.assertOpen();
if (keys.length === 0) return [];
return this.primary.mget(keys);
}
scan(pattern: string, opts: SharedStoreScanOptions = {}): AsyncIterable<string> {
this.assertOpen();
const client = this.primary;
const count = opts.count ?? 100;
return {
[Symbol.asyncIterator]: () => {
let cursor = "0";
let buffer: string[] = [];
let exhausted = false;
return {
async next(): Promise<IteratorResult<string>> {
while (buffer.length === 0 && !exhausted) {
const [nextCursor, keys] = (await client.scan(cursor, "MATCH", pattern, "COUNT", count)) as [
string,
string[],
];
buffer = keys;
cursor = nextCursor;
if (cursor === "0") {
exhausted = true;
}
}
if (buffer.length === 0) {
return { value: undefined as unknown as string, done: true };
}
const value = buffer.shift() as string;
return { value, done: false };
},
};
},
};
}
async publish(channel: string, message: string): Promise<number> {
this.assertOpen();
return this.publisher.publish(channel, message);
}
async subscribe(channel: string, handler: (message: string) => void | Promise<void>): Promise<() => Promise<void>> {
this.assertOpen();
this.wireSubscriber();
let handlers = this.handlers.get(channel);
if (!handlers) {
handlers = new Set();
this.handlers.set(channel, handlers);
await this.subscriber.subscribe(channel);
}
handlers.add(handler);
return async () => {
const set = this.handlers.get(channel);
if (!set) return;
set.delete(handler);
if (set.size === 0) {
this.handlers.delete(channel);
if (!this.closed) {
await this.subscriber.unsubscribe(channel);
}
}
};
}
async zAdd(key: string, score: number, member: string): Promise<number> {
this.assertOpen();
return this.primary.zadd(key, score, member);
}
async zRemRangeByScore(key: string, min: number, max: number): Promise<number> {
this.assertOpen();
return this.primary.zremrangebyscore(key, min, max);
}
async zCard(key: string): Promise<number> {
this.assertOpen();
return this.primary.zcard(key);
}
async eval(script: string, keys: string[], args: string[]): Promise<unknown> {
this.assertOpen();
let sha = this.scriptShaCache.get(script);
if (!sha) {
try {
sha = (await this.primary.script("LOAD", script)) as string;
this.scriptShaCache.set(script, sha);
} catch {
// SCRIPT LOAD is not supported on every backend (ioredis-mock).
// Fall back to raw EVAL; subsequent calls will retry the load
// so production Redis still benefits from the SHA cache.
return await this.primary.eval(script, keys.length, ...keys, ...args);
}
}
try {
return await this.primary.evalsha(sha, keys.length, ...keys, ...args);
} catch (error) {
if (error instanceof Error && /NOSCRIPT/.test(error.message)) {
this.scriptShaCache.delete(script);
return await this.primary.eval(script, keys.length, ...keys, ...args);
}
throw error;
}
}
/** Health probe. Not part of `SharedStoreAdapter`; used by #38 wiring. */
async ping(): Promise<boolean> {
this.assertOpen();
const result = await this.primary.ping();
return result === "PONG";
}
onReconnect(handler: () => void | Promise<void>): () => void {
this.assertOpen();
this.wireReconnectListener();
this.reconnectHandlers.add(handler);
return () => {
this.reconnectHandlers.delete(handler);
};
}
async close(): Promise<void> {
if (this.closed) return;
this.closed = true;
this.handlers.clear();
this.reconnectHandlers.clear();
await Promise.allSettled([
safeQuit(this.subscriber),
safeQuit(this.publisher),
safeQuit(this.primary),
]);
}
private assertOpen(): void {
if (this.closed) {
throw new Error("shared-store redis adapter is closed");
}
}
private wireSubscriber(): void {
if (this.subscriberWired) return;
this.subscriber.on("message", (channel: string, message: string) => {
const handlers = this.handlers.get(channel);
if (!handlers) return;
for (const handler of handlers) {
Promise.resolve()
.then(() => handler(message))
.catch(() => {
/* swallowed; consumers handle their own errors */
});
}
});
this.subscriberWired = true;
}
/**
* Wire a single `'ready'` listener onto the primary ioredis client.
* The first `'ready'` after construction is treated as the initial
* connect and ignored — only subsequent ones (after a `'reconnecting'`
* cycle) fan out to registered handlers. Errors from handlers are
* swallowed so a single bad handler cannot poison the others.
*/
private wireReconnectListener(): void {
if (this.reconnectWired) return;
this.reconnectWired = true;
const onReady = () => {
if (!this.hasConnectedOnce) {
this.hasConnectedOnce = true;
return;
}
if (this.closed) return;
for (const handler of this.reconnectHandlers) {
Promise.resolve()
.then(() => handler())
.catch(() => {
/* swallowed; handler owns its own error reporting */
});
}
};
this.primary.on("ready", onReady);
// ioredis sets status to "ready" only after the first successful
// handshake. When `lazyConnect: true` is used, the client may not
// have connected yet at the time onReconnect is first called — in
// that case the first emitted "ready" is the initial connect and is
// correctly skipped by the `hasConnectedOnce` latch above. When the
// client is already ready at registration time, mark the latch so
// the next "ready" (after a disconnect) is the one that fires.
const status = (this.primary as unknown as { status?: string }).status;
if (status === "ready") {
this.hasConnectedOnce = true;
}
}
}
function buildClient(_role: "primary" | "subscriber" | "publisher", options: RedisAdapterOptions): Redis {
const baseOptions: RedisOptions = {
db: options.db ?? 1,
connectTimeout: options.connectionTimeout ?? DEFAULT_CONNECTION_TIMEOUT_MS,
commandTimeout: options.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT_MS,
enableReadyCheck: true,
lazyConnect: true,
maxRetriesPerRequest: null,
...options.redisOptions,
};
if (options.redisUrl) {
return new Redis(options.redisUrl, baseOptions);
}
return new Redis(baseOptions);
}
async function safeQuit(client: Redis): Promise<void> {
try {
await client.quit();
} catch {
client.disconnect();
}
}