@objectstack/service-cluster 5.1.1

package/src/memory/pubsub.ts

@@ -0,0 +1,106 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+    IPubSub,
+    PubSubHandler,
+    PublishOptions,
+    SubscribeOptions,
+    Unsubscribe,
+} from '@objectstack/spec/contracts';
+
+/**
+ * In-memory PubSub for single-process deployments and tests.
+ *
+ * Behavior:
+ *   - Synchronous fan-out: every subscriber's handler is invoked in the
+ *     same tick that `publish()` resolves. Handler errors are swallowed
+ *     and logged via `onError` (so one bad subscriber can't poison the bus).
+ *   - At-least-once semantics held vacuously (a single in-process delivery).
+ *   - No cross-process delivery — use the redis/postgres/nats driver for
+ *     real multi-node setups.
+ */
+export interface MemoryPubSubOptions {
+    /** Optional error sink for handler exceptions. Defaults to console.error. */
+    onError?: (err: unknown, channel: string) => void;
+    /** Optional node id surfaced as `fromNode` on every message. */
+    nodeId?: string;
+}
+
+interface Subscription {
+    channel: string;
+    handler: PubSubHandler<unknown>;
+}
+
+export class MemoryPubSub implements IPubSub {
+    private readonly subs = new Map<string, Set<Subscription>>();
+    private readonly onError: (err: unknown, channel: string) => void;
+    private readonly nodeId?: string;
+    private closed = false;
+
+    constructor(opts: MemoryPubSubOptions = {}) {
+        this.onError =
+            opts.onError ??
+            ((err, channel) => {
+                // eslint-disable-next-line no-console
+                console.error(`[MemoryPubSub] handler error on channel "${channel}":`, err);
+            });
+        this.nodeId = opts.nodeId;
+    }
+
+    async publish<T = unknown>(
+        channel: string,
+        payload: T,
+        _opts?: PublishOptions,
+    ): Promise<void> {
+        if (this.closed) throw new Error('MemoryPubSub is closed');
+        const bucket = this.subs.get(channel);
+        if (!bucket || bucket.size === 0) return;
+        const publishedAt = Date.now();
+        // Snapshot so handler-driven unsubscribes during dispatch are safe.
+        const snapshot = Array.from(bucket);
+        for (const sub of snapshot) {
+            try {
+                const result = sub.handler({
+                    channel,
+                    payload,
+                    publishedAt,
+                    fromNode: this.nodeId,
+                });
+                if (result && typeof (result as Promise<void>).then === 'function') {
+                    (result as Promise<void>).catch((err) => this.onError(err, channel));
+                }
+            } catch (err) {
+                this.onError(err, channel);
+            }
+        }
+    }
+
+    subscribe<T = unknown>(
+        channel: string,
+        handler: PubSubHandler<T>,
+        _opts?: SubscribeOptions,
+    ): Unsubscribe {
+        if (this.closed) throw new Error('MemoryPubSub is closed');
+        let bucket = this.subs.get(channel);
+        if (!bucket) {
+            bucket = new Set();
+            this.subs.set(channel, bucket);
+        }
+        const sub: Subscription = { channel, handler: handler as PubSubHandler<unknown> };
+        bucket.add(sub);
+        let disposed = false;
+        return () => {
+            if (disposed) return;
+            disposed = true;
+            const b = this.subs.get(channel);
+            if (!b) return;
+            b.delete(sub);
+            if (b.size === 0) this.subs.delete(channel);
+        };
+    }
+
+    async close(): Promise<void> {
+        this.closed = true;
+        this.subs.clear();
+    }
+}

