actor-ts 0.9.1 → 0.10.0

package/dist/http/ws/WebSocketClientOptions.d.ts

@@ -0,0 +1,77 @@
+/**
+ * All WebSocket-client option-relevant types live here:
+ *
+ *   - {@link WebSocketClientOptionsType} — the plain settings-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<ClientMsg, ServerMsg> {
+ *       constructor() {
+ *         super(WebSocketClientOptions.create<ClientMsg, ServerMsg>()
+ *           .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 } from '../../io/broker/BrokerOptions.js';
+import type { BrokerCommonOptionsType } from '../../io/broker/BrokerSettings.js';
+import type { WsCodec } from './WsCodec.js';
+/** Plain settings-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?: WsCodec<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: WsCodec<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;
+}
+/**
+ * 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/ws/WebSocketClientOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketClientOptions.d.ts","sourceRoot":"","sources":["../../../src/http/ws/WebSocketClientOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,8EAA8E;AAC9E,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,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,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,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI;IAI1C,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;;;;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/ws/WebSocketClientOptions.js

@@ -0,0 +1,69 @@
+/**
+ * All WebSocket-client option-relevant types live here:
+ *
+ *   - {@link WebSocketClientOptionsType} — the plain settings-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<ClientMsg, ServerMsg> {
+ *       constructor() {
+ *         super(WebSocketClientOptions.create<ClientMsg, ServerMsg>()
+ *           .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 } 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);
+    }
+}
+/** Value alias so `WebSocketClientOptions.create()` / `new WebSocketClientOptions()` resolve to the builder. */
+export const WebSocketClientOptions = WebSocketClientOptionsBuilder;
+//# sourceMappingURL=WebSocketClientOptions.js.map

package/dist/http/ws/WebSocketClientOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketClientOptions.js","sourceRoot":"","sources":["../../../src/http/ws/WebSocketClientOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAqBxE,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,KAAyB;QACjC,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;AAUD,gHAAgH;AAChH,MAAM,CAAC,MAAM,sBAAsB,GAAG,6BAA6B,CAAC"}

package/dist/http/ws/WebSocketConnectionActor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Internal per-connection actor — a genuine child of the
+ * {@link WebSocketServerActor} hub (spawned via the hub's context, so
+ * the actor tree is `server → conn-1, conn-2, …`).  Users never see or
+ * manage it.
+ *
+ * It owns the whole communication for one connection:
+ *   - inbound: attaches the socket listeners in `preStart`, size-caps +
+ *     decodes each frame, and forwards the decoded message to the hub
+ *     with this connection as the sender;
+ *   - outbound: its mailbox is the connection's write queue — a
+ *     {@link WsConnection}'s `tell` / `sendRaw` / `close` enqueue here,
+ *     and it encodes + writes to the socket (with a backpressure check);
+ *   - lifecycle: on socket close it stops itself; `postStop` reports the
+ *     disconnect to the hub exactly once and closes the socket.
+ *
+ * The hub supervises these with `stoppingStrategy` — a crashed
+ * connection stops (and `postStop` still reports the disconnect) rather
+ * than restarting into a dead socket.
+ */
+import { Actor } from '../../Actor.js';
+import { type WebSocketSocketAdapter } from './SocketAdapter.js';
+import { type WsCodec } from './WsCodec.js';
+import { type WsOutboundCommand } from './WsConnection.js';
+import { type WsServerRef } from './WsMessages.js';
+import type { ResolvedWsPolicy } from './WsPolicy.js';
+import { type WsUpgradeInfo } from './types.js';
+export interface WebSocketConnectionDeps<TOut, TIn, TSelf> {
+    readonly socket: WebSocketSocketAdapter;
+    readonly codec: WsCodec<TOut, TIn>;
+    readonly policy: ResolvedWsPolicy;
+    readonly hub: WsServerRef<TOut, TIn, TSelf>;
+    readonly id: string;
+    readonly upgrade: WsUpgradeInfo;
+}
+export declare class WebSocketConnectionActor<TOut, TIn, TSelf = never> extends Actor<WsOutboundCommand<TOut>> {
+    private readonly d;
+    private connection;
+    private closed;
+    private disconnectReported;
+    private closeInfo;
+    constructor(deps: WebSocketConnectionDeps<TOut, TIn, TSelf>);
+    preStart(): void;
+    onReceive(cmd: WsOutboundCommand<TOut>): void;
+    postStop(): void;
+    private handleInbound;
+    private handleClose;
+    private write;
+    private closeSocket;
+}
+//# sourceMappingURL=WebSocketConnectionActor.d.ts.map

