actor-ts 0.9.0

package/dist/io/broker/SseActor.js

@@ -0,0 +1,129 @@
+import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { Lazy } from '../../util/Lazy.js';
+import { BrokerActor } from './BrokerActor.js';
+/**
+ * Server-Sent Events client actor.  Pure built-ins — uses `fetch`
+ * (Bun + Node 18+ + Deno all have it) and parses the wire format
+ * inline.  No outbound — SSE is unidirectional from server.
+ *
+ * The base class' reconnect machinery applies on stream close.
+ */
+export class SseActor extends BrokerActor {
+    aborter = null;
+    streamRunning = false;
+    constructor(settings = {}) { super(settings); }
+    configKey() { return ConfigKeys.io.broker.sse; }
+    builtInDefaults() { return {}; }
+    readSettingsFromConfig(c) {
+        const out = {};
+        if (c.hasPath('url'))
+            out.url = c.getString('url');
+        if (c.hasPath('headers')) {
+            const h = {};
+            for (const [k, v] of Object.entries(c.getObject('headers'))) {
+                if (typeof v === 'string')
+                    h[k] = v;
+            }
+            out.headers = h;
+        }
+        return out;
+    }
+    requiredSettings() { return ['url', 'target']; }
+    endpointLabel() { return this.settings.url ?? '<unknown>'; }
+    async connectImpl() {
+        this.aborter = new AbortController();
+        const fetchFn = await fetchLazy.get();
+        const res = await fetchFn(this.settings.url, {
+            method: 'GET',
+            headers: { Accept: 'text/event-stream', ...(this.settings.headers ?? {}) },
+            signal: this.aborter.signal,
+        });
+        if (!res.ok)
+            throw new Error(`SSE connect failed: HTTP ${res.status}`);
+        if (!res.body)
+            throw new Error('SSE connect: no response body');
+        this.streamRunning = true;
+        void this.consume(res.body);
+    }
+    async disconnectImpl() {
+        this.streamRunning = false;
+        try {
+            this.aborter?.abort();
+        }
+        catch { /* ignore */ }
+        this.aborter = null;
+    }
+    async dispatchOutgoing(_env) {
+        throw new Error('SseActor is read-only');
+    }
+    onReceive(_cmd) { }
+    /* ----------------------------- internals ----------------------------- */
+    async consume(stream) {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        try {
+            while (this.streamRunning) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let idx = buffer.indexOf('\n\n');
+                while (idx >= 0) {
+                    const block = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    const ev = parseEventBlock(block);
+                    if (ev && this.settings.target)
+                        this.settings.target.tell(ev);
+                    idx = buffer.indexOf('\n\n');
+                }
+            }
+        }
+        catch (e) {
+            if (this.streamRunning) {
+                this.handleConnectionLost(e instanceof Error ? e : new Error(String(e)));
+            }
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch { /* ignore */ }
+            if (this.streamRunning) {
+                this.handleConnectionLost(new Error('SSE stream ended'));
+            }
+        }
+    }
+}
+/* --------------------- inline SSE wire-format parser ------------------- */
+function parseEventBlock(block) {
+    let event = 'message';
+    let id;
+    const dataLines = [];
+    for (const raw of block.split('\n')) {
+        if (!raw || raw.startsWith(':'))
+            continue;
+        const colon = raw.indexOf(':');
+        const field = colon < 0 ? raw : raw.slice(0, colon);
+        let val = colon < 0 ? '' : raw.slice(colon + 1);
+        if (val.startsWith(' '))
+            val = val.slice(1);
+        if (field === 'event')
+            event = val;
+        else if (field === 'data')
+            dataLines.push(val);
+        else if (field === 'id')
+            id = val;
+    }
+    if (dataLines.length === 0)
+        return null;
+    return { event, data: dataLines.join('\n'), id };
+}
+const fetchLazy = Lazy.of(async () => {
+    const f = globalThis.fetch;
+    if (typeof f === 'function')
+        return f;
+    throw new Error('SseActor needs a global `fetch` (Bun, Node ≥18, Deno all provide one).  '
+        + 'On older Node versions, polyfill via `npm install undici` and `globalThis.fetch = require("undici").fetch`.');
+});
+//# sourceMappingURL=SseActor.js.map

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

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

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

