actor-ts 0.9.1 → 0.11.0

package/dist/http/websocket/WebsocketClientActor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Typed WebSocket **client** actor.  The counterpart to
+ * {@link WebsocketServerActor}: it dials a URL and speaks the same typed,
+ * codec-encoded protocol.  Built on {@link BrokerActor}, so it inherits
+ * reconnect-with-backoff, an outbound buffer that survives reconnects, a
+ * circuit breaker, and HOCON options resolution for free.
+ *
+ *     class FeedClient extends WebsocketClientActor<ClientMessage, ServerMessage> {
+ *       constructor() {
+ *         super(WebsocketClientOptions.create<ClientMessage, ServerMessage>()
+ *           .withUrl('ws://localhost:8080/ws'));
+ *       }
+ *       override onConnected(): void { this.send({ kind: 'ping', n: 1 }); }
+ *       onMessage(msg: ServerMessage): void { this.log.info(`pong ${msg.n}`); }
+ *     }
+ *
+ * `TOut` (what the client sends) comes first, then `TIn` (decoded server
+ * messages).  Lifecycle events (connected / disconnected / inbound) are
+ * delivered through the mailbox, so `onMessage` and the hooks always run
+ * on the actor thread.  Other actors can push a typed send with
+ * `ref.tell(websocketSend(msg))`.
+ */
+import type { Config } from '../../config/Config.js';
+import { BrokerActor, type OutboundEnvelope } from '../../io/broker/BrokerActor.js';
+import { WebsocketDecodeError } from './WebsocketCodec.js';
+import { WebsocketClientOptionsValidator } from './WebsocketClientOptions.js';
+import type { WebsocketClientOptions, WebsocketClientOptionsType } from './WebsocketClientOptions.js';
+import { type WebsocketClientMessage } from './WebsocketMessages.js';
+import { type WebsocketFrame } from './types.js';
+export declare abstract class WebsocketClientActor<TOut, TIn, TSelf = never> extends BrokerActor<WebsocketClientOptionsType<TOut, TIn>, WebsocketClientMessage<TOut, TIn, TSelf>, WebsocketFrame> {
+    private socket;
+    private pingTimer;
+    private _codec;
+    constructor(options?: WebsocketClientOptions<TOut, TIn>);
+    /** Handle one decoded server message. */
+    abstract onMessage(msg: TIn): void | Promise<void>;
+    /** The connection (re)opened.  A good place to send an initial handshake. */
+    protected onConnected(): void | Promise<void>;
+    /** The connection dropped; a reconnect cycle may follow (per options). */
+    protected onDisconnected(_cause?: Error): void | Promise<void>;
+    /** An inbound frame failed to decode.  Only called when onInvalidMessage is 'hook'. */
+    protected onInvalidMessage(_error: WebsocketDecodeError): void | Promise<void>;
+    /** App-level message told to this actor's ref (reachable only when TSelf ≠ never). */
+    protected onSelfMessage(msg: TSelf): void | Promise<void>;
+    /**
+     * Encode + enqueue an outbound message.  Buffered while disconnected and
+     * resent after reconnect (BrokerActor machinery).  Returns false if the
+     * message was dropped (encode failure or buffer overflow).
+     */
+    protected send(msg: TOut): boolean;
+    /** Send a raw frame, bypassing the codec. */
+    protected sendRaw(frame: WebsocketFrame): boolean;
+    private codec;
+    /** @internal Sealed — override onMessage + hooks instead. */
+    onReceive(cmd: WebsocketClientMessage<TOut, TIn, TSelf>): void | Promise<void>;
+    protected configKey(): string;
+    protected builtInDefaultOptions(): Partial<WebsocketClientOptionsType<TOut, TIn>>;
+    protected requiredOptions(): ReadonlyArray<keyof WebsocketClientOptionsType<TOut, TIn>>;
+    protected optionsValidator(): WebsocketClientOptionsValidator<TOut, TIn>;
+    protected endpointLabel(): string;
+    protected readOptionsFromConfig(config: Config): Partial<WebsocketClientOptionsType<TOut, TIn>>;
+    protected connectImplementation(): Promise<void>;
+    protected disconnectImplementation(): Promise<void>;
+    protected dispatchOutgoing(env: OutboundEnvelope<WebsocketFrame>): Promise<void>;
+    private onSocketDown;
+    private handleInbound;
+}
+//# sourceMappingURL=WebsocketClientActor.d.ts.map

