@objectstack/service-cluster-redis 5.1.1

package/src/counter.ts

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Redis } from 'ioredis';
+import type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';
+
+export interface RedisCounterOptions {
+    client: Redis;
+    keyPrefix?: string;
+}
+
+/**
+ * Redis-backed monotonic counter using INCRBY. Each counter key lives at
+ * `{prefix}ctr:{key}` so the same Redis instance can host multiple
+ * tenants without collision.
+ *
+ * Values are stored as ASCII decimals (Redis convention). We surface
+ * them as `bigint` to match the contract — INCRBY accepts up to a
+ * signed 64-bit range, well beyond Number.MAX_SAFE_INTEGER.
+ */
+export class RedisCounter implements ICounter {
+    private readonly client: Redis;
+    private readonly keyPrefix: string;
+    private closed = false;
+
+    constructor(opts: RedisCounterOptions) {
+        this.client = opts.client;
+        this.keyPrefix = opts.keyPrefix ?? 'os:';
+    }
+
+    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {
+        if (this.closed) throw new Error('RedisCounter is closed');
+        const by = opts.by ?? 1;
+        const next = await this.client.incrby(this.ctrKey(key), by);
+        return BigInt(next);
+    }
+
+    async peek(key: string): Promise<bigint> {
+        const raw = await this.client.get(this.ctrKey(key));
+        if (raw === null) return 0n;
+        try {
+            return BigInt(raw);
+        } catch {
+            return 0n;
+        }
+    }
+
+    async reset(key: string, value: bigint = 0n): Promise<void> {
+        if (this.closed) throw new Error('RedisCounter is closed');
+        if (value === 0n) {
+            await this.client.del(this.ctrKey(key));
+            return;
+        }
+        await this.client.set(this.ctrKey(key), value.toString());
+    }
+
+    async close(): Promise<void> {
+        this.closed = true;
+    }
+
+    private ctrKey(key: string): string {
+        return `${this.keyPrefix}ctr:${key}`;
+    }
+}

package/src/index.ts

@@ -0,0 +1,111 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/service-cluster-redis
+ *
+ * Redis driver for `@objectstack/service-cluster`. Import this package
+ * once at process start to register the `'redis'` driver:
+ *
+ * ```ts
+ * import '@objectstack/service-cluster-redis';
+ * import { defineCluster } from '@objectstack/service-cluster';
+ *
+ * const cluster = defineCluster({
+ *     driver: 'redis',
+ *     url: 'redis://localhost:6379',
+ *     nodeId: 'web-1',
+ * });
+ * ```
+ *
+ * The driver also exports raw constructors so callers who already own
+ * an ioredis client can compose primitives by hand.
+ */
+
+import type { Redis } from 'ioredis';
+import {
+    ComposedClusterService,
+    registerClusterDriver,
+    type DriverFactoryConfig,
+} from '@objectstack/service-cluster';
+import { createRedisClient } from './client.js';
+import { RedisPubSub } from './pubsub.js';
+import { RedisLock } from './lock.js';
+import { RedisKV } from './kv.js';
+import { RedisCounter } from './counter.js';
+
+// Re-exports for advanced composition.
+export { createRedisClient, duplicateForPubSub, type CreateRedisOptions } from './client.js';
+export { RedisPubSub, type RedisPubSubOptions } from './pubsub.js';
+export { RedisLock, type RedisLockOptions } from './lock.js';
+export { RedisKV, VersionMismatchError, type RedisKVOptions } from './kv.js';
+export { RedisCounter, type RedisCounterOptions } from './counter.js';
+
+/**
+ * Driver-specific options accepted under `driverOptions` in
+ * `ClusterCapabilityConfig`. All are optional — supply a `client` to
+ * share a Redis pool with other services (e.g. `service-cache`).
+ */
+export interface RedisDriverOptions {
+    /** Pre-built ioredis client. When provided, `url` is ignored. */
+    client?: Redis;
+    /** Key prefix applied to every Redis key (default: 'os:'). */
+    keyPrefix?: string;
+    /** Default lock TTL in ms. Overridden by `LockAcquireOptions.ttlMs`. */
+    lockTtlMs?: number;
+    /** Pub/sub subscriber error sink. */
+    onError?: (err: unknown, channel: string) => void;
+}
+
+/**
+ * Factory consumed by `defineCluster({ driver: 'redis' })`. Builds an
+ * `IClusterService` backed by Redis. Owns the underlying ioredis client
+ * iff it created it (i.e. when caller didn't pass `driverOptions.client`).
+ */
+function redisDriverFactory(config: DriverFactoryConfig) {
+    const driverOpts = (config.driverOptions ?? {}) as RedisDriverOptions;
+    const ownsClient = !driverOpts.client;
+    const client =
+        driverOpts.client ??
+        createRedisClient({ url: config.url });
+
+    const keyPrefix = driverOpts.keyPrefix ?? 'os:';
+    const ttlMs = config.lockTtlMs ?? driverOpts.lockTtlMs;
+
+    const pubsub = new RedisPubSub({
+        client,
+        nodeId: config.nodeId,
+        keyPrefix,
+        onError: driverOpts.onError,
+    });
+    const lock = new RedisLock({
+        client,
+        keyPrefix,
+        defaultTtlMs: ttlMs,
+        nodeId: config.nodeId,
+    });
+    const kv = new RedisKV({ client, keyPrefix });
+    const counter = new RedisCounter({ client, keyPrefix });
+
+    const facade = new ComposedClusterService(
+        config.nodeId,
+        'redis',
+        pubsub,
+        lock,
+        kv,
+        counter,
+    );
+
+    // Wrap close() so we also tear down the publisher client if we own it.
+    const originalClose = facade.close.bind(facade);
+    facade.close = async () => {
+        await originalClose();
+        if (ownsClient) {
+            try { await client.quit(); } catch { /* swallow */ }
+        }
+    };
+
+    return facade;
+}
+
+// Module-load registration — importing this package is enough.
+registerClusterDriver('redis', redisDriverFactory);

