@net-mesh/sdk 0.19.0

package/dist/groups.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Groups surface — `ReplicaGroup` / `ForkGroup` / `StandbyGroup`.
+ *
+ * Stage 2 of `SDK_GROUPS_SURFACE_PLAN.md`. Thin wrappers over the
+ * NAPI classes that add:
+ *
+ * - Typed `GroupError` extending `DaemonError` with a `kind`
+ *   discriminator parsed from the Rust side's stable
+ *   `daemon: group: <kind>[: detail]` error prefix.
+ * - `Buffer | Uint8Array` interop for `groupSeed`.
+ * - `MigrationOptions`-style config shapes with camelCase fields.
+ *
+ * @example
+ * ```typescript
+ * import { DaemonRuntime, Identity, ReplicaGroup } from '@net-mesh/sdk';
+ *
+ * // Register the factory the group will invoke for each member.
+ * rt.registerFactory('counter', () => new CounterDaemon());
+ *
+ * // Spawn a 3-member replica group. `spawn` is async — the
+ * // factory TSFN round-trip runs on a tokio worker so the Node
+ * // main thread stays free to execute JS factory callbacks.
+ * const group = await ReplicaGroup.spawn(rt, 'counter', {
+ *   replicaCount: 3,
+ *   groupSeed: Buffer.alloc(32, 0x11),  // 32 bytes
+ *   lbStrategy: 'round-robin',
+ * });
+ *
+ * // Route a request.
+ * const origin = group.routeEvent({ routingKey: 'user:42' });
+ * await rt.deliver(origin, someEvent);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type ReplicaGroupConfigJs, type ForkGroupConfigJs, type StandbyGroupConfigJs, type GroupHealthJs, type GroupHostConfigJs, type MemberInfoJs, type ForkRecordJs, type RequestContextJs, StrategyJs } from '@net-mesh/core';
+import { DaemonError } from './compute';
+import type { DaemonRuntime } from './compute';
+/**
+ * Stable machine-readable discriminator for group-layer failures.
+ * Parsed from the Rust side's `daemon: group: <kind>[: detail]`
+ * prefix; use `err.kind` in catch blocks rather than parsing the
+ * message string by hand.
+ */
+export type GroupErrorKind = 'not-ready' | 'factory-not-found' | 'no-healthy-member' | 'placement-failed' | 'registry-failed' | 'invalid-config' | 'daemon' | 'unknown';
+/**
+ * Typed group failure. Subclass of {@link DaemonError} so
+ * `catch (e: DaemonError)` still matches.
+ */
+export declare class GroupError extends DaemonError {
+    readonly kind: GroupErrorKind;
+    /** Optional detail string carried by `placement-failed` /
+     *  `registry-failed` / `invalid-config` / `daemon` variants. */
+    readonly detail?: string;
+    /** `factory-not-found` carries the requested kind name. */
+    readonly requestedKind?: string;
+    constructor(kind: GroupErrorKind, message: string, extras?: {
+        detail?: string;
+        requestedKind?: string;
+    });
+}
+/**
+ * Load-balancing strategy for inbound group events.
+ *
+ * - `round-robin` — rotate across healthy members.
+ * - `consistent-hash` — stable routing on `routingKey`.
+ * - `least-load` — pick the member with the lowest utilization.
+ * - `least-connections` — pick the member with the fewest in-flight calls.
+ * - `random` — uniformly-random healthy pick.
+ */
+export type GroupStrategy = StrategyJs;
+/** Per-member metadata. */
+export type GroupMemberInfo = MemberInfoJs;
+/** Aggregate health surface. */
+export type GroupHealth = GroupHealthJs;
+/** Lineage record for a single fork. */
+export type ForkRecord = ForkRecordJs;
+/** Routing context handed to `routeEvent`. */
+export type RequestContext = RequestContextJs;
+/** Per-daemon host config applied to every group member. */
+export type GroupHostConfig = GroupHostConfigJs;
+/** Config for a replica group. */
+export interface ReplicaGroupConfig extends Omit<ReplicaGroupConfigJs, 'groupSeed'> {
+    /** 32-byte seed. Accepts `Buffer` or `Uint8Array`. */
+    groupSeed: Buffer | Uint8Array;
+}
+/** Config for a fork group. */
+export type ForkGroupConfig = ForkGroupConfigJs;
+/** Config for a standby group. */
+export interface StandbyGroupConfig extends Omit<StandbyGroupConfigJs, 'groupSeed'> {
+    /** 32-byte seed. Accepts `Buffer` or `Uint8Array`. */
+    groupSeed: Buffer | Uint8Array;
+}
+/**
+ * N interchangeable copies of a daemon. Each replica has a
+ * deterministic identity derived from `groupSeed + index`;
+ * the group load-balances inbound events across healthy members
+ * and auto-replaces members on node failure.
+ */
+export declare class ReplicaGroup {
+    private readonly inner;
+    /**
+     * Spawn a replica group bound to `runtime`. `kind` must have
+     * been registered via {@link DaemonRuntime.registerFactory};
+     * the group calls the factory once per replica at spawn and
+     * again on scale-up / failure replacement.
+     *
+     * Async because the underlying SDK `spawn` runs on a tokio
+     * worker — the factory TSFN round-trip needs the Node main
+     * thread free to execute the JS factory callback, so a sync
+     * main-thread spawn would deadlock.
+     *
+     * Throws {@link GroupError} on `not-ready`, `factory-not-found`,
+     * `placement-failed`, `invalid-config`, or `registry-failed`.
+     */
+    static spawn(runtime: DaemonRuntime, kind: string, config: ReplicaGroupConfig): Promise<ReplicaGroup>;
+    /** Route to the best-available replica; returns the target
+     *  `origin_hash` which the caller feeds to `runtime.deliver`. */
+    routeEvent(ctx?: RequestContext): bigint;
+    /** Resize the group to `n` members. The kind is fixed at
+     *  spawn time and not accepted here — see the class docstring
+     *  for why. Async because growing invokes the factory (TSFN)
+     *  once per new replica. */
+    scaleTo(n: number): Promise<void>;
+    /** Replace all members on `failedNodeId` onto other nodes.
+     *  Returns the indices of replicas that were respawned.
+     *  Reuses the group's spawn kind. */
+    onNodeFailure(failedNodeId: bigint): Promise<number[]>;
+    onNodeRecovery(recoveredNodeId: bigint): void;
+    get health(): GroupHealth;
+    get groupId(): number;
+    get replicas(): GroupMemberInfo[];
+    get replicaCount(): number;
+    get healthyCount(): number;
+}
+/**
+ * N independent daemons forked from a common parent at
+ * `forkSeq`. Unique identities, shared ancestry via `ForkRecord`.
+ */
+export declare class ForkGroup {
+    private readonly inner;
+    /** Fork `config.forkCount` new daemons from `parentOrigin` at
+     *  `forkSeq`. Each fork gets a fresh unique keypair + a
+     *  `ForkRecord` linking it to the parent. Async for the same
+     *  deadlock-avoidance reason as {@link ReplicaGroup.spawn}. */
+    static fork(runtime: DaemonRuntime, kind: string, parentOrigin: bigint, forkSeq: bigint, config: ForkGroupConfig): Promise<ForkGroup>;
+    routeEvent(ctx?: RequestContext): bigint;
+    scaleTo(n: number): Promise<void>;
+    onNodeFailure(failedNodeId: bigint): Promise<number[]>;
+    onNodeRecovery(recoveredNodeId: bigint): void;
+    get health(): GroupHealth;
+    get parentOrigin(): bigint;
+    get forkSeq(): bigint;
+    get forkRecords(): ForkRecord[];
+    /** `true` iff every fork's `ForkRecord` verifies against its
+     *  parent. Core performs the signature + sentinel checks. */
+    verifyLineage(): boolean;
+    get members(): GroupMemberInfo[];
+    get forkCount(): number;
+    get healthyCount(): number;
+}
+/**
+ * Active-passive replication. One active processes events; N−1
+ * standbys hold snapshots and catch up via {@link sync}. On
+ * active failure, {@link promote} (or automatic failover via
+ * {@link onNodeFailure}) picks the most-synced standby.
+ *
+ * **Automatic replay buffering.** The group installs a
+ * post-delivery observer on its active member's origin at spawn
+ * and re-points it on promote / failover. Every
+ * `runtime.deliver(group.activeOrigin, event)` automatically
+ * feeds the standby replay buffer — no paired
+ * `onEventDelivered` call required from the caller. The method
+ * remains on the class for test scenarios that simulate a gap
+ * without a live runtime; production code should ignore it.
+ */
+export declare class StandbyGroup {
+    private readonly inner;
+    static spawn(runtime: DaemonRuntime, kind: string, config: StandbyGroupConfig): Promise<StandbyGroup>;
+    /** `origin_hash` of the current active. Target for inbound
+     *  events; standbys don't process inputs. */
+    get activeOrigin(): bigint;
+    /** Snapshot the active and push to every standby. Returns the
+     *  sequence number the sync caught up through. */
+    sync(): Promise<bigint>;
+    /** Promote the most-synced standby to active. Reuses the
+     *  group's spawn kind — no external parameter, so callers
+     *  can't accidentally promote with the wrong factory. Call
+     *  manually for planned failover; {@link onNodeFailure} calls
+     *  automatically when the active's node fails. */
+    promote(): Promise<bigint>;
+    /** Handle node failure. Returns the new active's `origin_hash`
+     *  if the active was on `failedNodeId`; `null` if only standbys
+     *  were affected. Reuses the group's spawn kind. */
+    onNodeFailure(failedNodeId: bigint): Promise<bigint | null>;
+    onNodeRecovery(recoveredNodeId: bigint): void;
+    get health(): GroupHealth;
+    get activeHealthy(): boolean;
+    get activeIndex(): number;
+    /** `"active"` | `"standby"` | `null` (out-of-range). */
+    memberRole(index: number): 'active' | 'standby' | null;
+    syncedThrough(index: number): bigint | null;
+    get bufferedEventCount(): number;
+    get groupId(): number;
+    get members(): GroupMemberInfo[];
+    get memberCount(): number;
+    get standbyCount(): number;
+}

package/dist/groups.js

@@ -0,0 +1,431 @@
+"use strict";
+/**
+ * Groups surface — `ReplicaGroup` / `ForkGroup` / `StandbyGroup`.
+ *
+ * Stage 2 of `SDK_GROUPS_SURFACE_PLAN.md`. Thin wrappers over the
+ * NAPI classes that add:
+ *
+ * - Typed `GroupError` extending `DaemonError` with a `kind`
+ *   discriminator parsed from the Rust side's stable
+ *   `daemon: group: <kind>[: detail]` error prefix.
+ * - `Buffer | Uint8Array` interop for `groupSeed`.
+ * - `MigrationOptions`-style config shapes with camelCase fields.
+ *
+ * @example
+ * ```typescript
+ * import { DaemonRuntime, Identity, ReplicaGroup } from '@net-mesh/sdk';
+ *
+ * // Register the factory the group will invoke for each member.
+ * rt.registerFactory('counter', () => new CounterDaemon());
+ *
+ * // Spawn a 3-member replica group. `spawn` is async — the
+ * // factory TSFN round-trip runs on a tokio worker so the Node
+ * // main thread stays free to execute JS factory callbacks.
+ * const group = await ReplicaGroup.spawn(rt, 'counter', {
+ *   replicaCount: 3,
+ *   groupSeed: Buffer.alloc(32, 0x11),  // 32 bytes
+ *   lbStrategy: 'round-robin',
+ * });
+ *
+ * // Route a request.
+ * const origin = group.routeEvent({ routingKey: 'user:42' });
+ * await rt.deliver(origin, someEvent);
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandbyGroup = exports.ForkGroup = exports.ReplicaGroup = exports.GroupError = void 0;
+const _internal_js_1 = require("./_internal.js");
+const compute_1 = require("./compute");
+/**
+ * Typed group failure. Subclass of {@link DaemonError} so
+ * `catch (e: DaemonError)` still matches.
+ */
+class GroupError extends compute_1.DaemonError {
+    kind;
+    /** Optional detail string carried by `placement-failed` /
+     *  `registry-failed` / `invalid-config` / `daemon` variants. */
+    detail;
+    /** `factory-not-found` carries the requested kind name. */
+    requestedKind;
+    constructor(kind, message, extras = {}) {
+        super(message);
+        this.name = 'GroupError';
+        this.kind = kind;
+        this.detail = extras.detail;
+        this.requestedKind = extras.requestedKind;
+        Object.setPrototypeOf(this, GroupError.prototype);
+    }
+}
+exports.GroupError = GroupError;
+/**
+ * Lift a caught unknown error into the right typed exception.
+ * The Rust side emits `daemon: group: <kind>[: detail]`; unknown
+ * kinds fall back to `kind: 'unknown'` with the raw body.
+ * Non-group errors pass through as plain `DaemonError` (or the
+ * original throw if the message doesn't start with `daemon:`).
+ */
+function toGroupError(e) {
+    const msg = e?.message ?? String(e);
+    if (msg.startsWith('daemon:')) {
+        const body = msg.slice('daemon:'.length).trim();
+        if (body.startsWith('group:')) {
+            throw parseGroupError(body, msg.slice('daemon:'.length).trim());
+        }
+        throw new compute_1.DaemonError(body);
+    }
+    throw e;
+}
+function parseGroupError(body, fullMessage) {
+    // Body shape after `daemon: ` stripping:
+    //   group: <kind>
+    //   group: <kind>: <detail>
+    const afterPrefix = body.slice('group:'.length).trim();
+    const firstColon = afterPrefix.indexOf(':');
+    const kind = firstColon === -1 ? afterPrefix : afterPrefix.slice(0, firstColon).trim();
+    const rest = firstColon === -1 ? '' : afterPrefix.slice(firstColon + 1).trim();
+    switch (kind) {
+        case 'not-ready':
+        case 'no-healthy-member':
+            return new GroupError(kind, fullMessage);
+        case 'factory-not-found':
+            return new GroupError(kind, fullMessage, { requestedKind: rest });
+        case 'placement-failed':
+        case 'registry-failed':
+        case 'invalid-config':
+        case 'daemon':
+            return new GroupError(kind, fullMessage, { detail: rest });
+        default:
+            return new GroupError('unknown', fullMessage);
+    }
+}
+function toBuffer(seed) {
+    return Buffer.isBuffer(seed) ? seed : Buffer.from(seed);
+}
+// ----------------------------------------------------------------------------
+// ReplicaGroup
+// ----------------------------------------------------------------------------
+/**
+ * N interchangeable copies of a daemon. Each replica has a
+ * deterministic identity derived from `groupSeed + index`;
+ * the group load-balances inbound events across healthy members
+ * and auto-replaces members on node failure.
+ */
+class ReplicaGroup {
+    inner;
+    /** @internal */
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Spawn a replica group bound to `runtime`. `kind` must have
+     * been registered via {@link DaemonRuntime.registerFactory};
+     * the group calls the factory once per replica at spawn and
+     * again on scale-up / failure replacement.
+     *
+     * Async because the underlying SDK `spawn` runs on a tokio
+     * worker — the factory TSFN round-trip needs the Node main
+     * thread free to execute the JS factory callback, so a sync
+     * main-thread spawn would deadlock.
+     *
+     * Throws {@link GroupError} on `not-ready`, `factory-not-found`,
+     * `placement-failed`, `invalid-config`, or `registry-failed`.
+     */
+    static async spawn(runtime, kind, config) {
+        try {
+            const napi = await (0, _internal_js_1.getNapiRuntime)(runtime).spawnReplicaGroup(kind, {
+                replicaCount: config.replicaCount,
+                groupSeed: toBuffer(config.groupSeed),
+                lbStrategy: config.lbStrategy,
+                hostConfig: config.hostConfig,
+            });
+            return new ReplicaGroup(napi);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    /** Route to the best-available replica; returns the target
+     *  `origin_hash` which the caller feeds to `runtime.deliver`. */
+    routeEvent(ctx = {}) {
+        try {
+            return this.inner.routeEvent(ctx);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    /** Resize the group to `n` members. The kind is fixed at
+     *  spawn time and not accepted here — see the class docstring
+     *  for why. Async because growing invokes the factory (TSFN)
+     *  once per new replica. */
+    async scaleTo(n) {
+        try {
+            await this.inner.scaleTo(n);
+        }
+        catch (e) {
+            toGroupError(e);
+        }
+    }
+    /** Replace all members on `failedNodeId` onto other nodes.
+     *  Returns the indices of replicas that were respawned.
+     *  Reuses the group's spawn kind. */
+    async onNodeFailure(failedNodeId) {
+        try {
+            return await this.inner.onNodeFailure(failedNodeId);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    onNodeRecovery(recoveredNodeId) {
+        try {
+            this.inner.onNodeRecovery(recoveredNodeId);
+        }
+        catch (e) {
+            toGroupError(e);
+        }
+    }
+    get health() {
+        return this.inner.health;
+    }
+    get groupId() {
+        return this.inner.groupId;
+    }
+    get replicas() {
+        return this.inner.replicas;
+    }
+    get replicaCount() {
+        return this.inner.replicaCount;
+    }
+    get healthyCount() {
+        return this.inner.healthyCount;
+    }
+}
+exports.ReplicaGroup = ReplicaGroup;
+// ----------------------------------------------------------------------------
+// ForkGroup
+// ----------------------------------------------------------------------------
+/**
+ * N independent daemons forked from a common parent at
+ * `forkSeq`. Unique identities, shared ancestry via `ForkRecord`.
+ */
+class ForkGroup {
+    inner;
+    /** @internal */
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /** Fork `config.forkCount` new daemons from `parentOrigin` at
+     *  `forkSeq`. Each fork gets a fresh unique keypair + a
+     *  `ForkRecord` linking it to the parent. Async for the same
+     *  deadlock-avoidance reason as {@link ReplicaGroup.spawn}. */
+    static async fork(runtime, kind, parentOrigin, forkSeq, config) {
+        try {
+            const napi = await (0, _internal_js_1.getNapiRuntime)(runtime).spawnForkGroup(kind, parentOrigin, forkSeq, config);
+            return new ForkGroup(napi);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    routeEvent(ctx = {}) {
+        try {
+            return this.inner.routeEvent(ctx);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    async scaleTo(n) {
+        try {
+            await this.inner.scaleTo(n);
+        }
+        catch (e) {
+            toGroupError(e);
+        }
+    }
+    async onNodeFailure(failedNodeId) {
+        try {
+            return await this.inner.onNodeFailure(failedNodeId);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    onNodeRecovery(recoveredNodeId) {
+        try {
+            this.inner.onNodeRecovery(recoveredNodeId);
+        }
+        catch (e) {
+            toGroupError(e);
+        }
+    }
+    get health() {
+        return this.inner.health;
+    }
+    get parentOrigin() {
+        return this.inner.parentOrigin;
+    }
+    get forkSeq() {
+        return this.inner.forkSeq;
+    }
+    get forkRecords() {
+        return this.inner.forkRecords;
+    }
+    /** `true` iff every fork's `ForkRecord` verifies against its
+     *  parent. Core performs the signature + sentinel checks. */
+    verifyLineage() {
+        return this.inner.verifyLineage();
+    }
+    get members() {
+        return this.inner.members;
+    }
+    get forkCount() {
+        return this.inner.forkCount;
+    }
+    get healthyCount() {
+        return this.inner.healthyCount;
+    }
+}
+exports.ForkGroup = ForkGroup;
+// ----------------------------------------------------------------------------
+// StandbyGroup
+// ----------------------------------------------------------------------------
+/**
+ * Active-passive replication. One active processes events; N−1
+ * standbys hold snapshots and catch up via {@link sync}. On
+ * active failure, {@link promote} (or automatic failover via
+ * {@link onNodeFailure}) picks the most-synced standby.
+ *
+ * **Automatic replay buffering.** The group installs a
+ * post-delivery observer on its active member's origin at spawn
+ * and re-points it on promote / failover. Every
+ * `runtime.deliver(group.activeOrigin, event)` automatically
+ * feeds the standby replay buffer — no paired
+ * `onEventDelivered` call required from the caller. The method
+ * remains on the class for test scenarios that simulate a gap
+ * without a live runtime; production code should ignore it.
+ */
+class StandbyGroup {
+    inner;
+    /** @internal */
+    constructor(inner) {
+        this.inner = inner;
+    }
+    static async spawn(runtime, kind, config) {
+        try {
+            const napi = await (0, _internal_js_1.getNapiRuntime)(runtime).spawnStandbyGroup(kind, {
+                memberCount: config.memberCount,
+                groupSeed: toBuffer(config.groupSeed),
+                hostConfig: config.hostConfig,
+            });
+            return new StandbyGroup(napi);
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    /** `origin_hash` of the current active. Target for inbound
+     *  events; standbys don't process inputs. */
+    get activeOrigin() {
+        return this.inner.activeOrigin;
+    }
+    /** Snapshot the active and push to every standby. Returns the
+     *  sequence number the sync caught up through. */
+    async sync() {
+        try {
+            return await this.inner.syncStandbys();
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    /**
+     * **Test-only.** Manually push an event into the replay
+     * buffer. Production code does NOT need to call this — the
+     * post-delivery observer installed at `spawn` / `promote`
+     * automatically feeds the buffer on every
+     * `runtime.deliver(group.activeOrigin, event)`. Exposed so
+     * tests can simulate a gap between the last sync and a
+     * failure without driving a live runtime. Not part of the
+     * stable public API.
+     *
+     * @internal
+     */
+    onEventDelivered(event) {
+        try {
+            this.inner.onEventDelivered(event);
+        }
+        catch (e) {
+            toGroupError(e);
+        }
+    }
+    /** Promote the most-synced standby to active. Reuses the
+     *  group's spawn kind — no external parameter, so callers
+     *  can't accidentally promote with the wrong factory. Call
+     *  manually for planned failover; {@link onNodeFailure} calls
+     *  automatically when the active's node fails. */
+    async promote() {
+        try {
+            return await this.inner.promote();
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    /** Handle node failure. Returns the new active's `origin_hash`
+     *  if the active was on `failedNodeId`; `null` if only standbys
+     *  were affected. Reuses the group's spawn kind. */
+    async onNodeFailure(failedNodeId) {
+        try {
+            const r = await this.inner.onNodeFailure(failedNodeId);
+            return r ?? null;
+        }
+        catch (e) {
+            return toGroupError(e);
+        }
+    }
+    onNodeRecovery(recoveredNodeId) {
+        try {
+            this.inner.onNodeRecovery(recoveredNodeId);
+        }
+        catch (e) {
+            toGroupError(e);
+        }
+    }
+    get health() {
+        return this.inner.health;
+    }
+    get activeHealthy() {
+        return this.inner.activeHealthy;
+    }
+    get activeIndex() {
+        return this.inner.activeIndex;
+    }
+    /** `"active"` | `"standby"` | `null` (out-of-range). */
+    memberRole(index) {
+        const r = this.inner.memberRole(index);
+        return r ?? null;
+    }
+    syncedThrough(index) {
+        return this.inner.syncedThrough(index) ?? null;
+    }
+    get bufferedEventCount() {
+        return this.inner.bufferedEventCount;
+    }
+    get groupId() {
+        return this.inner.groupId;
+    }
+    get members() {
+        return this.inner.members;
+    }
+    get memberCount() {
+        return this.inner.memberCount;
+    }
+    get standbyCount() {
+        return this.inner.standbyCount;
+    }
+}
+exports.StandbyGroup = StandbyGroup;