actor-ts 0.9.0

package/dist/io/broker/BrokerActor.d.ts

@@ -0,0 +1,125 @@
+import { Actor } from '../../Actor.js';
+import type { ActorRef } from '../../ActorRef.js';
+import type { Config } from '../../config/Config.js';
+import { type BrokerCommonSettings } from './BrokerSettings.js';
+/**
+ * Connection-lifecycle state machine.  Transitions are linear:
+ *   disconnected → connecting → connected → disconnecting → disconnected
+ *
+ * Reconnect after failure goes `connected → disconnected → connecting → …`
+ * with backoff between attempts.  Aktor-Stop terminates from any state
+ * via `disconnecting → disconnected`.
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'disconnecting';
+/**
+ * Outbound envelope queued by the base class.  Subclass `dispatchOutgoing`
+ * receives one of these when the connection is up.  The `payload` is
+ * intentionally `unknown` — broker-specific outbound types are layered
+ * on top by the subclass (e.g. MQTT publishes carry topic+QoS+retain).
+ */
+export interface OutboundEnvelope<P = unknown> {
+    readonly payload: P;
+    /** Wall-clock when the message was enqueued.  Useful for TTL evictions. */
+    readonly enqueuedAt: number;
+}
+/**
+ * Base class for actors that bridge external messaging systems
+ * (MQTT, WebSocket, Kafka, …) into the actor system.  Subclasses
+ * implement three protocol hooks (`connectImpl`, `disconnectImpl`,
+ * `dispatchOutgoing`); the base class owns the lifecycle, reconnect-
+ * backoff, outbound buffer, subscriber fan-out, and lifecycle-event
+ * publishing.
+ *
+ * **Settings precedence (highest first):**
+ *   1. Constructor argument (per-instance overrides).
+ *   2. HOCON config under `configKey()` (system-wide defaults).
+ *   3. Built-in defaults from `builtInDefaults()`.
+ *
+ * Subclasses pass their constructor settings via `super(settings)` and
+ * implement `configKey()`, `builtInDefaults()`, `readSettingsFromConfig()`,
+ * and `requiredSettings()` so the base class can resolve and validate
+ * the effective settings before `connectImpl()` runs.
+ */
+export declare abstract class BrokerActor<S extends BrokerCommonSettings, Cmd = unknown, P = unknown> extends Actor<Cmd> {
+    /** Constructor settings — partial; merged with HOCON + defaults in preStart. */
+    private readonly _ctorSettings;
+    /** Final, fully resolved settings.  `null` until preStart() ran. */
+    private _settings;
+    private _state;
+    private _outboundBuffer;
+    /** topic → set of subscriber ActorRefs (deathwatched). */
+    private readonly _subscribers;
+    /** Reverse index for O(1) cleanup on Terminated. */
+    private readonly _subscribed;
+    /** Reconnect bookkeeping for the current cycle (since the last successful connect). */
+    private _reconnectAttempt;
+    /** Circuit-breaker counters.  Zero-cost when no breaker is configured. */
+    private _consecutiveFailures;
+    private _breakerOpenUntil;
+    protected constructor(settings: Partial<S>);
+    /** Final resolved settings — only valid after `preStart`. */
+    protected get settings(): S;
+    /** Subclass: HOCON config path, e.g. `'actor-ts.io.broker.mqtt'`. */
+    protected abstract configKey(): string;
+    /** Subclass: defaults for everything not provided elsewhere. */
+    protected abstract builtInDefaults(): Partial<S>;
+    /** Subclass: parse a Config block into a partial settings object. */
+    protected abstract readSettingsFromConfig(config: Config): Partial<S>;
+    /** Subclass: list of fields that MUST be present in the resolved settings. */
+    protected abstract requiredSettings(): ReadonlyArray<keyof S>;
+    /** Subclass: human-readable label for the connection (used in events). */
+    protected abstract endpointLabel(): string;
+    /**
+     * Open the underlying connection.  Throw on failure to trigger
+     * reconnect; throwing during steady-state operation is also fine
+     * (the base class will start a reconnect cycle).
+     */
+    protected abstract connectImpl(): Promise<void>;
+    /** Close it.  Best-effort — exceptions are logged and swallowed. */
+    protected abstract disconnectImpl(): Promise<void>;
+    /**
+     * Send a single outbound envelope.  Only invoked when state is
+     * `connected`.  Throwing here is treated as a connection failure
+     * and triggers a reconnect cycle.
+     */
+    protected abstract dispatchOutgoing(envelope: OutboundEnvelope<P>): Promise<void>;
+    /**
+     * Subscribe `ref` to `topic`.  The ref is deathwatched — when it
+     * stops, it is automatically removed from every topic it was
+     * subscribed to (no leak).
+     */
+    protected subscribeRef(topic: string, ref: ActorRef<unknown>): void;
+    /** Remove `ref` from `topic`.  No-op if not subscribed. */
+    protected unsubscribeRef(topic: string, ref: ActorRef<unknown>): void;
+    /** Fan-out a received message to every subscriber of `topic`. */
+    protected fanOutToTopic(topic: string, msg: unknown): void;
+    /** Number of distinct topic subscriptions — useful for tests / metrics. */
+    protected subscriberCountForTopic(topic: string): number;
+    /**
+     * Enqueue an outbound message.  When connected, it is dispatched
+     * immediately (in the order they were enqueued); when disconnected
+     * or connecting, it is buffered.  Returns true if buffered or sent,
+     * false if the message was dropped (overflow / not-connected with
+     * `outboundBuffer: 0`).
+     */
+    protected enqueueOutbound(payload: P): boolean;
+    /** Current connection state — exposed for tests / health probes. */
+    protected get connectionState(): ConnectionState;
+    /** Buffer size — exposed for tests. */
+    protected get outboundBufferSize(): number;
+    preStart(): Promise<void>;
+    postStop(): Promise<void>;
+    private _resolveSettings;
+    private _validateRequired;
+    /** Begin (or restart after a disconnect) the connect cycle. */
+    private _beginConnect;
+    private _tryConnect;
+    /** Called when the connection drops (from inside `dispatchOutgoing` or by the subclass). */
+    protected handleConnectionLost(cause?: Error): void;
+    private _handleReconnect;
+    private _scheduleReconnect;
+    private _scheduledReconnectCancel;
+    private _drainBuffer;
+    private _dispatchOne;
+}
+//# sourceMappingURL=BrokerActor.d.ts.map