@@ -0,0 +1,73 @@
+import type { Config } from '../../config/Config.js';
+import type { ActorRef } from '../../ActorRef.js';
+import { BrokerActor, type OutboundEnvelope } from './BrokerActor.js';
+import type { BrokerCommonSettings } from './BrokerSettings.js';
+/**
+ * Frame extraction strategy on the inbound stream.
+ *
+ *   - `bytes`     — every chunk delivered raw, no framing.  Subscriber
+ *                   has to handle byte-stream semantics itself.
+ *   - `lines`     — split on `delimiter` (default `'\n'`).  Most useful
+ *                   for line-oriented protocols (HTTP/Telnet/Redis).
+ *   - `length-prefixed` — first 4 bytes (big-endian uint32) carry the
+ *                         payload size; what follows is the payload.
+ */
+export type TcpFraming = {
+    readonly kind: 'bytes';
+} | {
+    readonly kind: 'lines';
+    readonly delimiter?: string;
+    readonly maxLineLen?: number;
+} | {
+    readonly kind: 'length-prefixed';
+    readonly maxFrameLen?: number;
+};
+export interface TcpSocketActorSettings extends BrokerCommonSettings {
+    /** Remote host. */
+    readonly host?: string;
+    /** Remote port. */
+    readonly port?: number;
+    /** Frame extraction.  Default: `{ kind: 'bytes' }`. */
+    readonly framing?: TcpFraming;
+    /**
+     * Subscriber that receives every inbound frame.  Required — the actor
+     * has no useful behaviour without one.  Receives `Uint8Array` for
+     * `bytes` / `length-prefixed`, `string` for `lines`.
+     */
+    readonly target?: ActorRef<unknown>;
+}
+/** Outbound payload — bytes or string (auto-encoded as UTF-8). */
+export type TcpOutbound = Uint8Array | string;
+/**
+ * TCP-socket actor.  Uses `node:net` (built into Bun, Node, and the
+ * Deno node-compat layer).  Owns one outbound connection; reconnects
+ * via the base class' policy on disconnect.
+ *
+ * Inbound frames are pushed to `target` as plain messages.  Outbound is
+ * via the standard `enqueueOutbound` path — the actor exposes a small
+ * command surface (`send`) so user code can `tell({ kind: 'send', payload })`.
+ */
+export type TcpSocketCmd = {
+    readonly kind: 'send';
+    readonly payload: TcpOutbound;
+};
+export declare class TcpSocketActor extends BrokerActor<TcpSocketActorSettings, TcpSocketCmd, TcpOutbound> {
+    private socket;
+    /** Buffer for partial frames not yet matched by the framing strategy. */
+    private inboundBuffer;
+    constructor(settings?: Partial<TcpSocketActorSettings>);
+    protected configKey(): string;
+    protected builtInDefaults(): Partial<TcpSocketActorSettings>;
+    protected readSettingsFromConfig(c: Config): Partial<TcpSocketActorSettings>;
+    protected requiredSettings(): ReadonlyArray<keyof TcpSocketActorSettings>;
+    protected endpointLabel(): string;
+    protected connectImpl(): Promise<void>;
+    protected disconnectImpl(): Promise<void>;
+    protected dispatchOutgoing(env: OutboundEnvelope<TcpOutbound>): Promise<void>;
+    onReceive(cmd: TcpSocketCmd): void;
+    private handleData;
+    private extractLines;
+    private extractLengthPrefixed;
+    private deliver;
+}
+//# sourceMappingURL=TcpSocketActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TcpSocketActor.d.ts","sourceRoot":"","sources":["../../../src/io/broker/TcpSocketActor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,mBAAmB;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAE7D,qBAAa,cAAe,SAAQ,WAAW,CAAC,sBAAsB,EAAE,YAAY,EAAE,WAAW,CAAC;IAChG,OAAO,CAAC,MAAM,CAA0B;IACxC,yEAAyE;IACzE,OAAO,CAAC,aAAa,CAAiC;gBAE1C,QAAQ,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAE1D,SAAS,CAAC,SAAS,IAAI,MAAM;IAC7B,SAAS,CAAC,eAAe,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAG5D,SAAS,CAAC,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAsB5E,SAAS,CAAC,gBAAgB,IAAI,aAAa,CAAC,MAAM,sBAAsB,CAAC;IAGzE,SAAS,CAAC,aAAa,IAAI,MAAM;cAEjB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;cAuB5B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;cAY/B,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1E,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAM3C,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,qBAAqB;IAkB7B,OAAO,CAAC,OAAO;CAIhB"}