package/dist/http/ws/WebSocketConnectionActor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketConnectionActor.d.ts","sourceRoot":"","sources":["../../../src/http/ws/WebSocketConnectionActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAgB,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAuC,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,uBAAuB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK;IACvD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED,qBAAa,wBAAwB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,CAC5D,SAAQ,KAAK,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAEtC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAA4C;IAC9D,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,SAAS,CAA4B;gBAEjC,IAAI,EAAE,uBAAuB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;IAKlD,QAAQ,IAAI,IAAI;IAahB,SAAS,CAAC,GAAG,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI;IA0B7C,QAAQ,IAAI,IAAI;IAiBzB,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,KAAK;IAsBb,OAAO,CAAC,WAAW;CAOpB"}

package/dist/http/ws/WebSocketConnectionActor.js

@@ -0,0 +1,170 @@
+/**
+ * Internal per-connection actor — a genuine child of the
+ * {@link WebSocketServerActor} hub (spawned via the hub's context, so
+ * the actor tree is `server → conn-1, conn-2, …`).  Users never see or
+ * manage it.
+ *
+ * It owns the whole communication for one connection:
+ *   - inbound: attaches the socket listeners in `preStart`, size-caps +
+ *     decodes each frame, and forwards the decoded message to the hub
+ *     with this connection as the sender;
+ *   - outbound: its mailbox is the connection's write queue — a
+ *     {@link WsConnection}'s `tell` / `sendRaw` / `close` enqueue here,
+ *     and it encodes + writes to the socket (with a backpressure check);
+ *   - lifecycle: on socket close it stops itself; `postStop` reports the
+ *     disconnect to the hub exactly once and closes the socket.
+ *
+ * The hub supervises these with `stoppingStrategy` — a crashed
+ * connection stops (and `postStop` still reports the disconnect) rather
+ * than restarting into a dead socket.
+ */
+import { Actor } from '../../Actor.js';
+import { WsReadyState } from './SocketAdapter.js';
+import { WsDecodeError } from './WsCodec.js';
+import { WsConnectionImpl } from './WsConnection.js';
+import { WsConnectedSignal, WsDataSignal, WsDisconnectedSignal, WsInvalidSignal, } from './WsMessages.js';
+import { frameByteLength, normalizeInbound, } from './types.js';
+export class WebSocketConnectionActor extends Actor {
+    d;
+    connection = null;
+    closed = false;
+    disconnectReported = false;
+    closeInfo = null;
+    constructor(deps) {
+        super();
+        this.d = deps;
+    }
+    preStart() {
+        const conn = new WsConnectionImpl(this.d.id, this.d.upgrade, this.d.socket, this.self, this.system.name);
+        this.connection = conn;
+        // Tell the hub 'connected' BEFORE attaching listeners, so it is
+        // mailbox-ordered before any inbound data flushed by setListeners.
+        this.d.hub.tell(new WsConnectedSignal(conn), conn);
+        this.d.socket.setListeners({
+            onMessage: (data) => this.handleInbound(data),
+            onClose: (code, reason) => this.handleClose(code, reason),
+            onError: (err) => this.log.warn(`WebSocketConnectionActor ${this.d.id}: socket error: ${err.message}`),
+        });
+    }
+    onReceive(cmd) {
+        if (this.closed) {
+            this.log.debug(`WebSocketConnectionActor ${this.d.id}: command after close — ignored`);
+            return;
+        }
+        switch (cmd._cmd) {
+            case 'out': {
+                let frame;
+                try {
+                    frame = this.d.codec.encode(cmd.msg);
+                }
+                catch (err) {
+                    this.log.error(`WebSocketConnectionActor ${this.d.id}: encode failed, dropping message: ${err.message}`);
+                    return;
+                }
+                this.write(frame);
+                break;
+            }
+            case 'out-raw':
+                this.write(cmd.frame);
+                break;
+            case 'close':
+                this.closeSocket(cmd.code, cmd.reason);
+                break;
+        }
+    }
+    postStop() {
+        // Report the disconnect to the hub exactly once — covers normal
+        // close (info set by handleClose), hub-initiated close, and crashes
+        // (framework stops the actor → postStop runs → synthetic info).
+        if (this.connection && !this.disconnectReported) {
+            this.disconnectReported = true;
+            const info = this.closeInfo ?? { code: 1011, reason: '', initiatedBy: 'error' };
+            this.d.hub.tell(new WsDisconnectedSignal(this.connection, info), this.connection);
+        }
+        if (!this.closed) {
+            this.closed = true;
+            try {
+                this.d.socket.close();
+            }
+            catch { /* already closed */ }
+        }
+    }
+    /* ------------------------------ inbound ------------------------------- */
+    handleInbound(data) {
+        const frame = normalizeInbound(data);
+        if (!frame) {
+            this.log.warn(`WebSocketConnectionActor ${this.d.id}: unrecognised inbound frame type — dropped`);
+            return;
+        }
+        if (frameByteLength(frame) > this.d.policy.maxFrameBytes) {
+            if (this.d.policy.onOversizeFrame === 'close') {
+                this.closeSocket(1009, 'message too big');
+            }
+            else {
+                this.log.warn(`WebSocketConnectionActor ${this.d.id}: dropped oversize inbound frame (> ${this.d.policy.maxFrameBytes} bytes)`);
+            }
+            return;
+        }
+        let decoded;
+        try {
+            decoded = this.d.codec.decode(frame);
+        }
+        catch (err) {
+            const decodeErr = err instanceof WsDecodeError ? err : new WsDecodeError(String(err), frame);
+            if (this.d.policy.onInvalidMessage === 'close') {
+                this.closeSocket(1003, 'unsupported data');
+            }
+            else if (this.d.policy.onInvalidMessage === 'hook') {
+                this.d.hub.tell(new WsInvalidSignal(this.connection, decodeErr), this.connection);
+            }
+            else {
+                this.log.warn(`WebSocketConnectionActor ${this.d.id}: invalid inbound message — dropped: ${decodeErr.message}`);
+            }
+            return;
+        }
+        this.d.hub.tell(new WsDataSignal(this.connection, decoded), this.connection);
+    }
+    handleClose(code, reason) {
+        if (this.closed)
+            return;
+        this.closeInfo = { code, reason, initiatedBy: 'client' };
+        this.context.stopSelf();
+    }
+    /* ------------------------------ outbound ------------------------------ */
+    write(frame) {
+        if (this.d.socket.readyState !== WsReadyState.OPEN) {
+            this.log.debug(`WebSocketConnectionActor ${this.d.id}: write on non-open socket — dropped`);
+            return;
+        }
+        const buffered = this.d.socket.bufferedAmount?.();
+        if (buffered !== undefined && buffered > this.d.policy.maxBufferedBytes) {
+            if (this.d.policy.onBackpressure === 'close') {
+                this.log.warn(`WebSocketConnectionActor ${this.d.id}: send buffer ${buffered} > ${this.d.policy.maxBufferedBytes} — closing`);
+                this.closeSocket(1013, 'try again later');
+            }
+            else {
+                this.log.warn(`WebSocketConnectionActor ${this.d.id}: send buffer ${buffered} > ${this.d.policy.maxBufferedBytes} — dropping frame`);
+            }
+            return;
+        }
+        try {
+            this.d.socket.send(frame.data);
+        }
+        catch (err) {
+            this.log.warn(`WebSocketConnectionActor ${this.d.id}: send failed: ${err.message}`);
+        }
+    }
+    closeSocket(code, reason) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.closeInfo === null)
+            this.closeInfo = { code, reason, initiatedBy: 'server' };
+        try {
+            this.d.socket.close(code, reason);
+        }
+        catch { /* already closed */ }
+        this.context.stopSelf();
+    }
+}
+//# sourceMappingURL=WebSocketConnectionActor.js.map

