actor-ts 0.9.0

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

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

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

@@ -0,0 +1,69 @@
+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 entry from a Redis stream. */
+export interface RedisStreamEntry {
+    readonly stream: string;
+    readonly id: string;
+    readonly fields: Readonly<Record<string, string>>;
+}
+/** Outbound publish — adds an entry to a Redis stream via XADD. */
+export interface RedisStreamPublish {
+    readonly stream: string;
+    readonly fields: Readonly<Record<string, string>>;
+    /** Optional `MAXLEN ~ N` cap.  Drops oldest when set. */
+    readonly maxLenApprox?: number;
+}
+export interface RedisStreamsActorSettings extends BrokerCommonSettings {
+    /** Redis URL (`'redis://host:6379'`). */
+    readonly url?: string;
+    /** Streams to consume. */
+    readonly streams?: ReadonlyArray<string>;
+    /** Consumer-group settings — required to consume.  When omitted only producing works. */
+    readonly consumerGroup?: {
+        readonly group: string;
+        readonly consumer: string;
+        /** Auto-create the group if missing.  Default: true. */
+        readonly createIfMissing?: boolean;
+    };
+    /** Block timeout per XREADGROUP call in ms.  Default: 5_000. */
+    readonly blockMs?: number;
+    /** Subscriber for inbound entries.  Required to consume. */
+    readonly target?: ActorRef<RedisStreamEntry>;
+}
+export type RedisStreamsCmd = {
+    readonly kind: 'publish';
+    readonly publish: RedisStreamPublish;
+} | {
+    readonly kind: 'ack';
+    readonly stream: string;
+    readonly id: string;
+};
+/**
+ * Redis-Streams actor.  Wraps `ioredis` (already a peer-dep used by
+ * the cache layer).  Producer + optional consumer in one actor.
+ *
+ * Consumer mode uses `XREADGROUP` with a stable consumer name; entries
+ * are delivered to `target` and are NOT auto-acked — the caller must
+ * `tell({ kind: 'ack', stream, id })` after processing for at-least-
+ * once semantics with crash-recovery.  For at-most-once, ack
+ * immediately on delivery.
+ */
+export declare class RedisStreamsActor extends BrokerActor<RedisStreamsActorSettings, RedisStreamsCmd, RedisStreamPublish> {
+    private redis;
+    private redisProducer;
+    private consumerLoopRunning;
+    constructor(settings?: Partial<RedisStreamsActorSettings>);
+    protected configKey(): string;
+    protected builtInDefaults(): Partial<RedisStreamsActorSettings>;
+    protected readSettingsFromConfig(c: Config): Partial<RedisStreamsActorSettings>;
+    protected requiredSettings(): ReadonlyArray<keyof RedisStreamsActorSettings>;
+    protected endpointLabel(): string;
+    protected connectImpl(): Promise<void>;
+    protected disconnectImpl(): Promise<void>;
+    protected dispatchOutgoing(env: OutboundEnvelope<RedisStreamPublish>): Promise<void>;
+    onReceive(cmd: RedisStreamsCmd): void;
+    private consumerLoop;
+}
+//# sourceMappingURL=RedisStreamsActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RedisStreamsActor.d.ts","sourceRoot":"","sources":["../../../src/io/broker/RedisStreamsActor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACrE,yCAAyC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,wDAAwD;QACxD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;IACF,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;GASG;AACH,qBAAa,iBACX,SAAQ,WAAW,CAAC,yBAAyB,EAAE,eAAe,EAAE,kBAAkB,CAAC;IACnF,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,mBAAmB,CAAS;gBAExB,QAAQ,GAAE,OAAO,CAAC,yBAAyB,CAAM;IAE7D,SAAS,CAAC,SAAS,IAAI,MAAM;IAC7B,SAAS,CAAC,eAAe,IAAI,OAAO,CAAC,yBAAyB,CAAC;IAG/D,SAAS,CAAC,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAe/E,SAAS,CAAC,gBAAgB,IAAI,aAAa,CAAC,MAAM,yBAAyB,CAAC;IAC5E,SAAS,CAAC,aAAa,IAAI,MAAM;cAEjB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;cAuB5B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;cAQ/B,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjF,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;YAahC,YAAY;CA4B3B"}

package/dist/io/broker/RedisStreamsActor.js