package/src/metadata-cluster-bridge-plugin.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { IClusterService } from '@objectstack/spec/contracts';
+
+/**
+ * Bridges the cluster pub/sub bus to the metadata service so that
+ * metadata mutations on one node invalidate registry caches on peer
+ * nodes. Implements the "first real consumer" of the cluster API.
+ *
+ * Implementation detail: this plugin lives in `@objectstack/service-cluster`
+ * (not in `@objectstack/metadata`) to avoid forcing every metadata
+ * consumer to pull the cluster service. The metadata package only needs
+ * the `IPubSub` interface, which lives in `@objectstack/spec/contracts`.
+ *
+ * Activates only when both services are present and the metadata service
+ * exposes `attachClusterPubSub()`. Late binding is achieved via the
+ * `kernel:ready` lifecycle hook.
+ *
+ * Channel: `metadata.changed` — payload shape defined by
+ * `ClusterMetadataChangedPayload` in `@objectstack/metadata`.
+ *
+ * See `content/docs/concepts/cluster-semantics.mdx` §5.
+ */
+export class MetadataClusterBridgePlugin implements Plugin {
+    name = 'com.objectstack.service.metadata-cluster-bridge';
+    version = '1.0.0';
+    type = 'standard';
+
+    private detach?: () => void;
+
+    async init(ctx: PluginContext): Promise<void> {
+        ctx.hook('kernel:ready', async () => {
+            let cluster: IClusterService | undefined;
+            let md: unknown;
+            try {
+                cluster = ctx.getService<IClusterService>('cluster');
+            } catch {
+                ctx.logger.debug(
+                    'MetadataClusterBridgePlugin: no "cluster" service registered, skipping',
+                );
+                return;
+            }
+            try {
+                md = ctx.getService<unknown>('metadata');
+            } catch {
+                ctx.logger.debug(
+                    'MetadataClusterBridgePlugin: no "metadata" service registered, skipping',
+                );
+                return;
+            }
+
+            const attach = (md as { attachClusterPubSub?: unknown })
+                .attachClusterPubSub;
+            if (typeof attach !== 'function') {
+                ctx.logger.warn(
+                    'MetadataClusterBridgePlugin: metadata service does not expose attachClusterPubSub(); cross-node cache invalidation disabled',
+                );
+                return;
+            }
+
+            try {
+                this.detach = (attach as (
+                    pubsub: IClusterService['pubsub'],
+                    nodeId: string,
+                ) => () => void).call(md, cluster.pubsub, cluster.nodeId);
+                ctx.logger.info(
+                    `MetadataClusterBridgePlugin: bridged metadata.changed → cluster.pubsub (node=${cluster.nodeId})`,
+                );
+            } catch (err) {
+                ctx.logger.error(
+                    'MetadataClusterBridgePlugin: attach failed',
+                    err as Error,
+                );
+            }
+        });
+
+        ctx.hook('kernel:shutdown', async () => {
+            try {
+                this.detach?.();
+            } catch (err) {
+                ctx.logger.error(
+                    'MetadataClusterBridgePlugin: detach error',
+                    err as Error,
+                );
+            }
+            this.detach = undefined;
+        });
+    }
+}

package/src/testing.ts

