actor-ts 0.9.0

package/dist/cluster/singleton/ClusterSingletonManager.js

@@ -0,0 +1,300 @@
+import { match, P } from 'ts-pattern';
+import { Actor } from '../../Actor.js';
+import { Terminated } from '../../SystemMessages.js';
+import { LeaderChanged, MemberRemoved, SelfUp } from '../ClusterEvents.js';
+/**
+ * Path at which every node hosts its ClusterSingletonManager for a given
+ * singleton typeName.  Used by the proxy/envelope layer to address the
+ * manager on whichever node is currently the leader.
+ */
+export function singletonManagerPath(systemName, typeName) {
+    return `actor-ts://${systemName}/user/singleton-manager-${typeName}`;
+}
+/**
+ * Runs on every node.  Watches cluster events and (re)spawns the singleton
+ * child when this node is the cluster leader; stops the child when it is not.
+ * Remote Envelopes addressed to the singleton land here and are forwarded to
+ * the child — if the manager is not on the leader node, the envelope is
+ * dropped with a warning (the proxy shouldn't have forwarded there).
+ *
+ * **Two paths:**
+ *
+ * - **No lease (default).**  Synchronous reconcile — spawn the moment
+ *   cluster gossip says we're leader.  Same behaviour the manager has
+ *   shipped since v1.
+ * - **With lease.**  Async reconcile that gates child-spawn on
+ *   `lease.acquire()`, watches `lease.onLost(...)` for revocation, and
+ *   `release()`s on graceful handover.  All state transitions go through
+ *   the manager's own mailbox so concurrent cluster events can't race
+ *   with an in-flight acquire.
+ */
+export class ClusterSingletonManager extends Actor {
+    settings;
+    child = null;
+    /**
+     * The previous child while it is mid-stop.  We watch every child we
+     * spawn (see `spawn()`), and when leadership flips we move
+     * `this.child` here, send `PoisonPill`, and wait for the
+     * `Terminated` system message before allowing another `spawn()`.
+     * Without this, a fast leader-flap (or two cluster events back-to-
+     * back from `handleLeave`) reaches `spawn` while the previous
+     * child cell is still in the parent's `_children` map — the new
+     * spawn fails with "Child name 'X' is not unique".  It also avoids
+     * spawning a second user actor (e.g. a fresh `HttpIngressActor`
+     * trying to bind port 8080) before the previous one has finished
+     * `postStop` and released its resources.
+     */
+    pendingStop = null;
+    unsubCluster = null;
+    unsubLeaseLost = null;
+    retryTimer = null;
+    /** Lease lifecycle — only used when `settings.lease` is set. */
+    leaseState = 'none';
+    /** Callback the extension hands us so we can release the envelope path on stop. */
+    _envelopeUnsub = null;
+    constructor(settings) {
+        super();
+        this.settings = settings;
+    }
+    preStart() {
+        const cluster = this.settings.cluster;
+        // No-lease path stays sync: cluster events drive `reconcileSync()`
+        // directly, so a leader-change result is visible the moment the
+        // event fires.  This preserves the v1 timing guarantee (proxies
+        // can ask the cluster for the leader and immediately route).
+        //
+        // With a lease, every state transition has to flow through the
+        // manager's own mailbox so concurrent cluster events can't race
+        // with an in-flight `acquire()` — see `handleReconcile`.
+        this.unsubCluster = cluster.subscribe((evt) => match(evt)
+            .with(P.union(P.instanceOf(LeaderChanged), P.instanceOf(SelfUp), P.instanceOf(MemberRemoved)), () => {
+            if (this.settings.lease) {
+                this.self.tell({ t: 'reconcile' });
+            }
+            else {
+                this.reconcileSync();
+            }
+        })
+            .otherwise(() => { }));
+        if (this.settings.lease) {
+            this.unsubLeaseLost = this.settings.lease.onLost((reason) => {
+                this.self.tell({ t: 'lease-lost', reason });
+            });
+            // Lease path: kick the initial reconcile via the mailbox.
+            this.self.tell({ t: 'reconcile' });
+        }
+        else {
+            this.reconcileSync();
+        }
+    }
+    async postStop() {
+        this.unsubCluster?.();
+        this.unsubLeaseLost?.();
+        this._envelopeUnsub?.();
+        this.retryTimer?.cancel();
+        if (this.child) {
+            this.child.stop();
+            this.child = null;
+        }
+        // Drop any in-flight stop — the parent termination cascade will
+        // tear it down regardless, and we no longer need to react to its
+        // Terminated message.
+        this.pendingStop = null;
+        // Release the lease if held — the holder leaving cleanly lets a
+        // follower acquire faster than waiting for the TTL to expire.
+        if (this.settings.lease && this.leaseState === 'held') {
+            try {
+                await this.settings.lease.release();
+            }
+            catch { /* best-effort */ }
+            this.leaseState = 'none';
+        }
+    }
+    onReceive(msg) {
+        if (msg instanceof Terminated) {
+            this.handleTerminated(msg);
+            return;
+        }
+        return match(msg)
+            .with({ t: 'singleton-deliver' }, (m) => this.handleDeliver(m))
+            .with({ t: 'reconcile' }, () => this.handleReconcile())
+            .with({ t: 'lease-acquire-result' }, (m) => this.handleAcquireResult(m))
+            .with({ t: 'lease-lost' }, (m) => this.handleLeaseLost(m))
+            .with({ t: 'acquire-retry' }, () => this.handleReconcile())
+            .exhaustive();
+    }
+    /**
+     * Death-watch callback for the previous singleton child.  Fires once
+     * `pendingStop` has fully terminated (postStop run, cell removed
+     * from the parent's children map).  At that point it's safe to
+     * spawn a fresh child, so we re-run the reconcile logic — if we're
+     * still the leader, a new child will be created here.
+     */
+    handleTerminated(t) {
+        if (this.pendingStop && t.actor.equals(this.pendingStop)) {
+            this.log.debug(`previous child '${this.settings.typeName}' fully terminated — re-running reconcile`);
+            this.pendingStop = null;
+            // Re-trigger the appropriate reconcile path; either branch is
+            // safe to call when the singleton state is "no child running".
+            if (this.settings.lease) {
+                this.self.tell({ t: 'reconcile' });
+            }
+            else {
+                this.reconcileSync();
+            }
+        }
+    }
+    /* -------------------------- handlers -------------------------- */
+    handleDeliver(msg) {
+        if (msg.t !== 'singleton-deliver')
+            return;
+        if (!this.child) {
+            this.log.warn(`singleton '${this.settings.typeName}' not currently hosted on this node — dropping message`);
+            return;
+        }
+        this.child.tell(msg.body);
+    }
+    /** Sync reconcile — no lease.  Spawn / stop the child to match cluster state. */
+    reconcileSync() {
+        const want = this.wantHosted();
+        this.log.debug(`reconcile '${this.settings.typeName}': want=${want} child=${this.child !== null} pendingStop=${this.pendingStop !== null}`);
+        if (want && !this.child) {
+            this.spawn();
+        }
+        else if (!want && this.child) {
+            this.stopChild('leader moved away or role lost');
+        }
+    }
+    async handleReconcile() {
+        // Lease-gated path only — the no-lease path goes through
+        // `reconcileSync` directly from the cluster-event subscriber.
+        if (!this.settings.lease) {
+            this.reconcileSync();
+            return;
+        }
+        const want = this.wantHosted();
+        if (want) {
+            if (this.leaseState === 'held')
+                return; // already running
+            if (this.leaseState === 'acquiring')
+                return; // already in flight
+            // Cancel a retry if one is pending — we're starting a fresh attempt now.
+            this.retryTimer?.cancel();
+            this.retryTimer = null;
+            this.leaseState = 'acquiring';
+            void this.runAcquire();
+        }
+        else {
+            if (this.leaseState === 'held') {
+                this.stopChild('leader moved away or role lost');
+                try {
+                    await this.settings.lease.release();
+                }
+                catch (e) {
+                    this.log.warn(`lease release failed`, e);
+                }
+                this.leaseState = 'none';
+            }
+            else if (this.leaseState === 'acquiring') {
+                // Let the in-flight acquire finish — `handleAcquireResult` will
+                // re-check `wantHosted` and immediately release if it succeeded
+                // while we were no longer interested.
+            }
+            else {
+                this.retryTimer?.cancel();
+                this.retryTimer = null;
+            }
+        }
+    }
+    async runAcquire() {
+        try {
+            const got = await this.settings.lease.acquire();
+            this.self.tell({ t: 'lease-acquire-result', got });
+        }
+        catch (error) {
+            this.self.tell({
+                t: 'lease-acquire-result', got: false, error: error,
+            });
+        }
+    }
+    handleAcquireResult(msg) {
+        if (this.leaseState !== 'acquiring') {
+            // Spurious result — manager was reset or stopped while we were
+            // awaiting.  If we somehow got the lease, release it best-effort
+            // so we don't hold onto a slot we don't want.
+            if (msg.got)
+                void this.settings.lease.release().catch(() => { });
+            return;
+        }
+        if (!msg.got) {
+            // Acquire failed (another holder, or backend error).  Retry on
+            // the configured interval.  We log the error if there was one.
+            if (msg.error)
+                this.log.warn(`lease acquire failed`, msg.error);
+            this.leaseState = 'none';
+            this.scheduleAcquireRetry();
+            return;
+        }
+        // Got the lease.  Re-check whether we still want to be hosted —
+        // membership may have flipped while we were awaiting.
+        if (!this.wantHosted()) {
+            void this.settings.lease.release().catch((e) => this.log.warn(`lease release after stale acquire failed`, e));
+            this.leaseState = 'none';
+            return;
+        }
+        this.leaseState = 'held';
+        this.spawn();
+    }
+    handleLeaseLost(msg) {
+        if (this.leaseState !== 'held')
+            return; // stale callback
+        this.log.warn(`singleton '${this.settings.typeName}': lease lost — ${msg.reason}; stopping child`);
+        this.stopChild(`lease lost: ${msg.reason}`);
+        this.leaseState = 'none';
+        // If we're still the elected leader, kick a fresh reconcile so we
+        // try to re-acquire.  Cluster events would eventually do this on
+        // their own, but a missed re-acquire here is annoying.
+        this.self.tell({ t: 'reconcile' });
+    }
+    /* -------------------------- helpers -------------------------- */
+    wantHosted() {
+        const cluster = this.settings.cluster;
+        const iAmLeader = cluster.leader().exists((l) => l.address.equals(cluster.selfAddress));
+        const roleOk = !this.settings.role || cluster.selfRoles.has(this.settings.role);
+        return iAmLeader && roleOk;
+    }
+    spawn() {
+        if (this.child)
+            return;
+        // The previous child is still terminating.  Don't try to spawn
+        // with the same name — its cell is still in the parent's children
+        // map — and don't bring up the user actor (e.g. an HTTP server
+        // re-binding the same port) until postStop has released its
+        // resources.  `handleTerminated` will retrigger the reconcile
+        // once `pendingStop` clears.
+        if (this.pendingStop)
+            return;
+        this.child = this.context.spawn(this.settings.singletonProps, this.settings.typeName);
+        this.context.watch(this.child);
+        this.log.info(`singleton '${this.settings.typeName}' started on this node (now leader)`);
+    }
+    stopChild(reason) {
+        if (!this.child)
+            return;
+        this.log.info(`singleton '${this.settings.typeName}' stopping (${reason})`);
+        // Move into pendingStop instead of nulling immediately — the cell
+        // remains in the parent's children map until `Terminated` arrives,
+        // and any reconcile that fires in the meantime must wait.
+        this.pendingStop = this.child;
+        this.child.stop();
+        this.child = null;
+    }
+    scheduleAcquireRetry() {
+        const interval = this.settings.acquireRetryIntervalMs ?? 5_000;
+        this.retryTimer?.cancel();
+        this.retryTimer = this.system.scheduler.scheduleOnceFn(interval, () => {
+            this.self.tell({ t: 'acquire-retry' });
+        });
+    }
+}
+//# sourceMappingURL=ClusterSingletonManager.js.map