package/src/kv.ts

@@ -0,0 +1,187 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Redis } from 'ioredis';
+import type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';
+
+/**
+ * Stored payload shape: `{v: <value>, ver: <bigint as string>}`.
+ * Versions are stored as strings because Redis values are bytes and
+ * bigints can exceed JSON-safe-integer range.
+ */
+interface StoredKV {
+    v: unknown;
+    ver: string;
+}
+
+export class VersionMismatchError extends Error {
+    constructor(
+        public readonly key: string,
+        public readonly expected: bigint,
+        public readonly actual: bigint,
+    ) {
+        super(
+            `KV version mismatch on "${key}": expected v${expected}, found v${actual}`,
+        );
+        this.name = 'VersionMismatchError';
+    }
+}
+
+export interface RedisKVOptions {
+    client: Redis;
+    keyPrefix?: string;
+}
+
+/**
+ * Redis-backed coordination KV with optimistic concurrency via WATCH/MULTI.
+ *
+ * Each `set()` performs:
+ *   1. WATCH key
+ *   2. GET key            → read current version
+ *   3. compare to ifVersion (if provided)
+ *   4. MULTI / SET / [PEXPIRE] / EXEC
+ *
+ * If a competing writer modifies the key between WATCH and EXEC the
+ * transaction aborts and we throw `VersionMismatchError`, matching
+ * memory driver semantics.
+ *
+ * **Not** a cache — uses small JSON envelopes and per-key versioning.
+ * Use service-cache for high-throughput caching.
+ */
+export class RedisKV implements IKV {
+    private readonly client: Redis;
+    private readonly keyPrefix: string;
+    private closed = false;
+
+    constructor(opts: RedisKVOptions) {
+        this.client = opts.client;
+        this.keyPrefix = opts.keyPrefix ?? 'os:';
+    }
+
+    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {
+        const raw = await this.client.get(this.kvKey(key));
+        if (raw === null) return undefined;
+        const parsed = this.parse(raw);
+        if (!parsed) return undefined;
+        const pttl = await this.client.pttl(this.kvKey(key));
+        const expiresAt = pttl > 0 ? Date.now() + pttl : undefined;
+        return {
+            key,
+            value: parsed.v as T,
+            version: BigInt(parsed.ver),
+            expiresAt,
+        };
+    }
+
+    async set<T = unknown>(
+        key: string,
+        value: T,
+        opts: KVSetOptions = {},
+    ): Promise<KVEntry<T>> {
+        if (this.closed) throw new Error('RedisKV is closed');
+        const physical = this.kvKey(key);
+        const ttlMs = opts.ttl && opts.ttl > 0 ? opts.ttl * 1000 : undefined;
+
+        // Optimistic-concurrency loop — Redis WATCH aborts the MULTI on
+        // any intervening write.
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            await this.client.watch(physical);
+            const raw = await this.client.get(physical);
+            const existing = raw ? this.parse(raw) : undefined;
+            const existingVersion = existing ? BigInt(existing.ver) : 0n;
+
+            if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {
+                await this.client.unwatch();
+                throw new VersionMismatchError(key, opts.ifVersion, existingVersion);
+            }
+
+            const newVersion = existingVersion + 1n;
+            const payload: StoredKV = { v: value, ver: newVersion.toString() };
+            const encoded = JSON.stringify(payload);
+
+            const multi = this.client.multi();
+            if (ttlMs) {
+                multi.set(physical, encoded, 'PX', ttlMs);
+            } else {
+                multi.set(physical, encoded);
+            }
+            const result = await multi.exec();
+            // exec() returns null when WATCH detected a concurrent change.
+            if (result === null) continue;
+
+            return {
+                key,
+                value,
+                version: newVersion,
+                expiresAt: ttlMs ? Date.now() + ttlMs : undefined,
+            };
+        }
+    }
+
+    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {
+        if (this.closed) throw new Error('RedisKV is closed');
+        const physical = this.kvKey(key);
+
+        if (opts.ifVersion === undefined) {
+            const removed = await this.client.del(physical);
+            return removed > 0;
+        }
+
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            await this.client.watch(physical);
+            const raw = await this.client.get(physical);
+            if (!raw) {
+                await this.client.unwatch();
+                return false;
+            }
+            const parsed = this.parse(raw);
+            if (!parsed) {
+                await this.client.unwatch();
+                return false;
+            }
+            const currentVersion = BigInt(parsed.ver);
+            if (opts.ifVersion !== currentVersion) {
+                await this.client.unwatch();
+                throw new VersionMismatchError(key, opts.ifVersion, currentVersion);
+            }
+            const multi = this.client.multi();
+            multi.del(physical);
+            const result = await multi.exec();
+            if (result === null) continue;
+            return (result[0]?.[1] as number) > 0;
+        }
+    }
+
+    async cas<T = unknown>(
+        key: string,
+        expectedVersion: bigint,
+        next: T,
+        opts: Omit<KVSetOptions, 'ifVersion'> = {},
+    ): Promise<KVEntry<T> | undefined> {
+        try {
+            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });
+        } catch (err) {
+            if (err instanceof VersionMismatchError) return undefined;
+            throw err;
+        }
+    }
+
+    async close(): Promise<void> {
+        this.closed = true;
+    }
+
+    private kvKey(key: string): string {
+        return `${this.keyPrefix}kv:${key}`;
+    }
+
+    private parse(raw: string): StoredKV | undefined {
+        try {
+            const obj = JSON.parse(raw) as StoredKV;
+            if (typeof obj.ver !== 'string') return undefined;
+            return obj;
+        } catch {
+            return undefined;
+        }
+    }
+}