package/dist/http/websocket/WebsocketClientActor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketClientActor.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketClientActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,EAAa,oBAAoB,EAAuB,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,+BAA+B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACtG,OAAO,EASL,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,8BAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,CACjE,SAAQ,WAAW,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC;IAEpH,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,MAAM,CAA0C;gBAE5C,OAAO,GAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,CAAM;IAM3D,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD,6EAA6E;IAC7E,SAAS,CAAC,WAAW,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7C,0EAA0E;IAC1E,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9D,uFAAuF;IACvF,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9E,sFAAsF;IACtF,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzD;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO;IAWlC,6CAA6C;IAC7C,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;IAIjD,OAAO,CAAC,KAAK;IAMb,6DAA6D;IACpD,SAAS,CAAC,GAAG,EAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAavF,SAAS,CAAC,SAAS,IAAI,MAAM;IAC7B,SAAS,CAAC,qBAAqB,IAAI,OAAO,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjF,SAAS,CAAC,eAAe,IAAI,aAAa,CAAC,MAAM,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;cACpE,gBAAgB,IAAI,+BAA+B,CAAC,IAAI,EAAE,GAAG,CAAC;IAGjF,SAAS,CAAC,aAAa,IAAI,MAAM;IAEjC,SAAS,CAAC,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;cAe/E,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;cA+BtC,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC;cAOzC,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtF,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;CA6BtB"}

package/dist/http/websocket/WebsocketClientActor.js

