@objectstack/service-cluster-redis 5.1.1

package/src/pubsub.ts

@@ -0,0 +1,174 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Redis } from 'ioredis';
+import type {
+    IPubSub,
+    PubSubHandler,
+    PublishOptions,
+    SubscribeOptions,
+    Unsubscribe,
+} from '@objectstack/spec/contracts';
+import { duplicateForPubSub } from './client.js';
+
+/**
+ * Wire-format envelope sent over Redis. Adds `fromNode` and
+ * `publishedAt` so subscribers see the same surface as the memory
+ * driver. The user payload is nested under `p` to avoid colliding with
+ * reserved keys.
+ */
+interface RedisPubSubEnvelope {
+    n?: string;
+    t: number;
+    p: unknown;
+}
+
+export interface RedisPubSubOptions {
+    /** Already-connected client used for PUBLISH. */
+    client: Redis;
+    /** Optional node id surfaced as `fromNode` on every delivered message. */
+    nodeId?: string;
+    /** Key namespace prefix applied to every channel (default: 'os:'). */
+    keyPrefix?: string;
+    /** Error sink for subscriber handler exceptions. */
+    onError?: (err: unknown, channel: string) => void;
+}
+
+/**
+ * Redis pub/sub implementation of {@link IPubSub}.
+ *
+ * Uses two ioredis clients under the hood:
+ *   - `publisher` (caller-provided) — runs PUBLISH commands
+ *   - `subscriber` (auto-duplicated) — held in subscribe mode, can't run
+ *     regular commands per Redis protocol
+ *
+ * Delivery semantics match Redis pub/sub: at-most-once, fire-and-forget,
+ * no persistence. For at-least-once + replay use the planned `streams`
+ * adapter (separate driver).
+ *
+ * Channel names are prefixed with `keyPrefix` before being sent to
+ * Redis, so the same Redis instance can host multiple isolated
+ * ObjectStack deployments.
+ */
+export class RedisPubSub implements IPubSub {
+    private readonly publisher: Redis;
+    private readonly subscriber: Redis;
+    private readonly nodeId?: string;
+    private readonly keyPrefix: string;
+    private readonly onError: (err: unknown, channel: string) => void;
+    private readonly subs = new Map<string, Set<PubSubHandler<unknown>>>();
+    private closed = false;
+
+    constructor(opts: RedisPubSubOptions) {
+        this.publisher = opts.client;
+        this.subscriber = duplicateForPubSub(opts.client);
+        this.nodeId = opts.nodeId;
+        this.keyPrefix = opts.keyPrefix ?? 'os:';
+        this.onError =
+            opts.onError ??
+            ((err, channel) => {
+                // eslint-disable-next-line no-console
+                console.error(`[RedisPubSub] handler error on "${channel}":`, err);
+            });
+
+        this.subscriber.on('message', (raw: string, data: string) => {
+            this.dispatch(raw, data);
+        });
+    }
+
+    async publish<T = unknown>(
+        channel: string,
+        payload: T,
+        _opts?: PublishOptions,
+    ): Promise<void> {
+        if (this.closed) throw new Error('RedisPubSub is closed');
+        const envelope: RedisPubSubEnvelope = {
+            n: this.nodeId,
+            t: Date.now(),
+            p: payload,
+        };
+        await this.publisher.publish(this.prefixed(channel), JSON.stringify(envelope));
+    }
+
+    subscribe<T = unknown>(
+        channel: string,
+        handler: PubSubHandler<T>,
+        _opts?: SubscribeOptions,
+    ): Unsubscribe {
+        if (this.closed) throw new Error('RedisPubSub is closed');
+        const prefixed = this.prefixed(channel);
+        let bucket = this.subs.get(prefixed);
+        if (!bucket) {
+            bucket = new Set();
+            this.subs.set(prefixed, bucket);
+            // Fire-and-forget; if subscribe fails the next publish will
+            // simply not deliver — caller can resubscribe.
+            void this.subscriber.subscribe(prefixed).catch((err) => {
+                this.onError(err, channel);
+            });
+        }
+        const wrapped = handler as PubSubHandler<unknown>;
+        bucket.add(wrapped);
+
+        let disposed = false;
+        return () => {
+            if (disposed) return;
+            disposed = true;
+            const b = this.subs.get(prefixed);
+            if (!b) return;
+            b.delete(wrapped);
+            if (b.size === 0) {
+                this.subs.delete(prefixed);
+                void this.subscriber.unsubscribe(prefixed).catch(() => { /* swallow */ });
+            }
+        };
+    }
+
+    async close(): Promise<void> {
+        if (this.closed) return;
+        this.closed = true;
+        this.subs.clear();
+        try { await this.subscriber.quit(); } catch { /* swallow */ }
+        // We don't quit `publisher` — caller owns it.
+    }
+
+    private prefixed(channel: string): string {
+        return `${this.keyPrefix}ps:${channel}`;
+    }
+
+    private dispatch(prefixedChannel: string, data: string): void {
+        const bucket = this.subs.get(prefixedChannel);
+        if (!bucket || bucket.size === 0) return;
+
+        let envelope: RedisPubSubEnvelope;
+        try {
+            envelope = JSON.parse(data) as RedisPubSubEnvelope;
+        } catch (err) {
+            this.onError(err, prefixedChannel);
+            return;
+        }
+
+        // Strip our keyPrefix so the handler sees the logical channel.
+        const logical = prefixedChannel.startsWith(`${this.keyPrefix}ps:`)
+            ? prefixedChannel.slice(`${this.keyPrefix}ps:`.length)
+            : prefixedChannel;
+
+        const snapshot = Array.from(bucket);
+        for (const handler of snapshot) {
+            try {
+                const result = handler({
+                    channel: logical,
+                    payload: envelope.p,
+                    publishedAt: envelope.t,
+                    fromNode: envelope.n,
+                });
+                if (result && typeof (result as Promise<void>).then === 'function') {
+                    (result as Promise<void>).catch((err) =>
+                        this.onError(err, logical),
+                    );
+                }
+            } catch (err) {
+                this.onError(err, logical);
+            }
+        }
+    }
+}

