Zum Inhalt springen
Deutsch

WebsocketClientActor

WebsocketClientActor öffnet eine clientseitige WebSocket-Verbindung zu einem Remote-Endpoint. Eingehende Frames werden in typisierte Nachrichten dekodiert, die du in onMessage behandelst; ausgehende Nachrichten werden kodiert und gesendet (während der Trennung gepuffert, nach dem Reconnect erneut gesendet). Zum Annehmen eingehender WS-Verbindungen (Serverseite) siehe Server-WebSocket.

import { match } from 'ts-pattern';
import { WebsocketClientActor, WebsocketClientOptions, websocketSend } from 'actor-ts/http';
type ClientMessage = { kind: 'ping'; n: number };
type ServerMessage = { kind: 'pong'; n: number } | { kind: 'event'; data: unknown };
class Feed extends WebsocketClientActor<ClientMessage, ServerMessage> {
constructor() {
const webSocketClientOptions = WebsocketClientOptions.create<ClientMessage, ServerMessage>().withUrl('ws://localhost:8080/ws');
super(webSocketClientOptions);
}
override onConnected(): void {
this.send({ kind: 'ping', n: 1 });
}
onMessage(message: ServerMessage): void {
// decoded server message
match(message)
.with({ kind: 'pong' }, (m) => this.onPong(m))
.exhaustive();
}
private onPong(message: PongMessage): void {
this.log.info(`pong ${message.n}`);
}
}
const feed = system.spawn(Feed, 'feed');

Die beiden Typparameter sind aus Sicht des Clients zu lesen: TOut = die Nachrichten, die dieser Client sendet, TIn = die dekodierten Server-Nachrichten, die er empfängt.

WebsocketClientActor erweitert die gemeinsame BrokerActor-Basis und erbt damit Reconnect-mit-Backoff, den Outbound-Buffer über Reconnects hinweg und einen Circuit Breaker um den Connect — aus, bis du einen benennst.

Der Konstruktor nimmt Partial<WebsocketClientOptionsType<TOut, TIn>>. Nur url ist erforderlich; alles andere hat einen Default.

interface WebsocketClientOptionsType<TOut, TIn> extends BrokerCommonOptionsType {
url: string; // required — ws:// or wss://
protocols?: string | string[]; // subprotocols
codec?: WebsocketCodec<TOut, TIn>; // default jsonCodec()
maxFrameBytes?: number; // default 1 MiB; oversize inbound closes with 1009
onInvalidMessage?: 'drop' | 'hook' | 'disconnect'; // default 'drop'
pingIntervalMs?: number; // keepalive interval; default off, payload from keepAliveFrame()
idleTimeoutMs?: number; // read-idle deadline; default 0 (off)
connectTimeoutMs?: number; // connect deadline; default 0 (off)
inboundHighWaterMark?: number; // pause the socket at this many queued inbound frames; default off
inboundLowWaterMark?: number; // resume at this many; default a quarter of the high-water mark
}

Da die Settings BrokerCommonOptionsType erweitern, gelten der Block reconnect ({ initialDelayMs, maxDelayMs, factor, maxAttempts, randomFactor }), outboundBuffer und circuitBreaker — eine Breaker-Id, deren Zahlen unter actor-ts.circuit-breaker.<id> liegen — allesamt; ihre Semantik steht in der BrokerActor-Basis, die des Breakers unter Circuit Breaker.

Innerhalb des Actors kodiert this.send(message) die Nachricht über den Codec und stellt sie in die Queue; während der Trennung wird die Nachricht gepuffert und nach dem Reconnect erneut gesendet. Eingehende Frames werden dekodiert und an onMessage zugestellt.

class Chat extends WebsocketClientActor<ClientMessage, ServerMessage> {
constructor() {
const webSocketClientOptions = WebsocketClientOptions.create<ClientMessage, ServerMessage>().withUrl('wss://chat.example.com/ws');
super(webSocketClientOptions);
}
override onConnected(): void {
this.send({ kind: 'setName', name: 'alice' }); // encode + enqueue → true
}
onMessage(message: ServerMessage): void {
// one call per decoded server frame, in frame order
}
}