package/dist/cluster/singleton/ClusterSingletonManager.js.map

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

package/dist/cluster/singleton/ClusterSingletonProxy.d.ts

@@ -0,0 +1,32 @@
+import { ActorPath } from '../../ActorPath.js';
+import { ActorRef } from '../../ActorRef.js';
+import type { Cluster } from '../Cluster.js';
+/**
+ * Location-transparent handle to a cluster-wide singleton.  Every call to
+ * `tell` looks up the current leader and forwards to that node's
+ * ClusterSingletonManager (via direct `tell` if local, via envelope if
+ * remote).  Messages sent before the cluster has elected a leader are
+ * buffered and drained when the first `LeaderChanged` event fires.
+ *
+ * The proxy extends ActorRef<T> so it can be passed anywhere an ActorRef is
+ * expected (e.g. as a sender for ask patterns).  It is not backed by a real
+ * actor — it is a thin forwarder.
+ */
+export declare class ClusterSingletonProxy<T> extends ActorRef<T> {
+    private readonly cluster;
+    private readonly typeName;
+    private readonly localManagerRef;
+    readonly path: ActorPath;
+    private buffer;
+    private unsubscribe;
+    private stopped;
+    constructor(cluster: Cluster, typeName: string, localManagerRef: ActorRef);
+    tell(message: T, _sender?: ActorRef | null): void;
+    /** Stop forwarding; unsubscribes from cluster events. */
+    stop(): void;
+    /** True if at least one message is currently buffered. */
+    hasPending(): boolean;
+    private deliver;
+    private drainBuffer;
+}
+//# sourceMappingURL=ClusterSingletonProxy.d.ts.map

