@objectstack/service-cluster 5.1.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@objectstack/service-cluster",
+  "version": "5.1.1",
+  "license": "Apache-2.0",
+  "description": "Cluster Service for ObjectStack — pluggable PubSub/Lock/KV/Counter primitives. Memory driver included; postgres/redis drivers ship separately.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "dependencies": {
+    "@objectstack/core": "5.2.0",
+    "@objectstack/spec": "5.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "objectstack",
+    "service",
+    "cluster",
+    "pubsub",
+    "lock",
+    "kv"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/services/service-cluster"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/cluster-service-plugin.ts

@@ -0,0 +1,77 @@
+// 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';
+import type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';
+import { defineCluster } from './cluster.js';
+
+/**
+ * Options for `ClusterServicePlugin`.
+ *
+ * Pass either a pre-built `cluster` instance (advanced — for tests or
+ * custom drivers), or a `config` object that will be passed to
+ * `defineCluster()`. If both are omitted, a memory-driver cluster is
+ * created with auto-generated nodeId.
+ */
+export interface ClusterServicePluginOptions {
+    /** Pre-built cluster service. Wins over `config` when both provided. */
+    cluster?: IClusterService;
+    /** Config forwarded to `defineCluster()` when `cluster` is absent. */
+    config?: ClusterCapabilityConfigInput;
+}
+
+/**
+ * Registers an `IClusterService` under the well-known service name
+ * `'cluster'`. Plugins consume it via:
+ *
+ * ```ts
+ * import type { IClusterService } from '@objectstack/spec/contracts';
+ * const cluster = ctx.getService<IClusterService>('cluster');
+ * await cluster.pubsub.publish('metadata.changed', payload);
+ * ```
+ *
+ * The plugin closes the cluster on kernel shutdown.
+ *
+ * @example default memory driver
+ *   kernel.use(new ClusterServicePlugin());
+ *
+ * @example explicit config
+ *   kernel.use(new ClusterServicePlugin({ config: { driver: 'memory', nodeId: 'web-1' } }));
+ */
+export class ClusterServicePlugin implements Plugin {
+    name = 'com.objectstack.service.cluster';
+    version = '1.0.0';
+    type = 'standard';
+
+    private readonly options: ClusterServicePluginOptions;
+    private cluster?: IClusterService;
+    private owned = false;
+
+    constructor(options: ClusterServicePluginOptions = {}) {
+        this.options = options;
+    }
+
+    async init(ctx: PluginContext): Promise<void> {
+        if (this.options.cluster) {
+            this.cluster = this.options.cluster;
+            this.owned = false;
+        } else {
+            this.cluster = defineCluster(this.options.config ?? {});
+            this.owned = true;
+        }
+        ctx.registerService('cluster', this.cluster);
+        ctx.logger.info(
+            `ClusterServicePlugin: registered "${this.cluster.driver}" driver (node=${this.cluster.nodeId})`,
+        );
+
+        ctx.hook('kernel:shutdown', async () => {
+            if (this.owned && this.cluster) {
+                try {
+                    await this.cluster.close();
+                } catch (err) {
+                    ctx.logger.error('ClusterServicePlugin: close error', err as Error);
+                }
+            }
+        });
+    }
+}

package/src/cluster.ts

