actor-ts 0.9.0

package/dist/cluster/ClusterClient.js

@@ -0,0 +1,280 @@
+/**
+ * Outside-in entrypoint for talking to actors on a remote cluster (#86).
+ *
+ * `ClusterClient` is a lightweight handle that connects to one of a
+ * supplied list of "contact-point" cluster nodes and exchanges wire
+ * messages with the `ClusterClientReceptionist` running there.  The
+ * client itself does NOT join the cluster — it has no NodeAddress in
+ * the membership ring, no heartbeat duty, no gossip role.  It's
+ * appropriate for:
+ *
+ *   - REST frontends sending commands to a sharded entity actor.
+ *   - Cron / batch jobs poking specific actors on a schedule.
+ *   - Operator scripts talking to administrative actors.
+ *
+ * **What's IN scope for v1:**
+ *   - Fire-and-forget `send(targetPath, message)`.
+ *   - Request/reply `ask(targetPath, message, timeoutMs)`.
+ *   - Contact-point failover on dial errors (round-robin).
+ *
+ * **What's OUT of scope for v1:**
+ *   - ActorRef payloads.  If `message` contains an embedded `ActorRef`
+ *     it won't be rewritten — the cluster will receive whatever the
+ *     JSON-serialized form is, typically dead-letter-bound.
+ *   - Per-message routing to a specific cluster node.  Whoever
+ *     happens to be the active contact-point routes locally; if your
+ *     target is sharded across the cluster, the receiving node's
+ *     local `ShardRegion` does the further hop.
+ *   - Push-style subscriptions (the cluster pushing events to the
+ *     client without a prior ask).  Add a follow-up issue if needed.
+ *
+ * Design notes — TCP-piggyback over the cluster transport (Plan-A
+ * from the v0.8.0 plan-doc): the client opens one persistent TCP
+ * connection to the active contact-point, performs the standard
+ * `hello`/`hello-ack` handshake from `Protocol.ts` with a synthetic
+ * client address, then exchanges `cluster-client-envelope` and
+ * `cluster-client-reply` frames.  Reusing the wire layer means we
+ * inherit framing, ordering, and TLS for free.
+ */
+import { getTcpBackend } from '../runtime/tcp/index.js';
+import { ConsoleLogger, LogLevel } from '../Logger.js';
+import { DEFAULT_ASK_TIMEOUT_MS } from '../util/Constants.js';
+import { NodeAddress } from './NodeAddress.js';
+import { encodeFrame, FrameDecoder } from './Protocol.js';
+const HELLO_TIMEOUT_MS = 5_000;
+let _askCounter = 0;
+function nextAskId() {
+    _askCounter = (_askCounter + 1) >>> 0;
+    return `c${Date.now()}-${_askCounter}`;
+}
+/**
+ * Connect to a cluster via one of the listed contact-points and exchange
+ * messages with actors on the cluster.  See the file header for scope.
+ */
+export class ClusterClient {
+    settings;
+    contactPoints;
+    identity;
+    tls;
+    askTimeoutMs;
+    log;
+    socket = null;
+    decoder = new FrameDecoder();
+    connectingPromise = null;
+    nextContactIdx = 0;
+    pending = new Map();
+    stopped = false;
+    /** Filled by `hello-ack`; the contact-point's real address (post-handshake). */
+    contactPointPeer = null;
+    constructor(settings) {
+        this.settings = settings;
+        if (!settings.contactPoints || settings.contactPoints.length === 0) {
+            throw new Error('ClusterClient: contactPoints must contain at least one entry');
+        }
+        const sysName = settings.systemName ?? 'cluster-client';
+        this.contactPoints = settings.contactPoints.map((s) => {
+            const withSys = s.includes('@') ? s : `${sysName}@${s}`;
+            return NodeAddress.parse(withSys);
+        });
+        const id = settings.clientIdentity ?? {
+            host: '127.0.0.1',
+            // Synthetic port — must be unique per ClusterClient instance in the
+            // same process so the cluster's byPeer map doesn't collide.  Use
+            // hrtime-derived randomness within the ephemeral range.
+            port: 50_000 + Math.floor(Math.random() * 15_000),
+        };
+        this.identity = new NodeAddress(sysName, id.host, id.port);
+        this.tls = settings.tls ?? null;
+        this.askTimeoutMs = settings.askTimeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
+        this.log = settings.log ?? new ConsoleLogger(LogLevel.Warn, 'cluster-client');
+    }
+    /** The synthetic identity this client uses in its `hello` handshake. */
+    get clientAddress() { return this.identity; }
+    /**
+     * Fire-and-forget tell to the actor at `targetPath` on the cluster.
+     * `targetPath` accepts the same shapes as `ActorSystem.actorSelection`:
+     * full URI, absolute path, or relative-to-`/user`.
+     */
+    async send(targetPath, message) {
+        await this.ensureConnected();
+        const env = {
+            t: 'cluster-client-envelope',
+            from: this.identity.toJSON(),
+            to: targetPath,
+            body: message,
+        };
+        this.writeFrame(env);
+    }
+    /**
+     * Send a message and wait for a reply.  Resolves with the reply body
+     * on success, rejects with an Error on path-not-found / timeout /
+     * cluster-side ask failure.
+     */
+    async ask(targetPath, message, timeoutMs) {
+        await this.ensureConnected();
+        const askId = nextAskId();
+        const env = {
+            t: 'cluster-client-envelope',
+            from: this.identity.toJSON(),
+            to: targetPath,
+            askId,
+            body: message,
+        };
+        return new Promise((resolve, reject) => {
+            const ms = timeoutMs ?? this.askTimeoutMs;
+            const timer = setTimeout(() => {
+                this.pending.delete(askId);
+                reject(new Error(`ClusterClient.ask timed out after ${ms}ms (path=${targetPath})`));
+            }, ms);
+            this.pending.set(askId, {
+                resolve: (v) => resolve(v),
+                reject, timer,
+            });
+            this.writeFrame(env);
+        });
+    }
+    /** Close the connection.  Idempotent. */
+    async close() {
+        this.stopped = true;
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error('ClusterClient closed'));
+        }
+        this.pending.clear();
+        if (this.socket) {
+            try {
+                this.socket.end();
+            }
+            catch { /* ignore */ }
+            this.socket = null;
+        }
+    }
+    /* --------------------------- internals ---------------------------- */
+    async ensureConnected() {
+        if (this.stopped)
+            throw new Error('ClusterClient is closed');
+        if (this.socket && this.contactPointPeer)
+            return;
+        if (this.connectingPromise)
+            return this.connectingPromise;
+        this.connectingPromise = this.connect();
+        try {
+            await this.connectingPromise;
+        }
+        finally {
+            this.connectingPromise = null;
+        }
+    }
+    async connect() {
+        const backend = await getTcpBackend();
+        const errors = [];
+        // Try each contact-point in order, advancing the round-robin index
+        // so a future reconnect prefers the next one.
+        for (let attempt = 0; attempt < this.contactPoints.length; attempt++) {
+            const target = this.contactPoints[(this.nextContactIdx + attempt) % this.contactPoints.length];
+            try {
+                const sock = await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error(`ClusterClient connect to ${target} timed out after ${HELLO_TIMEOUT_MS}ms`)), HELLO_TIMEOUT_MS);
+                    let openSock = null;
+                    backend.connect({
+                        host: target.host,
+                        port: target.port,
+                        ...(this.tls ? { tls: this.tls } : {}),
+                        handlers: {
+                            onOpen: (s) => {
+                                openSock = s;
+                                // Send hello.
+                                const hello = { t: 'hello', self: this.identity.toJSON() };
+                                try {
+                                    s.write(encodeFrame(hello));
+                                }
+                                catch (e) {
+                                    clearTimeout(timer);
+                                    reject(e);
+                                }
+                            },
+                            onData: (s, chunk) => {
+                                this.onData(s, chunk, (peer) => {
+                                    this.contactPointPeer = peer;
+                                    this.socket = s;
+                                    clearTimeout(timer);
+                                    resolve(s);
+                                });
+                            },
+                            onClose: (_s) => this.onSocketClose(),
+                            onError: (_s, err) => {
+                                clearTimeout(timer);
+                                if (openSock === null)
+                                    reject(err);
+                                else
+                                    this.log.warn(`ClusterClient socket error`, err);
+                            },
+                        },
+                    }).catch((err) => {
+                        clearTimeout(timer);
+                        reject(err);
+                    });
+                });
+                void sock;
+                // Move the round-robin index past the successful contact-point
+                // so the next reconnect prefers a different one.
+                this.nextContactIdx = (this.nextContactIdx + attempt + 1) % this.contactPoints.length;
+                return;
+            }
+            catch (e) {
+                errors.push(e);
+            }
+        }
+        throw new Error(`ClusterClient: failed to connect to any of ${this.contactPoints.length} `
+            + `contact-point(s).  Errors: ${errors.map((e) => e.message).join('; ')}`);
+    }
+    onData(sock, chunk, onHelloAck) {
+        const frames = this.decoder.push(chunk);
+        for (const frame of frames) {
+            if (frame.t === 'hello-ack') {
+                const ack = frame;
+                onHelloAck(NodeAddress.fromJSON(ack.self));
+                continue;
+            }
+            const t = frame.t;
+            if (t === 'cluster-client-reply') {
+                this.handleReply(frame);
+                continue;
+            }
+            this.log.debug(`ClusterClient: ignoring unsolicited frame type "${t}"`);
+        }
+        void sock;
+    }
+    handleReply(reply) {
+        const pending = this.pending.get(reply.askId);
+        if (!pending)
+            return;
+        this.pending.delete(reply.askId);
+        clearTimeout(pending.timer);
+        if (reply.ok) {
+            pending.resolve(reply.body);
+        }
+        else {
+            pending.reject(new Error(typeof reply.body === 'string' ? reply.body : JSON.stringify(reply.body)));
+        }
+    }
+    onSocketClose() {
+        this.socket = null;
+        this.contactPointPeer = null;
+        this.decoder = new FrameDecoder();
+        // Pending asks fail — the user can retry, which will reconnect.
+        for (const [id, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error('ClusterClient: connection closed before reply arrived'));
+            void id;
+        }
+        this.pending.clear();
+    }
+    writeFrame(msg) {
+        if (!this.socket) {
+            throw new Error('ClusterClient: not connected — call send()/ask() which awaits ensureConnected()');
+        }
+        this.socket.write(encodeFrame(msg));
+    }
+}
+//# sourceMappingURL=ClusterClient.js.map