package/dist/http/ws/WebSocketConnectionActor.js.map

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

package/dist/http/ws/WebSocketRoute.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `websocket()` routing directive — the one-liner that turns a
+ * {@link WebSocketServerActor} into a WebSocket endpoint on the HTTP
+ * server, composable with `path()` / `concat()` / `withMiddleware()`
+ * exactly like `get()` / `post()`.
+ *
+ *     const server = system.spawn(Props.create(() => new PingServer()), 'ping');
+ *     await http.newServerAt('0.0.0.0', 8080).bind(websocket('/ws', server));
+ *
+ * Middleware wrapping the route runs once, against the HTTP upgrade
+ * request, so `BearerTokenAuth` / `IpAllowlist` gate the handshake.
+ */
+import { type Route } from '../Route.js';
+import type { WsServerRef } from './WsMessages.js';
+import type { WebSocketRouteOptions } from './WebSocketRouteOptions.js';
+/** `websocket(target)` — mount at the enclosing path. */
+export declare function websocket<TOut, TIn, TSelf = never>(target: WsServerRef<TOut, TIn, TSelf>, options?: WebSocketRouteOptions<TOut, TIn>): Route;
+/** `websocket('/ws', target)` — sugar for `path('/ws', websocket(target))`. */
+export declare function websocket<TOut, TIn, TSelf = never>(routePath: string, target: WsServerRef<TOut, TIn, TSelf>, options?: WebSocketRouteOptions<TOut, TIn>): Route;
+//# sourceMappingURL=WebSocketRoute.d.ts.map