@@ -0,0 +1,195 @@
+import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { BrokerActor } from '../../io/broker/BrokerActor.js';
+import { jsonCodec, WebsocketDecodeError } from './WebsocketCodec.js';
+import { WebsocketClientOptionsValidator } from './WebsocketClientOptions.js';
+import { websocketClientConnected, websocketClientDisconnected, websocketClientInbound, websocketClientInvalid, } from './WebsocketMessages.js';
+import { websocketClientConstructor } from './websocketConstructor.js';
+import { DEFAULT_WEBSOCKET_MAX_FRAME_BYTES, frameByteLength, normalizeInbound, } from './types.js';
+export class WebsocketClientActor extends BrokerActor {
+    socket = null;
+    pingTimer = null;
+    _codec = null;
+    constructor(options = {}) {
+        super(options);
+    }
+    /** The connection (re)opened.  A good place to send an initial handshake. */
+    onConnected() { }
+    /** The connection dropped; a reconnect cycle may follow (per options). */
+    onDisconnected(_cause) { }
+    /** An inbound frame failed to decode.  Only called when onInvalidMessage is 'hook'. */
+    onInvalidMessage(_error) { }
+    /** App-level message told to this actor's ref (reachable only when TSelf ≠ never). */
+    onSelfMessage(msg) {
+        this.log.warn(`WebsocketClientActor: unhandled self message: ${String(msg)}`);
+    }
+    /* ----------------------- helpers ------------------------------- */
+    /**
+     * Encode + enqueue an outbound message.  Buffered while disconnected and
+     * resent after reconnect (BrokerActor machinery).  Returns false if the
+     * message was dropped (encode failure or buffer overflow).
+     */
+    send(msg) {
+        let frame;
+        try {
+            frame = this.codec().encode(msg);
+        }
+        catch (err) {
+            this.log.error(`WebsocketClientActor: encode failed, dropping message: ${err.message}`);
+            return false;
+        }
+        return this.enqueueOutbound(frame);
+    }
+    /** Send a raw frame, bypassing the codec. */
+    sendRaw(frame) {
+        return this.enqueueOutbound(frame);
+    }
+    codec() {
+        return (this._codec ??= this.options.codec ?? jsonCodec());
+    }
+    /* ----------------------- sealed dispatch ----------------------- */
+    /** @internal Sealed — override onMessage + hooks instead. */
+    onReceive(cmd) {
+        switch (cmd.kind) {
+            case 'websocket-client-send': return void this.send(cmd.message);
+            case 'websocket-client-inbound': return this.onMessage(cmd.message);
+            case 'websocket-client-invalid': return this.onInvalidMessage(cmd.error);
+            case 'websocket-client-connected': return this.onConnected();
+            case 'websocket-client-disconnected': return this.onDisconnected(cmd.cause);
+            default: return this.onSelfMessage(cmd);
+        }
+    }
+    /* ----------------------- BrokerActor plumbing ------------------ */
+    configKey() { return ConfigKeys.io.broker.websocket; }
+    builtInDefaultOptions() { return {}; }
+    requiredOptions() { return ['url']; }
+    optionsValidator() {
+        return new WebsocketClientOptionsValidator();
+    }
+    endpointLabel() { return this.options.url ?? '<unknown>'; }
+    readOptionsFromConfig(config) {
+        const out = {};
+        if (config.hasPath('url'))
+            out.url = config.getString('url');
+        if (config.hasPath('protocols'))
+            out.protocols = config.getStringList('protocols');
+        if (config.hasPath('pingIntervalMs'))
+            out.pingIntervalMs = config.getDuration('pingIntervalMs');
+        if (config.hasPath('maxFrameBytes'))
+            out.maxFrameBytes = config.getBytes('maxFrameBytes');
+        if (config.hasPath('headers')) {
+            const obj = config.getObject('headers');
+            const headers = {};
+            for (const [k, v] of Object.entries(obj))
+                if (typeof v === 'string')
+                    headers[k] = v;
+            out.headers = headers;
+        }
+        return out;
+    }
+    async connectImplementation() {
+        const ctor = await websocketClientConstructor.get();
+        const ws = ctor.create(this.options.url, {
+            protocols: this.options.protocols,
+            headers: this.options.headers,
+        });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            ws.addEventListener('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.socket = ws;
+                ws.addEventListener('message', (ev) => this.handleInbound(ev.data));
+                ws.addEventListener('close', () => this.onSocketDown(new Error('websocket closed')));
+                ws.addEventListener('error', () => this.onSocketDown(new Error('websocket error')));
+                const ping = this.options.pingIntervalMs;
+                if (ping && ping > 0) {
+                    this.pingTimer = setInterval(() => { try {
+                        ws.ping?.();
+                    }
+                    catch { /* ignore */ } }, ping);
+                }
+                this.self.tell(websocketClientConnected());
+                resolve();
+            });
+            ws.addEventListener('error', () => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    ws.close();
+                }
+                catch { /* ignore */ }
+                reject(new Error('websocket connect error'));
+            });
+        });
+    }
+    async disconnectImplementation() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        const sock = this.socket;
+        this.socket = null;
+        if (sock) {
+            try {
+                sock.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    async dispatchOutgoing(env) {
+        if (!this.socket)
+            throw new Error('WebsocketClientActor: not open');
+        this.socket.send(env.payload.data);
+    }
+    /* ----------------------- inbound ------------------------------- */
+    onSocketDown(cause) {
+        if (!this.socket)
+            return; // already handled this connection's drop
+        this.socket = null;
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        this.self.tell(websocketClientDisconnected(cause));
+        // Trigger BrokerActor's reconnect cycle.
+        this.handleConnectionLost(cause);
+    }
+    handleInbound(data) {
+        const frame = normalizeInbound(data);
+        if (!frame) {
+            this.log.warn('WebsocketClientActor: unrecognised inbound frame type — dropped');
+            return;
+        }
+        const cap = this.options.maxFrameBytes ?? DEFAULT_WEBSOCKET_MAX_FRAME_BYTES;
+        if (frameByteLength(frame) > cap) {
+            this.log.warn(`WebsocketClientActor: dropped oversize inbound frame (> ${cap} bytes) from ${this.options.url}`);
+            return;
+        }
+        let decoded;
+        try {
+            decoded = this.codec().decode(frame);
+        }
+        catch (err) {
+            const decodeError = err instanceof WebsocketDecodeError ? err : new WebsocketDecodeError(String(err), frame);
+            const policy = this.options.onInvalidMessage ?? 'drop';
+            if (policy === 'hook') {
+                this.self.tell(websocketClientInvalid(decodeError));
+            }
+            else if (policy === 'disconnect') {
+                this.log.warn(`WebsocketClientActor: invalid inbound message — disconnecting: ${decodeError.message}`);
+                try {
+                    this.socket?.close(1003, 'unsupported data');
+                }
+                catch { /* ignore */ }
+            }
+            else {
+                this.log.warn(`WebsocketClientActor: invalid inbound message — dropped: ${decodeError.message}`);
+            }
+            return;
+        }
+        this.self.tell(websocketClientInbound(decoded));
+    }
+}
+//# sourceMappingURL=WebsocketClientActor.js.map

package/dist/http/websocket/WebsocketClientActor.js.map

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

package/dist/http/websocket/WebsocketClientOptions.d.ts

@@ -0,0 +1,82 @@
+/**
+ * All WebSocket-client option-relevant types live here:
+ *
+ *   - {@link WebsocketClientOptionsType} — the plain options-object shape
+ *     (what you may also pass as a bare `{ … }` object).
+ *   - {@link WebsocketClientOptionsBuilder} — the fluent builder
+ *     (`WebsocketClientOptions.create()…`).
+ *   - {@link WebsocketClientOptions} — the accepted-input **union**
+ *     (`WebsocketClientOptionsBuilder | WebsocketClientOptionsType`), plus a
+ *     value alias to the builder so `WebsocketClientOptions.create()` /
+ *     `new WebsocketClientOptions()` keep working.
+ *
+ * A `WebsocketClientActor` subclass takes a `WebsocketClientOptions` (or builds
+ * one inline) and passes it to `super(...)`:
+ *
+ *     class FeedClient extends WebsocketClientActor<ClientMessage, ServerMessage> {
+ *       constructor() {
+ *         super(WebsocketClientOptions.create<ClientMessage, ServerMessage>()
+ *           .withUrl('ws://localhost:8080/ws'));
+ *       }
+ *     }
+ *
+ * The reconnect / circuit-breaker / outbound-buffer knobs come from
+ * {@link BrokerOptionsBuilder} (the WS client is a {@link BrokerActor}); this
+ * class adds only the WebSocket-specific fields.  The builder records only the
+ * fields you set (as own enumerable props), so it reads/spreads exactly like a
+ * plain object; the same three-layer merge applies (constructor > HOCON under
+ * `actor-ts.io.broker.websocket` > built-in defaults), so any field left unset
+ * falls through to HOCON.
+ */
+import { BrokerOptionsBuilder, BrokerOptionsValidator } from '../../io/broker/BrokerOptions.js';
+import type { BrokerCommonOptionsType } from '../../io/broker/BrokerOptions.js';
+import type { WebsocketCodec } from './WebsocketCodec.js';
+/** Plain options-object shape accepted by a {@link WebsocketClientActor}. */
+export interface WebsocketClientOptionsType<TOut = unknown, TIn = unknown> extends BrokerCommonOptionsType {
+    /** WebSocket URL (`ws://…` or `wss://…`).  Required (ctor or HOCON). */
+    readonly url?: string;
+    readonly protocols?: string | ReadonlyArray<string>;
+    /** Custom request headers — Node/`ws` only; native/browsers ignore them. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    readonly codec?: WebsocketCodec<TOut, TIn>;
+    /** Inbound frame size cap; oversize frames are dropped with a warning.  Default 1 MiB. */
+    readonly maxFrameBytes?: number;
+    /** What to do with an inbound frame the codec can't decode.  Default 'drop'. */
+    readonly onInvalidMessage?: 'drop' | 'hook' | 'disconnect';
+    /** Send a ping every `pingIntervalMs` to keep the connection alive.  Default: disabled. */
+    readonly pingIntervalMs?: number;
+}
+/** Fluent builder for {@link WebsocketClientOptionsType}. */
+export declare class WebsocketClientOptionsBuilder<TOut = unknown, TIn = unknown> extends BrokerOptionsBuilder<WebsocketClientOptionsType<TOut, TIn>> {
+    /** Start a fresh builder.  Equivalent to `new WebsocketClientOptionsBuilder()`. */
+    static create<TOut = unknown, TIn = unknown>(): WebsocketClientOptionsBuilder<TOut, TIn>;
+    /** WebSocket URL (`ws://…` or `wss://…`).  Required (here or via HOCON). */
+    withUrl(url: string): this;
+    /** Sub-protocol(s) offered in the handshake. */
+    withProtocols(protocols: string | ReadonlyArray<string>): this;
+    /** Custom request headers — Node/`ws` only; native/browsers ignore them. */
+    withHeaders(headers: Readonly<Record<string, string>>): this;
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    withCodec(codec: WebsocketCodec<TOut, TIn>): this;
+    /** Inbound frame size cap; oversize frames are dropped with a warning.  Default 1 MiB. */
+    withMaxFrameBytes(bytes: number): this;
+    /** What to do with an inbound frame the codec can't decode.  Default 'drop'. */
+    withOnInvalidMessage(policy: 'drop' | 'hook' | 'disconnect'): this;
+    /** Send a ping every `ms` to keep the connection alive.  Default: disabled. */
+    withPingIntervalMs(ms: number): this;
+}
+/** Validates resolved {@link WebsocketClientOptionsType} settings. */
+export declare class WebsocketClientOptionsValidator<TOut = unknown, TIn = unknown> extends BrokerOptionsValidator<WebsocketClientOptionsType<TOut, TIn>> {
+    constructor();
+    protected rules(s: Partial<WebsocketClientOptionsType<TOut, TIn>>): void;
+}
+/**
+ * Accepted input for any WebSocket-client-configurable constructor: the fluent
+ * {@link WebsocketClientOptionsBuilder} OR a plain
+ * {@link WebsocketClientOptionsType} object.
+ */
+export type WebsocketClientOptions<TOut = unknown, TIn = unknown> = WebsocketClientOptionsBuilder<TOut, TIn> | Partial<WebsocketClientOptionsType<TOut, TIn>>;
+/** Value alias so `WebsocketClientOptions.create()` / `new WebsocketClientOptions()` resolve to the builder. */
+export declare const WebsocketClientOptions: typeof WebsocketClientOptionsBuilder;
+//# sourceMappingURL=WebsocketClientOptions.d.ts.map

package/dist/http/websocket/WebsocketClientOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketClientOptions.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketClientOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAChG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,CAAE,SAAQ,uBAAuB;IACxG,wEAAwE;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACpD,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3C,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3D,2FAA2F;IAC3F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,6DAA6D;AAC7D,qBAAa,6BAA6B,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,CACtE,SAAQ,oBAAoB,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnE,mFAAmF;IACnF,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,KAAK,6BAA6B,CAAC,IAAI,EAAE,GAAG,CAAC;IAIxF,4EAA4E;IAC5E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,gDAAgD;IAChD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI;IAI9D,4EAA4E;IAC5E,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI;IAI5D,sDAAsD;IACtD,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI;IAIjD,0FAA0F;IAC1F,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAItC,gFAAgF;IAChF,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,IAAI;IAIlE,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAGrC;AAED,sEAAsE;AACtE,qBAAa,+BAA+B,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,CACxE,SAAQ,sBAAsB,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;;IAIrE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI;CAOzE;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,IAC5D,6BAA6B,CAAC,IAAI,EAAE,GAAG,CAAC,GACxC,OAAO,CAAC,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AACnD,gHAAgH;AAChH,eAAO,MAAM,sBAAsB,sCAAgC,CAAC"}

package/dist/http/websocket/WebsocketClientOptions.js

@@ -0,0 +1,82 @@
+/**
+ * All WebSocket-client option-relevant types live here:
+ *
+ *   - {@link WebsocketClientOptionsType} — the plain options-object shape
+ *     (what you may also pass as a bare `{ … }` object).
+ *   - {@link WebsocketClientOptionsBuilder} — the fluent builder
+ *     (`WebsocketClientOptions.create()…`).
+ *   - {@link WebsocketClientOptions} — the accepted-input **union**
+ *     (`WebsocketClientOptionsBuilder | WebsocketClientOptionsType`), plus a
+ *     value alias to the builder so `WebsocketClientOptions.create()` /
+ *     `new WebsocketClientOptions()` keep working.
+ *
+ * A `WebsocketClientActor` subclass takes a `WebsocketClientOptions` (or builds
+ * one inline) and passes it to `super(...)`:
+ *
+ *     class FeedClient extends WebsocketClientActor<ClientMessage, ServerMessage> {
+ *       constructor() {
+ *         super(WebsocketClientOptions.create<ClientMessage, ServerMessage>()
+ *           .withUrl('ws://localhost:8080/ws'));
+ *       }
+ *     }
+ *
+ * The reconnect / circuit-breaker / outbound-buffer knobs come from
+ * {@link BrokerOptionsBuilder} (the WS client is a {@link BrokerActor}); this
+ * class adds only the WebSocket-specific fields.  The builder records only the
+ * fields you set (as own enumerable props), so it reads/spreads exactly like a
+ * plain object; the same three-layer merge applies (constructor > HOCON under
+ * `actor-ts.io.broker.websocket` > built-in defaults), so any field left unset
+ * falls through to HOCON.
+ */
+import { BrokerOptionsBuilder, BrokerOptionsValidator } from '../../io/broker/BrokerOptions.js';
+/** Fluent builder for {@link WebsocketClientOptionsType}. */
+export class WebsocketClientOptionsBuilder extends BrokerOptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new WebsocketClientOptionsBuilder()`. */
+    static create() {
+        return new WebsocketClientOptionsBuilder();
+    }
+    /** WebSocket URL (`ws://…` or `wss://…`).  Required (here or via HOCON). */
+    withUrl(url) {
+        return this.set('url', url);
+    }
+    /** Sub-protocol(s) offered in the handshake. */
+    withProtocols(protocols) {
+        return this.set('protocols', protocols);
+    }
+    /** Custom request headers — Node/`ws` only; native/browsers ignore them. */
+    withHeaders(headers) {
+        return this.set('headers', headers);
+    }
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    withCodec(codec) {
+        return this.set('codec', codec);
+    }
+    /** Inbound frame size cap; oversize frames are dropped with a warning.  Default 1 MiB. */
+    withMaxFrameBytes(bytes) {
+        return this.set('maxFrameBytes', bytes);
+    }
+    /** What to do with an inbound frame the codec can't decode.  Default 'drop'. */
+    withOnInvalidMessage(policy) {
+        return this.set('onInvalidMessage', policy);
+    }
+    /** Send a ping every `ms` to keep the connection alive.  Default: disabled. */
+    withPingIntervalMs(ms) {
+        return this.set('pingIntervalMs', ms);
+    }
+}
+/** Validates resolved {@link WebsocketClientOptionsType} settings. */
+export class WebsocketClientOptionsValidator extends BrokerOptionsValidator {
+    constructor() {
+        super('WebsocketClientOptions');
+    }
+    rules(s) {
+        this.commonRules(s);
+        this.url('url', ['ws', 'wss']);
+        this.positiveInt('maxFrameBytes');
+        this.positiveNumber('pingIntervalMs');
+        this.oneOf('onInvalidMessage', ['drop', 'hook', 'disconnect']);
+    }
+}
+/** Value alias so `WebsocketClientOptions.create()` / `new WebsocketClientOptions()` resolve to the builder. */
+export const WebsocketClientOptions = WebsocketClientOptionsBuilder;
+//# sourceMappingURL=WebsocketClientOptions.js.map