@@ -0,0 +1,129 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+    IClusterService,
+    IPubSub,
+    ILock,
+    IKV,
+    ICounter,
+} from '@objectstack/spec/contracts';
+import type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';
+import { ClusterCapabilityConfigSchema } from '@objectstack/spec/kernel';
+
+import { MemoryPubSub } from './memory/pubsub.js';
+import { MemoryLock } from './memory/lock.js';
+import { MemoryKV } from './memory/kv.js';
+import { MemoryCounter } from './memory/counter.js';
+
+/**
+ * Compose four cluster primitives into a single `IClusterService` facade.
+ * Useful for custom driver authors who want to mix and match.
+ */
+export class ComposedClusterService implements IClusterService {
+    constructor(
+        public readonly nodeId: string,
+        public readonly driver: string,
+        public readonly pubsub: IPubSub,
+        public readonly lock: ILock,
+        public readonly kv: IKV,
+        public readonly counter: ICounter,
+    ) { }
+
+    async close(): Promise<void> {
+        // Reverse order, swallow errors so a slow close doesn't block siblings.
+        const closers = [this.counter, this.kv, this.lock, this.pubsub];
+        for (const c of closers) {
+            try {
+                await c.close();
+            } catch (err) {
+                // eslint-disable-next-line no-console
+                console.error('[ClusterService] close error:', err);
+            }
+        }
+    }
+}
+
+/**
+ * Build an `IClusterService` from a `ClusterCapabilityConfig`. The only
+ * driver shipped from this package is `memory`; other drivers (postgres,
+ * redis, nats) live in dedicated packages and register themselves via
+ * `registerClusterDriver()`.
+ *
+ * @example
+ *   const cluster = defineCluster({ driver: 'memory' });
+ *   await cluster.pubsub.publish('metadata.changed', { id: 'x' });
+ */
+export function defineCluster(
+    config: ClusterCapabilityConfigInput = {},
+): IClusterService {
+    const parsed = ClusterCapabilityConfigSchema.parse(config);
+    const nodeId = parsed.nodeId ?? generateNodeId();
+
+    if (parsed.driver === 'memory') {
+        return new ComposedClusterService(
+            nodeId,
+            'memory',
+            new MemoryPubSub({ nodeId }),
+            new MemoryLock({ defaultTtlMs: parsed.lockTtlMs }),
+            new MemoryKV(),
+            new MemoryCounter(),
+        );
+    }
+
+    const factory = driverRegistry.get(parsed.driver);
+    if (!factory) {
+        throw new Error(
+            `Cluster driver "${parsed.driver}" is not registered. ` +
+                `Did you forget to import @objectstack/service-cluster-${parsed.driver} ` +
+                `or call registerClusterDriver()? ` +
+                `See content/docs/concepts/cluster-semantics.mdx §6.`,
+        );
+    }
+    return factory({ ...parsed, nodeId });
+}
+
+// ---------------------------------------------------------------------------
+// Driver registry (for postgres/redis/nats/custom drivers)
+// ---------------------------------------------------------------------------
+
+export interface DriverFactoryConfig {
+    driver: string;
+    nodeId: string;
+    url?: string;
+    useExistingPool?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    tenantIsolation?: string;
+    driverOptions?: Record<string, unknown>;
+}
+
+export type ClusterDriverFactory = (config: DriverFactoryConfig) => IClusterService;
+
+const driverRegistry = new Map<string, ClusterDriverFactory>();
+
+/**
+ * Register a custom cluster driver. Driver packages (e.g.
+ * `@objectstack/service-cluster-postgres`) should call this at module
+ * load time so `defineCluster({ driver: 'postgres' })` resolves them.
+ */
+export function registerClusterDriver(
+    name: string,
+    factory: ClusterDriverFactory,
+): void {
+    if (name === 'memory') {
+        throw new Error('The "memory" driver is reserved.');
+    }
+    driverRegistry.set(name, factory);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function generateNodeId(): string {
+    // Avoid the `crypto` import dance for a single use; this is dev-only
+    // randomness and the driver upgrades replace it.
+    const rand = Math.random().toString(36).slice(2, 10);
+    const ts = Date.now().toString(36);
+    return `node-${ts}-${rand}`;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/service-cluster
+ *
+ * Pluggable cluster primitives (PubSub / Lock / KV / Counter) for
+ * ObjectStack. The default `memory` driver is exported here; remote
+ * drivers (postgres/redis/nats) ship as sibling packages and register
+ * themselves via `registerClusterDriver()`.
+ *
+ * See `content/docs/concepts/cluster-semantics.mdx` for the protocol.
+ */
+
+export {
+    defineCluster,
+    registerClusterDriver,
+    ComposedClusterService,
+    type ClusterDriverFactory,
+    type DriverFactoryConfig,
+} from './cluster.js';
+
+export { MemoryPubSub, type MemoryPubSubOptions } from './memory/pubsub.js';
+export { MemoryLock, type MemoryLockOptions } from './memory/lock.js';
+export { MemoryKV, VersionMismatchError } from './memory/kv.js';
+export { MemoryCounter } from './memory/counter.js';
+
+export {
+    ClusterServicePlugin,
+    type ClusterServicePluginOptions,
+} from './cluster-service-plugin.js';
+
+export { MetadataClusterBridgePlugin } from './metadata-cluster-bridge-plugin.js';
+
+// Re-export contracts for convenience.
+export type {
+    IClusterService,
+    IPubSub,
+    PubSubMessage,
+    PubSubHandler,
+    PublishOptions,
+    SubscribeOptions,
+    Unsubscribe,
+    ILock,
+    LockHandle,
+    LockAcquireOptions,
+    IKV,
+    KVEntry,
+    KVSetOptions,
+    ICounter,
+    CounterIncrOptions,
+    ClusterCallContext,
+} from '@objectstack/spec/contracts';

package/src/memory/counter.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';
+
+/**
+ * In-memory monotonic counter. Single-process only — for cross-node id
+ * allocation, use the postgres or redis driver.
+ */
+export class MemoryCounter implements ICounter {
+    private readonly counters = new Map<string, bigint>();
+    private closed = false;
+
+    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {
+        if (this.closed) throw new Error('MemoryCounter is closed');
+        const by = BigInt(opts.by ?? 1);
+        const current = this.counters.get(key) ?? 0n;
+        const next = current + by;
+        this.counters.set(key, next);
+        return next;
+    }
+
+    async peek(key: string): Promise<bigint> {
+        return this.counters.get(key) ?? 0n;
+    }
+
+    async reset(key: string, value: bigint = 0n): Promise<void> {
+        if (this.closed) throw new Error('MemoryCounter is closed');
+        if (value === 0n) this.counters.delete(key);
+        else this.counters.set(key, value);
+    }
+
+    async close(): Promise<void> {
+        this.closed = true;
+        this.counters.clear();
+    }
+}

package/src/memory/kv.ts

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';
+
+interface Entry<T = unknown> {
+    value: T;
+    version: bigint;
+    expiresAt?: number;
+    timer?: NodeJS.Timeout;
+}
+
+/**
+ * In-memory coordination KV. Supports optimistic concurrency via
+ * `ifVersion` and TTL via `ttl` (seconds).
+ *
+ * NOT a cache, NOT a database — intended for small cluster bookkeeping.
+ */
+export class MemoryKV implements IKV {
+    private readonly store = new Map<string, Entry>();
+    private closed = false;
+
+    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {
+        const e = this.store.get(key);
+        if (!e) return undefined;
+        if (e.expiresAt && Date.now() >= e.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return {
+            key,
+            value: e.value as T,
+            version: e.version,
+            expiresAt: e.expiresAt,
+        };
+    }
+
+    async set<T = unknown>(
+        key: string,
+        value: T,
+        opts: KVSetOptions = {},
+    ): Promise<KVEntry<T>> {
+        if (this.closed) throw new Error('MemoryKV is closed');
+        const existing = this.store.get(key);
+        const existingVersion = existing
+            ? existing.expiresAt && Date.now() >= existing.expiresAt
+                ? 0n
+                : existing.version
+            : 0n;
+        if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {
+            throw new VersionMismatchError(key, opts.ifVersion, existingVersion);
+        }
+        if (existing?.timer) clearTimeout(existing.timer);
+        const version = existingVersion + 1n;
+        const expiresAt = opts.ttl && opts.ttl > 0 ? Date.now() + opts.ttl * 1000 : undefined;
+        const entry: Entry<T> = { value, version, expiresAt };
+        if (expiresAt) {
+            entry.timer = setTimeout(() => {
+                const current = this.store.get(key);
+                if (current === (entry as Entry<unknown>)) this.store.delete(key);
+            }, expiresAt - Date.now());
+        }
+        this.store.set(key, entry as Entry<unknown>);
+        return { key, value, version, expiresAt };
+    }
+
+    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {
+        const e = this.store.get(key);
+        if (!e) return false;
+        if (e.expiresAt && Date.now() >= e.expiresAt) {
+            this.store.delete(key);
+            return false;
+        }
+        if (opts.ifVersion !== undefined && opts.ifVersion !== e.version) {
+            throw new VersionMismatchError(key, opts.ifVersion, e.version);
+        }
+        if (e.timer) clearTimeout(e.timer);
+        this.store.delete(key);
+        return true;
+    }
+
+    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;
+        for (const [, e] of this.store) {
+            if (e.timer) clearTimeout(e.timer);
+        }
+        this.store.clear();
+    }
+}
+
+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';
+    }
+}