@@ -0,0 +1,140 @@
+import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { Lazy } from '../../util/Lazy.js';
+import { lazyImportModule } from '../../util/LazyImport.js';
+import { BrokerActor } from './BrokerActor.js';
+/**
+ * Redis-Streams actor.  Wraps `ioredis` (already a peer-dep used by
+ * the cache layer).  Producer + optional consumer in one actor.
+ *
+ * Consumer mode uses `XREADGROUP` with a stable consumer name; entries
+ * are delivered to `target` and are NOT auto-acked — the caller must
+ * `tell({ kind: 'ack', stream, id })` after processing for at-least-
+ * once semantics with crash-recovery.  For at-most-once, ack
+ * immediately on delivery.
+ */
+export class RedisStreamsActor extends BrokerActor {
+    redis = null;
+    redisProducer = null;
+    consumerLoopRunning = false;
+    constructor(settings = {}) { super(settings); }
+    configKey() { return ConfigKeys.io.broker.redisStreams; }
+    builtInDefaults() {
+        return { blockMs: 5_000 };
+    }
+    readSettingsFromConfig(c) {
+        const out = {};
+        if (c.hasPath('url'))
+            out.url = c.getString('url');
+        if (c.hasPath('streams'))
+            out.streams = c.getStringList('streams');
+        if (c.hasPath('blockMs'))
+            out.blockMs = c.getDuration('blockMs');
+        if (c.hasPath('consumerGroup')) {
+            const g = c.getConfig('consumerGroup');
+            out.consumerGroup = {
+                group: g.getString('group'),
+                consumer: g.getString('consumer'),
+                createIfMissing: g.hasPath('createIfMissing') ? g.getBoolean('createIfMissing') : undefined,
+            };
+        }
+        return out;
+    }
+    requiredSettings() { return ['url']; }
+    endpointLabel() { return this.settings.url ?? '<unknown>'; }
+    async connectImpl() {
+        const ioredis = await ioredisLazy.get();
+        const Ctor = ioredis.default ?? ioredis;
+        this.redisProducer = new Ctor(this.settings.url);
+        if (this.settings.consumerGroup && this.settings.streams && this.settings.target) {
+            this.redis = new Ctor(this.settings.url);
+            const cg = this.settings.consumerGroup;
+            if (cg.createIfMissing ?? true) {
+                for (const stream of this.settings.streams) {
+                    try {
+                        await this.redis.xgroup('CREATE', stream, cg.group, '$', 'MKSTREAM');
+                    }
+                    catch (e) {
+                        // BUSYGROUP = group already exists; ignore.  Anything else → log.
+                        if (!e.message.includes('BUSYGROUP')) {
+                            this.log.warn(`xgroup CREATE failed for '${stream}/${cg.group}': ${e.message}`);
+                        }
+                    }
+                }
+            }
+            this.consumerLoopRunning = true;
+            void this.consumerLoop();
+        }
+    }
+    async disconnectImpl() {
+        this.consumerLoopRunning = false;
+        try {
+            await this.redisProducer?.quit();
+        }
+        catch { /* ignore */ }
+        try {
+            await this.redis?.quit();
+        }
+        catch { /* ignore */ }
+        this.redisProducer = null;
+        this.redis = null;
+    }
+    async dispatchOutgoing(env) {
+        if (!this.redisProducer)
+            throw new Error('RedisStreamsActor: producer not connected');
+        const p = env.payload;
+        const args = [p.stream];
+        if (p.maxLenApprox !== undefined) {
+            args.push('MAXLEN', '~', String(p.maxLenApprox));
+        }
+        args.push('*'); // auto-id
+        for (const [k, v] of Object.entries(p.fields)) {
+            args.push(k, v);
+        }
+        await this.redisProducer.xadd(...args);
+    }
+    onReceive(cmd) {
+        if (cmd.kind === 'publish') {
+            this.enqueueOutbound(cmd.publish);
+        }
+        else if (cmd.kind === 'ack') {
+            if (this.redis && this.settings.consumerGroup) {
+                void this.redis.xack(cmd.stream, this.settings.consumerGroup.group, cmd.id)
+                    .catch((e) => this.log.warn(`xack failed: ${e.message}`));
+            }
+        }
+    }
+    /* ----------------------------- internals ----------------------------- */
+    async consumerLoop() {
+        const cg = this.settings.consumerGroup;
+        const blockMs = this.settings.blockMs ?? 5_000;
+        while (this.consumerLoopRunning && this.redis) {
+            try {
+                const args = ['GROUP', cg.group, cg.consumer,
+                    'BLOCK', String(blockMs), 'COUNT', '32',
+                    'STREAMS', ...(this.settings.streams ?? []),
+                    ...(this.settings.streams ?? []).map(() => '>'),
+                ];
+                const result = await this.redis.xreadgroup(...args);
+                if (!result)
+                    continue;
+                for (const [stream, entries] of result) {
+                    for (const [id, fields] of entries) {
+                        const obj = {};
+                        for (let i = 0; i + 1 < fields.length; i += 2) {
+                            obj[fields[i]] = fields[i + 1];
+                        }
+                        this.settings.target?.tell({ stream, id, fields: obj });
+                    }
+                }
+            }
+            catch (e) {
+                if (!this.consumerLoopRunning)
+                    return;
+                this.log.warn(`RedisStreams consumer loop error: ${e.message}`);
+                await new Promise((r) => setTimeout(r, 500));
+            }
+        }
+    }
+}
+const ioredisLazy = Lazy.of(() => lazyImportModule('ioredis', { context: 'RedisStreamsActor' }));
+//# sourceMappingURL=RedisStreamsActor.js.map

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

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

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