package/dist/cluster/ClusterClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterClient.js","sourceRoot":"","sources":["../../src/cluster/ClusterClient.ts"],"names":[],"mappings":"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"}

package/dist/cluster/ClusterClientReceptionist.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Cluster-side endpoint for {@link ClusterClient} (#86).
+ *
+ * The receptionist is a thin wire-handler bridge: a `cluster-client-
+ * envelope` frame coming over a cluster transport gets unpacked, the
+ * target actor is resolved through the local `ActorSystem`, and the
+ * message is delivered.  When the envelope carries an `askId`, the
+ * receptionist forwards as an ask + sends the reply back as a
+ * `cluster-client-reply` over the same transport.
+ *
+ * What this is NOT:
+ *   - It is NOT a gateway for *cross-cluster* communication.  A
+ *     ClusterClient connects to one cluster — the receptionist on that
+ *     cluster forwards locally to that node's user actor tree.
+ *   - It does NOT route to other cluster nodes.  If you want sharded
+ *     routing, the local actor on the receiving node has to do that
+ *     (e.g. via `ClusterSharding`).  Receptionist's job is just the
+ *     in-tree lookup.
+ *
+ * Wire format — symmetric on both directions:
+ *
+ *   {
+ *     t: 'cluster-client-envelope',
+ *     from: NodeAddressData,          // synthetic client address
+ *     to: '/user/some/actor',          // actor path on the cluster
+ *     askId: 'a-42' | undefined,       // present for ask
+ *     body: unknown,                   // user payload
+ *   }
+ *
+ *   {
+ *     t: 'cluster-client-reply',
+ *     askId: 'a-42',
+ *     ok: true | false,
+ *     body: unknown,                   // the reply, or error.message if !ok
+ *   }
+ *
+ * Receptionist failures (path not found, ask timeout) come back as
+ * `{ ok: false, body: '<reason>' }` so the client always sees a
+ * deterministic shape.
+ */
+import type { ActorSystem } from '../ActorSystem.js';
+import { type Extension, type ExtensionId } from '../Extension.js';
+import { type NodeAddressData } from './NodeAddress.js';
+import type { Cluster } from './Cluster.js';
+/** Inbound: a client wants to deliver `body` to actor at `to`. */
+export interface ClusterClientEnvelopeMsg {
+    readonly t: 'cluster-client-envelope';
+    readonly from: NodeAddressData;
+    readonly to: string;
+    readonly askId?: string;
+    readonly body: unknown;
+}
+/** Outbound: reply to a client ask. */
+export interface ClusterClientReplyMsg {
+    readonly t: 'cluster-client-reply';
+    readonly askId: string;
+    readonly ok: boolean;
+    readonly body: unknown;
+}
+export interface ClusterClientReceptionistSettings {
+    /**
+     * Default ask timeout (ms) when a client envelope carries an `askId`.
+     * Default: 5_000.
+     */
+    readonly askTimeoutMs?: number;
+}
+/**
+ * Per-system extension that runs once `start(cluster)` is called.
+ * Registers a wire handler on the cluster transport; calling `stop()`
+ * unregisters it.  Re-callable: a second `start(cluster)` on the same
+ * cluster returns the same handle.
+ */
+export declare class ClusterClientReceptionist implements Extension {
+    private readonly system;
+    private _started;
+    private _unsubscribe;
+    private _cluster;
+    constructor(system: ActorSystem);
+    start(cluster: Cluster, settings?: ClusterClientReceptionistSettings): void;
+    /** Stop accepting client envelopes.  Idempotent. */
+    stop(): void;
+    private sendReply;
+}
+export declare const ClusterClientReceptionistId: ExtensionId<ClusterClientReceptionist>;
+//# sourceMappingURL=ClusterClientReceptionist.d.ts.map

package/dist/cluster/ClusterClientReceptionist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterClientReceptionist.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterClientReceptionist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhF,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,kEAAkE;AAClE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,CAAC,EAAE,yBAAyB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,CAAC,EAAE,sBAAsB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAID,MAAM,WAAW,iCAAiC;IAChD;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,YAAW,SAAS;IAK7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAwB;gBAEX,MAAM,EAAE,WAAW;IAEhD,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,iCAAsC,GAAG,IAAI;IAwD/E,oDAAoD;IACpD,IAAI,IAAI,IAAI;IASZ,OAAO,CAAC,SAAS;CAYlB;AAED,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,yBAAyB,CAI5E,CAAC"}

package/dist/cluster/ClusterClientReceptionist.js

@@ -0,0 +1,159 @@
+/**
+ * Cluster-side endpoint for {@link ClusterClient} (#86).
+ *
+ * The receptionist is a thin wire-handler bridge: a `cluster-client-
+ * envelope` frame coming over a cluster transport gets unpacked, the
+ * target actor is resolved through the local `ActorSystem`, and the
+ * message is delivered.  When the envelope carries an `askId`, the
+ * receptionist forwards as an ask + sends the reply back as a
+ * `cluster-client-reply` over the same transport.
+ *
+ * What this is NOT:
+ *   - It is NOT a gateway for *cross-cluster* communication.  A
+ *     ClusterClient connects to one cluster — the receptionist on that
+ *     cluster forwards locally to that node's user actor tree.
+ *   - It does NOT route to other cluster nodes.  If you want sharded
+ *     routing, the local actor on the receiving node has to do that
+ *     (e.g. via `ClusterSharding`).  Receptionist's job is just the
+ *     in-tree lookup.
+ *
+ * Wire format — symmetric on both directions:
+ *
+ *   {
+ *     t: 'cluster-client-envelope',
+ *     from: NodeAddressData,          // synthetic client address
+ *     to: '/user/some/actor',          // actor path on the cluster
+ *     askId: 'a-42' | undefined,       // present for ask
+ *     body: unknown,                   // user payload
+ *   }
+ *
+ *   {
+ *     t: 'cluster-client-reply',
+ *     askId: 'a-42',
+ *     ok: true | false,
+ *     body: unknown,                   // the reply, or error.message if !ok
+ *   }
+ *
+ * Receptionist failures (path not found, ask timeout) come back as
+ * `{ ok: false, body: '<reason>' }` so the client always sees a
+ * deterministic shape.
+ */
+import { extensionId } from '../Extension.js';
+import { DEFAULT_ASK_TIMEOUT_MS } from '../util/Constants.js';
+import { NodeAddress } from './NodeAddress.js';
+/**
+ * Per-system extension that runs once `start(cluster)` is called.
+ * Registers a wire handler on the cluster transport; calling `stop()`
+ * unregisters it.  Re-callable: a second `start(cluster)` on the same
+ * cluster returns the same handle.
+ */
+export class ClusterClientReceptionist {
+    system;
+    _started = false;
+    _unsubscribe = null;
+    _cluster = null;
+    constructor(system) {
+        this.system = system;
+    }
+    start(cluster, settings = {}) {
+        if (this._started && this._cluster === cluster)
+            return;
+        if (this._started) {
+            throw new Error('ClusterClientReceptionist is already bound to a different cluster');
+        }
+        this._cluster = cluster;
+        const askTimeoutMs = settings.askTimeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
+        const log = this.system.log.withSource(`cluster-client-receptionist@${cluster.selfAddress}`);
+        this._unsubscribe = cluster._onWire('cluster-client-envelope', (msg) => {
+            const env = msg;
+            const from = NodeAddress.fromJSON(env.from);
+            // Resolve the target locally.  We use the synchronous `_resolvePath`
+            // rather than `actorSelection().resolveOne()` because the client
+            // expects a deterministic immediate reply if the path is unknown —
+            // there's no point waiting for it to maybe spawn.
+            const segments = parsePathSegments(env.to);
+            const refOpt = segments
+                ? this.system._resolvePath(segments)
+                : { isSome: () => false };
+            if (!refOpt.isSome()) {
+                // Unknown path — for asks, return an error reply; for tells, drop.
+                if (env.askId !== undefined) {
+                    this.sendReply(cluster, from, env.askId, false, `path not found on cluster node ${cluster.selfAddress}: ${env.to}`);
+                }
+                else {
+                    log.debug(`cluster-client tell to unknown path ${env.to} — dropped`);
+                }
+                return;
+            }
+            const target = refOpt.value;
+            if (env.askId === undefined) {
+                // Fire-and-forget tell.
+                try {
+                    target.tell(env.body);
+                }
+                catch (e) {
+                    log.warn(`cluster-client tell to ${env.to} threw`, e);
+                }
+                return;
+            }
+            // Ask-and-reply.
+            void target.ask(env.body, askTimeoutMs).then((reply) => {
+                this.sendReply(cluster, from, env.askId, true, reply);
+            }, (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                this.sendReply(cluster, from, env.askId, false, message);
+            });
+        });
+        this._started = true;
+    }
+    /** Stop accepting client envelopes.  Idempotent. */
+    stop() {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+        this._cluster = null;
+        this._started = false;
+    }
+    /* --------------------------- internals ---------------------------- */
+    sendReply(cluster, to, askId, ok, body) {
+        const reply = {
+            t: 'cluster-client-reply', askId, ok, body,
+        };
+        cluster.transport.send(to, reply);
+    }
+}
+export const ClusterClientReceptionistId = extensionId('actor-ts/cluster/cluster-client-receptionist', (system) => new ClusterClientReceptionist(system));
+/* ----------------------- path-segment parser ---------------------- */
+/**
+ * Parse a path string into segments suitable for `_resolvePath`.
+ * Accepts:
+ *   - 'actor-ts://<sys>/user/foo/bar' — full URI
+ *   - '/user/foo/bar'                  — absolute with leading slash
+ *   - 'user/foo/bar'                   — absolute without leading slash
+ *   - 'foo/bar'                        — relative to `/user`
+ *
+ * Returns `null` if the URI's system name doesn't match — the helper
+ * doesn't accept that branch.
+ */
+function parsePathSegments(path) {
+    // Strip URI scheme + authority.
+    let p = path;
+    const uriPrefix = 'actor-ts://';
+    if (p.startsWith(uriPrefix)) {
+        const slash = p.indexOf('/', uriPrefix.length);
+        p = slash < 0 ? '' : p.slice(slash + 1);
+    }
+    else if (p.startsWith('/')) {
+        p = p.slice(1);
+    }
+    // Convention: paths under `/user` can be addressed bare.  Map both
+    // `user/foo/bar` and `foo/bar` to the segments `['user', 'foo', 'bar']`.
+    if (!p.startsWith('user/') && p !== 'user') {
+        if (p !== '')
+            p = `user/${p}`;
+        else
+            p = 'user';
+    }
+    const segs = p.split('/').filter((s) => s.length > 0);
+    return segs.length === 0 ? null : segs;
+}
+//# sourceMappingURL=ClusterClientReceptionist.js.map

package/dist/cluster/ClusterClientReceptionist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterClientReceptionist.js","sourceRoot":"","sources":["../../src/cluster/ClusterClientReceptionist.ts"],"names":[],"mappings":"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"}

package/dist/cluster/ClusterEvents.d.ts

@@ -0,0 +1,99 @@
+import { Member } from './Member.js';
+import type { Option } from '../util/Option.js';
+/** Fired on the local node when its own member transitions to Up. */
+export declare class SelfUp {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/**
+ * Fired on the local node when its own member has been removed.
+ * After this event fires, the local cluster instance is effectively
+ * dead — call `system.terminate()` to clean up.  The tombstone
+ * behaviour described on {@link MemberRemoved} also applies: peers
+ * keep this node's address as a `removed` tombstone until their
+ * `tombstoneTtlMs` (default 24 h) expires (#75).
+ */
+export declare class SelfRemoved {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** Fired on the local node when the cluster leader has changed. */
+export declare class LeaderChanged {
+    readonly leader: Option<Member>;
+    constructor(leader: Option<Member>);
+}
+/** A member was added to the cluster (first time we see it). */
+export declare class MemberJoined {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** A member transitioned to the Up state and is ready to receive work. */
+export declare class MemberUp {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** A joining member has been tentatively upgraded to WeaklyUp. */
+export declare class MemberWeaklyUp {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** Heartbeats have been missed; the member may still come back. */
+export declare class MemberUnreachable {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** Previously-unreachable member responded again. */
+export declare class MemberReachable {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** Confirmed down — taken out of the cluster and shards re-assigned. */
+export declare class MemberDown {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** Member is leaving gracefully (after calling cluster.leave()). */
+export declare class MemberLeft {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/**
+ * Member removed from the cluster.  Fires on two distinct paths:
+ *
+ *   - **Definitive removal** — `handleLeave` (peer sent `leave`)
+ *     and `evaluateDowning` (force-down via a `DowningProvider`)
+ *     mark the address as a **tombstone**: the entry stays in the
+ *     local `members` map with `status === 'removed'` and a
+ *     `removedAt` timestamp, so stale gossip from a slow peer
+ *     can't resurrect the address.  The tombstone is reclaimed
+ *     by `tombstonePruneTick` once `tombstoneTtlMs` (default 24 h)
+ *     has elapsed — see #75 for the full lifecycle.
+ *   - **FD-driven** — the failure detector's elapsed-time
+ *     `unreachable → down → removed` cascade.  Here the entry is
+ *     deleted outright (no tombstone) so a healed partition can
+ *     re-discover the peer.
+ *
+ * Public APIs (`getMembers`, `upMembers`, `reachableMembers`) skip
+ * `removed` entries, so most user code stays unaffected.  Code that
+ * iterates the raw membership view directly should check
+ * `member.status !== 'removed'` (or use `member.isReachable()`,
+ * which already returns false for `removed`).  An attempt to
+ * `Cluster.join` on the same `host:port` after `MemberRemoved` will
+ * still work — the framework detects the new incarnation via
+ * `mergeMember`'s wall-clock version epoch and supersedes the
+ * tombstone.  See `tests/cluster.test.ts` → "a node that
+ * gracefully left can rejoin on the same address".
+ */
+export declare class MemberRemoved {
+    readonly member: Member;
+    constructor(member: Member);
+}
+/** Shard ownership map recomputed. */
+export declare class ShardMapChanged {
+    readonly type: string;
+    readonly shards: ReadonlyMap<number, string>;
+    readonly version: number;
+    constructor(type: string, shards: ReadonlyMap<number, string>, version: number);
+}
+export type ClusterEvent = SelfUp | SelfRemoved | LeaderChanged | MemberJoined | MemberUp | MemberWeaklyUp | MemberUnreachable | MemberReachable | MemberDown | MemberLeft | MemberRemoved | ShardMapChanged;
+//# sourceMappingURL=ClusterEvents.d.ts.map

package/dist/cluster/ClusterEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterEvents.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterEvents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,qEAAqE;AACrE,qBAAa,MAAM;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAEtE;;;;;;;GAOG;AACH,qBAAa,WAAW;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE3E,mEAAmE;AACnE,qBAAa,aAAa;aACI,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;gBAAtB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACnD;AAID,gEAAgE;AAChE,qBAAa,YAAY;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE5E,0EAA0E;AAC1E,qBAAa,QAAQ;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAExE,kEAAkE;AAClE,qBAAa,cAAc;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE9E,mEAAmE;AACnE,qBAAa,iBAAiB;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAEjF,qDAAqD;AACrD,qBAAa,eAAe;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE/E,wEAAwE;AACxE,qBAAa,UAAU;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE1E,oEAAoE;AACpE,qBAAa,UAAU;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;aAA+B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAAM;AAE7E,sCAAsC;AACtC,qBAAa,eAAe;aAER,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;aACnC,OAAO,EAAE,MAAM;gBAFf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,EAAE,MAAM;CAElC;AAED,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,WAAW,GACX,aAAa,GACb,YAAY,GACZ,QAAQ,GACR,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,UAAU,GACV,UAAU,GACV,aAAa,GACb,eAAe,CAAC"}