package/src/memory/lock.ts

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+    ILock,
+    LockAcquireOptions,
+    LockHandle,
+} from '@objectstack/spec/contracts';
+
+/**
+ * In-memory lock for single-process deployments and tests.
+ *
+ * Behavior:
+ *   - Per-key FIFO wait queue (so `waitMs > 0` callers receive the lock
+ *     in arrival order).
+ *   - TTL is honored: if a holder doesn't renew before `ttlMs` elapses,
+ *     the lock is auto-released and the next waiter wakes.
+ *   - Fencing tokens are process-local monotonic bigints.
+ */
+
+const DEFAULT_TTL_MS = 15_000;
+
+export interface MemoryLockOptions {
+    /** Default TTL for `acquire` when caller doesn't supply one. */
+    defaultTtlMs?: number;
+}
+
+interface Holder {
+    fencingToken: bigint;
+    expiresAt: number;
+    released: boolean;
+    timer?: NodeJS.Timeout;
+}
+
+interface Waiter {
+    resolve: (h: LockHandle | null) => void;
+    deadline: number;
+    opts: LockAcquireOptions;
+    timer?: NodeJS.Timeout;
+}
+
+export class MemoryLock implements ILock {
+    private readonly holders = new Map<string, Holder>();
+    private readonly queues = new Map<string, Waiter[]>();
+    private readonly defaultTtlMs: number;
+    private fenceSeq = 0n;
+    private closed = false;
+
+    constructor(opts: MemoryLockOptions = {}) {
+        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;
+    }
+
+    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {
+        if (this.closed) throw new Error('MemoryLock is closed');
+        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;
+        const waitMs = opts.waitMs ?? 0;
+
+        if (!this.holders.has(key)) {
+            return this.grant(key, ttlMs);
+        }
+        if (waitMs <= 0) return null;
+
+        return new Promise<LockHandle | null>((resolve) => {
+            const deadline = Date.now() + waitMs;
+            const waiter: Waiter = { resolve, deadline, opts };
+            const queue = this.queues.get(key) ?? [];
+            queue.push(waiter);
+            this.queues.set(key, queue);
+            waiter.timer = setTimeout(() => {
+                const q = this.queues.get(key);
+                if (q) {
+                    const idx = q.indexOf(waiter);
+                    if (idx >= 0) q.splice(idx, 1);
+                }
+                resolve(null);
+            }, waitMs);
+        });
+    }
+
+    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;
+        for (const [, holder] of this.holders) {
+            if (holder.timer) clearTimeout(holder.timer);
+            holder.released = true;
+        }
+        this.holders.clear();
+        for (const [, q] of this.queues) {
+            for (const w of q) {
+                if (w.timer) clearTimeout(w.timer);
+                w.resolve(null);
+            }
+        }
+        this.queues.clear();
+    }
+
+    private grant(key: string, ttlMs: number): LockHandle {
+        const fencingToken = ++this.fenceSeq;
+        const holder: Holder = {
+            fencingToken,
+            expiresAt: Date.now() + ttlMs,
+            released: false,
+        };
+        holder.timer = setTimeout(() => this.expire(key, holder), ttlMs);
+        this.holders.set(key, holder);
+
+        const self = this;
+        const handle: LockHandle = {
+            key,
+            fencingToken,
+            isHeld: () => !holder.released && self.holders.get(key) === holder,
+            async renew(extendMs?: number) {
+                if (holder.released || self.holders.get(key) !== holder) {
+                    throw new Error(`Lock "${key}" no longer held (fence=${fencingToken})`);
+                }
+                const next = extendMs ?? ttlMs;
+                holder.expiresAt = Date.now() + next;
+                if (holder.timer) clearTimeout(holder.timer);
+                holder.timer = setTimeout(() => self.expire(key, holder), next);
+            },
+            async release() {
+                if (holder.released || self.holders.get(key) !== holder) return;
+                holder.released = true;
+                if (holder.timer) clearTimeout(holder.timer);
+                self.holders.delete(key);
+                self.handoff(key);
+            },
+        };
+        return handle;
+    }
+
+    private expire(key: string, holder: Holder): void {
+        if (holder.released) return;
+        if (this.holders.get(key) !== holder) return;
+        holder.released = true;
+        this.holders.delete(key);
+        this.handoff(key);
+    }
+
+    private handoff(key: string): void {
+        const queue = this.queues.get(key);
+        if (!queue || queue.length === 0) return;
+        const next = queue.shift()!;
+        if (next.timer) clearTimeout(next.timer);
+        if (Date.now() > next.deadline) {
+            next.resolve(null);
+            this.handoff(key);
+            return;
+        }
+        const ttlMs = next.opts.ttlMs ?? this.defaultTtlMs;
+        next.resolve(this.grant(key, ttlMs));
+        if (queue.length === 0) this.queues.delete(key);
+    }
+}