package/dist/io/broker/TcpSocketActor.js

@@ -0,0 +1,168 @@
+import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { Lazy } from '../../util/Lazy.js';
+import { BrokerActor } from './BrokerActor.js';
+export class TcpSocketActor extends BrokerActor {
+    socket = null;
+    /** Buffer for partial frames not yet matched by the framing strategy. */
+    inboundBuffer = new Uint8Array(0);
+    constructor(settings = {}) { super(settings); }
+    configKey() { return ConfigKeys.io.broker.tcp; }
+    builtInDefaults() {
+        return { framing: { kind: 'bytes' } };
+    }
+    readSettingsFromConfig(c) {
+        const out = {};
+        if (c.hasPath('host'))
+            out.host = c.getString('host');
+        if (c.hasPath('port'))
+            out.port = c.getInt('port');
+        if (c.hasPath('framing')) {
+            const f = c.getConfig('framing');
+            const kind = f.getString('kind');
+            if (kind === 'lines') {
+                out.framing = {
+                    kind, delimiter: f.hasPath('delimiter') ? f.getString('delimiter') : undefined,
+                    maxLineLen: f.hasPath('maxLineLen') ? f.getInt('maxLineLen') : undefined,
+                };
+            }
+            else if (kind === 'length-prefixed') {
+                out.framing = {
+                    kind, maxFrameLen: f.hasPath('maxFrameLen') ? f.getInt('maxFrameLen') : undefined,
+                };
+            }
+            else {
+                out.framing = { kind: 'bytes' };
+            }
+        }
+        return out;
+    }
+    requiredSettings() {
+        return ['host', 'port', 'target'];
+    }
+    endpointLabel() { return `tcp://${this.settings.host}:${this.settings.port}`; }
+    async connectImpl() {
+        const net = await netLazy.get();
+        return new Promise((resolve, reject) => {
+            const sock = net.createConnection({ host: this.settings.host, port: this.settings.port });
+            let done = false;
+            sock.once('connect', () => {
+                if (done)
+                    return;
+                done = true;
+                sock.removeAllListeners('error');
+                this.socket = sock;
+                sock.on('data', (chunk) => this.handleData(chunk));
+                sock.on('close', () => this.handleConnectionLost(new Error('socket closed')));
+                sock.on('error', (e) => this.handleConnectionLost(e));
+                resolve();
+            });
+            sock.once('error', (e) => {
+                if (done)
+                    return;
+                done = true;
+                reject(e);
+            });
+        });
+    }
+    async disconnectImpl() {
+        if (!this.socket)
+            return;
+        const sock = this.socket;
+        this.socket = null;
+        return new Promise((resolve) => {
+            sock.removeAllListeners();
+            sock.end(() => resolve());
+            // Hard-cap: if `end()` doesn't fire within 1s, destroy + resolve.
+            setTimeout(() => { try {
+                sock.destroy();
+            }
+            catch { /* ignore */ } resolve(); }, 1_000);
+        });
+    }
+    async dispatchOutgoing(env) {
+        if (!this.socket)
+            throw new Error('TcpSocketActor: socket not open');
+        const bytes = env.payload instanceof Uint8Array
+            ? env.payload
+            : new TextEncoder().encode(env.payload);
+        return new Promise((resolve, reject) => {
+            this.socket.write(bytes, (err) => err ? reject(err) : resolve());
+        });
+    }
+    onReceive(cmd) {
+        if (cmd.kind === 'send')
+            this.enqueueOutbound(cmd.payload);
+    }
+    /* ---------------------------- framing ----------------------------- */
+    handleData(chunk) {
+        // Append to buffer.
+        if (this.inboundBuffer.length === 0) {
+            this.inboundBuffer = chunk;
+        }
+        else {
+            const merged = new Uint8Array(this.inboundBuffer.length + chunk.length);
+            merged.set(this.inboundBuffer, 0);
+            merged.set(chunk, this.inboundBuffer.length);
+            this.inboundBuffer = merged;
+        }
+        const f = this.settings.framing ?? { kind: 'bytes' };
+        if (f.kind === 'bytes') {
+            this.deliver(this.inboundBuffer);
+            this.inboundBuffer = new Uint8Array(0);
+        }
+        else if (f.kind === 'lines') {
+            this.extractLines(f.delimiter ?? '\n', f.maxLineLen ?? 1_048_576);
+        }
+        else {
+            this.extractLengthPrefixed(f.maxFrameLen ?? 16 * 1024 * 1024);
+        }
+    }
+    extractLines(delimiter, maxLineLen) {
+        const text = new TextDecoder('utf-8', { fatal: false }).decode(this.inboundBuffer);
+        let cursor = 0;
+        while (true) {
+            const idx = text.indexOf(delimiter, cursor);
+            if (idx < 0)
+                break;
+            const line = text.slice(cursor, idx);
+            if (line.length > maxLineLen) {
+                this.handleConnectionLost(new Error(`line exceeds maxLineLen=${maxLineLen}`));
+                return;
+            }
+            this.deliver(line);
+            cursor = idx + delimiter.length;
+        }
+        if (cursor === 0)
+            return;
+        // Re-encode the leftover suffix as bytes.
+        this.inboundBuffer = new TextEncoder().encode(text.slice(cursor));
+    }
+    extractLengthPrefixed(maxFrameLen) {
+        let cursor = 0;
+        const buf = this.inboundBuffer;
+        while (buf.length - cursor >= 4) {
+            const len = (buf[cursor] << 24 | buf[cursor + 1] << 16
+                | buf[cursor + 2] << 8 | buf[cursor + 3]) >>> 0;
+            if (len > maxFrameLen) {
+                this.handleConnectionLost(new Error(`frame exceeds maxFrameLen=${maxFrameLen}`));
+                return;
+            }
+            if (buf.length - cursor - 4 < len)
+                break;
+            const frame = buf.slice(cursor + 4, cursor + 4 + len);
+            this.deliver(frame);
+            cursor += 4 + len;
+        }
+        this.inboundBuffer = cursor === 0 ? buf : buf.slice(cursor);
+    }
+    deliver(frame) {
+        const target = this.settings.target;
+        if (target)
+            target.tell(frame);
+    }
+}
+const netLazy = Lazy.of(async () => {
+    const name = 'node:net';
+    return (await import(name));
+});
+//# sourceMappingURL=TcpSocketActor.js.map

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

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

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