@@ -0,0 +1,109 @@
+import { Actor } from '../../Actor.js';
+import type { ActorRef } from '../../ActorRef.js';
+import type { WebSocketCmd, WebSocketFrame } from './WebSocketActor.js';
+/**
+ * Server-side counterpart to {@link WebSocketActor} (#1).  Wraps an
+ * already-upgraded WebSocket — typically handed in by a Fastify /
+ * Hono / Bun.serve upgrade handler — and bridges its lifecycle into
+ * the actor system.
+ *
+ * **Why a separate actor instead of teaching `WebSocketActor` to be
+ * dual-mode?**  The two halves have fundamentally different
+ * lifecycle assumptions:
+ *
+ *   - `WebSocketActor` (client) dials a URL, owns reconnect-backoff,
+ *     buffers outbound while disconnected, retries.  The remote peer
+ *     is the server; we drive the connection.
+ *   - `ServerWebSocketActor` is handed a connected socket whose
+ *     lifecycle is owned by the *client*.  When the client goes
+ *     away, the actor's job is over — there's nothing to "reconnect"
+ *     to.  Reconnect-backoff and outbound buffering across reconnects
+ *     would be incorrect.
+ *
+ * The shared piece is the message envelope (`WebSocketFrame`) and the
+ * outbound command shape (`WebSocketCmd`); we re-export those rather
+ * than duplicate the types.
+ *
+ * **Lifecycle.**
+ *
+ *   - On `preStart`, registers `message` / `close` / `error`
+ *     listeners.  Inbound frames are forwarded to `target` as
+ *     `WebSocketFrame`s (text / binary).
+ *   - On socket `close`, the actor stops itself by default
+ *     (`stopOnSocketClose: true`); flip the flag to keep the actor
+ *     alive — useful when you want to handle the close yourself
+ *     (e.g. log + emit a domain event).
+ *   - On `postStop`, the socket is closed.  Idempotent — closing an
+ *     already-closed socket is a no-op.
+ *
+ * **Outbound** flows through the same `WebSocketCmd` shape as the
+ * client actor, so handlers written against one work against the
+ * other.  No buffering — sends fail loud if the socket is closed.
+ *
+ *   import { ServerWebSocketActor, bunWebSocketHandler } from 'actor-ts';
+ *
+ *   Bun.serve({
+ *     port: 3000,
+ *     fetch: bunWebSocketHandler(system, '/ws', {
+ *       onOpen: (ws, ref, _ctx) => {
+ *         // ref is the actor reference.  Subscribe it to a chat room, etc.
+ *         chatRoom.tell({ kind: 'join', client: ref });
+ *       },
+ *     }),
+ *     websocket: { /* placeholder, filled by bunWebSocketHandler */ /** Re-export so callers don't have to import from two places. */
+export type { WebSocketCmd, WebSocketFrame } from './WebSocketActor.js';
+export interface ServerWebSocketActorOptions {
+    /** Subscriber that receives every inbound text/binary frame. */
+    readonly target?: ActorRef<WebSocketFrame>;
+    /**
+     * Stop the actor when the socket closes.  Default `true` — the
+     * usual case where the actor exists solely to bridge one
+     * connection.  Flip to `false` to handle close yourself
+     * (e.g. when an outer supervisor wants to react before teardown).
+     */
+    readonly stopOnSocketClose?: boolean;
+    /**
+     * Optional callback fired when the socket emits an error.  Useful
+     * for backend-specific telemetry; the actor still proceeds to
+     * stop unless you turn `stopOnSocketClose` off.
+     */
+    readonly onError?: (err: Error) => void;
+}
+/**
+ * Minimal socket surface the actor depends on.  Bun's native
+ * `ServerWebSocket`, the `ws` package's `WebSocket`, and the W3C
+ * `WebSocket` all satisfy it.  Adapter helpers normalise the small
+ * shape differences.
+ */
+export interface ServerWebSocketLike {
+    send(data: string | Uint8Array | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(event: 'message', cb: (ev: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(event: 'close', cb: () => void): void;
+    addEventListener(event: 'error', cb: (ev: unknown) => void): void;
+    removeEventListener?(event: string, cb: (...args: never[]) => void): void;
+    /**
+     * Optional readyState — when present we skip `send` on a closing
+     * socket so we don't queue a 'send after close' error in tests.
+     */
+    readonly readyState?: number;
+}
+export declare class ServerWebSocketActor extends Actor<WebSocketCmd> {
+    private readonly socket;
+    private readonly opts;
+    private closed;
+    private readonly onMessage;
+    private readonly onClose;
+    private readonly onErrorEvent;
+    constructor(socket: ServerWebSocketLike, opts?: ServerWebSocketActorOptions);
+    preStart(): void;
+    postStop(): void;
+    onReceive(cmd: WebSocketCmd): void;
+    private send;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+}
+//# sourceMappingURL=ServerWebSocketActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ServerWebSocketActor.d.ts","sourceRoot":"","sources":["../../../src/io/broker/ServerWebSocketActor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAiDoE,CAIpE,iEAAiE;AACjE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC9E,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACvD,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAClE,mBAAmB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1E;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,YAAY,CAAC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,MAAM,CAAS;IAIvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;IAC1F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+C;gBAEhE,MAAM,EAAE,mBAAmB,EAAE,IAAI,GAAE,2BAAgC;IAMtE,QAAQ,IAAI,IAAI;IAOhB,QAAQ,IAAI,IAAI;IAchB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAyB3C,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,aAAa;IAuCrB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,WAAW;CAOpB"}

package/dist/io/broker/ServerWebSocketActor.js

@@ -0,0 +1,128 @@
+import { Actor } from '../../Actor.js';
+export class ServerWebSocketActor extends Actor {
+    socket;
+    opts;
+    closed = false;
+    // Pinned listener refs so `removeEventListener` (where supported)
+    // can detach them on stop.
+    onMessage = (ev) => this.handleMessage(ev.data);
+    onClose = () => this.handleClose();
+    onErrorEvent = (ev) => this.handleError(ev);
+    constructor(socket, opts = {}) {
+        super();
+        this.socket = socket;
+        this.opts = opts;
+    }
+    preStart() {
+        this.log.debug('ServerWebSocketActor: attached to socket');
+        this.socket.addEventListener('message', this.onMessage);
+        this.socket.addEventListener('close', this.onClose);
+        this.socket.addEventListener('error', this.onErrorEvent);
+    }
+    postStop() {
+        if (this.socket.removeEventListener) {
+            try {
+                this.socket.removeEventListener('message', this.onMessage);
+                this.socket.removeEventListener('close', this.onClose);
+                this.socket.removeEventListener('error', this.onErrorEvent);
+            }
+            catch { /* ignore — best-effort detach */ }
+        }
+        if (!this.closed) {
+            this.closed = true;
+            try {
+                this.socket.close();
+            }
+            catch { /* already closed */ }
+        }
+    }
+    onReceive(cmd) {
+        if (this.closed) {
+            this.log.debug('ServerWebSocketActor: send after close — ignored');
+            return;
+        }
+        try {
+            if (cmd.kind === 'send') {
+                this.log.debug(`ServerWebSocketActor: send ${cmd.frame.kind} frame (${cmd.frame.kind === 'text' ? `${cmd.frame.data.length} chars` : `${cmd.frame.data.byteLength} bytes`})`);
+                this.send(cmd.frame);
+            }
+            else if (cmd.kind === 'sendText') {
+                this.log.debug(`ServerWebSocketActor: send text (${cmd.data.length} chars)`);
+                this.socket.send(cmd.data);
+            }
+            else {
+                this.log.debug(`ServerWebSocketActor: send binary (${cmd.data.byteLength} bytes)`);
+                this.socket.send(cmd.data);
+            }
+        }
+        catch (err) {
+            this.log.warn(`ServerWebSocketActor: send failed: ${err.message}`);
+        }
+    }
+    /* ------------------------------ inbound ------------------------------- */
+    send(frame) {
+        if (frame.kind === 'text')
+            this.socket.send(frame.data);
+        else
+            this.socket.send(frame.data);
+    }
+    handleMessage(data) {
+        const target = this.opts.target;
+        if (!target)
+            return;
+        if (typeof data === 'string') {
+            this.log.debug(`ServerWebSocketActor: recv text (${data.length} chars)`);
+            target.tell({ kind: 'text', data });
+            return;
+        }
+        if (data instanceof ArrayBuffer) {
+            this.log.debug(`ServerWebSocketActor: recv binary (${data.byteLength} bytes)`);
+            target.tell({ kind: 'binary', data: new Uint8Array(data) });
+            return;
+        }
+        if (data instanceof Uint8Array) {
+            this.log.debug(`ServerWebSocketActor: recv binary (${data.byteLength} bytes)`);
+            target.tell({ kind: 'binary', data });
+            return;
+        }
+        // ws-lib delivers a Buffer (which is a Uint8Array subtype) or
+        // arrays of Buffer chunks for fragmented messages — coerce.
+        if (Array.isArray(data)) {
+            const total = data.reduce((n, b) => n + b.byteLength, 0);
+            const merged = new Uint8Array(total);
+            let off = 0;
+            for (const part of data) {
+                const u8 = new Uint8Array(part);
+                merged.set(u8, off);
+                off += u8.byteLength;
+            }
+            target.tell({ kind: 'binary', data: merged });
+            return;
+        }
+        if (data && typeof data.byteLength === 'number') {
+            target.tell({ kind: 'binary', data: new Uint8Array(data) });
+            return;
+        }
+        this.log.warn(`ServerWebSocketActor: unrecognised inbound frame type (${typeof data})`);
+    }
+    handleClose() {
+        if (this.closed)
+            return;
+        this.log.debug('ServerWebSocketActor: socket closed');
+        this.closed = true;
+        if (this.opts.stopOnSocketClose ?? true) {
+            this.context.stopSelf();
+        }
+    }
+    handleError(ev) {
+        const err = ev instanceof Error
+            ? ev
+            : new Error(typeof ev === 'string' ? ev : 'WebSocket error');
+        this.log.warn(`ServerWebSocketActor: ${err.message}`);
+        try {
+            this.opts.onError?.(err);
+        }
+        catch { /* user code throwing in onError shouldn't kill us */ }
+    }
+}
+//# sourceMappingURL=ServerWebSocketActor.js.map

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

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

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

@@ -0,0 +1,45 @@
+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 SSE event delivered to subscribers. */
+export interface SseEvent {
+    /** The `event:` field value, or `'message'` (default per SSE spec). */
+    readonly event: string;
+    /** The `data:` field value (newline-joined when split across lines). */
+    readonly data: string;
+    /** Last-event-id, when the server sent one. */
+    readonly id?: string;
+}
+export interface SseActorSettings extends BrokerCommonSettings {
+    /** SSE endpoint URL. */
+    readonly url?: string;
+    /** Custom request headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Subscriber for inbound events.  Required. */
+    readonly target?: ActorRef<SseEvent>;
+}
+export type SseCmd = never;
+/**
+ * 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 declare class SseActor extends BrokerActor<SseActorSettings, SseCmd, never> {
+    private aborter;
+    private streamRunning;
+    constructor(settings?: Partial<SseActorSettings>);
+    protected configKey(): string;
+    protected builtInDefaults(): Partial<SseActorSettings>;
+    protected readSettingsFromConfig(c: Config): Partial<SseActorSettings>;
+    protected requiredSettings(): ReadonlyArray<keyof SseActorSettings>;
+    protected endpointLabel(): string;
+    protected connectImpl(): Promise<void>;
+    protected disconnectImpl(): Promise<void>;
+    protected dispatchOutgoing(_env: OutboundEnvelope<never>): Promise<void>;
+    onReceive(_cmd: SseCmd): void;
+    private consume;
+}
+//# sourceMappingURL=SseActor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SseActor.d.ts","sourceRoot":"","sources":["../../../src/io/broker/SseActor.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,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB;IAC5D,wBAAwB;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;CACtC;AAED,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC;AAE3B;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,WAAW,CAAC,gBAAgB,EAAE,MAAM,EAAE,KAAK,CAAC;IACxE,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,aAAa,CAAS;gBAElB,QAAQ,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAEpD,SAAS,CAAC,SAAS,IAAI,MAAM;IAC7B,SAAS,CAAC,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;IACtD,SAAS,CAAC,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYtE,SAAS,CAAC,gBAAgB,IAAI,aAAa,CAAC,MAAM,gBAAgB,CAAC;IACnE,SAAS,CAAC,aAAa,IAAI,MAAM;cAEjB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;cAe5B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;cAM/B,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;YAIxB,OAAO;CA6BtB"}