send(message: TOut): boolean gibt zurück, ob die Nachricht angenommen wurde (sie kann abgelehnt werden, wenn der Outbound-Buffer voll ist). Für einen rohen Frame — unter Umgehung des Codecs — nutze sendRaw(frame: WebsocketFrame): boolean.

Andere Actors rufen send nicht direkt auf; sie pushen einen typisierten Send über die Ref mit dem websocketSend-Helper:

import { websocketSend } from 'actor-ts/http';
feed.tell(websocketSend({ kind: 'ping', n: 42 }));

onMessage(message: TIn) ist abstrakt — du musst es implementieren. Der Rest sind optionale Overrides:

HookWann
onConnected()Die Verbindung ist (wieder) aufgebaut. Guter Ort für einen Handshake / Re-Subscribe.
onDisconnected(cause?: Error)Die Verbindung ist abgerissen; cause ist bei fehlergetriebenen Abbrüchen gesetzt.
onInvalidMessage(error: WebsocketDecodeError)Ein Frame ließ sich nicht dekodieren (nur bei onInvalidMessage: 'hook').
onSelfMessage(message: TSelf)Behandelt den optionalen dritten Typparameter — Nachrichten, die der Actor an sich selbst sendet — und alles andere an seine Ref, das keinen seiner eigenen Kinds trifft, auch den Body eines entfernten Knotens. Default: ein Warn mit der Klasse der Nachricht (nie ihrem Payload), dann this.unhandled(message) — ein Dead Letter, der diesen Actor nennt, gezählt in actor_unhandled_total{class}.
onTerminated(signal: Terminated)Ein Aktor, den du mit context.watch beobachtest, hat gestoppt. Von BrokerActor geerbt.

onReceive und onCommand sind versiegelt — die Basisklassen dispatchen an die Hooks oben; überschreibe sie nicht. Ein Terminated aus einer eigenen Watch landet bei onTerminated, nicht bei onSelfMessage.

Der Codec wandelt TOut-Nachrichten in Wire-Frames und Wire-Frames zurück in TIn-Nachrichten. Der Default ist jsonCodec():

import { jsonCodec } from 'actor-ts/http';
new Feed(); // uses jsonCodec() — text frames <-> JSON
// With runtime validation (zod etc.):
class Validated extends WebsocketClientActor<ClientMessage, ServerMessage> {
constructor() {
const webSocketClientOptions = WebsocketClientOptions.create<ClientMessage, ServerMessage>()
.withUrl('wss://...')
.withCodec(jsonCodec<ClientMessage, ServerMessage>({
validate: (value: unknown): ServerMessage => ServerMessageSchema.parse(value),
}));
super(
webSocketClientOptions,
);
}
onMessage(message: ServerMessage): void { /* already validated */ }
}

Für Binärprotokolle ist rawCodec() die Ausweichluke — TOut = TIn = WebsocketFrame, sodass du rohe Text-/Binär-Frames selbst behandelst:

import { match } from 'ts-pattern';
import { rawCodec, type WebsocketFrame } from 'actor-ts/http';
class Binary extends WebsocketClientActor<WebsocketFrame, WebsocketFrame> {
constructor() {
const webSocketClientOptions = WebsocketClientOptions.create<WebsocketFrame, WebsocketFrame>()
.withUrl('wss://...')
.withCodec(rawCodec());
super(webSocketClientOptions);
}
onMessage(frame: WebsocketFrame): void {
match(frame)
.with({ kind: 'binary' }, (f) => this.onBinary(f))
.otherwise(() => {});
}
private onBinary(frame: BinaryFrame): void {
this.handleBytes(frame.data); // Uint8Array
}
}

Ein WebsocketFrame ist { kind: 'text'; data: string } oder { kind: 'binary'; data: Uint8Array }. Dekodier-Fehler werfen einen WebsocketDecodeError; das Frame-Größenlimit (maxFrameBytes) wird am rohen Frame vor dem Dekodieren durchgesetzt.