package/dist/cluster/singleton/ClusterSingletonProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterSingletonProxy.d.ts","sourceRoot":"","sources":["../../../src/cluster/singleton/ClusterSingletonProxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAK7C;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAOrD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe;IARlC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,OAAO,CAAS;gBAGL,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,QAAQ;IAcnC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,GAAE,QAAQ,GAAG,IAAW,GAAG,IAAI;IAUhE,yDAAyD;IACzD,IAAI,IAAI,IAAI;IAMZ,0DAA0D;IAC1D,UAAU,IAAI,OAAO;IAErB,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,WAAW;CAOpB"}

package/dist/cluster/singleton/ClusterSingletonProxy.js

@@ -0,0 +1,81 @@
+import { match, P } from 'ts-pattern';
+import { ActorPath } from '../../ActorPath.js';
+import { ActorRef } from '../../ActorRef.js';
+import { LeaderChanged } from '../ClusterEvents.js';
+import { singletonManagerPath } from './ClusterSingletonManager.js';
+/**
+ * Location-transparent handle to a cluster-wide singleton.  Every call to
+ * `tell` looks up the current leader and forwards to that node's
+ * ClusterSingletonManager (via direct `tell` if local, via envelope if
+ * remote).  Messages sent before the cluster has elected a leader are
+ * buffered and drained when the first `LeaderChanged` event fires.
+ *
+ * The proxy extends ActorRef<T> so it can be passed anywhere an ActorRef is
+ * expected (e.g. as a sender for ask patterns).  It is not backed by a real
+ * actor — it is a thin forwarder.
+ */
+export class ClusterSingletonProxy extends ActorRef {
+    cluster;
+    typeName;
+    localManagerRef;
+    path;
+    buffer = [];
+    unsubscribe = null;
+    stopped = false;
+    constructor(cluster, typeName, localManagerRef) {
+        super();
+        this.cluster = cluster;
+        this.typeName = typeName;
+        this.localManagerRef = localManagerRef;
+        this.path = new ActorPath('', null, cluster.system.name)
+            .child('user').child(`singleton-proxy-${typeName}`);
+        this.unsubscribe = cluster.subscribe((evt) => match(evt)
+            .with(P.instanceOf(LeaderChanged), () => this.drainBuffer())
+            .otherwise(() => { }));
+        // Drain in case a leader is already known by the time we start.
+        queueMicrotask(() => this.drainBuffer());
+    }
+    tell(message, _sender = null) {
+        if (this.stopped)
+            return;
+        const leaderOpt = this.cluster.leader();
+        if (leaderOpt.isNone()) {
+            this.buffer.push(message);
+            return;
+        }
+        this.deliver(message, leaderOpt.value.address);
+    }
+    /** Stop forwarding; unsubscribes from cluster events. */
+    stop() {
+        this.stopped = true;
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+    }
+    /** True if at least one message is currently buffered. */
+    hasPending() { return this.buffer.length > 0; }
+    deliver(message, leaderAddr) {
+        if (leaderAddr.equals(this.cluster.selfAddress)) {
+            const payload = { t: 'singleton-deliver', body: message };
+            this.localManagerRef.tell(payload);
+        }
+        else {
+            this.cluster._sendEnvelope(leaderAddr, {
+                t: 'envelope',
+                to: singletonManagerPath(this.cluster.system.name, this.typeName),
+                from: null,
+                body: message,
+                tag: 'Singleton',
+            });
+        }
+    }
+    drainBuffer() {
+        const leaderOpt = this.cluster.leader();
+        if (leaderOpt.isNone() || this.buffer.length === 0)
+            return;
+        const leaderAddr = leaderOpt.value.address;
+        const drained = this.buffer.splice(0, this.buffer.length);
+        for (const m of drained)
+            this.deliver(m, leaderAddr);
+    }
+}
+//# sourceMappingURL=ClusterSingletonProxy.js.map

