actor-ts 0.9.0

package/dist/cluster/sharding/ShardCoordinator.d.ts

@@ -0,0 +1,218 @@
+import { Actor } from '../../Actor.js';
+import type { ActorRef } from '../../ActorRef.js';
+import type { Lease } from '../../coordination/Lease.js';
+import type { Cluster } from '../Cluster.js';
+import { type AllocationStrategy } from './AllocationStrategy.js';
+import type { CoordinatorStateStore } from './CoordinatorState.js';
+import type { RememberEntitiesStore } from './RememberEntitiesStore.js';
+import type { ShardingMessage } from './ShardingProtocol.js';
+/**
+ * The lease-aware path uses internal events instead of inline awaits so
+ * cluster-event triggers can't interleave their `reconcile` calls with
+ * an in-flight `lease.acquire()`.  Mirrors the same pattern used in
+ * `ClusterSingletonManager` (#38).
+ */
+type CoordinatorEvent = {
+    t: 'reconcile';
+} | {
+    t: 'lease-acquire-result';
+    got: boolean;
+    error?: Error;
+} | {
+    t: 'lease-lost';
+    reason: string;
+} | {
+    t: 'acquire-retry';
+};
+type CoordinatorInbox = ShardingMessage | CoordinatorEvent;
+export interface ShardCoordinatorSettings {
+    readonly typeName: string;
+    readonly cluster: Cluster;
+    readonly allocationStrategy: AllocationStrategy;
+    readonly role?: string;
+    readonly rebalanceIntervalMs?: number;
+    readonly handOffTimeoutMs?: number;
+    readonly rememberEntities?: boolean;
+    /** Resolver for local actor paths — used when coordinator lives on the same node as a region. */
+    readonly localResolver: (path: string) => ActorRef | null;
+    /**
+     * Optional split-brain protection.  When set, the elected leader's
+     * coordinator must hold the lease before it processes shard
+     * messages.  Under a network partition where two nodes converge to
+     * "I am the leader" gossip views, only the side that successfully
+     * acquires the lease ever issues `AllocateShard` / `HandOff`
+     * directives — the other side stays passive and drops messages
+     * (regions retry naturally on their next cache miss).
+     *
+     * Without a lease the coordinator gates only on `isLeader()` —
+     * v1 behaviour, no extra coordination.
+     */
+    readonly lease?: Lease;
+    /** Retry interval for `lease.acquire()` after a failed attempt.  Default: 5 s. */
+    readonly acquireRetryIntervalMs?: number;
+    /**
+     * Optional persistence backend for the entity registry.  Only used
+     * when `rememberEntities: true`.  Without it, `entitiesPerShard`
+     * stays in-memory only and a full cluster restart loses the
+     * registry — until messages re-arrive and trigger fresh
+     * EntityStarted notifications.  Set to a `JournalRememberEntitiesStore`
+     * (or any custom impl) to make the registry survive cold-starts.
+     *
+     * The `ClusterSharding` extension auto-instantiates the default
+     * `JournalRememberEntitiesStore` (using the active Journal) when
+     * `rememberEntities: true` and no explicit store is provided —
+     * so most users don't need to touch this field.
+     */
+    readonly rememberEntitiesStore?: RememberEntitiesStore;
+    /**
+     * Optional persistence backend for the allocation state itself
+     * (`regions` + `shardHome`).  Without it, `LeaderChanged` triggers
+     * a full rebuild from `Register` gossip — fine for a few hundred
+     * shards, painful at thousands.  With it, the new leader loads
+     * the last-known snapshot from the store (e.g. `DistributedData`)
+     * and skips the reallocation storm.
+     *
+     * `ClusterSharding` does NOT auto-instantiate this — the user
+     * must explicitly start a DistributedData extension first and
+     * pass `new DistributedDataCoordinatorStateStore(...)`.  Without
+     * that opt-in, `ShardCoordinator` keeps the v1 rebuild-from-
+     * Register behaviour (backwards-compat).
+     */
+    readonly coordinatorStateStore?: CoordinatorStateStore;
+}
+/**
+ * Cluster-wide authoritative source of shard-to-region assignments.  Runs on
+ * every node but only responds to requests when the local node is the
+ * cluster leader.  Non-leader coordinators ignore incoming messages so that
+ * duplicate coordinators during a leader transition are harmless.
+ *
+ * State is reconstructed from Register messages: each region reports the
+ * shards it currently hosts, and the coordinator merges that with any new
+ * allocation requests.  This is deliberately lightweight — a production
+ * upgrade would snapshot state to a journal so the coordinator can recover
+ * across restarts without re-allocating every shard from scratch.
+ */
+export declare class ShardCoordinator extends Actor<CoordinatorInbox> {
+    readonly settings: ShardCoordinatorSettings;
+    private readonly regions;
+    private readonly shardHome;
+    private readonly pending;
+    private readonly rebalanceInProgress;
+    private readonly entitiesPerShard;
+    private rebalanceTimer;
+    private unsubscribeCluster;
+    private unsubscribeLeaseLost;
+    private acquireRetryTimer;
+    /**
+     * Lease lifecycle (only used when `settings.lease` is set).
+     * Drives the `isActive()` predicate — coordinator only processes
+     * shard messages while `isLeader() && leaseState === 'held'`.
+     */
+    private leaseState;
+    /**
+     * Sharding messages received while we're the leader but waiting
+     * for the lease.  Drained on the `acquiring → held` transition so
+     * regions that asked early get an answer instead of having to
+     * wait for the next cluster event to retrigger their ask.
+     *
+     * Non-leader messages are NOT buffered — they're dropped because
+     * the regions on this node will retry against whichever node is
+     * the actual leader on their next attempt.
+     *
+     * Capped to avoid unbounded growth if the lease never resolves.
+     */
+    private acquireBuffer;
+    private static readonly ACQUIRE_BUFFER_CAP;
+    /**
+     * Promise chain over remembered-entity persistence.  Each new
+     * `EntityStarted` / `EntityStopped` chains its append onto the tail
+     * of this promise so writes serialise — `Journal.append`'s
+     * optimistic `expectedSeq` would otherwise race when two events
+     * fire in fast succession.  `.catch` on each link prevents a
+     * failed write from breaking the chain for subsequent writes.
+     */
+    private rememberWriteChain;
+    /**
+     * Coalesced save state for `coordinatorStateStore`.  State
+     * mutations are bursty during rebalance; rather than fire one
+     * disk write per mutation we mark the state dirty and the
+     * in-flight save's `.finally` kicks off a follow-up if more
+     * changes accumulated meanwhile.  Same pattern as
+     * `DistributedData.scheduleDurableSave` from #40.
+     */
+    private coordinatorStateInFlight;
+    private coordinatorStateDirty;
+    constructor(settings: ShardCoordinatorSettings);
+    /** Path used by ClusterSharding to locate the coordinator on any node. */
+    static pathFor(typeName: string): string;
+    preStart(): Promise<void>;
+    /** Apply a single `RememberEvent` to the in-memory `entitiesPerShard`
+     *  map.  Used by both the preStart replay AND
+     *  `handleEntityStarted` / `handleEntityStopped` so the in-memory
+     *  derivation rule lives in exactly one place. */
+    private applyRememberEvent;
+    postStop(): Promise<void>;
+    onReceive(msg: CoordinatorInbox): void;
+    private dispatchShardingMessage;
+    private isLeader;
+    /**
+     * True iff this coordinator is the authoritative one — i.e. should
+     * be processing shard messages.  Without a lease this is just
+     * `isLeader()`; with a lease it additionally requires that the
+     * lease be currently held by this replica.
+     */
+    private isActive;
+    private handleCoordinatorEvent;
+    private reconcileLease;
+    private runAcquire;
+    private handleAcquireResult;
+    private handleLeaseLost;
+    private scheduleAcquireRetry;
+    private candidates;
+    private currentShardCounts;
+    private handleRegister;
+    private handleGetShardHome;
+    private tryAllocate;
+    private handleHandOffComplete;
+    private handleEntityStarted;
+    private handleEntityStopped;
+    /**
+     * Append a remembered-entity event to the persistent store.  Chains
+     * onto `rememberWriteChain` so two events fired in fast succession
+     * don't race the journal's optimistic-`expectedSeq` check — each
+     * append awaits the previous one.  Errors are caught + logged so a
+     * transient store failure doesn't break the chain for subsequent
+     * writes.
+     */
+    private persistRememberEvent;
+    private onRegionTerminated;
+    private onMemberRemoved;
+    private onLeaderChanged;
+    /**
+     * Read the most recent snapshot from `coordinatorStateStore` and
+     * seed `regions` + `shardHome` from it.  Drops any region whose
+     * node has left the cluster between the snapshot and now —
+     * otherwise we'd happily route shards to dead pods.  Existing
+     * pending queries get a fresh allocation pass via the regular
+     * onMessage flow.
+     */
+    private loadCoordinatorState;
+    /**
+     * Mark coordinator state dirty + schedule a save.  Called after
+     * every meaningful mutation — handleRegister, tryAllocate,
+     * handleHandOffComplete, onRegionTerminated.  Coalesces
+     * overlapping bursts into 1-2 store writes via the
+     * `inFlight + dirty` flag pair.
+     */
+    private scheduleCoordinatorStateSave;
+    private snapshotCoordinatorState;
+    private rebalanceTick;
+    private beginHandOff;
+    private findRegionKey;
+    private flushPending;
+    private shipRememberedEntities;
+    private sendToRegion;
+    private replyTo;
+}
+export {};
+//# sourceMappingURL=ShardCoordinator.d.ts.map

package/dist/cluster/sharding/ShardCoordinator.d.ts.map

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