actor-ts 0.9.1 → 0.11.0

package/dist/http/websocket/WebsocketPolicy.js

@@ -0,0 +1,70 @@
+import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+import { DEFAULT_WEBSOCKET_MAX_FRAME_BYTES } from './types.js';
+export const DEFAULT_WEBSOCKET_POLICY = {
+    maxFrameBytes: DEFAULT_WEBSOCKET_MAX_FRAME_BYTES,
+    onOversizeFrame: 'close',
+    onInvalidMessage: 'close',
+    maxBufferedBytes: 4 * 1024 * 1024,
+    onBackpressure: 'drop',
+    maxConnections: Infinity,
+};
+/**
+ * Validates the per-connection policy knobs — from any path (route options,
+ * HOCON, defaults) since it runs on the fully-resolved policy.  Rejections
+ * throw `OptionsError`, replacing the earlier HOCON-only bare-`Error` enum
+ * guard.  `maxConnections` admits `Infinity` (the unlimited default), which
+ * the generic `positiveInt` helper rejects, so its rule is bespoke.
+ */
+export class WebsocketPolicyOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('WebsocketPolicyOptions');
+    }
+    rules(s) {
+        this.positiveInt('maxFrameBytes');
+        this.positiveInt('maxBufferedBytes');
+        this.oneOf('onOversizeFrame', ['close', 'drop']);
+        this.oneOf('onInvalidMessage', ['close', 'drop', 'hook']);
+        this.oneOf('onBackpressure', ['drop', 'close']);
+        const { maxConnections } = s;
+        if (maxConnections !== undefined && maxConnections !== Infinity &&
+            (typeof maxConnections !== 'number' || !Number.isInteger(maxConnections) || maxConnections < 1)) {
+            this.fail('maxConnections', 'must be a positive integer or Infinity', maxConnections);
+        }
+    }
+}
+/** Merge built-in defaults, HOCON server defaults, and per-route options. */
+export function resolveWebsocketPolicy(system, options) {
+    let base = DEFAULT_WEBSOCKET_POLICY;
+    const key = ConfigKeys.http.websocket;
+    if (system.config.hasPath(key)) {
+        const config = system.config.getConfig(key);
+        // Read HOCON leaves as-is (a bad enum flows through as a plain string and
+        // is caught below by the validator as an OptionsError, not a bare Error).
+        base = {
+            maxFrameBytes: config.hasPath('maxFrameBytes') ? config.getBytes('maxFrameBytes') : base.maxFrameBytes,
+            onOversizeFrame: config.hasPath('onOversizeFrame')
+                ? config.getString('onOversizeFrame')
+                : base.onOversizeFrame,
+            onInvalidMessage: config.hasPath('onInvalidMessage')
+                ? config.getString('onInvalidMessage')
+                : base.onInvalidMessage,
+            maxBufferedBytes: config.hasPath('maxBufferedBytes') ? config.getBytes('maxBufferedBytes') : base.maxBufferedBytes,
+            onBackpressure: config.hasPath('onBackpressure')
+                ? config.getString('onBackpressure')
+                : base.onBackpressure,
+            maxConnections: config.hasPath('maxConnections') ? config.getInt('maxConnections') : base.maxConnections,
+        };
+    }
+    const resolved = {
+        maxFrameBytes: options.maxFrameBytes ?? base.maxFrameBytes,
+        onOversizeFrame: options.onOversizeFrame ?? base.onOversizeFrame,
+        onInvalidMessage: options.onInvalidMessage ?? base.onInvalidMessage,
+        maxBufferedBytes: options.maxBufferedBytes ?? base.maxBufferedBytes,
+        onBackpressure: options.onBackpressure ?? base.onBackpressure,
+        maxConnections: options.maxConnections ?? base.maxConnections,
+    };
+    new WebsocketPolicyOptionsValidator().validate(resolved);
+    return resolved;
+}
+//# sourceMappingURL=WebsocketPolicy.js.map

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

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