package/dist/cluster/singleton/ClusterSingletonProxy.js.map

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

package/dist/cluster/singleton/index.d.ts

@@ -0,0 +1,6 @@
+export { ClusterSingleton, ClusterSingletonId, } from './ClusterSingleton.js';
+export type { StartSingletonSettings, SingletonHandle, } from './ClusterSingleton.js';
+export { ClusterSingletonManager, singletonManagerPath, } from './ClusterSingletonManager.js';
+export type { ClusterSingletonManagerSettings, SingletonDeliver, } from './ClusterSingletonManager.js';
+export { ClusterSingletonProxy } from './ClusterSingletonProxy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cluster/singleton/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cluster/singleton/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,sBAAsB,EACtB,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,+BAA+B,EAC/B,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/cluster/singleton/index.js

@@ -0,0 +1,4 @@
+export { ClusterSingleton, ClusterSingletonId, } from './ClusterSingleton.js';
+export { ClusterSingletonManager, singletonManagerPath, } from './ClusterSingletonManager.js';
+export { ClusterSingletonProxy } from './ClusterSingletonProxy.js';
+//# sourceMappingURL=index.js.map

package/dist/cluster/singleton/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cluster/singleton/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,8BAA8B,CAAC;AAKtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/cluster/transports/MessageChannelTransport.d.ts