package/dist/io/broker/BrokerActor.d.ts.map

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

package/dist/io/broker/BrokerActor.js

@@ -0,0 +1,289 @@
+import { match } from 'ts-pattern';
+import { Actor } from '../../Actor.js';
+import { BrokerBufferOverflow, BrokerConnected, BrokerDisconnected, BrokerNotConnected, BrokerReconnectAttempt, BrokerReconnectFailed, } from './BrokerEvents.js';
+import { BrokerSettingsError, DEFAULT_OUTBOUND_BUFFER, DEFAULT_RECONNECT, mergeSettings, readCommonSettings, } from './BrokerSettings.js';
+/**
+ * Base class for actors that bridge external messaging systems
+ * (MQTT, WebSocket, Kafka, …) into the actor system.  Subclasses
+ * implement three protocol hooks (`connectImpl`, `disconnectImpl`,
+ * `dispatchOutgoing`); the base class owns the lifecycle, reconnect-
+ * backoff, outbound buffer, subscriber fan-out, and lifecycle-event
+ * publishing.
+ *
+ * **Settings precedence (highest first):**
+ *   1. Constructor argument (per-instance overrides).
+ *   2. HOCON config under `configKey()` (system-wide defaults).
+ *   3. Built-in defaults from `builtInDefaults()`.
+ *
+ * Subclasses pass their constructor settings via `super(settings)` and
+ * implement `configKey()`, `builtInDefaults()`, `readSettingsFromConfig()`,
+ * and `requiredSettings()` so the base class can resolve and validate
+ * the effective settings before `connectImpl()` runs.
+ */
+export class BrokerActor extends Actor {
+    /** Constructor settings — partial; merged with HOCON + defaults in preStart. */
+    _ctorSettings;
+    /** Final, fully resolved settings.  `null` until preStart() ran. */
+    _settings = null;
+    _state = 'disconnected';
+    _outboundBuffer = [];
+    /** topic → set of subscriber ActorRefs (deathwatched). */
+    _subscribers = new Map();
+    /** Reverse index for O(1) cleanup on Terminated. */
+    _subscribed = new WeakMap();
+    /** Reconnect bookkeeping for the current cycle (since the last successful connect). */
+    _reconnectAttempt = 0;
+    /** Circuit-breaker counters.  Zero-cost when no breaker is configured. */
+    _consecutiveFailures = 0;
+    _breakerOpenUntil = 0;
+    constructor(settings) {
+        super();
+        this._ctorSettings = settings;
+    }
+    /* ------------------------------- Settings ------------------------------- */
+    /** Final resolved settings — only valid after `preStart`. */
+    get settings() {
+        if (!this._settings) {
+            throw new Error(`BrokerActor.settings accessed before preStart`);
+        }
+        return this._settings;
+    }
+    /* ------------------------------- Subscribers ---------------------------- */
+    /**
+     * Subscribe `ref` to `topic`.  The ref is deathwatched — when it
+     * stops, it is automatically removed from every topic it was
+     * subscribed to (no leak).
+     */
+    subscribeRef(topic, ref) {
+        let set = this._subscribers.get(topic);
+        if (!set) {
+            set = new Set();
+            this._subscribers.set(topic, set);
+        }
+        if (!set.has(ref)) {
+            set.add(ref);
+            let topics = this._subscribed.get(ref);
+            if (!topics) {
+                topics = new Set();
+                this._subscribed.set(ref, topics);
+                // First subscription for this ref → start watching.
+                this.context.watch(ref);
+            }
+            topics.add(topic);
+        }
+    }
+    /** Remove `ref` from `topic`.  No-op if not subscribed. */
+    unsubscribeRef(topic, ref) {
+        const set = this._subscribers.get(topic);
+        if (!set)
+            return;
+        set.delete(ref);
+        if (set.size === 0)
+            this._subscribers.delete(topic);
+        const topics = this._subscribed.get(ref);
+        if (topics) {
+            topics.delete(topic);
+            if (topics.size === 0) {
+                this._subscribed.delete(ref);
+                // Last subscription gone → drop the watch.
+                this.context.unwatch(ref);
+            }
+        }
+    }
+    /** Fan-out a received message to every subscriber of `topic`. */
+    fanOutToTopic(topic, msg) {
+        const set = this._subscribers.get(topic);
+        if (!set)
+            return;
+        for (const ref of set)
+            ref.tell(msg);
+    }
+    /** Number of distinct topic subscriptions — useful for tests / metrics. */
+    subscriberCountForTopic(topic) {
+        return this._subscribers.get(topic)?.size ?? 0;
+    }
+    /* ------------------------------- Outbound ------------------------------- */
+    /**
+     * Enqueue an outbound message.  When connected, it is dispatched
+     * immediately (in the order they were enqueued); when disconnected
+     * or connecting, it is buffered.  Returns true if buffered or sent,
+     * false if the message was dropped (overflow / not-connected with
+     * `outboundBuffer: 0`).
+     */
+    enqueueOutbound(payload) {
+        const env = { payload, enqueuedAt: Date.now() };
+        const limit = this.settings.outboundBuffer ?? DEFAULT_OUTBOUND_BUFFER;
+        // Dispatch on connection state with compile-time exhaustiveness:
+        // adding a new state to `ConnectionState` forces every site that
+        // matches on it (including this one) to handle the new variant.
+        return match(this._state)
+            .with('connected', () => {
+            // Dispatch directly.  If an earlier flush is still draining the
+            // buffer, append at the tail to preserve order.
+            if (this._outboundBuffer.length > 0) {
+                this._outboundBuffer.push(env);
+                return true;
+            }
+            void this._dispatchOne(env);
+            return true;
+        })
+            .with('connecting', 'disconnected', 'disconnecting', () => {
+            if (limit === 0) {
+                this.system.eventStream.publish(new BrokerNotConnected(this.self.path.toString()));
+                return false;
+            }
+            if (this._outboundBuffer.length >= limit) {
+                this._outboundBuffer.shift(); // drop oldest (FIFO eviction)
+                this.system.eventStream.publish(new BrokerBufferOverflow(this.self.path.toString(), limit));
+            }
+            this._outboundBuffer.push(env);
+            return true;
+        })
+            .exhaustive();
+    }
+    /** Current connection state — exposed for tests / health probes. */
+    get connectionState() { return this._state; }
+    /** Buffer size — exposed for tests. */
+    get outboundBufferSize() { return this._outboundBuffer.length; }
+    /* ------------------------------- Lifecycle ------------------------------ */
+    async preStart() {
+        this._settings = this._resolveSettings();
+        await this._validateRequired();
+        await this._beginConnect();
+    }
+    async postStop() {
+        this._scheduledReconnectCancel?.();
+        this._scheduledReconnectCancel = null;
+        if (this._state !== 'disconnected') {
+            this._state = 'disconnecting';
+            try {
+                await this.disconnectImpl();
+            }
+            catch (e) {
+                this.log.warn(`broker disconnectImpl threw: ${e.message}`);
+            }
+        }
+        this._state = 'disconnected';
+        this._outboundBuffer = [];
+        this._subscribers.clear();
+    }
+    /* ----------------------------- Internal flow ---------------------------- */
+    _resolveSettings() {
+        const defaults = this.builtInDefaults();
+        const cfg = this.system.config.hasPath(this.configKey())
+            ? this.system.config.getConfig(this.configKey())
+            : null;
+        const fromConfig = cfg
+            ? { ...readCommonSettings(cfg), ...this.readSettingsFromConfig(cfg) }
+            : {};
+        return mergeSettings(defaults, fromConfig, this._ctorSettings);
+    }
+    async _validateRequired() {
+        const required = this.requiredSettings();
+        const missing = [];
+        for (const k of required) {
+            if (this._settings[k] === undefined || this._settings[k] === null) {
+                missing.push(String(k));
+            }
+        }
+        if (missing.length > 0) {
+            throw new BrokerSettingsError(`${this.constructor.name} missing required settings: ${missing.join(', ')}.  `
+                + `Pass them in the constructor or under HOCON path '${this.configKey()}'.`, this.configKey());
+        }
+    }
+    /** Begin (or restart after a disconnect) the connect cycle. */
+    async _beginConnect() {
+        this._reconnectAttempt = 0;
+        await this._tryConnect();
+    }
+    async _tryConnect() {
+        // Honour an open circuit breaker.
+        const breaker = this.settings.circuitBreaker;
+        if (breaker && Date.now() < this._breakerOpenUntil) {
+            const remaining = this._breakerOpenUntil - Date.now();
+            this._scheduleReconnect(remaining);
+            return;
+        }
+        this._state = 'connecting';
+        try {
+            await this.connectImpl();
+            this._state = 'connected';
+            this._reconnectAttempt = 0;
+            this._consecutiveFailures = 0;
+            this.system.eventStream.publish(new BrokerConnected(this.self.path.toString(), this.endpointLabel()));
+            // Drain any buffered outbound now that we're connected.
+            void this._drainBuffer();
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            this._state = 'disconnected';
+            this._consecutiveFailures++;
+            if (breaker && this._consecutiveFailures >= breaker.failureThreshold) {
+                this._breakerOpenUntil = Date.now() + breaker.resetMs;
+                this._consecutiveFailures = 0;
+            }
+            this._handleReconnect(err);
+        }
+    }
+    /** Called when the connection drops (from inside `dispatchOutgoing` or by the subclass). */
+    handleConnectionLost(cause) {
+        if (this._state !== 'connected' && this._state !== 'connecting')
+            return;
+        this._state = 'disconnected';
+        this.system.eventStream.publish(new BrokerDisconnected(this.self.path.toString(), this.endpointLabel(), cause));
+        this._handleReconnect(cause ?? new Error('connection lost'));
+    }
+    _handleReconnect(cause) {
+        const policy = this.settings.reconnect;
+        if (policy === false)
+            return;
+        const initial = policy?.initialDelayMs ?? DEFAULT_RECONNECT.initialDelayMs;
+        const maxDelay = policy?.maxDelayMs ?? DEFAULT_RECONNECT.maxDelayMs;
+        const factor = policy?.factor ?? DEFAULT_RECONNECT.factor;
+        const maxAttempts = policy?.maxAttempts ?? DEFAULT_RECONNECT.maxAttempts;
+        this._reconnectAttempt++;
+        if (this._reconnectAttempt > maxAttempts) {
+            this.system.eventStream.publish(new BrokerReconnectFailed(this.self.path.toString(), this.endpointLabel(), this._reconnectAttempt - 1, cause));
+            return;
+        }
+        const delay = Math.min(initial * Math.pow(factor, this._reconnectAttempt - 1), maxDelay);
+        this.system.eventStream.publish(new BrokerReconnectAttempt(this.self.path.toString(), this.endpointLabel(), this._reconnectAttempt, delay));
+        this._scheduleReconnect(delay);
+    }
+    _scheduleReconnect(delayMs) {
+        // Cancel any pending reconnect timer first (e.g. when reconnect is
+        // re-triggered before the previous timer fired).
+        this._scheduledReconnectCancel?.();
+        const reconnect = () => { void this._tryConnect(); };
+        // Use the system scheduler (not the actor TimerScheduler): reconnect
+        // is detached from the message pipeline — it should not queue behind
+        // user commands.  Cancel-handle is tracked for postStop teardown.
+        const handle = this.system.scheduler.scheduleOnceFn(delayMs, reconnect);
+        this._scheduledReconnectCancel = () => { handle.cancel(); };
+    }
+    _scheduledReconnectCancel = null;
+    async _drainBuffer() {
+        while (this._outboundBuffer.length > 0 && this._state === 'connected') {
+            const env = this._outboundBuffer.shift();
+            try {
+                await this.dispatchOutgoing(env);
+            }
+            catch (e) {
+                // Push back at the head so the message isn't lost across reconnect.
+                this._outboundBuffer.unshift(env);
+                this.handleConnectionLost(e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+        }
+    }
+    async _dispatchOne(env) {
+        try {
+            await this.dispatchOutgoing(env);
+        }
+        catch (e) {
+            this._outboundBuffer.unshift(env);
+            this.handleConnectionLost(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+}
+//# sourceMappingURL=BrokerActor.js.map

package/dist/io/broker/BrokerActor.js.map

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

package/dist/io/broker/BrokerEvents.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Lifecycle events published on `system.eventStream` by every
+ * `BrokerActor`.  Health-checks, metrics, and admin tools subscribe
+ * via `system.eventStream.subscribe(probeRef, BrokerConnected)` to get
+ * a uniform view across all broker types.
+ *
+ * Each event carries the actor path so listeners can attribute it
+ * even when many broker actors run in the same system.
+ */
+export declare class BrokerConnected {
+    readonly actorPath: string;
+    readonly endpoint: string;
+    constructor(actorPath: string, endpoint: string);
+}
+export declare class BrokerDisconnected {
+    readonly actorPath: string;
+    readonly endpoint: string;
+    readonly cause?: Error | undefined;
+    constructor(actorPath: string, endpoint: string, cause?: Error | undefined);
+}
+export declare class BrokerReconnectAttempt {
+    readonly actorPath: string;
+    readonly endpoint: string;
+    /** 1-based attempt counter for the *current* reconnect cycle. */
+    readonly attempt: number;
+    readonly delayMs: number;
+    constructor(actorPath: string, endpoint: string, 
+    /** 1-based attempt counter for the *current* reconnect cycle. */
+    attempt: number, delayMs: number);
+}
+export declare class BrokerReconnectFailed {
+    readonly actorPath: string;
+    readonly endpoint: string;
+    /** Total attempts that ran in the cycle that just gave up. */
+    readonly attempts: number;
+    readonly cause: Error;
+    constructor(actorPath: string, endpoint: string, 
+    /** Total attempts that ran in the cycle that just gave up. */
+    attempts: number, cause: Error);
+}
+/**
+ * One outbound message had to be evicted because the buffer was full.
+ * The dropped envelope is *not* attached — listeners that need it
+ * should use a smaller buffer with explicit overflow handling.
+ */
+export declare class BrokerBufferOverflow {
+    readonly actorPath: string;
+    readonly bufferLimit: number;
+    constructor(actorPath: string, bufferLimit: number);
+}
+/**
+ * An attempt to send while disconnected was rejected because the
+ * outbound buffer is sized `0` (fail-fast mode).
+ */
+export declare class BrokerNotConnected {
+    readonly actorPath: string;
+    constructor(actorPath: string);
+}
+//# sourceMappingURL=BrokerEvents.d.ts.map

package/dist/io/broker/BrokerEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrokerEvents.d.ts","sourceRoot":"","sources":["../../../src/io/broker/BrokerEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qBAAa,eAAe;aAER,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;gBADhB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM;CAEnC;AAED,qBAAa,kBAAkB;aAEX,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;aAChB,KAAK,CAAC,EAAE,KAAK;gBAFb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,KAAK,YAAA;CAEhC;AAED,qBAAa,sBAAsB;aAEf,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;IAChC,iEAAiE;aACjD,OAAO,EAAE,MAAM;aACf,OAAO,EAAE,MAAM;gBAJf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM;IAChC,iEAAiE;IACjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;CAElC;AAED,qBAAa,qBAAqB;aAEd,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;IAChC,8DAA8D;aAC9C,QAAQ,EAAE,MAAM;aAChB,KAAK,EAAE,KAAK;gBAJZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM;IAChC,8DAA8D;IAC9C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK;CAE/B;AAED;;;;GAIG;AACH,qBAAa,oBAAoB;aAEb,SAAS,EAAE,MAAM;aACjB,WAAW,EAAE,MAAM;gBADnB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAEtC;AAED;;;GAGG;AACH,qBAAa,kBAAkB;aAEX,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAEpC"}

package/dist/io/broker/BrokerEvents.js

@@ -0,0 +1,79 @@
+/**
+ * Lifecycle events published on `system.eventStream` by every
+ * `BrokerActor`.  Health-checks, metrics, and admin tools subscribe
+ * via `system.eventStream.subscribe(probeRef, BrokerConnected)` to get
+ * a uniform view across all broker types.
+ *
+ * Each event carries the actor path so listeners can attribute it
+ * even when many broker actors run in the same system.
+ */
+export class BrokerConnected {
+    actorPath;
+    endpoint;
+    constructor(actorPath, endpoint) {
+        this.actorPath = actorPath;
+        this.endpoint = endpoint;
+    }
+}
+export class BrokerDisconnected {
+    actorPath;
+    endpoint;
+    cause;
+    constructor(actorPath, endpoint, cause) {
+        this.actorPath = actorPath;
+        this.endpoint = endpoint;
+        this.cause = cause;
+    }
+}
+export class BrokerReconnectAttempt {
+    actorPath;
+    endpoint;
+    attempt;
+    delayMs;
+    constructor(actorPath, endpoint, 
+    /** 1-based attempt counter for the *current* reconnect cycle. */
+    attempt, delayMs) {
+        this.actorPath = actorPath;
+        this.endpoint = endpoint;
+        this.attempt = attempt;
+        this.delayMs = delayMs;
+    }
+}
+export class BrokerReconnectFailed {
+    actorPath;
+    endpoint;
+    attempts;
+    cause;
+    constructor(actorPath, endpoint, 
+    /** Total attempts that ran in the cycle that just gave up. */
+    attempts, cause) {
+        this.actorPath = actorPath;
+        this.endpoint = endpoint;
+        this.attempts = attempts;
+        this.cause = cause;
+    }
+}
+/**
+ * One outbound message had to be evicted because the buffer was full.
+ * The dropped envelope is *not* attached — listeners that need it
+ * should use a smaller buffer with explicit overflow handling.
+ */
+export class BrokerBufferOverflow {
+    actorPath;
+    bufferLimit;
+    constructor(actorPath, bufferLimit) {
+        this.actorPath = actorPath;
+        this.bufferLimit = bufferLimit;
+    }
+}
+/**
+ * An attempt to send while disconnected was rejected because the
+ * outbound buffer is sized `0` (fail-fast mode).
+ */
+export class BrokerNotConnected {
+    actorPath;
+    constructor(actorPath) {
+        this.actorPath = actorPath;
+    }
+}
+//# sourceMappingURL=BrokerEvents.js.map

package/dist/io/broker/BrokerEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrokerEvents.js","sourceRoot":"","sources":["../../../src/io/broker/BrokerEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,OAAO,eAAe;IAER;IACA;IAFlB,YACkB,SAAiB,EACjB,QAAgB;QADhB,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;IAC/B,CAAC;CACL;AAED,MAAM,OAAO,kBAAkB;IAEX;IACA;IACA;IAHlB,YACkB,SAAiB,EACjB,QAAgB,EAChB,KAAa;QAFb,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,UAAK,GAAL,KAAK,CAAQ;IAC5B,CAAC;CACL;AAED,MAAM,OAAO,sBAAsB;IAEf;IACA;IAEA;IACA;IALlB,YACkB,SAAiB,EACjB,QAAgB;IAChC,iEAAiE;IACjD,OAAe,EACf,OAAe;QAJf,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,YAAO,GAAP,OAAO,CAAQ;QACf,YAAO,GAAP,OAAO,CAAQ;IAC9B,CAAC;CACL;AAED,MAAM,OAAO,qBAAqB;IAEd;IACA;IAEA;IACA;IALlB,YACkB,SAAiB,EACjB,QAAgB;IAChC,8DAA8D;IAC9C,QAAgB,EAChB,KAAY;QAJZ,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,UAAK,GAAL,KAAK,CAAO;IAC3B,CAAC;CACL;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IAEb;IACA;IAFlB,YACkB,SAAiB,EACjB,WAAmB;QADnB,cAAS,GAAT,SAAS,CAAQ;QACjB,gBAAW,GAAX,WAAW,CAAQ;IAClC,CAAC;CACL;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAEX;IADlB,YACkB,SAAiB;QAAjB,cAAS,GAAT,SAAS,CAAQ;IAChC,CAAC;CACL"}

package/dist/io/broker/BrokerSettings.d.ts

@@ -0,0 +1,72 @@
+import type { Config } from '../../config/Config.js';
+/**
+ * Common settings every broker actor accepts on top of its protocol-
+ * specific options.  Subclasses extend this interface with their own
+ * required fields (e.g. `brokerUrl`, `topics`).
+ */
+export interface BrokerCommonSettings {
+    /**
+     * Reconnect strategy applied when the underlying connection drops or
+     * `connectImpl` throws.  Default: exponential backoff starting at
+     * `200ms`, doubling, capped at `30s`, infinite attempts.  Set to
+     * `false` to disable auto-reconnect (one-shot connections).
+     */
+    readonly reconnect?: false | {
+        readonly initialDelayMs?: number;
+        readonly maxDelayMs?: number;
+        readonly factor?: number;
+        /** Cap on retry attempts.  Default: `Infinity` (retry forever). */
+        readonly maxAttempts?: number;
+    };
+    /**
+     * Optional circuit-breaker around `connectImpl`.  After
+     * `failureThreshold` consecutive failed connect attempts the breaker
+     * opens for `resetMs` and rejects new attempts immediately.
+     */
+    readonly circuitBreaker?: {
+        readonly failureThreshold: number;
+        readonly resetMs: number;
+    };
+    /**
+     * Maximum number of outbound messages buffered while the connection
+     * is `connecting` or `disconnected`.  When the buffer is full the
+     * oldest message is dropped (FIFO eviction) and a
+     * `BrokerBufferOverflow` event is published.  Default: `1000`.  Set
+     * to `0` to fail-fast (publish a `BrokerNotConnected` event and drop
+     * the message).
+     */
+    readonly outboundBuffer?: number;
+}
+export declare const DEFAULT_RECONNECT: {
+    readonly initialDelayMs: 200;
+    readonly maxDelayMs: 30000;
+    readonly factor: 2;
+    readonly maxAttempts: number;
+};
+export declare const DEFAULT_OUTBOUND_BUFFER = 1000;
+/**
+ * Read the common reconnect / circuit-breaker / buffer fields from a
+ * Config block.  Subclass-specific fields are read by the subclass'
+ * own `readSettingsFromConfig()` method.
+ *
+ * Note: to *disable* reconnect via HOCON, set the leaf
+ * `reconnect.maxAttempts = 1` (one connect attempt, no retry).  The
+ * boolean `false` form is only supported via the constructor argument.
+ */
+export declare function readCommonSettings(config: Config): BrokerCommonSettings;
+/**
+ * Merge settings in the documented precedence order:
+ *   1. constructor args  (highest)
+ *   2. HOCON config under `configKey`
+ *   3. built-in defaults  (lowest)
+ *
+ * Falsy / undefined values from a higher layer don't shadow lower
+ * layers — `undefined` means "not set", not "explicitly clear".
+ */
+export declare function mergeSettings<S extends object>(builtInDefaults: Partial<S>, fromConfig: Partial<S>, fromConstructor: Partial<S>): S;
+/** Raised when required settings are missing from every layer. */
+export declare class BrokerSettingsError extends Error {
+    readonly configKey: string;
+    constructor(message: string, configKey: string);
+}
+//# sourceMappingURL=BrokerSettings.d.ts.map

package/dist/io/broker/BrokerSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrokerSettings.d.ts","sourceRoot":"","sources":["../../../src/io/broker/BrokerSettings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG;QAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,mEAAmE;QACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;IAEF;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CA0BvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,EACtB,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,GAC1B,CAAC,CAMH;AAUD,kEAAkE;AAClE,qBAAa,mBAAoB,SAAQ,KAAK;aACC,SAAS,EAAE,MAAM;gBAAlD,OAAO,EAAE,MAAM,EAAkB,SAAS,EAAE,MAAM;CAI/D"}