actor-ts 0.9.0

package/dist/cluster/Cluster.d.ts

@@ -0,0 +1,251 @@
+import type { ActorSystem } from '../ActorSystem.js';
+import { type Option } from '../util/Option.js';
+import { type ClusterEvent } from './ClusterEvents.js';
+import { type FailureDetectorSettings } from './FailureDetector.js';
+import { Member } from './Member.js';
+import { NodeAddress } from './NodeAddress.js';
+import { ClusterSharding } from './sharding/ClusterSharding.js';
+import type { EnvelopeMsg, WireMessage } from './Protocol.js';
+import { type Transport } from './Transport.js';
+import type { DowningProvider } from './downing/DowningProvider.js';
+export interface ClusterSettings {
+    readonly host: string;
+    readonly port: number;
+    /** Other nodes this node should try to contact on startup. */
+    readonly seeds?: string[];
+    /** Role tags exposed to other members — used to constrain sharding placement. */
+    readonly roles?: string[];
+    /** Failure detector thresholds. */
+    readonly failureDetector?: Partial<FailureDetectorSettings>;
+    /** Override the transport (e.g. InMemoryTransport for tests). */
+    readonly transport?: Transport;
+    /** How often gossip is pushed to a random reachable peer. */
+    readonly gossipIntervalMs?: number;
+    /** How often to resend the initial join gossip to seeds until self is Up. */
+    readonly seedRetryIntervalMs?: number;
+    /**
+     * How long to keep a `removed` tombstone in the local members map
+     * before pruning it.  Tombstones exist so stale gossip from a slow
+     * peer can't resurrect a definitively-removed address; the TTL
+     * caps their accumulation in long-running clusters with frequent
+     * node churn (#75).  Default 24 h — comfortably above any
+     * realistic gossip-propagation lag.
+     */
+    readonly tombstoneTtlMs?: number;
+    /**
+     * How often the tombstone-prune pass runs.  Default 5 min — small
+     * enough that a freshly-expired tombstone disappears within one
+     * pruning window, large enough to be negligible CPU.
+     */
+    readonly tombstonePruneIntervalMs?: number;
+    /**
+     * Minimum age before a tombstone is eligible for pruning, regardless
+     * of {@link tombstoneTtlMs}.  Defaults to `6 × downAfterMs`, which
+     * gives a few failure-detector rounds of breathing room so peers
+     * that haven't fully converged still see the tombstone before it
+     * vanishes.  Mostly relevant for tests that set a very low TTL.
+     */
+    readonly tombstoneMinRetentionMs?: number;
+    /**
+     * Auto-promote a `joining` member to `weakly-up` after this many ms if
+     * convergence (leader + `up` transition) hasn't happened yet.  Set to 0
+     * to disable.  Default: 0 (disabled — opt-in only).
+     */
+    readonly weaklyUpAfterMs?: number;
+    /**
+     * Optional split-brain resolver.  When provided, the cluster invokes
+     * `provider.decide(view)` whenever a member transitions to / from
+     * `unreachable`, and force-downs every address in the returned set
+     * (regardless of failure-detector state).  Without a provider, the
+     * cluster relies solely on the failure detector's elapsed-time
+     * `unreachable → down → removed` cascade — fine for unilateral
+     * crashes, weak under network partitions.
+     *
+     * See `src/cluster/downing/` for the bundled strategies (KeepMajority,
+     * KeepOldest, KeepReferee, StaticQuorum, LeaseMajority).
+     */
+    readonly downing?: DowningProvider;
+}
+type EnvelopeHandler = (env: EnvelopeMsg, from: NodeAddress) => void;
+/**
+ * The Cluster is a single-instance "extension" attached to an ActorSystem.
+ * It owns a Transport, a gossip-based membership view, a failure detector
+ * and the plumbing that dispatches inbound envelope messages to local actors.
+ */
+export declare class Cluster {
+    readonly selfAddress: NodeAddress;
+    readonly selfRoles: ReadonlySet<string>;
+    readonly system: ActorSystem;
+    readonly transport: Transport;
+    private readonly log;
+    private readonly members;
+    private readonly failureDetector;
+    private readonly gossipIntervalMs;
+    private readonly seedRetryIntervalMs;
+    private readonly seedAddrs;
+    private readonly tombstoneTtlMs;
+    private readonly tombstonePruneIntervalMs;
+    private readonly tombstoneMinRetentionMs;
+    private heartbeatSeq;
+    private gossipTimer;
+    private heartbeatTimer;
+    private fdTimer;
+    private seedTimer;
+    private weaklyUpTimer;
+    private tombstonePruneTimer;
+    private currentLeader;
+    private readonly weaklyUpAfterMs;
+    private envelopeHandler;
+    private readonly _envelopeHandlersByPath;
+    private readonly wireHandlers;
+    private started;
+    private readonly downing;
+    /**
+     * Set of unreachable address keys observed at the last downing
+     * evaluation.  We only re-invoke the provider when the set
+     * actually changes — without this debounce a steady "always one
+     * unreachable peer" state would call `decide()` on every tick.
+     */
+    private lastDownedView;
+    private constructor();
+    /** Entry point: start the cluster and attempt to contact seed nodes. */
+    static join(system: ActorSystem, settings: ClusterSettings): Promise<Cluster>;
+    /**
+     * One-call bootstrap — creates the {@link ActorSystem}, joins the
+     * cluster, starts the Receptionist, waits for `SelfUp`, and wires
+     * SIGTERM/SIGINT shutdown.  The headline shape for the clustered
+     * case:
+     *
+     * ```ts
+     * const { system, cluster, shutdown } = await Cluster.bootstrap({ name: 'my-app' });
+     * ```
+     *
+     * For full configuration knobs see {@link ClusterBootstrapOptions}.
+     * For the power-user path (own `ActorSystem.create`, own
+     * `Cluster.join`, own signal wiring) keep using those directly —
+     * this is purely additive sugar.
+     *
+     * The helper lives in `ClusterBootstrap.ts` and is loaded lazily
+     * here to avoid a static import cycle (`ClusterBootstrap` ↔
+     * `Cluster.join`).
+     */
+    static bootstrap(opts: import('./ClusterBootstrap.js').ClusterBootstrapOptions): Promise<import('./ClusterBootstrap.js').BootstrappedCluster>;
+    /**
+     * The cluster's sharding facade.  Lazily constructs (and memoises) a
+     * single `ClusterSharding` instance per `ActorSystem` so callers can
+     * start regions inline:
+     *
+     * ```ts
+     * const region = cluster.sharding.start('cart', CartActor, {
+     *   extractEntityId: (m) => m.entityId,
+     * });
+     * ```
+     *
+     * Equivalent to `ClusterSharding.get(cluster.system, cluster)` —
+     * which still works for callers that prefer the explicit form.
+     */
+    get sharding(): ClusterSharding;
+    /**
+     * Subscribe to membership events.  The listener is immediately replayed
+     * the current cluster state as a series of Member/SelfUp events so that
+     * late subscribers still see the world they joined.
+     */
+    subscribe(listener: (event: ClusterEvent) => void): () => void;
+    private _listeners;
+    /**
+     * Current snapshot of known members.  `removed` entries are kept
+     * internally as tombstones (so stale gossip can't resurrect them
+     * via the merge path) but are filtered out here — the public
+     * contract is "members the cluster currently considers part of
+     * the topology".
+     */
+    getMembers(): ReadonlyArray<Member>;
+    /** Members in the `up` state, ordered by address — the "active set". */
+    upMembers(): Member[];
+    /** Reachable members (up + joining + leaving). */
+    reachableMembers(): Member[];
+    /** Up members that carry the given role tag. */
+    upMembersWithRole(role: string): Member[];
+    /** The oldest up-member is the cluster leader (deterministic across nodes). */
+    leader(): Option<Member>;
+    /** True if this node is currently the leader. */
+    isLeader(): boolean;
+    /**
+     * Register a handler for inbound user envelopes.  Kept for backward
+     * compatibility — prefer `_registerEnvelopeHandler(path, handler)` which
+     * allows multiple extensions (ClusterSharding, DistributedPubSub, …) to
+     * share the envelope pipeline.
+     */
+    _setEnvelopeHandler(handler: EnvelopeHandler): void;
+    /** Route envelopes addressed to `path` to `handler`.  Returns unsubscribe. */
+    _registerEnvelopeHandler(path: string, handler: EnvelopeHandler): () => void;
+    /**
+     * Send an envelope to a remote node.  Used by RemoteActorRef and by the
+     * PubSub / Singleton extensions.  Any `ActorRef` embedded in the user
+     * payload is rewritten to a `WireActorRef` marker here — this is the
+     * single chokepoint where every cross-node message leaves, so hooking
+     * the encode step once covers all paths (sharding, pub-sub, singleton,
+     * direct remote-ref).  Receiving nodes decode in `handleEnvelope`.
+     */
+    _sendEnvelope(to: NodeAddress, env: EnvelopeMsg): void;
+    /** Register a handler for a specific wire-message discriminator. */
+    _onWire(kind: string, handler: (msg: WireMessage, from: NodeAddress) => void): () => void;
+    /**
+     * Operator-initiated force-down of a remote peer (#56).  Mirrors the
+     * private `evaluateDowning` path: marks the peer `down`, emits the
+     * lifecycle events, tombstones with `removedAt` so stale gossip
+     * can't resurrect it, and tells the failure detector to forget it.
+     *
+     * Returns `true` if a member was found and downed, `false` if the
+     * address was unknown or already terminal (`down`/`removed`).
+     *
+     * Intended for operator tooling — the management HTTP endpoint
+     * `POST /cluster/down` calls this directly.  Don't use it as a
+     * replacement for the failure detector / downing provider in normal
+     * flow; it's a manual override.
+     */
+    down(addr: NodeAddress | string): boolean;
+    /** Gracefully leave the cluster (broadcast `leave`, stop transport). */
+    leave(): Promise<void>;
+    private _start;
+    private contactSeeds;
+    private handleWire;
+    private handleHeartbeat;
+    private handleGossip;
+    private handleEnvelope;
+    private dispatchEnvelope;
+    private handleLeave;
+    private gossipTick;
+    private heartbeatTick;
+    private failureDetectionTick;
+    /**
+     * Build a `ClusterPartitionView` from the current member set and
+     * ask the configured `DowningProvider` to decide which addresses
+     * (if any) need to be force-downed.  Debounces by the JSON shape of
+     * the unreachable set + member view so a steady-state cluster
+     * doesn't re-invoke the provider on every tick.
+     */
+    private evaluateDowning;
+    private mergeMember;
+    private updateMember;
+    private emitStatusTransition;
+    private maybeEmitLeaderChange;
+    private emit;
+    /**
+     * Drop tombstones whose `removedAt` exceeds `tombstoneTtlMs` (and
+     * the `tombstoneMinRetentionMs` floor).  Each peer makes the same
+     * decision on its local clock — with TTL ≫ gossip propagation lag,
+     * peers prune within seconds of each other and stale-gossip
+     * resurrection is filtered out by `mergeMember`'s "expired
+     * tombstone" guard.  See #75 for the full rationale.
+     *
+     * Tombstones lacking `removedAt` (older nodes pre-dating the field)
+     * are kept — we have no age info to compare against.  They drop
+     * out naturally when those nodes are upgraded or restart.
+     */
+    private tombstonePruneTick;
+}
+/** Helper — creates an InMemoryTransport for tests. */
+export declare function inMemoryTransport(system: ActorSystem, host: string, port: number): Transport;
+export {};
+//# sourceMappingURL=Cluster.d.ts.map

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

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