@@ -0,0 +1,54 @@
+import type { Config } from '../../config/Config.js';
+import type { ActorRef } from '../../ActorRef.js';
+import { BrokerActor, type OutboundEnvelope } from './BrokerActor.js';
+import type { BrokerCommonSettings } from './BrokerSettings.js';
+/** Inbound datagram delivered to the target actor. */
+export interface UdpDatagram {
+    readonly payload: Uint8Array;
+    readonly remoteHost: string;
+    readonly remotePort: number;
+}
+/** Outbound datagram — explicit destination (UDP is not connection-oriented). */
+export interface UdpOutbound {
+    readonly payload: Uint8Array | string;
+    readonly host: string;
+    readonly port: number;
+}
+export interface UdpSocketActorSettings extends BrokerCommonSettings {
+    /** Local bind address.  Default: `'0.0.0.0'`. */
+    readonly bindHost?: string;
+    /** Local port.  `0` (default) lets the OS pick. */
+    readonly bindPort?: number;
+    /** IPv4 (`'udp4'`) or IPv6 (`'udp6'`).  Default: `'udp4'`. */
+    readonly type?: 'udp4' | 'udp6';
+    /** Subscriber for inbound datagrams.  Required. */
+    readonly target?: ActorRef<UdpDatagram>;
+}
+export type UdpSocketCmd = {
+    readonly kind: 'send';
+    readonly datagram: UdpOutbound;
+};
+/**
+ * UDP-socket actor.  Uses `node:dgram` (built-in everywhere).  No
+ * connection lifecycle in the TCP sense; we treat "bound" as
+ * `connected` and "unbound" as `disconnected`, so the base class'
+ * lifecycle events still apply (`BrokerConnected` fires once the
+ * socket is bound).
+ */
+export declare class UdpSocketActor extends BrokerActor<UdpSocketActorSettings, UdpSocketCmd, UdpOutbound> {
+    private socket;
+    private actualPort;
+    constructor(settings?: Partial<UdpSocketActorSettings>);
+    protected configKey(): string;
+    protected builtInDefaults(): Partial<UdpSocketActorSettings>;
+    protected readSettingsFromConfig(c: Config): Partial<UdpSocketActorSettings>;
+    protected requiredSettings(): ReadonlyArray<keyof UdpSocketActorSettings>;
+    protected endpointLabel(): string;
+    /** OS-assigned port after `bind` (0 before, real number after). */
+    get boundPort(): number;
+    protected connectImpl(): Promise<void>;
+    protected disconnectImpl(): Promise<void>;
+    protected dispatchOutgoing(env: OutboundEnvelope<UdpOutbound>): Promise<void>;
+    onReceive(cmd: UdpSocketCmd): void;
+}
+//# sourceMappingURL=UdpSocketActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UdpSocketActor.d.ts","sourceRoot":"","sources":["../../../src/io/broker/UdpSocketActor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC;AAErF;;;;;;GAMG;AACH,qBAAa,cACX,SAAQ,WAAW,CAAC,sBAAsB,EAAE,YAAY,EAAE,WAAW,CAAC;IACtE,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,UAAU,CAAK;gBAEX,QAAQ,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAE1D,SAAS,CAAC,SAAS,IAAI,MAAM;IAC7B,SAAS,CAAC,eAAe,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAG5D,SAAS,CAAC,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAO5E,SAAS,CAAC,gBAAgB,IAAI,aAAa,CAAC,MAAM,sBAAsB,CAAC;IAGzE,SAAS,CAAC,aAAa,IAAI,MAAM;IAIjC,mEAAmE;IACnE,IAAI,SAAS,IAAI,MAAM,CAA4B;cAEnC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;cA6B5B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;cAY/B,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;CAG5C"}