package/dist/http/ws/WebSocketRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketRoute.d.ts","sourceRoot":"","sources":["../../../src/http/ws/WebSocketRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAQ,KAAK,KAAK,EAAgC,MAAM,aAAa,CAAC;AAG7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,KAAK,EAAE,qBAAqB,EAA6B,MAAM,4BAA4B,CAAC;AAEnG,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,EAChD,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EACrC,OAAO,CAAC,EAAE,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,GACzC,KAAK,CAAC;AACT,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,EAChD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EACrC,OAAO,CAAC,EAAE,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,GACzC,KAAK,CAAC"}

package/dist/http/ws/WebSocketRoute.js

@@ -0,0 +1,44 @@
+/**
+ * The `websocket()` routing directive — the one-liner that turns a
+ * {@link WebSocketServerActor} into a WebSocket endpoint on the HTTP
+ * server, composable with `path()` / `concat()` / `withMiddleware()`
+ * exactly like `get()` / `post()`.
+ *
+ *     const server = system.spawn(Props.create(() => new PingServer()), 'ping');
+ *     await http.newServerAt('0.0.0.0', 8080).bind(websocket('/ws', server));
+ *
+ * Middleware wrapping the route runs once, against the HTTP upgrade
+ * request, so `BearerTokenAuth` / `IpAllowlist` gate the handshake.
+ */
+import { path } from '../Route.js';
+import { jsonCodec } from './WsCodec.js';
+import { wireConnection } from './ConnectionWiring.js';
+import { resolveWsPolicy, } from './WsPolicy.js';
+export function websocket(a, b, c) {
+    let segment;
+    let target;
+    let builder;
+    if (typeof a === 'string') {
+        segment = a;
+        target = b;
+        builder = c;
+    }
+    else {
+        segment = null;
+        target = a;
+        builder = b;
+    }
+    const options = (builder ?? {});
+    const codec = options.codec ?? jsonCodec();
+    // Policy needs the ActorSystem's config, only available at connect
+    // time; resolve once (route options > HOCON > defaults) and memoise.
+    let policy = null;
+    const connect = (system, req, socket) => {
+        if (policy === null)
+            policy = resolveWsPolicy(system, options);
+        wireConnection(system, target, req, socket, codec, policy);
+    };
+    const node = { kind: 'websocket', connect };
+    return segment === null ? node : path(segment, node);
+}
+//# sourceMappingURL=WebSocketRoute.js.map