@@ -0,0 +1,52 @@
+import { NodeAddress } from '../NodeAddress.js';
+import type { WireMessage } from '../Protocol.js';
+import type { Transport, WireHandler } from '../Transport.js';
+/**
+ * Message shape carried over the underlying MessageChannel.  The broker
+ * pattern means every outbound frame from a worker includes the sender
+ * address (so the receiver can put it in `WireHandler`) and the intended
+ * recipient (so the broker can route it).
+ */
+export interface BrokeredMessage {
+    readonly from: ReturnType<NodeAddress['toJSON']>;
+    readonly to: ReturnType<NodeAddress['toJSON']>;
+    readonly payload: WireMessage;
+}
+/**
+ * MessagePort-like minimal surface — we only use these three members so
+ * the transport works equally well with browser `MessagePort`,
+ * Node/Bun `worker_threads.MessagePort`, or any in-process shim used by
+ * tests.
+ */
+export interface PortLike {
+    postMessage(value: unknown, transfer?: unknown[]): void;
+    onmessage: ((e: {
+        data: unknown;
+    }) => void) | null;
+    close?(): void;
+    start?(): void;
+}
+/**
+ * Transport that talks to the rest of the cluster through a single pair of
+ * `MessagePort`s — this node holds one end; a broker (typically the
+ * main-thread `WorkerCluster`) holds the other end of every worker and
+ * forwards traffic based on the envelope's `to` address.  Use this to
+ * build a multi-core cluster inside one process without paying the TCP
+ * overhead.
+ */
+export declare class MessageChannelTransport implements Transport {
+    readonly self: NodeAddress;
+    private readonly port;
+    private handler;
+    private running;
+    private readonly knownPeers;
+    constructor(self: NodeAddress, port: PortLike);
+    setHandler(handler: WireHandler): void;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    send(to: NodeAddress, msg: WireMessage): void;
+    disconnect(_peer: NodeAddress): void;
+    peers(): NodeAddress[];
+    private onFrame;
+}
+//# sourceMappingURL=MessageChannelTransport.d.ts.map