package/dist/io/broker/UdpSocketActor.js

@@ -0,0 +1,100 @@
+import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { Lazy } from '../../util/Lazy.js';
+import { BrokerActor } from './BrokerActor.js';
+/**
+ * UDP-socket actor.  Uses `node:dgram` (built-in everywhere).  No
+ * connection lifecycle in the TCP sense; we treat "bound" as
+ * `connected` and "unbound" as `disconnected`, so the base class'
+ * lifecycle events still apply (`BrokerConnected` fires once the
+ * socket is bound).
+ */
+export class UdpSocketActor extends BrokerActor {
+    socket = null;
+    actualPort = 0;
+    constructor(settings = {}) { super(settings); }
+    configKey() { return ConfigKeys.io.broker.udp; }
+    builtInDefaults() {
+        return { bindHost: '0.0.0.0', bindPort: 0, type: 'udp4' };
+    }
+    readSettingsFromConfig(c) {
+        const out = {};
+        if (c.hasPath('bindHost'))
+            out.bindHost = c.getString('bindHost');
+        if (c.hasPath('bindPort'))
+            out.bindPort = c.getInt('bindPort');
+        if (c.hasPath('type'))
+            out.type = c.getString('type');
+        return out;
+    }
+    requiredSettings() {
+        return ['target'];
+    }
+    endpointLabel() {
+        return `${this.settings.type}://${this.settings.bindHost}:${this.actualPort || this.settings.bindPort}`;
+    }
+    /** OS-assigned port after `bind` (0 before, real number after). */
+    get boundPort() { return this.actualPort; }
+    async connectImpl() {
+        const dgram = await dgramLazy.get();
+        const sock = dgram.createSocket(this.settings.type ?? 'udp4');
+        return new Promise((resolve, reject) => {
+            let done = false;
+            sock.once('listening', () => {
+                if (done)
+                    return;
+                done = true;
+                sock.removeAllListeners('error');
+                this.socket = sock;
+                const addr = sock.address();
+                this.actualPort = addr.port;
+                sock.on('message', (msg, rinfo) => {
+                    this.settings.target?.tell({
+                        payload: msg, remoteHost: rinfo.address, remotePort: rinfo.port,
+                    });
+                });
+                sock.on('error', (e) => this.handleConnectionLost(e));
+                resolve();
+            });
+            sock.once('error', (e) => {
+                if (done)
+                    return;
+                done = true;
+                reject(e);
+            });
+            sock.bind(this.settings.bindPort ?? 0, this.settings.bindHost);
+        });
+    }
+    async disconnectImpl() {
+        if (!this.socket)
+            return;
+        const sock = this.socket;
+        this.socket = null;
+        this.actualPort = 0;
+        return new Promise((resolve) => {
+            sock.removeAllListeners();
+            sock.close(() => resolve());
+            setTimeout(() => resolve(), 500);
+        });
+    }
+    async dispatchOutgoing(env) {
+        if (!this.socket)
+            throw new Error('UdpSocketActor: socket not bound');
+        const bytes = env.payload.payload instanceof Uint8Array
+            ? env.payload.payload
+            : new TextEncoder().encode(env.payload.payload);
+        return new Promise((resolve, reject) => {
+            this.socket.send(bytes, env.payload.port, env.payload.host, (err) => {
+                err ? reject(err) : resolve();
+            });
+        });
+    }
+    onReceive(cmd) {
+        if (cmd.kind === 'send')
+            this.enqueueOutbound(cmd.datagram);
+    }
+}
+const dgramLazy = Lazy.of(async () => {
+    const name = 'node:dgram';
+    return (await import(name));
+});
+//# sourceMappingURL=UdpSocketActor.js.map

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

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

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