data ist auf jeder Laufzeitumgebung ein schlichtes Uint8Array. Der Client setzt beim Verbindungsaufbau binaryType des Sockets auf 'arraybuffer', denn die Laufzeitumgebungen sind sich über den Standardwert uneins — Bun liefert einen Node-Buffer, Node und Deno liefern ein Blob —, und ein Blob gibt seine Bytes nur asynchron heraus, was der Eingangspfad nicht bezahlen kann: Darauf zu warten würde die maxFrameBytes-Prüfung hinter einen Microtask schieben und die Garantie aufgeben, dass Frames in Ankunftsreihenfolge bei onMessage landen. Zwei Folgen sind wissenswert. Die Bytes gehören immer dem Frame selbst und sind nie ein Ausschnitt aus einem gepoolten Puffer, frame.data.buffer darfst du also weiterreichen. Und der Wert ist auch auf Bun ein Uint8Array und kein Buffer — für toString('hex') und Verwandte greifst du also zu Buffer.from(frame.data).

Ein zu großer Frame schließt die Verbindung mit Code 1009 (“Message Too Big”) und startet den üblichen Reconnect, statt an Ort und Stelle verworfen zu werden. Sei dir im Klaren darüber, was das bringt und was nicht: Die Allokation verhindert es nicht. Anders als die Server-Backends hat der Client kein Transport-Limit, an das er die Grenze durchreichen könnte — kein natives WebSocket der unterstützten Runtimes beachtet ein Payload-Limit, das man seinem Konstruktor übergibt. Wenn maxFrameBytes geprüft wird, hat die Runtime den Frame also längst vollständig auf dem Heap zusammengesetzt. Was das Schließen bringt: Das Gegenüber kann diesen Heap nicht erneut auf derselben Verbindung ausgeben — ohne den Close ließe sich eine einzige Verbindung dazu bringen, die Allokation für jeden beliebigen weiteren Frame zu wiederholen. Eine weitere Runde kostet das Gegenüber jetzt einen vollständigen Reconnect — und nur das. Ein gelungener Connect setzt den reconnect-Backoff zurück und zählt für einen Circuit Breaker als Erfolg, sodass keins von beiden ein Gegenüber bremst, das jeden Connect annimmt und dann einen übergroßen Frame schickt: Der Client ist etwa alle initialDelayMs wieder bei ihm. Siehe Untrusted Input begrenzen.