package/dist/http/websocket/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 { WebsocketServerRef } from './WebsocketMessages.js';
+import type { WebsocketRouteOptions } from './WebsocketRouteOptions.js';
+/** `websocket(target)` — mount at the enclosing path. */
+export declare function websocket<TOut, TIn, TSelf = never>(target: WebsocketServerRef<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: WebsocketServerRef<TOut, TIn, TSelf>, options?: WebsocketRouteOptions<TOut, TIn>): Route;
+//# sourceMappingURL=WebsocketRoute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketRoute.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAQ,KAAK,KAAK,EAAgC,MAAM,aAAa,CAAC;AAI7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAMjE,OAAO,KAAK,EAAE,qBAAqB,EAA6B,MAAM,4BAA4B,CAAC;AAEnG,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,EAChD,MAAM,EAAE,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC5C,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,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC5C,OAAO,CAAC,EAAE,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,GACzC,KAAK,CAAC"}

package/dist/http/websocket/WebsocketRoute.js

@@ -0,0 +1,72 @@
+/**
+ * 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 { Status } from '../types.js';
+import { jsonCodec } from './WebsocketCodec.js';
+import { wireConnection } from './ConnectionWiring.js';
+import { resolveWebsocketPolicy, } from './WebsocketPolicy.js';
+import { WebsocketRouteOptionsValidator } from './WebsocketRouteOptions.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 ?? {});
+    new WebsocketRouteOptionsValidator().validate(options);
+    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 = resolveWebsocketPolicy(system, options);
+        wireConnection(system, target, req, socket, codec, policy);
+    };
+    // CSWSH defence — an Origin allowlist folds into the route's innermost
+    // upgrade `authorize`, which every backend runs before the handshake.
+    const originGuard = makeOriginGuard(options.allowedOrigins);
+    const node = originGuard
+        ? { kind: 'websocket', connect, authorize: originGuard }
+        : { kind: 'websocket', connect };
+    return segment === null ? node : path(segment, node);
+}
+/**
+ * Build an Origin-allowlist guard for the upgrade handshake, or `undefined`
+ * when no origins are configured.  See
+ * {@link WebsocketRouteOptionsType.allowedOrigins} and security audit WS-2.
+ */
+function makeOriginGuard(allowedOrigins) {
+    if (!allowedOrigins || allowedOrigins.length === 0)
+        return undefined;
+    const allow = new Set(allowedOrigins.map((o) => o.toLowerCase()));
+    return (req) => {
+        const origin = req.headers['origin'];
+        // Missing Origin → non-browser client (native WS / server-to-server);
+        // CSWSH can't apply, so allow.  Present-but-unlisted → reject.
+        if (origin === undefined)
+            return null;
+        if (allow.has(origin.toLowerCase()))
+            return null;
+        return { status: Status.Forbidden, body: { error: `websocket origin not allowed: ${origin}` } };
+    };
+}
+//# sourceMappingURL=WebsocketRoute.js.map

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

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

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