package/dist/cluster/transports/MessageChannelTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageChannelTransport.d.ts","sourceRoot":"","sources":["../../../src/cluster/transports/MessageChannelTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACxD,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,YAAW,SAAS;IACvD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEpC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ;IAK7C,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAEhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI;IAU7C,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIpC,KAAK,IAAI,WAAW,EAAE;IAMtB,OAAO,CAAC,OAAO;CAMhB"}

package/dist/cluster/transports/MessageChannelTransport.js

@@ -0,0 +1,59 @@
+import { NodeAddress } from '../NodeAddress.js';
+/**
+ * Transport that talks to the rest of the cluster through a single pair of
+ * `MessagePort`s — this node holds one end; a broker (typically the
+ * main-thread `WorkerCluster`) holds the other end of every worker and
+ * forwards traffic based on the envelope's `to` address.  Use this to
+ * build a multi-core cluster inside one process without paying the TCP
+ * overhead.
+ */
+export class MessageChannelTransport {
+    self;
+    port;
+    handler = () => { };
+    running = false;
+    knownPeers = new Set();
+    constructor(self, port) {
+        this.self = self;
+        this.port = port;
+    }
+    setHandler(handler) { this.handler = handler; }
+    async start() {
+        this.running = true;
+        this.port.onmessage = (evt) => this.onFrame(evt.data);
+        this.port.start?.();
+    }
+    async shutdown() {
+        this.running = false;
+        this.port.onmessage = null;
+        try {
+            this.port.close?.();
+        }
+        catch { /* ignore */ }
+    }
+    send(to, msg) {
+        if (!this.running)
+            return;
+        const envelope = {
+            from: this.self.toJSON(),
+            to: to.toJSON(),
+            payload: msg,
+        };
+        this.port.postMessage(envelope);
+    }
+    disconnect(_peer) {
+        // In the broker model we don't own per-peer connections.  Nothing to do.
+    }
+    peers() {
+        return Array.from(this.knownPeers).map(s => NodeAddress.parse(s));
+    }
+    /* -------------------------------- Internal ------------------------------- */
+    onFrame(env) {
+        if (!this.running)
+            return;
+        const from = NodeAddress.fromJSON(env.from);
+        this.knownPeers.add(from.toString());
+        this.handler(from, env.payload);
+    }
+}
+//# sourceMappingURL=MessageChannelTransport.js.map