package/dist/http/websocket/WebsocketClientOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketClientOptions.js","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketClientOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAqBhG,6DAA6D;AAC7D,MAAM,OAAO,6BACX,SAAQ,oBAA2D;IACnE,mFAAmF;IACnF,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,6BAA6B,EAAa,CAAC;IACxD,CAAC;IAED,4EAA4E;IAC5E,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,gDAAgD;IAChD,aAAa,CAAC,SAAyC;QACrD,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,4EAA4E;IAC5E,WAAW,CAAC,OAAyC;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,sDAAsD;IACtD,SAAS,CAAC,KAAgC;QACxC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,0FAA0F;IAC1F,iBAAiB,CAAC,KAAa;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,gFAAgF;IAChF,oBAAoB,CAAC,MAAsC;QACzD,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,+EAA+E;IAC/E,kBAAkB,CAAC,EAAU;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC;CACF;AAED,sEAAsE;AACtE,MAAM,OAAO,+BACX,SAAQ,sBAA6D;IACrE;QACE,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAClC,CAAC;IACS,KAAK,CAAC,CAAiD;QAC/D,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QAClC,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IACjE,CAAC;CACF;AAUD,gHAAgH;AAChH,MAAM,CAAC,MAAM,sBAAsB,GAAG,6BAA6B,CAAC"}