@@ -0,0 +1,91 @@
+/**
+ * All `websocket()`-route option-relevant types live here:
+ *
+ *   - {@link WebsocketRouteOptionsType} — the plain options-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 websocketOptions = WebsocketRouteOptions.create().withCodec(rawCodec());
+ *     websocket('/ws', ingress, websocketOptions);
+ *
+ * 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 { OptionsValidator } from '../../util/OptionsValidator.js';
+import type { WebsocketCodec } from './WebsocketCodec.js';
+import type { BackpressurePolicy, InvalidMessagePolicy, OversizeFramePolicy, WebsocketPolicyOptions } from './WebsocketPolicy.js';
+/** The options a `websocket()` route may carry — codec + per-connection policy. */
+export interface WebsocketRouteOptionsType<TOut, TIn> extends WebsocketPolicyOptions {
+    /** Wire codec.  Default: `jsonCodec<TOut, TIn>()`. */
+    readonly codec?: WebsocketCodec<TOut, TIn>;
+    /**
+     * Allowed browser `Origin`s for the upgrade handshake — the defence
+     * against Cross-Site WebSocket Hijacking (CSWSH).  When set, an upgrade
+     * whose `Origin` header is present but not in this list is rejected with
+     * 403.  A **missing** `Origin` (non-browser client: native WebSocket,
+     * server-to-server) is allowed — CSWSH rides a victim browser's ambient
+     * cookie/session credentials, so a request without an Origin can't be
+     * that attack.  Comparison is case-insensitive.  Unset → no origin check.
+     *
+     * Bearer-token auth is already resistant (browsers can't set the
+     * `Authorization` header on a WS handshake); set this when the route's
+     * auth is ambient (cookie / `IpAllowlist`).
+     */
+    readonly allowedOrigins?: ReadonlyArray<string>;
+}
+/** 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: WebsocketCodec<TOut, TIn>): this;
+    /**
+     * Restrict the upgrade to these browser origins (CSWSH defence).  A
+     * present-but-unlisted `Origin` gets 403; a missing `Origin` (non-browser
+     * client) is allowed.  Case-insensitive.
+     */
+    withAllowedOrigins(origins: ReadonlyArray<string>): 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;
+    /**
+     * Cap concurrent connections for this route.  A new upgrade beyond the cap
+     * is closed with 1013 ("try again later") before it is wired up
+     * (security audit WS-5).  Default: unlimited.
+     */
+    withMaxConnections(max: number): this;
+}
+/**
+ * Validates the route-only option fields.  The per-connection policy knobs
+ * (frame / buffer caps, enums, `maxConnections`) are validated separately, on
+ * the resolved policy, by `WebsocketPolicyOptionsValidator` — this validator
+ * covers what does not go through policy resolution: `allowedOrigins`.
+ */
+export declare class WebsocketRouteOptionsValidator<TOut = unknown, TIn = unknown> extends OptionsValidator<WebsocketRouteOptionsType<TOut, TIn>> {
+    constructor();
+    protected rules(s: Partial<WebsocketRouteOptionsType<TOut, TIn>>): void;
+}
+/**
+ * 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/websocket/WebsocketRouteOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketRouteOptions.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketRouteOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,mFAAmF;AACnF,MAAM,WAAW,yBAAyB,CAAC,IAAI,EAAE,GAAG,CAAE,SAAQ,sBAAsB;IAClF,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACjD;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,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI;IAIjD;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI;IAIxD,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;IAIpD;;;;OAIG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGtC;AAED;;;;;GAKG;AACH,qBAAa,8BAA8B,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,CACvE,SAAQ,gBAAgB,CAAC,yBAAyB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;;IAI9D,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI;CAWxE;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/websocket/WebsocketRouteOptions.js

@@ -0,0 +1,92 @@
+/**
+ * All `websocket()`-route option-relevant types live here:
+ *
+ *   - {@link WebsocketRouteOptionsType} — the plain options-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 websocketOptions = WebsocketRouteOptions.create().withCodec(rawCodec());
+ *     websocket('/ws', ingress, websocketOptions);
+ *
+ * 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 { OptionsValidator } from '../../util/OptionsValidator.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);
+    }
+    /**
+     * Restrict the upgrade to these browser origins (CSWSH defence).  A
+     * present-but-unlisted `Origin` gets 403; a missing `Origin` (non-browser
+     * client) is allowed.  Case-insensitive.
+     */
+    withAllowedOrigins(origins) {
+        return this.set('allowedOrigins', origins);
+    }
+    /** 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);
+    }
+    /**
+     * Cap concurrent connections for this route.  A new upgrade beyond the cap
+     * is closed with 1013 ("try again later") before it is wired up
+     * (security audit WS-5).  Default: unlimited.
+     */
+    withMaxConnections(max) {
+        return this.set('maxConnections', max);
+    }
+}
+/**
+ * Validates the route-only option fields.  The per-connection policy knobs
+ * (frame / buffer caps, enums, `maxConnections`) are validated separately, on
+ * the resolved policy, by `WebsocketPolicyOptionsValidator` — this validator
+ * covers what does not go through policy resolution: `allowedOrigins`.
+ */
+export class WebsocketRouteOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('WebsocketRouteOptions');
+    }
+    rules(s) {
+        const { allowedOrigins } = s;
+        // An empty array means "no guard" (allow all) — permitted; only entries
+        // must be plausible: a non-array or an empty / non-string entry is a bug.
+        if (allowedOrigins !== undefined &&
+            (!Array.isArray(allowedOrigins) || allowedOrigins.some((origin) => typeof origin !== 'string' || origin.length === 0))) {
+            this.fail('allowedOrigins', 'must be an array of non-empty origin strings', allowedOrigins);
+        }
+    }
+}
+/** Value alias so `WebsocketRouteOptions.create()` / `new WebsocketRouteOptions()` resolve to the builder. */
+export const WebsocketRouteOptions = WebsocketRouteOptionsBuilder;
+//# sourceMappingURL=WebsocketRouteOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketRouteOptions.js","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketRouteOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AA6BlE,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,KAAgC;QACxC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,OAA8B;QAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC7C,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;IAED;;;;OAIG;IACH,kBAAkB,CAAC,GAAW;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,8BACX,SAAQ,gBAAsD;IAC9D;QACE,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACjC,CAAC;IACS,KAAK,CAAC,CAAgD;QAC9D,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;QAC7B,wEAAwE;QACxE,0EAA0E;QAC1E,IACE,cAAc,KAAK,SAAS;YAC5B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,EACtH,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,8CAA8C,EAAE,cAAc,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;CACF;AAUD,8GAA8G;AAC9G,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAC"}

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

