Zum Inhalt springen
actor-ts
Deutsch

WebSocket (Client)

WebSocketActor öffnet eine clientseitige WebSocket-Verbindung zu einem Remote-Endpoint. Zum Annehmen eingehender WS-Verbindungen (Serverseite) siehe ServerWebSocketActor.

import { ActorSystem, Props, WebSocketActor } from 'actor-ts';


const ws = system.spawn(
  Props.create(() => new WebSocketActor({
    url: 'wss://realtime.example.com/feed',
    protocols: ['my-proto-v1'],
    headers: {
      authorization: `Bearer ${process.env.API_TOKEN}`,
    },
  })),
  'ws-client',
);


// Eingehende Nachrichten subscribieren:
ws.tell({ kind: 'subscribe', subscriber: feedHandler });


// Senden:
ws.tell({ kind: 'send', payload: JSON.stringify({ subscribe: 'channel-1' }) });

Settings

Abschnitt betitelt „Settings“
interface WebSocketActorSettings extends BrokerCommonSettings {
  url:        string;                        // ws:// oder wss://
  protocols?: string | string[];             // Subprotokolle
  headers?:   Record<string, string>;        // Header für den initialen Handshake
  pingIntervalMs?: number;                   // Ping auf Anwendungsebene; Default aus
}

Eingehende Nachrichten

Abschnitt betitelt „Eingehende Nachrichten“
import { match } from 'ts-pattern';


class FeedHandler extends Actor<WsInbound> {
  override onReceive(msg: WsInbound): void {
    match(msg)
      .with({ kind: 'text' },   (m) => this.handleEvent(JSON.parse(m.payload)))
      .with({ kind: 'binary' }, (m) => this.handleBinary(m.payload))   // rohe Uint8Array
      .exhaustive();
  }
}

Zwei eingehende Arten — text und binary — passend zu den WebSocket-Frame-Typen. Das Framework dispatched nicht nach Payload-Inhalt; das ist Sache des Subscribers.

Auto-Reconnect

Abschnitt betitelt „Auto-Reconnect“

Der gemeinsame BrokerActor-Lifecycle übernimmt Reconnect mit Backoff. Eine unerwartete Trennung:

  • Versetzt den Actor in disconnected.
  • Löst BrokerDisconnected auf dem Event-Stream aus.
  • Startet den Reconnect-Zyklus.
  • Nach jedem erfolgreichen Reconnect löst BrokerConnected aus.

Ausgehende Nachrichten, die während der Trennung gesendet werden, werden gepuffert (gemäß Outbound-Buffer-Policy). Eingehende Subscriber bleiben über Reconnects hinweg erhalten.

Ping / Keep-Alive

Abschnitt betitelt „Ping / Keep-Alive“
new WebSocketActor({
  url: 'wss://...',
  pingIntervalMs: 30_000,   // alle 30s einen Ping senden
});

Ein Ping auf Anwendungsebene verhindert, dass zwischengeschaltete Proxies / Load-Balancer Idle-Verbindungen schließen. Die meisten produktiven WebSocket-Setups brauchen das.

Der WebSocket-Ping auf Protokollebene (Control-Frame) wird automatisch gesendet; der Ping auf Anwendungsebene ist für Proxies, die Payloads inspizieren, keine Frames.

Wann einsetzen

Abschnitt betitelt „Wann einsetzen“

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, OpenAI-Streaming, IoT-Vendor-APIs).
  3. Eigene WS-basierte Protokolle, die darauf aufsetzen.

Für serverseitiges WebSocket (Client-Verbindungen annehmen) nimm ServerWebSocketActor.

Wohin als Nächstes

Abschnitt betitelt „Wohin als Nächstes“