package/dist/http/websocket/WebsocketCodec.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Codec seam for the typed WebSocket stack.  A codec turns application
+ * messages into wire frames and back:
+ *
+ *   - `encode(msg: TOut): WebsocketFrame`  — outbound (server→client / client→server)
+ *   - `decode(frame: WebsocketFrame): TIn` — inbound
+ *
+ * `TOut` comes first to match the actor-class generic order
+ * (`WebsocketServerActor<TOut, TIn>`).  The default is {@link jsonCodec};
+ * {@link rawCodec} is the escape hatch for apps that want the raw frames
+ * (e.g. binary audio).  Custom codecs (CBOR, protobuf, a zod-validated
+ * JSON codec) implement the same two methods.
+ *
+ * Error contract: `decode` throws {@link WebsocketDecodeError} on malformed
+ * input — the connection layer then applies the route's
+ * `onInvalidMessage` policy (close / drop / hook).  `encode` throws
+ * {@link WebsocketEncodeError}; since sends are fire-and-forget the message is
+ * logged and dropped rather than surfaced to the caller.
+ */
+import type { WebsocketFrame } from './types.js';
+/** Thrown by `decode` when an inbound frame can't be parsed or validated. */
+export declare class WebsocketDecodeError extends Error {
+    /** The offending raw frame — useful for logging / an onInvalidMessage hook. */
+    readonly frame: WebsocketFrame;
+    constructor(message: string, 
+    /** The offending raw frame — useful for logging / an onInvalidMessage hook. */
+    frame: WebsocketFrame, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown by `encode` when an outbound message can't be serialised. */
+export declare class WebsocketEncodeError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Bidirectional wire codec.  `TOut` = what we send, `TIn` = what we receive. */
+export interface WebsocketCodec<TOut, TIn> {
+    /** Stable identifier — 'json' | 'raw' | custom.  Informational (logs). */
+    readonly name: string;
+    encode(msg: TOut): WebsocketFrame;
+    decode(frame: WebsocketFrame): TIn;
+}
+/**
+ * Default codec: application messages ↔ JSON.  Text frames are
+ * `JSON.parse`d directly; binary frames are UTF-8 decoded first (so a
+ * client that sends JSON as a binary frame still works).  Outbound
+ * messages become text frames via `JSON.stringify`.
+ *
+ * Pass `validate` to run a schema check (e.g. a zod parser) on the
+ * parsed value — it receives the `unknown` parse result and must return
+ * (or throw for) a `TIn`.  A thrown validator is wrapped as a
+ * {@link WebsocketDecodeError}.
+ */
+export declare function jsonCodec<TOut, TIn>(opts?: {
+    validate?: (value: unknown) => TIn;
+}): WebsocketCodec<TOut, TIn>;
+/**
+ * Escape-hatch codec: no encoding at all — `TOut` and `TIn` are both
+ * {@link WebsocketFrame}, so the actor sees and sends raw text/binary frames.
+ * Use for binary protocols (audio/video) or when you want to own the
+ * wire format entirely.
+ */
+export declare function rawCodec(): WebsocketCodec<WebsocketFrame, WebsocketFrame>;
+//# sourceMappingURL=WebsocketCodec.d.ts.map

package/dist/http/websocket/WebsocketCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketCodec.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,6EAA6E;AAC7E,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,+EAA+E;aAC/D,KAAK,EAAE,cAAc;gBAFrC,OAAO,EAAE,MAAM;IACf,+EAA+E;IAC/D,KAAK,EAAE,cAAc,EACrC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAED,uEAAuE;AACvE,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc,CAAC,IAAI,EAAE,GAAG;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC;IAClC,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,CAAC;CACpC;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,GAAG,CAAA;CAAO,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAiCjH;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAAC,cAAc,EAAE,cAAc,CAAC,CAMzE"}

package/dist/http/websocket/WebsocketCodec.js

@@ -0,0 +1,82 @@
+/** Thrown by `decode` when an inbound frame can't be parsed or validated. */
+export class WebsocketDecodeError extends Error {
+    frame;
+    constructor(message, 
+    /** The offending raw frame — useful for logging / an onInvalidMessage hook. */
+    frame, options) {
+        super(message, options);
+        this.frame = frame;
+        this.name = 'WebsocketDecodeError';
+    }
+}
+/** Thrown by `encode` when an outbound message can't be serialised. */
+export class WebsocketEncodeError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'WebsocketEncodeError';
+    }
+}
+const textDecoder = /* @__PURE__ */ new TextDecoder('utf-8', { fatal: false });
+/**
+ * Default codec: application messages ↔ JSON.  Text frames are
+ * `JSON.parse`d directly; binary frames are UTF-8 decoded first (so a
+ * client that sends JSON as a binary frame still works).  Outbound
+ * messages become text frames via `JSON.stringify`.
+ *
+ * Pass `validate` to run a schema check (e.g. a zod parser) on the
+ * parsed value — it receives the `unknown` parse result and must return
+ * (or throw for) a `TIn`.  A thrown validator is wrapped as a
+ * {@link WebsocketDecodeError}.
+ */
+export function jsonCodec(opts = {}) {
+    const validate = opts.validate;
+    return {
+        name: 'json',
+        encode(msg) {
+            let data;
+            try {
+                data = JSON.stringify(msg);
+            }
+            catch (cause) {
+                throw new WebsocketEncodeError('jsonCodec: failed to stringify outbound message', { cause });
+            }
+            if (data === undefined) {
+                // JSON.stringify(undefined) / a function returns undefined.
+                throw new WebsocketEncodeError('jsonCodec: outbound message is not JSON-serialisable');
+            }
+            return { kind: 'text', data };
+        },
+        decode(frame) {
+            const text = frame.kind === 'text' ? frame.data : textDecoder.decode(frame.data);
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (cause) {
+                throw new WebsocketDecodeError('jsonCodec: inbound frame is not valid JSON', frame, { cause });
+            }
+            if (!validate)
+                return parsed;
+            try {
+                return validate(parsed);
+            }
+            catch (cause) {
+                throw new WebsocketDecodeError('jsonCodec: inbound message failed validation', frame, { cause });
+            }
+        },
+    };
+}
+/**
+ * Escape-hatch codec: no encoding at all — `TOut` and `TIn` are both
+ * {@link WebsocketFrame}, so the actor sees and sends raw text/binary frames.
+ * Use for binary protocols (audio/video) or when you want to own the
+ * wire format entirely.
+ */
+export function rawCodec() {
+    return {
+        name: 'raw',
+        encode: (frame) => frame,
+        decode: (frame) => frame,
+    };
+}
+//# sourceMappingURL=WebsocketCodec.js.map