@@ -0,0 +1,65 @@
+/**
+ * Base class for a WebSocket server hub — the actor you bind a route to
+ * with `websocket(path, ref)`.  ONE hub handles every connection on the
+ * route; the framework spawns an internal session actor per connection
+ * behind the scenes (you never manage those).
+ *
+ *     type In  = { kind: 'ping'; n: number };
+ *     type Out = { kind: 'pong'; n: number };
+ *
+ *     class PingServer extends WebsocketServerActor<Out, In> {
+ *       onMessage(msg: In): void {
+ *         this.reply({ kind: 'pong', n: msg.n });   // → the sending connection
+ *       }
+ *     }
+ *
+ * `TOut` (what you send) comes first, then `TIn` (what you receive), to
+ * match the `websocket()` / client generic order.  `TSelf` (default
+ * `never`) is for app-level messages other actors `tell` this hub.
+ *
+ * You override `onMessage` (required) and optionally the lifecycle
+ * hooks.  Do NOT override `onReceive` — it is the sealed dispatcher that
+ * turns mailbox envelopes into these calls.  Per connection you observe
+ * exactly: `onClientConnected` → zero+ `onMessage` (in frame order) →
+ * `onClientDisconnected`, all serialised through this one actor.
+ */
+import { Actor } from '../../Actor.js';
+import { type SupervisorStrategy } from '../../Supervision.js';
+import type { WebsocketDecodeError } from './WebsocketCodec.js';
+import type { WebsocketConnection } from './WebsocketConnection.js';
+import type { WebsocketServerMessage } from './WebsocketMessages.js';
+import type { WebsocketCloseInfo } from './types.js';
+export declare abstract class WebsocketServerActor<TOut, TIn, TSelf = never> extends Actor<WebsocketServerMessage<TOut, TIn, TSelf>> {
+    private readonly _clients;
+    private _current;
+    /** Handle one decoded client message.  `this.connection` / `this.sender` = the sender. */
+    abstract onMessage(msg: TIn): void | Promise<void>;
+    /** A client completed the upgrade.  Ordered before its first `onMessage`. */
+    protected onClientConnected(_client: WebsocketConnection<TOut>): void | Promise<void>;
+    /** A client went away.  Ordered after its last `onMessage`; then it leaves `clients`. */
+    protected onClientDisconnected(_client: WebsocketConnection<TOut>, _info: WebsocketCloseInfo): void | Promise<void>;
+    /** A frame failed to decode.  Only called when the route policy is `'hook'`. */
+    protected onInvalidMessage(_client: WebsocketConnection<TOut>, _error: WebsocketDecodeError): void | Promise<void>;
+    /** App-level message told to this hub's ref (reachable only when `TSelf` ≠ `never`). */
+    protected onSelfMessage(msg: TSelf): void | Promise<void>;
+    /** The connection whose event is being processed.  Throws outside a hook / onMessage. */
+    protected get connection(): WebsocketConnection<TOut>;
+    /** Reply to the current connection.  Sugar for `this.connection.tell(msg)`. */
+    protected reply(msg: TOut): void;
+    /** Send to every open connection (optionally filtered). */
+    protected broadcast(msg: TOut, filter?: (c: WebsocketConnection<TOut>) => boolean): void;
+    /** Live connections, keyed by connection id. */
+    protected get clients(): ReadonlyMap<string, WebsocketConnection<TOut>>;
+    /** Close every connection. */
+    protected closeAll(code?: number, reason?: string): void;
+    /**
+     * Supervision for the per-connection child actors: stop a crashed
+     * connection (its `postStop` still reports the disconnect) rather than
+     * restart it into a dead socket.  Override on your subclass only if you
+     * really mean to change how connection failures are handled.
+     */
+    supervisorStrategy(): SupervisorStrategy;
+    /** @internal Sealed — do not override; override `onMessage` + hooks instead. */
+    onReceive(msg: WebsocketServerMessage<TOut, TIn, TSelf>): Promise<void>;
+}
+//# sourceMappingURL=WebsocketServerActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketServerActor.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/WebsocketServerActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAMV,sBAAsB,EACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,8BAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,CACjE,SAAQ,KAAK,CAAC,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAEvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAA0C;IAI1D,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD,6EAA6E;IAC7E,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAErF,yFAAyF;IACzF,SAAS,CAAC,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnH,gFAAgF;IAChF,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElH,wFAAwF;IACxF,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzD,yFAAyF;IACzF,SAAS,KAAK,UAAU,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAKpD;IAED,+EAA+E;IAC/E,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI;IAIhC,2DAA2D;IAC3D,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,OAAO,GAAG,IAAI;IAMxF,gDAAgD;IAChD,SAAS,KAAK,OAAO,IAAI,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAEtE;IAED,8BAA8B;IAC9B,SAAS,CAAC,QAAQ,CAAC,IAAI,SAAO,EAAE,MAAM,SAAK,GAAG,IAAI;IAMlD;;;;;OAKG;IACM,kBAAkB,IAAI,kBAAkB;IAIjD,gFAAgF;IACjE,SAAS,CAAC,GAAG,EAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAwDvF"}