package/src/lock.ts

@@ -0,0 +1,205 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Redis } from 'ioredis';
+import type {
+    ILock,
+    LockAcquireOptions,
+    LockHandle,
+} from '@objectstack/spec/contracts';
+
+const DEFAULT_TTL_MS = 15_000;
+const POLL_INTERVAL_MS = 50;
+
+/**
+ * Lua script for safe release: only DEL when the value matches our
+ * fencing token. Prevents a delayed release from kicking out the
+ * legitimate next holder.
+ */
+const RELEASE_SCRIPT = `
+if redis.call("GET", KEYS[1]) == ARGV[1] then
+    return redis.call("DEL", KEYS[1])
+else
+    return 0
+end
+`;
+
+/**
+ * Lua script for renew: PEXPIRE only when we still hold the lock.
+ * Returns 1 on success, 0 if the lock was lost.
+ */
+const RENEW_SCRIPT = `
+if redis.call("GET", KEYS[1]) == ARGV[1] then
+    return redis.call("PEXPIRE", KEYS[1], ARGV[2])
+else
+    return 0
+end
+`;
+
+export interface RedisLockOptions {
+    client: Redis;
+    /** Counter client for fencing-token allocation. Same Redis is fine. */
+    counterClient?: Redis;
+    keyPrefix?: string;
+    defaultTtlMs?: number;
+    /** Stable node id baked into lock values for debugging. */
+    nodeId?: string;
+}
+
+/**
+ * Redis-backed distributed lock with TTL fencing.
+ *
+ * Algorithm (single-instance Redis, NOT Redlock — adequate for
+ * typical ObjectStack deployments with one Redis primary):
+ *
+ *   acquire = SET key {nodeId}:{token} NX PX ttl
+ *   release = Lua: GET == expected ? DEL : 0
+ *   renew   = Lua: GET == expected ? PEXPIRE : 0
+ *
+ * Fencing tokens come from a Redis counter (INCR on `{prefix}fence:{key}`)
+ * so that two clients in a split-brain see strictly increasing tokens
+ * downstream.
+ *
+ * For multi-master Redis (Sentinel failover, etc.) consider switching to
+ * a Redlock variant — not implemented yet.
+ */
+export class RedisLock implements ILock {
+    private readonly client: Redis;
+    private readonly counterClient: Redis;
+    private readonly keyPrefix: string;
+    private readonly defaultTtlMs: number;
+    private readonly nodeId: string;
+    private closed = false;
+
+    constructor(opts: RedisLockOptions) {
+        this.client = opts.client;
+        this.counterClient = opts.counterClient ?? opts.client;
+        this.keyPrefix = opts.keyPrefix ?? 'os:';
+        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;
+        this.nodeId = opts.nodeId ?? 'node';
+    }
+
+    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {
+        if (this.closed) throw new Error('RedisLock is closed');
+        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;
+        const waitMs = opts.waitMs ?? 0;
+        const deadline = Date.now() + waitMs;
+        const lockKey = this.lockKey(key);
+
+        // Allocate a fresh fencing token up-front.
+        const fencingToken = BigInt(
+            await this.counterClient.incr(this.fenceKey(key)),
+        );
+        const value = `${this.nodeId}:${fencingToken}`;
+
+        // First attempt — fast path.
+        if (await this.trySet(lockKey, value, ttlMs)) {
+            return this.makeHandle(key, lockKey, value, fencingToken, ttlMs);
+        }
+        if (waitMs <= 0) return null;
+
+        // Polling loop: simple, correct, good enough for typical
+        // contention. Future: pub/sub-driven wakeup on release.
+        while (Date.now() < deadline) {
+            await sleep(Math.min(POLL_INTERVAL_MS, Math.max(1, deadline - Date.now())));
+            if (await this.trySet(lockKey, value, ttlMs)) {
+                return this.makeHandle(key, lockKey, value, fencingToken, ttlMs);
+            }
+        }
+        return null;
+    }
+
+    async withLock<T>(
+        key: string,
+        fn: (h: LockHandle) => Promise<T>,
+        opts?: LockAcquireOptions,
+    ): Promise<T | null> {
+        const handle = await this.acquire(key, opts);
+        if (!handle) return null;
+        try {
+            return await fn(handle);
+        } finally {
+            await handle.release();
+        }
+    }
+
+    async close(): Promise<void> {
+        this.closed = true;
+    }
+
+    private async trySet(lockKey: string, value: string, ttlMs: number): Promise<boolean> {
+        // SET key value NX PX ttlMs — atomic acquire.
+        const res = await this.client.set(lockKey, value, 'PX', ttlMs, 'NX');
+        return res === 'OK';
+    }
+
+    private makeHandle(
+        logicalKey: string,
+        lockKey: string,
+        value: string,
+        fencingToken: bigint,
+        ttlMs: number,
+    ): LockHandle {
+        const self = this;
+        let released = false;
+        let currentTtl = ttlMs;
+        // Local expiry timer — mirrors memory driver so `isHeld()` flips
+        // on TTL without a Redis roundtrip. Not authoritative (clocks may
+        // drift), but matches contract test expectations.
+        let timer: NodeJS.Timeout | undefined = setTimeout(() => {
+            released = true;
+        }, ttlMs);
+
+        return {
+            key: logicalKey,
+            fencingToken,
+            isHeld(): boolean {
+                return !released;
+            },
+            async renew(extendMs?: number): Promise<void> {
+                if (released) {
+                    throw new Error(`Lock "${logicalKey}" already released`);
+                }
+                const next = extendMs ?? currentTtl;
+                const result = await self.client.eval(
+                    RENEW_SCRIPT,
+                    1,
+                    lockKey,
+                    value,
+                    String(next),
+                );
+                if (result !== 1) {
+                    released = true;
+                    if (timer) { clearTimeout(timer); timer = undefined; }
+                    throw new Error(
+                        `Lock "${logicalKey}" no longer held (fence=${fencingToken})`,
+                    );
+                }
+                currentTtl = next;
+                if (timer) clearTimeout(timer);
+                timer = setTimeout(() => { released = true; }, next);
+            },
+            async release(): Promise<void> {
+                if (released) return;
+                released = true;
+                if (timer) { clearTimeout(timer); timer = undefined; }
+                try {
+                    await self.client.eval(RELEASE_SCRIPT, 1, lockKey, value);
+                } catch {
+                    /* swallow — release is best-effort */
+                }
+            },
+        };
+    }
+
+    private lockKey(key: string): string {
+        return `${this.keyPrefix}lock:${key}`;
+    }
+
+    private fenceKey(key: string): string {
+        return `${this.keyPrefix}fence:${key}`;
+    }
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((r) => setTimeout(r, ms));
+}