package/src/memory/memory.contract.test.ts

@@ -0,0 +1,65 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, expect, it } from 'vitest';
+import { runFullContract } from '../testing.js';
+import { MemoryPubSub } from './pubsub.js';
+import { MemoryLock } from './lock.js';
+import { MemoryKV } from './kv.js';
+import { MemoryCounter } from './counter.js';
+import { defineCluster } from '../cluster.js';
+
+runFullContract('memory', {
+    makePubSub: async () => new MemoryPubSub(),
+    makeLock: async () => new MemoryLock(),
+    makeKV: async () => new MemoryKV(),
+    makeCounter: async () => new MemoryCounter(),
+});
+
+describe('defineCluster(memory) smoke', () => {
+    it('builds a working facade with all four primitives', async () => {
+        const cluster = defineCluster({ driver: 'memory', nodeId: 'test-1' });
+        expect(cluster.nodeId).toBe('test-1');
+        expect(cluster.driver).toBe('memory');
+
+        // Round-trip through all four.
+        const received: unknown[] = [];
+        cluster.pubsub.subscribe('e', (m) => received.push(m.payload));
+        await cluster.pubsub.publish('e', 'hi');
+        expect(received).toEqual(['hi']);
+
+        const h = await cluster.lock.acquire('k');
+        expect(h).not.toBeNull();
+        await h!.release();
+
+        await cluster.kv.set('s', { ok: true });
+        expect((await cluster.kv.get('s'))?.value).toEqual({ ok: true });
+
+        expect(await cluster.counter.incr('seq')).toBe(1n);
+        expect(await cluster.counter.incr('seq')).toBe(2n);
+
+        await cluster.close();
+    });
+
+    it('auto-generates a nodeId when absent', () => {
+        const cluster = defineCluster();
+        expect(cluster.nodeId).toMatch(/^node-/);
+        void cluster.close();
+    });
+
+    it('rejects unknown drivers with a helpful message', () => {
+        expect(() => defineCluster({ driver: 'redis' })).toThrow(
+            /not registered/i,
+        );
+    });
+
+    it('PubSub messages carry the nodeId as fromNode', async () => {
+        const cluster = defineCluster({ driver: 'memory', nodeId: 'node-X' });
+        let from: string | undefined;
+        cluster.pubsub.subscribe('c', (m) => {
+            from = m.fromNode;
+        });
+        await cluster.pubsub.publish('c', 'p');
+        expect(from).toBe('node-X');
+        await cluster.close();
+    });
+});