@objectstack/service-cluster-redis 16.1.0 → 17.0.0-rc.1

package/src/kv.ts

@@ -1,187 +0,0 @@
-// 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

@@ -1,205 +0,0 @@
-// 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));
-}

package/src/pubsub.ts

@@ -1,188 +0,0 @@
-// 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);
-        });
-    }
-
-    /**
-     * Durability contract (P1-5): this awaits the Redis `PUBLISH` command (so the
-     * message left this node), but Redis pub/sub is **at-most-once** — there is no
-     * delivery guarantee to subscribers and no replay for a node that was down or
-     * slow at publish time. This is acceptable **only** for events that are pure
-     * cache-invalidation hints, never the source of truth.
-     *
-     * In particular `metadata.changed` is such a hint: the durable record of every
-     * metadata mutation is the transactional write to `sys_metadata`
-     * (+ `sys_metadata_history`). A subscriber that misses the event keeps serving
-     * its cached schema until its next reload and **loses no data** — it self-heals
-     * on restart / reload against the DB. Do not route any state that must be
-     * delivered exactly-once through this channel; use a durable outbox instead.
-     */
-    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);
-            }
-        }
-    }
-}