package/dist/cluster/transports/MessageChannelTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageChannelTransport.js","sourceRoot":"","sources":["../../../src/cluster/transports/MessageChannelTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6BhD;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAuB;IACzB,IAAI,CAAc;IACV,IAAI,CAAW;IACxB,OAAO,GAAgB,GAAG,EAAE,GAAE,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,CAAC;IACP,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhD,YAAY,IAAiB,EAAE,IAAc;QAC3C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,UAAU,CAAC,OAAoB,IAAU,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAElE,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAuB,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC;YAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,CAAC,EAAe,EAAE,GAAgB;QACpC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,MAAM,QAAQ,GAAoB;YAChC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YACxB,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE;YACf,OAAO,EAAE,GAAG;SACb,CAAC;QACF,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,UAAU,CAAC,KAAkB;QAC3B,yEAAyE;IAC3E,CAAC;IAED,KAAK;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,+EAA+E;IAEvE,OAAO,CAAC,GAAoB;QAClC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/config/Config.d.ts

@@ -0,0 +1,73 @@
+import { type ConfigObject, type ConfigValue, deepMerge, isPlainObject, parseHocon, resolveSubstitutions } from './HoconParser.js';
+/**
+ * Immutable configuration tree loaded from HOCON files and/or code
+ * overrides.  All accessors throw `ConfigError` on missing or
+ * incorrectly-typed paths; `hasPath` lets callers probe beforehand.
+ *
+ *  Primary entry points:
+ *  - `Config.load()` — merge reference.conf + application.conf + env.
+ *  - `Config.parseString(s)` — parse an inline HOCON snippet.
+ *  - `Config.parseFile(path)` — parse a file.
+ *  - `Config.fromObject(obj)` — build from a plain JS object (code overrides).
+ */
+export declare class Config {
+    private readonly tree;
+    private constructor();
+    static empty(): Config;
+    static parseString(source: string): Config;
+    static parseFile(path: string): Config;
+    static fromObject(obj: unknown): Config;
+    /**
+     * Load the standard config chain.  Precedence (highest first):
+     *
+     *   1. `overrides` passed in code.
+     *   2. `application.conf` resolved via `appConfPath` → `process.env.ACTOR_TS_CONFIG`
+     *      → `./application.conf` in CWD.
+     *   3. `reference.conf` bundled with this package.
+     *
+     * Environment variables are consulted during substitution resolution
+     * (inside each parse step), not as a separate layer.
+     */
+    static load(options?: LoadOptions): Config;
+    /** Load the bundled reference defaults.  Cached for the process. */
+    private static _referenceCache;
+    static loadReference(): Config;
+    hasPath(path: string): boolean;
+    getString(path: string): string;
+    getInt(path: string): number;
+    getNumber(path: string): number;
+    getBoolean(path: string): boolean;
+    /** Duration in milliseconds. */
+    getDuration(path: string): number;
+    /** Byte count. */
+    getBytes(path: string): number;
+    getStringList(path: string): string[];
+    getList(path: string): ConfigValue[];
+    getObject(path: string): ConfigObject;
+    getConfig(path: string): Config;
+    /**
+     * Merge `other` underneath this config — i.e. values defined here win,
+     * keys that only exist in `other` are filled in.
+     */
+    withFallback(other: Config): Config;
+    /** Inverse of withFallback — layer `overlay` on top. */
+    merge(overlay: Config): Config;
+    /** Wrap the tree under the given path: `{a:{b:1}}`.atPath("x.y") → `{x:{y:{a:{b:1}}}}`. */
+    atPath(path: string): Config;
+    /** Deep-clone the underlying tree as a plain object. */
+    toJSON(): ConfigObject;
+    private lookup;
+    private requireValue;
+}
+export interface LoadOptions {
+    readonly appConfPath?: string;
+    readonly overrides?: Config | unknown;
+}
+/** Thrown on type mismatches or missing paths. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** Re-exports for callers that want to build Configs without using the class. */
+export { deepMerge, isPlainObject, parseHocon, resolveSubstitutions };
+export type { ConfigObject, ConfigValue } from './HoconParser.js';
+//# sourceMappingURL=Config.d.ts.map