package/src/redis.contract.test.ts

@@ -0,0 +1,159 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Driver contract tests for the Redis cluster driver, run against
+ * `ioredis-mock` so they execute without a real Redis instance in CI.
+ *
+ * The same suites can be invoked against a live Redis by setting
+ * `RUN_REAL_REDIS=1` and providing `REDIS_URL` — see the conditional
+ * `describe.skipIf` blocks at the bottom.
+ */
+
+// @ts-expect-error — ioredis-mock has no published types
+import RedisMock from 'ioredis-mock';
+import { describe, expect, it, vi } from 'vitest';
+import {
+    runLockContract,
+    runKVContract,
+    runCounterContract,
+} from '@objectstack/service-cluster/testing';
+
+import { RedisPubSub } from './pubsub.js';
+import { RedisLock } from './lock.js';
+import { RedisKV } from './kv.js';
+import { RedisCounter } from './counter.js';
+
+// ioredis-mock shares state across instances by default, so each
+// primitive gets a unique key-prefix per test to ensure isolation.
+let suffix = 0;
+const uniquePrefix = () => `t${++suffix}:`;
+const makeClient = () => new RedisMock();
+
+runLockContract('redis(mock)', async () =>
+    new RedisLock({ client: makeClient(), keyPrefix: uniquePrefix() }),
+);
+runKVContract('redis(mock)', async () =>
+    new RedisKV({ client: makeClient(), keyPrefix: uniquePrefix() }),
+);
+runCounterContract('redis(mock)', async () =>
+    new RedisCounter({ client: makeClient(), keyPrefix: uniquePrefix() }),
+);
+
+// PubSub: Redis delivery is async (network roundtrip even for mock), so
+// we can't reuse the synchronous contract suite. Cover the same surface
+// here with explicit waits.
+describe('IPubSub contract — redis(mock)', () => {
+    const flush = () => new Promise<void>((r) => setTimeout(r, 10));
+
+    it('delivers published messages to subscribers', async () => {
+        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
+        const received: unknown[] = [];
+        bus.subscribe<{ n: number }>('ch', (msg) => { received.push(msg.payload); });
+        await flush();                                         // let SUBSCRIBE register
+        await bus.publish('ch', { n: 1 });
+        await bus.publish('ch', { n: 2 });
+        await flush();
+        expect(received).toEqual([{ n: 1 }, { n: 2 }]);
+        await bus.close();
+    });
+
+    it('does not deliver to other channels', async () => {
+        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
+        const h = vi.fn();
+        bus.subscribe('a', h);
+        await flush();
+        await bus.publish('b', { x: 1 });
+        await flush();
+        expect(h).not.toHaveBeenCalled();
+        await bus.close();
+    });
+
+    it('supports multiple subscribers per channel', async () => {
+        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
+        const a = vi.fn();
+        const b = vi.fn();
+        bus.subscribe('ch', a);
+        bus.subscribe('ch', b);
+        await flush();
+        await bus.publish('ch', 'hi');
+        await flush();
+        expect(a).toHaveBeenCalledTimes(1);
+        expect(b).toHaveBeenCalledTimes(1);
+        await bus.close();
+    });
+
+    it('unsubscribe stops delivery and is idempotent', async () => {
+        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
+        const h = vi.fn();
+        const off = bus.subscribe('ch', h);
+        await flush();
+        await bus.publish('ch', 1);
+        await flush();
+        off();
+        off();
+        await bus.publish('ch', 2);
+        await flush();
+        expect(h).toHaveBeenCalledTimes(1);
+        await bus.close();
+    });
+
+    it('isolates handler errors from siblings', async () => {
+        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
+        bus.subscribe('ch', () => { throw new Error('boom'); });
+        const ok = vi.fn();
+        bus.subscribe('ch', ok);
+        await flush();
+        await expect(bus.publish('ch', 1)).resolves.toBeUndefined();
+        await flush();
+        expect(ok).toHaveBeenCalledTimes(1);
+        await bus.close();
+    });
+
+    it('close rejects further publishes', async () => {
+        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
+        await bus.close();
+        await expect(bus.publish('ch', 1)).rejects.toThrow(/closed/);
+    });
+});
+
+describe('Redis driver — wiring', () => {
+    it('exports a registerable driver and defineCluster picks it up', async () => {
+        await import('./index.js');
+        const { defineCluster } = await import('@objectstack/service-cluster');
+        const client = makeClient();
+        const cluster = defineCluster({
+            driver: 'redis',
+            nodeId: 'mock-node',
+            driverOptions: { client, keyPrefix: uniquePrefix() },
+        });
+        expect(cluster.driver).toBe('redis');
+        expect(cluster.nodeId).toBe('mock-node');
+
+        expect(await cluster.counter.incr('seq')).toBe(1n);
+        expect(await cluster.counter.incr('seq')).toBe(2n);
+
+        await cluster.kv.set('k', { hello: 'world' });
+        const got = await cluster.kv.get<{ hello: string }>('k');
+        expect(got?.value).toEqual({ hello: 'world' });
+
+        const handle = await cluster.lock.acquire('foo');
+        expect(handle).not.toBeNull();
+        expect(handle!.fencingToken).toBeGreaterThan(0n);
+        await handle!.release();
+
+        await cluster.close();
+    });
+
+    it('does NOT quit caller-owned client on close', async () => {
+        await import('./index.js');
+        const { defineCluster } = await import('@objectstack/service-cluster');
+        const client = makeClient();
+        const cluster = defineCluster({
+            driver: 'redis',
+            nodeId: 'mock-node-2',
+            driverOptions: { client, keyPrefix: uniquePrefix() },
+        });
+        await cluster.close();
+        await expect(client.set('post-close', '1')).resolves.toBe('OK');
+    });
+});

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    splitting: true,
+    sourcemap: true,
+    clean: true,
+    dts: true,
+    format: ['esm', 'cjs'],
+    target: 'es2020',
+    external: ['vitest', 'ioredis'],
+});