package/dist/http/ws/WebSocketRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketRoute.js","sourceRoot":"","sources":["../../../src/http/ws/WebSocketRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,IAAI,EAA4C,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAgB,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EACL,eAAe,GAEhB,MAAM,eAAe,CAAC;AAcvB,MAAM,UAAU,SAAS,CACvB,CAAyC,EACzC,CAAoE,EACpE,CAAoC;IAEpC,IAAI,OAAsB,CAAC;IAC3B,IAAI,MAAqC,CAAC;IAC1C,IAAI,OAAqD,CAAC;IAC1D,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,GAAG,CAAC,CAAC;QACZ,MAAM,GAAG,CAAkC,CAAC;QAC5C,OAAO,GAAG,CAAC,CAAC;IACd,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,GAAG,CAAC,CAAC;QACX,OAAO,GAAG,CAAiD,CAAC;IAC9D,CAAC;IACD,MAAM,OAAO,GAA0C,CAAC,OAAO,IAAI,EAAE,CAA0C,CAAC;IAEhH,MAAM,KAAK,GAAuB,OAAO,CAAC,KAAK,IAAI,SAAS,EAAa,CAAC;IAC1E,mEAAmE;IACnE,qEAAqE;IACrE,IAAI,MAAM,GAA4B,IAAI,CAAC;IAE3C,MAAM,OAAO,GAA4B,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;QAC/D,IAAI,MAAM,KAAK,IAAI;YAAE,MAAM,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/D,cAAc,CAAmB,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/E,CAAC,CAAC;IAEF,MAAM,IAAI,GAAU,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IACnD,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/http/ws/WebSocketRouteOptions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * All `websocket()`-route option-relevant types live here:
+ *
+ *   - {@link WebSocketRouteOptionsType} — the plain settings-object shape
+ *     (what you may also pass as a bare `{ … }` object).
+ *   - {@link WebSocketRouteOptionsBuilder} — the fluent builder
+ *     (`WebSocketRouteOptions.create()…`).
+ *   - {@link WebSocketRouteOptions} — the accepted-input **union**
+ *     (`WebSocketRouteOptionsBuilder | WebSocketRouteOptionsType`), plus a
+ *     value alias to the builder so `WebSocketRouteOptions.create()` /
+ *     `new WebSocketRouteOptions()` keep working.
+ *
+ *     const wsOptions = WebSocketRouteOptions.create().withCodec(rawCodec());
+ *     websocket('/ws', ingress, wsOptions);
+ *
+ * The builder records only the fields you set (as own enumerable props), so it
+ * reads/spreads exactly like a plain object; it feeds the same per-route
+ * resolution (route options > HOCON `actor-ts.http.websocket` > defaults) —
+ * unset fields fall through to HOCON.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import type { WsCodec } from './WsCodec.js';
+import type { BackpressurePolicy, InvalidMessagePolicy, OversizeFramePolicy, WebSocketPolicyOptions } from './WsPolicy.js';
+/** The settings a `websocket()` route may carry — codec + per-connection policy. */
+export interface WebSocketRouteOptionsType<TOut, TIn> extends WebSocketPolicyOptions {
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    readonly codec?: WsCodec<TOut, TIn>;
+}
+/** Fluent builder for {@link WebSocketRouteOptionsType}. */
+export declare class WebSocketRouteOptionsBuilder<TOut = unknown, TIn = unknown> extends OptionsBuilder<WebSocketRouteOptionsType<TOut, TIn>> {
+    /** Start a fresh builder.  Equivalent to `new WebSocketRouteOptionsBuilder()`. */
+    static create<TOut = unknown, TIn = unknown>(): WebSocketRouteOptionsBuilder<TOut, TIn>;
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    withCodec(codec: WsCodec<TOut, TIn>): this;
+    /** Inbound frame size cap in bytes.  Default 1 MiB. */
+    withMaxFrameBytes(bytes: number): this;
+    /** What to do with an inbound frame exceeding `maxFrameBytes`.  Default 'close'. */
+    withOnOversizeFrame(policy: OversizeFramePolicy): this;
+    /** What to do with an inbound frame the codec can't decode.  Default 'close'. */
+    withOnInvalidMessage(policy: InvalidMessagePolicy): this;
+    /** Outbound buffer cap in bytes before backpressure kicks in.  Default 4 MiB. */
+    withMaxBufferedBytes(bytes: number): this;
+    /** What to do when a slow consumer overflows the buffer.  Default 'drop'. */
+    withOnBackpressure(policy: BackpressurePolicy): this;
+}
+/**
+ * Accepted input for a `websocket()` route's options: the fluent
+ * {@link WebSocketRouteOptionsBuilder} OR a plain
+ * {@link WebSocketRouteOptionsType} object.
+ */
+export type WebSocketRouteOptions<TOut = unknown, TIn = unknown> = WebSocketRouteOptionsBuilder<TOut, TIn> | Partial<WebSocketRouteOptionsType<TOut, TIn>>;
+/** Value alias so `WebSocketRouteOptions.create()` / `new WebSocketRouteOptions()` resolve to the builder. */
+export declare const WebSocketRouteOptions: typeof WebSocketRouteOptionsBuilder;
+//# sourceMappingURL=WebSocketRouteOptions.d.ts.map