package/dist/http/websocket/WebsocketCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketCodec.js","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketCodec.ts"],"names":[],"mappings":"AAqBA,6EAA6E;AAC7E,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAI3B;IAHlB,YACE,OAAe;IACf,+EAA+E;IAC/D,KAAqB,EACrC,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAHR,UAAK,GAAL,KAAK,CAAgB;QAIrC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAUD,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAY,OAA+C,EAAE;IACpF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM,CAAC,GAAS;YACd,IAAI,IAAY,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,oBAAoB,CAAC,iDAAiD,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/F,CAAC;YACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,4DAA4D;gBAC5D,MAAM,IAAI,oBAAoB,CAAC,sDAAsD,CAAC,CAAC;YACzF,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAChC,CAAC;QACD,MAAM,CAAC,KAAqB;YAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjF,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,oBAAoB,CAAC,4CAA4C,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACjG,CAAC;YACD,IAAI,CAAC,QAAQ;gBAAE,OAAO,MAAa,CAAC;YACpC,IAAI,CAAC;gBACH,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,oBAAoB,CAAC,8CAA8C,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACnG,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO;QACL,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,CAAC,KAAqB,EAAkB,EAAE,CAAC,KAAK;QACxD,MAAM,EAAE,CAAC,KAAqB,EAAkB,EAAE,CAAC,KAAK;KACzD,CAAC;AACJ,CAAC"}