@@ -0,0 +1,310 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Generic contract tests for cluster primitives.
+ *
+ * These are written once and run against any driver. The memory driver
+ * suite calls them directly; future postgres/redis driver packages will
+ * `import { runPubSubContract } from '@objectstack/service-cluster/testing'`
+ * to get the same coverage for free.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import type {
+    IPubSub,
+    ILock,
+    IKV,
+    ICounter,
+} from '@objectstack/spec/contracts';
+
+export interface ContractFactories {
+    makePubSub: () => Promise<IPubSub>;
+    makeLock: () => Promise<ILock>;
+    makeKV: () => Promise<IKV>;
+    makeCounter: () => Promise<ICounter>;
+}
+
+export function runPubSubContract(name: string, make: () => Promise<IPubSub>) {
+    describe(`IPubSub contract — ${name}`, () => {
+        it('delivers published messages to subscribers', async () => {
+            const bus = await make();
+            const received: unknown[] = [];
+            bus.subscribe<{ n: number }>('ch', (msg) => {
+                received.push(msg.payload);
+            });
+            await bus.publish('ch', { n: 1 });
+            await bus.publish('ch', { n: 2 });
+            expect(received).toEqual([{ n: 1 }, { n: 2 }]);
+            await bus.close();
+        });
+
+        it('does not deliver to other channels', async () => {
+            const bus = await make();
+            const h = vi.fn();
+            bus.subscribe('a', h);
+            await bus.publish('b', { x: 1 });
+            expect(h).not.toHaveBeenCalled();
+            await bus.close();
+        });
+
+        it('supports multiple subscribers per channel', async () => {
+            const bus = await make();
+            const a = vi.fn();
+            const b = vi.fn();
+            bus.subscribe('ch', a);
+            bus.subscribe('ch', b);
+            await bus.publish('ch', 'hi');
+            expect(a).toHaveBeenCalledTimes(1);
+            expect(b).toHaveBeenCalledTimes(1);
+            await bus.close();
+        });
+
+        it('unsubscribe stops delivery and is idempotent', async () => {
+            const bus = await make();
+            const h = vi.fn();
+            const off = bus.subscribe('ch', h);
+            await bus.publish('ch', 1);
+            off();
+            off(); // idempotent
+            await bus.publish('ch', 2);
+            expect(h).toHaveBeenCalledTimes(1);
+            await bus.close();
+        });
+
+        it('isolates handler errors from siblings', async () => {
+            const errors: unknown[] = [];
+            const bus = await make();
+            // Memory driver allows override via constructor; for the
+            // generic contract we just verify no throw leaks to publish().
+            bus.subscribe('ch', () => {
+                throw new Error('boom');
+            });
+            const ok = vi.fn();
+            bus.subscribe('ch', ok);
+            await expect(bus.publish('ch', 1)).resolves.toBeUndefined();
+            expect(ok).toHaveBeenCalledTimes(1);
+            await bus.close();
+            void errors;
+        });
+
+        it('close rejects further publishes', async () => {
+            const bus = await make();
+            await bus.close();
+            await expect(bus.publish('ch', 1)).rejects.toThrow(/closed/);
+        });
+    });
+}
+
+export function runLockContract(name: string, make: () => Promise<ILock>) {
+    describe(`ILock contract — ${name}`, () => {
+        it('acquires and releases a free lock', async () => {
+            const l = await make();
+            const h = await l.acquire('k');
+            expect(h).not.toBeNull();
+            expect(h!.isHeld()).toBe(true);
+            await h!.release();
+            expect(h!.isHeld()).toBe(false);
+            await l.close();
+        });
+
+        it('fails fast when waitMs=0 and lock is held', async () => {
+            const l = await make();
+            const h1 = await l.acquire('k');
+            expect(h1).not.toBeNull();
+            const h2 = await l.acquire('k');
+            expect(h2).toBeNull();
+            await h1!.release();
+            await l.close();
+        });
+
+        it('hands off lock to a waiter on release', async () => {
+            const l = await make();
+            const h1 = await l.acquire('k');
+            const waiterP = l.acquire('k', { waitMs: 1000 });
+            await new Promise((r) => setTimeout(r, 10));
+            await h1!.release();
+            const h2 = await waiterP;
+            expect(h2).not.toBeNull();
+            expect(h2!.isHeld()).toBe(true);
+            await h2!.release();
+            await l.close();
+        });
+
+        it('TTL auto-releases a stuck holder', async () => {
+            const l = await make();
+            const h1 = await l.acquire('k', { ttlMs: 30 });
+            expect(h1).not.toBeNull();
+            await new Promise((r) => setTimeout(r, 60));
+            expect(h1!.isHeld()).toBe(false);
+            const h2 = await l.acquire('k');
+            expect(h2).not.toBeNull();
+            await h2!.release();
+            await l.close();
+        });
+
+        it('fencing tokens are monotonically increasing per key', async () => {
+            const l = await make();
+            const h1 = await l.acquire('k');
+            const t1 = h1!.fencingToken;
+            await h1!.release();
+            const h2 = await l.acquire('k');
+            expect(h2!.fencingToken).toBeGreaterThan(t1);
+            await h2!.release();
+            await l.close();
+        });
+
+        it('renew extends the lease', async () => {
+            const l = await make();
+            const h = await l.acquire('k', { ttlMs: 40 });
+            await new Promise((r) => setTimeout(r, 20));
+            await h!.renew(100);
+            await new Promise((r) => setTimeout(r, 30));
+            // total 50ms in, original TTL would have expired at 40ms.
+            expect(h!.isHeld()).toBe(true);
+            await h!.release();
+            await l.close();
+        });
+
+        it('renew on a lost lock throws', async () => {
+            const l = await make();
+            const h = await l.acquire('k', { ttlMs: 20 });
+            await new Promise((r) => setTimeout(r, 50));
+            await expect(h!.renew()).rejects.toThrow();
+            await l.close();
+        });
+
+        it('withLock returns fn result and auto-releases', async () => {
+            const l = await make();
+            const result = await l.withLock('k', async () => 42);
+            expect(result).toBe(42);
+            // Lock should be free immediately.
+            const h = await l.acquire('k');
+            expect(h).not.toBeNull();
+            await h!.release();
+            await l.close();
+        });
+
+        it('withLock returns null without calling fn on timeout', async () => {
+            const l = await make();
+            const h = await l.acquire('k');
+            const fn = vi.fn();
+            const result = await l.withLock('k', fn, { waitMs: 0 });
+            expect(result).toBeNull();
+            expect(fn).not.toHaveBeenCalled();
+            await h!.release();
+            await l.close();
+        });
+
+        it('release is idempotent', async () => {
+            const l = await make();
+            const h = await l.acquire('k');
+            await h!.release();
+            await expect(h!.release()).resolves.toBeUndefined();
+            await l.close();
+        });
+    });
+}
+
+export function runKVContract(name: string, make: () => Promise<IKV>) {
+    describe(`IKV contract — ${name}`, () => {
+        it('set then get round-trips and increments version', async () => {
+            const kv = await make();
+            const a = await kv.set('k', { v: 1 });
+            expect(a.version).toBe(1n);
+            const got = await kv.get<{ v: number }>('k');
+            expect(got?.value).toEqual({ v: 1 });
+            const b = await kv.set('k', { v: 2 });
+            expect(b.version).toBe(2n);
+            await kv.close();
+        });
+
+        it('get on missing key returns undefined', async () => {
+            const kv = await make();
+            expect(await kv.get('absent')).toBeUndefined();
+            await kv.close();
+        });
+
+        it('delete removes the key', async () => {
+            const kv = await make();
+            await kv.set('k', 1);
+            expect(await kv.delete('k')).toBe(true);
+            expect(await kv.get('k')).toBeUndefined();
+            expect(await kv.delete('k')).toBe(false);
+            await kv.close();
+        });
+
+        it('ifVersion=0n requires absent key', async () => {
+            const kv = await make();
+            await kv.set('k', 'first', { ifVersion: 0n });
+            await expect(kv.set('k', 'dup', { ifVersion: 0n })).rejects.toThrow(
+                /version mismatch/i,
+            );
+            await kv.close();
+        });
+
+        it('cas succeeds on match, fails on mismatch', async () => {
+            const kv = await make();
+            const e1 = await kv.set('k', 1);
+            const e2 = await kv.cas('k', e1.version, 2);
+            expect(e2?.value).toBe(2);
+            const failed = await kv.cas('k', e1.version, 3);
+            expect(failed).toBeUndefined();
+            await kv.close();
+        });
+
+        it('TTL expires entries', async () => {
+            const kv = await make();
+            await kv.set('k', 'v', { ttl: 0.03 }); // 30ms
+            expect((await kv.get('k'))?.value).toBe('v');
+            await new Promise((r) => setTimeout(r, 60));
+            expect(await kv.get('k')).toBeUndefined();
+            await kv.close();
+        });
+    });
+}
+
+export function runCounterContract(name: string, make: () => Promise<ICounter>) {
+    describe(`ICounter contract — ${name}`, () => {
+        it('starts at 0, incr returns new value', async () => {
+            const c = await make();
+            expect(await c.peek('k')).toBe(0n);
+            expect(await c.incr('k')).toBe(1n);
+            expect(await c.incr('k')).toBe(2n);
+            expect(await c.peek('k')).toBe(2n);
+            await c.close();
+        });
+
+        it('incr by custom delta', async () => {
+            const c = await make();
+            expect(await c.incr('k', { by: 5 })).toBe(5n);
+            expect(await c.incr('k', { by: -2 })).toBe(3n);
+            await c.close();
+        });
+
+        it('reset', async () => {
+            const c = await make();
+            await c.incr('k', { by: 10 });
+            await c.reset('k', 100n);
+            expect(await c.peek('k')).toBe(100n);
+            await c.reset('k');
+            expect(await c.peek('k')).toBe(0n);
+            await c.close();
+        });
+
+        it('isolates keys', async () => {
+            const c = await make();
+            await c.incr('a');
+            await c.incr('b', { by: 7 });
+            expect(await c.peek('a')).toBe(1n);
+            expect(await c.peek('b')).toBe(7n);
+            await c.close();
+        });
+    });
+}
+
+export function runFullContract(name: string, f: ContractFactories) {
+    runPubSubContract(name, f.makePubSub);
+    runLockContract(name, f.makeLock);
+    runKVContract(name, f.makeKV);
+    runCounterContract(name, f.makeCounter);
+}

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', 'src/testing.ts'],
+  splitting: true,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  format: ['esm', 'cjs'],
+  target: 'es2020',
+  external: ['vitest'],
+});