@@ -0,0 +1,77 @@
+import type { Config } from '../../config/Config.js';
+import type { ActorRef } from '../../ActorRef.js';
+import { BrokerActor, type OutboundEnvelope } from './BrokerActor.js';
+import type { BrokerCommonSettings } from './BrokerSettings.js';
+/** WebSocket message — frames are either text or binary. */
+export type WebSocketFrame = {
+    readonly kind: 'text';
+    readonly data: string;
+} | {
+    readonly kind: 'binary';
+    readonly data: Uint8Array;
+};
+export interface WebSocketActorSettings extends BrokerCommonSettings {
+    /** WebSocket URL (`ws://...` or `wss://...`). */
+    readonly url?: string;
+    /** Subprotocols negotiated with the server. */
+    readonly protocols?: string | ReadonlyArray<string>;
+    /** Custom request headers (Node only — browsers ignore these). */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Subscriber that receives every inbound frame.  Required. */
+    readonly target?: ActorRef<WebSocketFrame>;
+    /** Send a ping every `pingIntervalMs` to keep the connection alive.  Default: disabled. */
+    readonly pingIntervalMs?: number;
+    /**
+     * Maximum allowed size of a single inbound frame, in bytes.
+     * Frames larger than this are dropped (logged at warn level)
+     * without being forwarded to `target`.  Default: 1 MiB.
+     *
+     * **Why this exists (security):** a malicious (or compromised) WS
+     * peer can send arbitrarily-large frames.  Without a cap, the
+     * actor's mailbox grows unbounded if `target` consumes slowly —
+     * one 100-MiB frame plus a stalled consumer exhausts the process.
+     * Set to `Infinity` to disable (not recommended for public-facing
+     * endpoints); raise the cap if you legitimately need bigger
+     * frames (audio/video streams).
+     */
+    readonly maxInboundFrameBytes?: number;
+}
+export type WebSocketCmd = {
+    readonly kind: 'send';
+    readonly frame: WebSocketFrame;
+} | {
+    readonly kind: 'sendText';
+    readonly data: string;
+} | {
+    readonly kind: 'sendBinary';
+    readonly data: Uint8Array;
+};
+/**
+ * WebSocket-client actor.  Picks up the native `WebSocket` API on
+ * Bun + Deno; on Node, lazy-imports the `ws` peer-dep.  Either way
+ * inbound text/binary frames are routed to `target`; outbound is the
+ * standard `enqueueOutbound` path so messages buffered while
+ * disconnected are resent after reconnect.
+ *
+ * Server-side WebSocket upgrades (Hono/Fastify integration) are out of
+ * scope for v1 — those need access to the underlying HTTP request,
+ * which is backend-specific.
+ */
+export declare class WebSocketActor extends BrokerActor<WebSocketActorSettings, WebSocketCmd, WebSocketFrame> {
+    private socket;
+    private pingTimer;
+    constructor(settings?: Partial<WebSocketActorSettings>);
+    protected configKey(): string;
+    protected builtInDefaults(): Partial<WebSocketActorSettings>;
+    protected readSettingsFromConfig(c: Config): Partial<WebSocketActorSettings>;
+    protected requiredSettings(): ReadonlyArray<keyof WebSocketActorSettings>;
+    protected endpointLabel(): string;
+    protected connectImpl(): Promise<void>;
+    protected disconnectImpl(): Promise<void>;
+    protected dispatchOutgoing(env: OutboundEnvelope<WebSocketFrame>): Promise<void>;
+    onReceive(cmd: WebSocketCmd): void;
+    private handleMessage;
+}
+/** Default cap on a single inbound WebSocket frame — 1 MiB. */
+export declare const DEFAULT_WS_MAX_INBOUND_FRAME_BYTES: number;
+//# sourceMappingURL=WebSocketActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketActor.d.ts","sourceRoot":"","sources":["../../../src/io/broker/WebSocketActor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,iDAAiD;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC3C,2FAA2F;IAC3F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,WAAW,CAAC,sBAAsB,EAAE,YAAY,EAAE,cAAc,CAAC;IACnG,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,SAAS,CAA+C;gBAEpD,QAAQ,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAE1D,SAAS,CAAC,SAAS,IAAI,MAAM;IAC7B,SAAS,CAAC,eAAe,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAC5D,SAAS,CAAC,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAe5E,SAAS,CAAC,gBAAgB,IAAI,aAAa,CAAC,MAAM,sBAAsB,CAAC;IAGzE,SAAS,CAAC,aAAa,IAAI,MAAM;cAEjB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;cAiC5B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;cAQ/B,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7E,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAQ3C,OAAO,CAAC,aAAa;CAyDtB;AAED,+DAA+D;AAC/D,eAAO,MAAM,kCAAkC,QAAkB,CAAC"}