package/dist/http/websocket/WebsocketServerActor.js

@@ -0,0 +1,141 @@
+/**
+ * Base class for a WebSocket server hub — the actor you bind a route to
+ * with `websocket(path, ref)`.  ONE hub handles every connection on the
+ * route; the framework spawns an internal session actor per connection
+ * behind the scenes (you never manage those).
+ *
+ *     type In  = { kind: 'ping'; n: number };
+ *     type Out = { kind: 'pong'; n: number };
+ *
+ *     class PingServer extends WebsocketServerActor<Out, In> {
+ *       onMessage(msg: In): void {
+ *         this.reply({ kind: 'pong', n: msg.n });   // → the sending connection
+ *       }
+ *     }
+ *
+ * `TOut` (what you send) comes first, then `TIn` (what you receive), to
+ * match the `websocket()` / client generic order.  `TSelf` (default
+ * `never`) is for app-level messages other actors `tell` this hub.
+ *
+ * You override `onMessage` (required) and optionally the lifecycle
+ * hooks.  Do NOT override `onReceive` — it is the sealed dispatcher that
+ * turns mailbox envelopes into these calls.  Per connection you observe
+ * exactly: `onClientConnected` → zero+ `onMessage` (in frame order) →
+ * `onClientDisconnected`, all serialised through this one actor.
+ */
+import { Actor } from '../../Actor.js';
+import { stoppingStrategy } from '../../Supervision.js';
+export class WebsocketServerActor extends Actor {
+    _clients = new Map();
+    _current = null;
+    /** A client completed the upgrade.  Ordered before its first `onMessage`. */
+    onClientConnected(_client) { }
+    /** A client went away.  Ordered after its last `onMessage`; then it leaves `clients`. */
+    onClientDisconnected(_client, _info) { }
+    /** A frame failed to decode.  Only called when the route policy is `'hook'`. */
+    onInvalidMessage(_client, _error) { }
+    /** App-level message told to this hub's ref (reachable only when `TSelf` ≠ `never`). */
+    onSelfMessage(msg) {
+        this.log.warn(`WebsocketServerActor: unhandled self message: ${String(msg)}`);
+    }
+    /* ----------------------- helpers ------------------------------- */
+    /** The connection whose event is being processed.  Throws outside a hook / onMessage. */
+    get connection() {
+        if (this._current === null) {
+            throw new Error('this.connection is only valid inside onMessage / onClient* hooks');
+        }
+        return this._current;
+    }
+    /** Reply to the current connection.  Sugar for `this.connection.tell(msg)`. */
+    reply(msg) {
+        this.connection.tell(msg);
+    }
+    /** Send to every open connection (optionally filtered). */
+    broadcast(msg, filter) {
+        for (const client of this._clients.values()) {
+            if (client.isOpen && (!filter || filter(client)))
+                client.tell(msg);
+        }
+    }
+    /** Live connections, keyed by connection id. */
+    get clients() {
+        return this._clients;
+    }
+    /** Close every connection. */
+    closeAll(code = 1000, reason = '') {
+        for (const client of this._clients.values())
+            client.close(code, reason);
+    }
+    /* ----------------------- sealed dispatch ----------------------- */
+    /**
+     * Supervision for the per-connection child actors: stop a crashed
+     * connection (its `postStop` still reports the disconnect) rather than
+     * restart it into a dead socket.  Override on your subclass only if you
+     * really mean to change how connection failures are handled.
+     */
+    supervisorStrategy() {
+        return stoppingStrategy;
+    }
+    /** @internal Sealed — do not override; override `onMessage` + hooks instead. */
+    async onReceive(msg) {
+        // Uniform `kind` dispatch over the accept command + lifecycle signals.
+        switch (msg.kind) {
+            case 'websocket-accept': {
+                // Spawn the per-connection actor as THIS actor's child, so the
+                // tree is server → conn-N and supervision/teardown are automatic.
+                const command = msg;
+                this.context.spawn(command.props, command.name);
+                return;
+            }
+            case 'websocket-connected': {
+                const signal = msg;
+                this._clients.set(signal.connection.id, signal.connection);
+                this._current = signal.connection;
+                try {
+                    await this.onClientConnected(signal.connection);
+                }
+                finally {
+                    this._current = null;
+                }
+                return;
+            }
+            case 'websocket-data': {
+                const signal = msg;
+                this._current = signal.connection;
+                try {
+                    await this.onMessage(signal.message);
+                }
+                finally {
+                    this._current = null;
+                }
+                return;
+            }
+            case 'websocket-disconnected': {
+                const signal = msg;
+                this._current = signal.connection;
+                try {
+                    await this.onClientDisconnected(signal.connection, signal.info);
+                }
+                finally {
+                    this._current = null;
+                    this._clients.delete(signal.connection.id);
+                }
+                return;
+            }
+            case 'websocket-invalid': {
+                const signal = msg;
+                this._current = signal.connection;
+                try {
+                    await this.onInvalidMessage(signal.connection, signal.error);
+                }
+                finally {
+                    this._current = null;
+                }
+                return;
+            }
+            default:
+                await this.onSelfMessage(msg);
+        }
+    }
+}
+//# sourceMappingURL=WebsocketServerActor.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * Public WebSocket API surface.  Internals (session actor, connection
+ * impl, wiring, socket adapter, message signals) are intentionally NOT
+ * re-exported — users interact only through `websocket()`,
+ * `WebsocketServerActor`, the `WebsocketConnection` handle, and the codecs.
+ */
+export { websocket } from './WebsocketRoute.js';
+export { WebsocketRouteOptions, WebsocketRouteOptionsBuilder, WebsocketRouteOptionsValidator } from './WebsocketRouteOptions.js';
+export type { WebsocketRouteOptionsType } from './WebsocketRouteOptions.js';
+export { WebsocketServerActor } from './WebsocketServerActor.js';
+export { WebsocketClientActor } from './WebsocketClientActor.js';
+export { WebsocketClientOptions, WebsocketClientOptionsBuilder, WebsocketClientOptionsValidator } from './WebsocketClientOptions.js';
+export type { WebsocketClientOptionsType } from './WebsocketClientOptions.js';
+export type { WebsocketConnection } from './WebsocketConnection.js';
+export { websocketSend } from './WebsocketMessages.js';
+export type { WebsocketServerMessage, WebsocketServerRef, WebsocketClientMessage } from './WebsocketMessages.js';
+export { jsonCodec, rawCodec, WebsocketDecodeError, WebsocketEncodeError, } from './WebsocketCodec.js';
+export type { WebsocketCodec } from './WebsocketCodec.js';
+export type { OversizeFramePolicy, InvalidMessagePolicy, BackpressurePolicy, } from './WebsocketPolicy.js';
+export { DEFAULT_WEBSOCKET_MAX_FRAME_BYTES, } from './types.js';
+export type { WebsocketFrame, WebsocketUpgradeInfo, WebsocketCloseInfo } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AACjI,YAAY,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAE5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,+BAA+B,EAAE,MAAM,6BAA6B,CAAC;AACrI,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAE9E,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEjH,OAAO,EACL,SAAS,EACT,QAAQ,EACR,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iCAAiC,GAClC,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}