package/dist/http/ws/WebSocketRouteOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketRouteOptions.d.ts","sourceRoot":"","sources":["../../../src/http/ws/WebSocketRouteOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,eAAe,CAAC;AAEvB,oFAAoF;AACpF,MAAM,WAAW,yBAAyB,CAAC,IAAI,EAAE,GAAG,CAAE,SAAQ,sBAAsB;IAClF,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;CACrC;AAED,4DAA4D;AAC5D,qBAAa,4BAA4B,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,CACrE,SAAQ,cAAc,CAAC,yBAAyB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5D,kFAAkF;IAClF,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,KAAK,4BAA4B,CAAC,IAAI,EAAE,GAAG,CAAC;IAIvF,sDAAsD;IACtD,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI;IAI1C,uDAAuD;IACvD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAItC,oFAAoF;IACpF,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAItD,iFAAiF;IACjF,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAIxD,iFAAiF;IACjF,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,6EAA6E;IAC7E,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;CAGrD;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,IAC3D,4BAA4B,CAAC,IAAI,EAAE,GAAG,CAAC,GACvC,OAAO,CAAC,yBAAyB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AAClD,8GAA8G;AAC9G,eAAO,MAAM,qBAAqB,qCAA+B,CAAC"}

package/dist/http/ws/WebSocketRouteOptions.js

@@ -0,0 +1,55 @@
+/**
+ * All `websocket()`-route option-relevant types live here:
+ *
+ *   - {@link WebSocketRouteOptionsType} — the plain settings-object shape
+ *     (what you may also pass as a bare `{ … }` object).
+ *   - {@link WebSocketRouteOptionsBuilder} — the fluent builder
+ *     (`WebSocketRouteOptions.create()…`).
+ *   - {@link WebSocketRouteOptions} — the accepted-input **union**
+ *     (`WebSocketRouteOptionsBuilder | WebSocketRouteOptionsType`), plus a
+ *     value alias to the builder so `WebSocketRouteOptions.create()` /
+ *     `new WebSocketRouteOptions()` keep working.
+ *
+ *     const wsOptions = WebSocketRouteOptions.create().withCodec(rawCodec());
+ *     websocket('/ws', ingress, wsOptions);
+ *
+ * The builder records only the fields you set (as own enumerable props), so it
+ * reads/spreads exactly like a plain object; it feeds the same per-route
+ * resolution (route options > HOCON `actor-ts.http.websocket` > defaults) —
+ * unset fields fall through to HOCON.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/** Fluent builder for {@link WebSocketRouteOptionsType}. */
+export class WebSocketRouteOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new WebSocketRouteOptionsBuilder()`. */
+    static create() {
+        return new WebSocketRouteOptionsBuilder();
+    }
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    withCodec(codec) {
+        return this.set('codec', codec);
+    }
+    /** Inbound frame size cap in bytes.  Default 1 MiB. */
+    withMaxFrameBytes(bytes) {
+        return this.set('maxFrameBytes', bytes);
+    }
+    /** What to do with an inbound frame exceeding `maxFrameBytes`.  Default 'close'. */
+    withOnOversizeFrame(policy) {
+        return this.set('onOversizeFrame', policy);
+    }
+    /** What to do with an inbound frame the codec can't decode.  Default 'close'. */
+    withOnInvalidMessage(policy) {
+        return this.set('onInvalidMessage', policy);
+    }
+    /** Outbound buffer cap in bytes before backpressure kicks in.  Default 4 MiB. */
+    withMaxBufferedBytes(bytes) {
+        return this.set('maxBufferedBytes', bytes);
+    }
+    /** What to do when a slow consumer overflows the buffer.  Default 'drop'. */
+    withOnBackpressure(policy) {
+        return this.set('onBackpressure', policy);
+    }
+}
+/** Value alias so `WebSocketRouteOptions.create()` / `new WebSocketRouteOptions()` resolve to the builder. */
+export const WebSocketRouteOptions = WebSocketRouteOptionsBuilder;
+//# sourceMappingURL=WebSocketRouteOptions.js.map

package/dist/http/ws/WebSocketRouteOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketRouteOptions.js","sourceRoot":"","sources":["../../../src/http/ws/WebSocketRouteOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAe9D,4DAA4D;AAC5D,MAAM,OAAO,4BACX,SAAQ,cAAoD;IAC5D,kFAAkF;IAClF,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,4BAA4B,EAAa,CAAC;IACvD,CAAC;IAED,sDAAsD;IACtD,SAAS,CAAC,KAAyB;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,uDAAuD;IACvD,iBAAiB,CAAC,KAAa;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,oFAAoF;IACpF,mBAAmB,CAAC,MAA2B;QAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,iFAAiF;IACjF,oBAAoB,CAAC,MAA4B;QAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,iFAAiF;IACjF,oBAAoB,CAAC,KAAa;QAChC,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,6EAA6E;IAC7E,kBAAkB,CAAC,MAA0B;QAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;CACF;AAUD,8GAA8G;AAC9G,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAC"}