Begleitet wird der Close von einer Warnzeile. Sie benennt die Verbindung mit einem redigierten Label (wss://feed.example.com/ws/orders) statt mit url: Userinfo und Query-String fallen weg, denn ein WebSocket-Endpunkt wird üblicherweise mit einem ?token=… authentifiziert, und der Pfad bleibt erhalten, weil er zwei Verbindungen zum selben Host unterscheidet. Eine URL mit einem @ hinter dem Host — in einem Pfad wie /rooms/@general oder in einem Query-Token — heißt stattdessen wss://***: Dieselben Bytes könnten ein Passwort sein, und der Host hinter dem @ wäre dann der falsche. Dieselbe Maskierung steht deinem eigenen Code als redactedUrlLabel zur Verfügung.

Eine unerwartete Trennung übernimmt der BrokerActor-Lifecycle:

  • Der Actor wechselt in disconnected und löst BrokerDisconnected auf dem Event-Stream aus.
  • Der Reconnect-Zyklus startet, mit exponentiellem Backoff gemäß den reconnect-Settings (initialDelayMs, maxDelayMs, factor, maxAttempts) — gejittert um randomFactor (Default ±20 %), damit eine Flotte nicht im Gleichschritt reconnectet.
  • Nach einem erfolgreichen Reconnect läuft onConnected() und BrokerConnected wird ausgelöst.

Ausgehende Nachrichten, die während der Trennung gesendet werden, werden gemäß der Outbound-Buffer-Policy gepuffert und nach dem Reconnect erneut gesendet.

Einen Circuit Breaker gibt es erst, wenn circuitBreaker einen nennt, und maxAttempts ist standardmäßig Infinity — für sich genommen wird ein toter Endpoint also endlos wiederholt, im Backoff von oben. Mit einem Breaker hört der Client nach max-failures fehlgeschlagenen Connects in Folge für das Fenster des Breakers auf zu wählen und schickt danach eine einzige Probe. Clients, die sich die Id teilen, machen höchstens einen Versuch je Fenster, und eine Probe antwortet nur so lange für alle, wie ein fehlschlagender Connect kurz ist gegenüber der Streuung ihres Aufwachens — ein Connect, der hängt, läuft noch, wenn der nächste Client aufwacht, und der probt ebenfalls (siehe Circuit Breaker). Er versucht es weiterhin, solange maxAttempts es erlaubt; der Breaker streckt die Versuche, er beendet sie nicht.

pingIntervalMs startet einen Keep-Alive-Timer, damit ein zwischengeschalteter Proxy oder Load-Balancer die Verbindung nicht wegen Untätigkeit schließt. Was dieser Timer sendet, lieferst du selbst — überschreibe dazu keepAliveFrame():

class KeepAlive extends WebsocketClientActor<ClientMessage, ServerMessage> {
constructor() {
const webSocketClientOptions = WebsocketClientOptions.create<ClientMessage, ServerMessage>()
.withUrl('wss://...')
.withPingIntervalMs(30_000)
.withIdleTimeoutMs(90_000);
super(webSocketClientOptions);
}
protected override keepAliveFrame(): WebsocketFrame {
return { kind: 'text', data: JSON.stringify({ kind: 'heartbeat' }) };
}
onMessage(message: ServerMessage): void {}
}

Der Frame umgeht den Codec — kodiere ihn selbst. Das Framework liefert bewusst keinen Default-Frame: erfundene Bytes wären eine unangekündigte Nachricht in deinem Protokoll, und ein Peer, der bei einer unbekannten Nachricht schließt, würde von seinem eigenen Keep-Alive gekappt.

Ein Keep-Alive wird direkt auf den offenen Socket geschrieben, niemals über den Outbound-Buffer. Es ist nicht sendRaw() unter anderem Namen, und der Unterschied zeigt sich genau dann, wenn die Verbindung in Schwierigkeiten ist. Ein Tick, der keine offene Verbindung vorfindet, sendet überhaupt nichts: er wird nicht gepuffert, solange die Verbindung getrennt ist, nach dem Reconnect nicht erneut gesendet und belegt nie einen Slot, den eine Anwendungsnachricht innehatte. Ein wiederholt gesendetes Heartbeat wäre ein Keep-Alive für eine Verbindung, die es nicht mehr gibt, gemessen gegen eine bereits verstrichene Periode — und bei vollem Buffer würde es dafür eine echte Nachricht verdrängen. Ein Frame, den du sehr wohl erneut gesendet haben willst, gehört in sendRaw(), das genau das Gegenteil zusagt.

Ohne die Überschreibung hat der Timer womöglich nichts zu senden. Er fällt dann auf das native WebSocket.ping() der Runtime zurück, und das ist ein Control-Frame auf Protokollebene, den es nur auf Bun gibt — das WHATWG-WebSocket von Node und Deno hat überhaupt keine ping()-Methode. Auf diesen beiden Runtimes kann ein nicht überschriebener Hook nichts senden; der Client startet deshalb keinen Timer und schreibt stattdessen zur Connect-Zeit eine einzige Warnung (#751). Ein Timer, der nachweislich nichts sendet, ist schlechter als gar keiner: er ist genau das, was dich glauben lässt, die Verbindung werde warm gehalten.

Nur ein Frame auf Anwendungsebene erreicht einen Proxy, der Payloads statt Frames inspiziert, und nur ein Frame auf Anwendungsebene zählt gegen die Lese-Deadline des Peers — ein Pong auf Protokollebene wird auf keiner unterstützten Runtime an den message-Listener zugestellt.

Kombiniere es mit idleTimeoutMs (nächster Abschnitt). Ein Keep-Alive verhindert, dass ein Proxy eine untätige Verbindung schließt; nur die Lese-Deadline bemerkt eine, die trotzdem gekappt wurde.

Ein Ping verhindert, dass ein Proxy die Verbindung schließt. Er sagt dir nicht, wann eine trotzdem gekappt wurde — ein verfallener NAT-Eintrag, ein Load-Balancer, der den Flow vergessen hat, ein mit SIGKILL beendeter Peer. Keine Seite wird benachrichtigt, also feuern close und error nie, onDisconnected läuft nie, und der Actor meldet connected, während jedes send ins Leere geht.

idleTimeoutMs ist die Deadline, die diesen Zustand beendet:

const webSocketClientOptions = WebsocketClientOptions.create<ClientMessage, ServerMessage>()
.withUrl('wss://realtime.example.com/feed')
.withIdleTimeoutMs(90_000) // no inbound frame for 90 s → reconnect
.withConnectTimeoutMs(10_000); // handshake stalled for 10 s → fail the attempt

Läuft sie ab, wird der Socket geschlossen, onDisconnected läuft mit einer idle timeout-Ursache, und der gewöhnliche Reconnect-Zyklus startet — derselbe Pfad, den ein beobachtetes close nimmt.

Gezählt werden Anwendungsnachrichten, keine Pongs. Ein Pong auf Protokollebene wird auf keiner unterstützten Runtime als message-Event zugestellt, pingIntervalMs frischt diese Deadline also nicht auf. Bemiss idleTimeoutMs am Heartbeat-Intervall des Servers, nicht an deinem Ping-Intervall; darunter kappt die Deadline gesunde Verbindungen in Endlosschleife. Genau deshalb ist sie standardmäßig aus.

connectTimeoutMs deckt das andere Ende ab: der Handshake endet nur über open oder error, also hält ein Server, der die TCP-Verbindung annimmt und den Upgrade nie abschließt, den Actor unbegrenzt in connecting.

Alles, was auf dieser Seite bisher Backpressure hieß, regelt die ausgehende Richtung: den Sende-Buffer, maxBufferedBytes, die BackpressurePolicy. Auf der Empfangsseite hat der Client per Default gar keine Flusskontrolle — jeder Frame wird dekodiert und in dem Moment an die Mailbox gereicht, in dem er ankommt. Ein Peer, der schneller publiziert, als onMessage abarbeitet, findet nichts, wogegen er drücken könnte, und eine begrenzte Mailbox verwirft dann dekodierte Anwendungsnachrichten — genau das Falsche.

Eine eingehende Hochwassermarke pausiert stattdessen den Socket, sodass TCP das Zurückdrücken übernimmt:

const webSocketClientOptions = WebsocketClientOptions.create<ClientMessage, ServerMessage>()
.withUrl('wss://realtime.example.com/feed')
.withInboundHighWaterMark(256) // frames queued in the mailbox before pause()
.withInboundLowWaterMark(64); // resume() once the backlog is down to this

Gezählt werden dekodierte Frames, die in der Mailbox warten — an den Actor gereicht, aber noch nicht an onMessage. An der Hochwassermarke wird der Socket pausiert; sobald der Rückstau auf die Niedrigwassermarke abgebaut ist, läuft er weiter. Die Niedrigwassermarke ist per Default ein Viertel der hohen, und am ersten freien Platz weiterzulaufen ist bewusst nicht der Default: der Socket würde pro Frame zwischen pausiert und lesend flattern.

In der Praxis nur Bun. pause() und resume() gibt es auf dem Client-WebSocket von Bun 1.4.1+ und weder auf dem WHATWG-WebSocket von Node noch dem von Deno. Der Actor prüft den Socket, nicht den Runtime-Namen; fehlt das Paar, bleibt es beim Verhalten oben und er sagt das beim Verbinden einmal — ein Limit, das angewendet aussieht und es nicht ist, ist schlimmer als keins.

websocket_client_inbound_paused_seconds_total summiert die Zeit, die der Socket pausiert war, sodass der Zustand beobachtbar ist statt aus einem Stau auf der Gegenseite gefolgert.

Client-Defaults lassen sich unter actor-ts.io.broker.websocket setzen:

actor-ts.io.broker.websocket {
url = "wss://realtime.example.com/feed"
protocols = ["my-proto-v1"]
ping-interval = 30s
idle-timeout = 90s
connect-timeout = 10s
max-frame-bytes = 1M
inbound-high-water-mark = 256 # pause the socket at this many queued inbound frames (Bun 1.4.1+)
inbound-low-water-mark = 64 # resume once the backlog is down to this many
on-invalid-message = "drop" # drop | hook | disconnect
reconnect { initial-delay = 500ms, max-delay = 30s, factor = 2.0, random-factor = 0.2 } // max-attempts omitted = unlimited (the default)
circuit-breaker = "realtime-feed" // a breaker id; none when unset (the default)
outbound-buffer = 1000 // messages held while disconnected; 0 = fail-fast
}
actor-ts.circuit-breaker.realtime-feed { max-failures = 5, reset-timeout = 30s }

Die Präzedenz folgt der Broker-Konvention: Konstruktor-Argument > HOCON > eingebaute Defaults.

Einige Hinweise zu diesem Block.

Jedes Blatt ist das kebab-case seiner Option ohne Einheiten-Suffix, die drei Intervalle sind also Dauern und max-frame-bytes ist eine Größe. Die camelCase-Schreibweisen, die diese Blätter vorher hatten — pingIntervalMs, maxFrameBytes und die übrigen —, werden mit einem ConfigError abgelehnt, der den neuen Key nennt, statt ignoriert zu werden: Gerade die Frame-Grenze fiele sonst still auf ihren Default zurück. Der Client ist ein Broker-Actor, die Ablehnung kommt also, wenn er startet, in seinem preStart — nicht bei ActorSystem.create.

circuit-breaker enthält die Id eines Breakers, nicht seine Einstellungen: Die gehören unter actor-ts.circuit-breaker.<id>, wie in der letzten Zeile, über die Defaults, die sich alle Breaker teilen. Ein Block an seiner Stelle — das alte circuit-breaker { failure-threshold, reset } oder die eigenen Blätter des Breakers unter dem Root des Clients — wird beim Start abgelehnt, mit dem Hinweis auf die Id-Form.

on-invalid-message hat ein Gegenstück auf der Server-Seite, actor-ts.http.websocket.on-invalid-message, und dessen Werteliste ist nicht dieselbe — dort heißt der dritte Wert close, hier disconnect. Die beiden lassen sich also nicht voneinander abschreiben.

codec hat gar keinen Config-Key: es ist ein Paar von Funktionen, und eine Funktion kann nicht aus einer Config-Datei kommen.

Drei primäre Einsatzfälle:

  1. Echtzeit-Datenfeeds subscribieren — Aktien-Ticker, Krypto-Börsen, Social-Media-Streams.
  2. Ausgehende WebSocket-Clients zu Drittservices (Slack RTM, Streaming-LLM-APIs, IoT-Vendor-APIs).
  3. Eigene WS-basierte Protokolle, die darauf aufsetzen — nutze rawCodec() für binäre Wire-Formate.

Für serverseitiges WebSocket (Client-Verbindungen annehmen) siehe die Server-WebSocket-Seite.

  • I/O-Übersicht — das große Bild.
  • Server-WebSocket — die websocket()-Direktive + WebsocketServerActor.
  • SSE — Server-Sent Events als einseitige Streaming-Alternative.
  • BrokerActor-Basis — der gemeinsame Reconnect-/Buffer-/Circuit-Breaker-Lifecycle.