Zum Inhalt springen
Deutsch

Server-WebSocket

Serverseitiges WebSocket ist Teil des HTTP-Route-DSL. Die websocket()-Direktive upgradet passende Requests und verbindet jede Verbindung mit einem einzelnen WebsocketServerActor — dem Hub — den du implementierst. Für ausgehende Client-Verbindungen siehe WebsocketClientActor.

import {
ActorSystem,
} from 'actor-ts';
import {
HttpExtensionId,
WebsocketServerActor,
websocket,
type WebsocketConnection,
} from 'actor-ts/http';
import { match } from 'ts-pattern';
type SetNameMessage = { kind: 'setName'; name: string };
type SayMessage = { kind: 'say'; text: string };
type ClientMessage = SetNameMessage | SayMessage;
type ServerMessage = { kind: 'system'; text: string } | { kind: 'chat'; from: string; text: string };
class ChatRoom extends WebsocketServerActor<ServerMessage, ClientMessage> {
private readonly names = new Map<string, string>();
onMessage(message: ClientMessage): void {
match(message)
.with({ kind: 'setName' }, (m) => this.onSetName(m))
.with({ kind: 'say' }, (m) => this.onSay(m))
.exhaustive();
}
private onSetName(m: SetNameMessage): void {
this.names.set(this.connection.id, m.name);
this.reply({ kind: 'system', text: `hi ${m.name}` });
}
private onSay(m: SayMessage): void {
this.broadcast({ kind: 'chat', from: this.names.get(this.connection.id) ?? 'anon', text: m.text });
}
override onClientDisconnected(c: WebsocketConnection<ServerMessage>): void {
this.names.delete(c.id);
}
}
const system = ActorSystem.create('chat');
const chat = system.spawn(ChatRoom, 'chat');
await system.extension(HttpExtensionId)
.newServerAt('0.0.0.0', 8080)
.bind(websocket('/ws', chat));

Die Typparameter des Hubs sind aus Sicht des Servers zu lesen: TOut = die Nachrichten, die der Server sendet, TIn = die dekodierten Nachrichten, die er empfängt.

websocket() erzeugt eine Route und komponiert daher mit dem restlichen Route-DSL — path(), concat() und withMiddleware(). Zwei Formen:

import { websocket, path, concat } from 'actor-ts/http';
// 1. Bare directive — mount it under a path yourself:
path('ws', websocket(chat));
// 2. Path sugar — equivalent to path(p, websocket(target)):
websocket('/ws', chat);
// Mixed with normal HTTP routes on the same server:
concat(
path('api', apiRoutes),
websocket('/ws', chat),
);
type WebsocketRouteOptions<TOut, TIn> = {
codec?: WebsocketCodec<TOut, TIn>; // default jsonCodec()
maxFrameBytes?: number; // default 1 MiB
onOversizeFrame?: 'close' | 'drop'; // default 'close' (1009)
onInvalidMessage?: 'close' | 'drop' | 'hook'; // default 'close' (1003)
maxBufferedBytes?: number; // default 4 MiB
onBackpressure?: 'drop' | 'close'; // default 'drop'
allowedOrigins?: string[]; // CSWSH defence — see below
requireSameOrigin?: boolean; // CSWSH defence; default true — see below
maxConnections?: number; // concurrent-connection cap; default unlimited
maxPreAttachFrames?: number; // setup-window frame cap; default 256
maxPreAttachBytes?: number; // setup-window byte cap; default 4 MiB
acceptTimeoutMs?: number; // setup deadline; default 10 000, Infinity to disable
connectionMailboxCapacity?: number; // per-connection queue bound; default unset (global bound)
connectionMailboxOverflow?: 'drop-head' | 'drop-new' | 'reject'; // needs a capacity
};
const webSocketRouteOptions = WebsocketRouteOptions.create()
.withMaxFrameBytes(256 * 1024)
.withOnOversizeFrame('close') // close with 1009 Message Too Big
.withOnInvalidMessage('close');
websocket('/ws', chat, webSocketRouteOptions); // close with 1003 Unsupported Data

Das Frame-Größenlimit wird am rohen Frame vor dem Dekodieren durchgesetzt. onInvalidMessage: 'hook' leitet Dekodier-Fehler an den onInvalidMessage-Hook des Actors weiter, statt zu schließen.

maxFrameBytes wird zweimal geprüft, zu zwei verschiedenen Zeitpunkten:

  • Im Transport, bei deinem aufgelösten maxFrameBytes — das Framework reicht es beim Binden an den Socket der Laufzeit weiter. Ein größerer Frame wird abgewiesen, während er eintrifft; ein feindlicher Peer kann den Prozess also nicht dazu bringen, 16 MiB (Bun) oder 100 MiB (ws) zu puffern, nur damit das Ergebnis anschließend verworfen wird. Weil die Laufzeit dabei auflegt, statt einen Policy-Close zu senden, sieht der Client hier einen abnormalen Close (1006) und keine 1009. Zwei Laufzeit/Backend-Paare haben diese Ebene nicht — siehe den Warnhinweis weiter unten.
  • Im Connection-Actor, bei demselben maxFrameBytes — am vollständig empfangenen Frame, vor dem Dekodieren, mit Close 1009.

Nur die zweite Ebene ist eine Zusage. Sie läuft überall und hält den zu großen Frame von deinem Actor fern; das Transport-Limit ist eine Optimierung darüber, die dem Prozess die Pufferung erspart.

Die Zahl ist in beide Richtungen deine: maxFrameBytes zu senken verkleinert auch das Puffer-Fenster, und es über den 1-MiB-Default anzuheben, lässt Frames dieser Größe tatsächlich durch. Aufgelöst wird wie üblich — Route-Options, dann actor-ts.http.websocket.max-frame-bytes, dann der eingebaute Default —, und zwar beim Binden des Servers; ein ungültiger Wert ist damit ein Fehler in bind() und nicht erst beim ersten Upgrade.

Das Transport-Limit gilt pro Server, nicht pro Route. Ein Server hat genau einen Transport für alle seine WebSocket-Routen (ein WebSocketServer auf Express, eine Plugin-Registrierung auf Fastify, ein Bun.serve). Wo mehrere Routen sich unterscheiden, nimmt der Transport deshalb das größte ihrer Limits. Was eine strengere Route annimmt, ändert das nicht — der Connection-Actor weist ihre zu großen Frames weiterhin mit 1009 ab —, sie bekommt nur nicht das engere Puffer-Fenster, das sie allein gehabt hätte.

Das ist eine Entscheidung und keine Lücke. Fastify und Bun.serve können immer nur ein einziges Limit halten; Express könnte strukturell eines pro Route halten, und es dort zu tun hieße, dass dieselbe Konfiguration je nach Backend etwas anderes bedeutet — bei einem Limit, dessen ganze Aufgabe es ist zu begrenzen, was eine feindliche Gegenstelle allozieren kann, ist eine Form überall mehr wert als ein engeres Fenster auf einem Backend von dreien.

Zwischen dem Abschluss des Handshakes und dem Moment, in dem der Connection-Actor seine Listener anhängt, liegt ein kurzes Fenster — zwei Mailbox-Schritte —, in dem der Socket lebt und niemand mitliest. Frames, die darin ankommen, werden gehalten und in dem Moment nachgespielt, in dem der Actor anhängt; verloren geht also nichts. Zwei Stellschrauben begrenzen, was dieses Fenster kosten darf, und beide gibt es, weil sein Ende nicht garantiert ist: den Actor spawnt der Hub, und ein Hub, der gestoppt wurde, hängt oder umkonfiguriert wurde, liefert unter Umständen nie einen.

  • maxPreAttachFrames / maxPreAttachBytes begrenzen, was gehalten wird. Jenseits davon wird der Socket mit 1013 (“try again later”) geschlossen statt weiter gepuffert. Ein legitimer Client schickt in dieses Fenster nichts oder eine Begrüßung, die Defaults — 256 Frames, 4 MiB — liegen also um Größenordnungen über normalem Verkehr; abgewiesen wird ein Peer, der in eine noch gar nicht angenommene Verbindung hineinstreamt. Der erste Frame wird immer angenommen, unabhängig von seiner Größe (maxFrameBytes begrenzt ihn ohnehin bereits) — eine Route, die maxFrameBytes über 4 MiB hebt, muss maxPreAttachBytes also nur mitheben, wenn ihre Clients mehrere solcher Frames auf einmal senden.
  • acceptTimeoutMs begrenzt, wie lange das Fenster offen bleiben darf. Hat sich innerhalb dieser Frist kein Connection-Actor angehängt, wird der Socket mit 1013 geschlossen und sein maxConnections-Platz freigegeben. Standardmäßig zehn Sekunden: ein gesunder Hub hängt sich in Mikrosekunden an, das hier ist also ein Auffangnetz und keine Liveness-Regel — und ein Actor, der nach der Frist doch noch auftaucht, bekommt das Close statt eines Sockets, den das Framework längst geschlossen hat. Infinity schaltet es ab.

Beides ist nicht versehentlich erreichbar. Beides beantwortet dieselbe Störung: ein aufgewerteter Socket ohne Actor dahinter, der vorher für die Lebensdauer des Prozesses offen blieb, Frames sammelte, die niemand je abholt, und einen Platz belegte, den niemand je zurückgibt.

Ein beschäftigter Hub ist diese Störung nicht. Das Kommando, das den Actor spawnt, ist eine der Control-Nachrichten des Hubs und wird vor den Frames behandelt, die andere Verbindungen bereits eingereiht haben (siehe Die Mailbox des Hubs begrenzen). Ein Rückstau auf einem Hub mit seiner Default-Mailbox kann ein abgeschlossenes Upgrade also nicht über acceptTimeoutMs hinaus festhalten und zu einem 1013 machen. Ein Hub, der mit withMailbox(...) gespawnt wurde, reiht das Kommando ein wie jede andere Nachricht in dieser Mailbox, und hinter einem FIFO-Rückstau, dessen Abarbeitung länger als acceptTimeoutMs dauert, wird die neue Verbindung weiterhin mit 1013 geschlossen.

Browser hängen die Cookies des Nutzers automatisch an einen WebSocket-Upgrade an — eine WS-Route mit ambienter Authentifizierung (Session-Cookie oder IpAllowlist) ist damit anfällig für Cross-Site-WebSocket-Hijacking: eine fremde Seite öffnet new WebSocket('wss://dein-host/ws') und nutzt die Credentials des Opfers.

Zwei Regeln sichern den Handshake über den Origin-Header des Browsers ab, und sie ergänzen sich — ein Upgrade kommt durch, sobald eine von beiden es zulässt.

requireSameOrigin lässt einen Origin zu, der diesen Server selbst benennt, indem es ihn mit dem Host des Requests vergleicht. Es braucht keinerlei Konfiguration — genau deshalb ist es der Default: eine Route bekommt die Prüfung, ohne dass ihr Autor die Option kennen muss.

websocket('/ws', chat); // same-origin required

Verglichen wird nur der Host, denn Host trägt kein Schema. Ein Reverse-Proxy, der Host, aber nicht Origin umschreibt, fällt deshalb durch die Prüfung — trag dort die echten Origins in allowedOrigins ein. Nur den Host zu vergleichen heißt zugleich schemablind: eine http://-Seite auf demselben host:port kommt durch, die Regel ersetzt also nicht, Klartext abzulehnen.

Beide Header kommen vom Client, und das begrenzt, was die Regel zusagen kann. Eine Seite, die diesen Server unter einem eigenen Namen erreicht (DNS-Rebinding), sendet Origin und Host übereinstimmend und kommt damit durch den Same-Origin-Arm. Das ist die übliche Schwäche jeder Same-Origin-Prüfung auf Basis von Host, und genau dafür gibt es allowedOrigins. Gewonnen ist damit Erreichbarkeit, keine Session: der Browser hängt keine Cookies des echten Hosts an — relevant ist also eine Route, deren Authentifizierung das Netz selbst ist (IpAllowlist oder Vertrauen auf Loopback). Trag bei so einer Route die erwarteten Origins in allowedOrigins ein, statt dich auf diesen Arm zu verlassen.

Dafür, dass die Seite, die den Socket öffnet, woanders ausgeliefert wird:

const wsOptions = WebsocketRouteOptions.create()
.withAllowedOrigins(['https://app.example.com']);
websocket('/ws', chat, wsOptions);

Ein Upgrade, dessen Origin vorhanden ist, aber zu keiner der beiden Regeln passt, wird auf allen drei Backends vor dem Handshake mit 403 abgelehnt. Der Vergleich ist case-insensitiv.

Fehlender Origin — Nicht-Browser-Clients bleiben unberührt

Abschnitt betitelt „Fehlender Origin — Nicht-Browser-Clients bleiben unberührt“

Ein fehlender Origin wird von beiden Regeln zugelassen. Ein WebSocket aus Node, Bun oder Deno und jeder Server-zu-Server-Dialer sendet überhaupt keinen Origin-Header, sodass nichts davon sie betrifft: CSWSH nutzt die ambienten Credentials eines Opfer-Browsers, und ein Browser sendet den Header immer. Das macht den Default gefahrlos einschaltbar — abgewiesen wird neuerdings Browser-Verkehr von einer Seite, die du nicht ausgeliefert hast.

const wsOptions = WebsocketRouteOptions.create()
.withRequireSameOrigin(false);
websocket('/ws', chat, wsOptions); // no origin check at all

withRequireSameOrigin(false) zusammen mit withAllowedOrigins([...]) behält die Allowlist und entfernt nur den Same-Origin-Arm. Ohne Allowlist bleibt die Route ganz ohne Origin-Prüfung — das Verhalten vor #756, und einen Kommentar wert, der festhält, welche Credential-Form das unbedenklich macht.

BearerTokenAuth ist so eine Form: bereits geschützt, weil Browser beim WS-Handshake keinen Authorization-Header setzen können. Die Origin-Regeln sind v. a. bei Cookie- oder IP-basierter Auth relevant.

withMiddleware() komponiert mit websocket(), aber die Middleware läuft einmal, zur Upgrade-Zeit, gegen den HTTP-Upgrade-Request — nicht pro WebSocket-Nachricht. Eine ablehnende Middleware gibt einen normalen HTTP-Fehler zurück und das Upgrade kommt nie zustande, sodass Auth-Middleware wie BearerTokenAuth oder IpAllowlist den Handshake absichert:

import { websocket, withMiddleware } from 'actor-ts/http';
withMiddleware(BearerTokenAuth({ /* ... */ }), websocket('/ws', chat));
// A bad token → HTTP 401, no upgrade. A good token → the socket opens.

Die Middleware-Sammlung steht in der HTTP-Übersicht.

Antwort-dekorierende Middleware funktioniert ebenfalls

Abschnitt betitelt „Antwort-dekorierende Middleware funktioniert ebenfalls“

Middleware, die next() aufruft und eine dekorierte Kopie des Ergebnisses zurückgibt — securityHeaders(), contentSecurityPolicy(), strictTransportSecurity(), requestId(), csrfProtection() —, komponiert ebenso über einer websocket()-Route. Ein einziges Wrap kann damit einen ganzen Baum härten, ohne den Socket herauszuschneiden:

import { requestId, securityHeaders, websocket, withMiddleware } from 'actor-ts/http';
withMiddleware(securityHeaders(), withMiddleware(requestId(), websocket('/ws', chat)));
// Both run at upgrade time. The socket opens.

Die Header, die solche Middleware setzt, erreichen einen erfolgreichen Handshake nicht — diese 101-Antwort schreibt das Backend selbst, und eine WebSocket-Verbindung ist kein Dokument, auf das ein Browser X-Frame-Options oder eine CSP anwenden würde. Auf einer Ablehnung fahren sie dagegen mit: Ein 401 einer inneren BearerTokenAuth kommt mit den Security-Headern zurück — und genau das ist der Fall, auf den es ankommt, denn diese Antwort rendert ein Browser tatsächlich.

Middleware reicht den Handlern darin Werte als Request-Attribute weiter — next(withAttribute(request, key, value)) —, und so liefert JwtAuth die Claims, die es geprüft hat. Um eine websocket()-Route herum erreichen diese Werte die Verbindung nicht: Die Middleware läuft innerhalb der Upgrade-Prüfung, und das Backend übergibt der Verbindung den Upgrade-Request, den es selbst adaptiert hat — die Upgrade-Info, die ein Hub sieht, trägt Pfad, Query und Header, nicht die Attribute. Den Handshake sichert die Middleware trotzdem: Ein Token, das JwtAuth ablehnt, wird mit 401 beantwortet, und kein Socket öffnet sich.

withMiddleware() ist der portable Weg — auf jedem Backend identisch —, aber ein Handshake ist auch für das darunterliegende Framework ein ganz normaler Request, und dessen eigene Middleware läuft ebenfalls:

BackendWas beim Handshake zusätzlich läuft
FastifyRoute-Hooks, inklusive preValidation
Expressalles, was mit app.use(...) registriert wurde
Honoalles, was mit app.use(...) registriert wurde

Eine App, die /ws mit app.use(requireLogin) absichert, ist also wirklich abgesichert, und eine native Middleware, die den Request beantwortet, lehnt das Upgrade ab. Der Guard des Frameworks läuft nach allen anderen — withMiddleware() und allowedOrigins haben damit immer das letzte Wort.

Nimm withMiddleware(), wenn sich eine Route über alle Backends hinweg gleich verhalten soll; greif zu nativer Middleware, wenn du ein bestehendes Ökosystem weiterverwendest (Sessions, Rate Limiting, Observability).

Ein Actor pro Route — der Hub. Er sieht die Events jeder Verbindung, serialisiert:

abstract class WebsocketServerActor<TOut, TIn, TSelf = never> {
// You implement:
abstract onMessage(message: TIn): void | Promise<void>;
// Optional overrides:
protected onClientConnected(client: WebsocketConnection<TOut>): void;
protected onClientDisconnected(client: WebsocketConnection<TOut>, info: WebsocketCloseInfo): void;
protected onInvalidMessage(client: WebsocketConnection<TOut>, error: WebsocketDecodeError): void;
// Default: warn with the message's class, then this.unhandled(message).
protected onSelfMessage(message: TSelf): void;
}

onSelfMessage bekommt, was andere Actors dem Hub tellen (dein TSelf), und alles andere, das keinen der eigenen Kinds des Hubs trifft, auch einen Body, den ein entfernter Knoten an den Pfad des Hubs adressiert hat. Wenn du ihn nicht überschreibst, lehnt er ab: ein warn mit der Klasse der Nachricht, nie ihrem Payload, dann this.unhandled(message), sodass die Nachricht zu einem Dead Letter wird, der den Hub nennt, und in actor_unhandled_total{class} gezählt wird.

Ein Body, der einen der eigenen Kinds des Hubs bloß buchstabiert, landet ebenfalls hier. Der Hub erkennt seine Signale an Feldern, die nur das Framework liefern kann — eine lebende Verbindung, die Factory, die eine spawnt —, und ein dekodierter Peer-Body trägt keins von beiden. Ein { kind: 'websocket-connected', … } von der Leitung kann also keinen Client einschleusen, kein onMessage auslösen und keine Verbindung verdrängen.

Innerhalb von onMessage und den Hooks stehen zur Verfügung:

MemberWas er tut
this.connectionDie WebsocketConnection<TOut>, deren Event gerade verarbeitet wird.
this.reply(message)Sendet message an die aktuelle Verbindung.
this.broadcast(message, filter?)Sendet an jede Verbindung (optional per Prädikat gefiltert).
this.clientsReadonlyMap<string, WebsocketConnection<TOut>> aller aktiven Verbindungen.
this.closeAll(code?, reason?)Schließt jede Verbindung.
onMessage(message: ClientMessage): void {
this.reply({ kind: 'system', text: 'got it' }); // → the sender
this.broadcast({ kind: 'chat', from: 'x', text: 'hi' }); // → everyone
this.broadcast(notice, (c) => c.id !== this.connection.id); // → everyone else
}

Jedes Event einer gegebenen Verbindung wird über den einen Hub-Actor in dieser Reihenfolge serialisiert:

onClientConnected → onMessage* (in frame order) → onClientDisconnected

onClientConnected läuft einmal, dann null oder mehr onMessage-Aufrufe in Frame-Reihenfolge, dann genau ein onClientDisconnected. Da alles auf einem einzelnen Actor läuft, bekommst du die übliche Garantie des Actor-Modells — keine nebenläufige Handler-Ausführung, keine Locks.

Auch über Verbindungen hinweg hält der Hub die Ankunftsreihenfolge ein, mit einer Ausnahme: der Aufbau einer neuen Verbindung — das Kommando, das ihren Actor spawnt, und ihr onClientConnected — wird vor den Frames behandelt, die andere Verbindungen bereits eingereiht haben, und wartet also nie auf deren Rückstau. Siehe Die Mailbox des Hubs begrenzen.

Ein Hub trägt jeden eingehenden Frame jeder Verbindung der Route und ist damit der Musterfall für eine begrenzte Mailbox: ein Actor, der einem Produzenten ausgesetzt ist, den du nicht kontrollierst. Auf ihm läuft aber auch der verbindungsinterne Verkehr des Frameworks, und der wird nicht wie die Frames behandelt.

Ein Hub hat standardmäßig eine Control-Spur. Solange du ihn nicht mit einer eigenen Mailbox spawnst, ist seine Queue eine ControlAwareMailbox, und zwei Nachrichten des Frameworks sind ihre Control-Nachrichten: das Kommando, das nach abgeschlossenem Upgrade den Actor einer Verbindung spawnt, und das Signal onClientConnected, das dieser Actor meldet. Beide werden vor allem behandelt, was bereits eingereiht ist — Frames anderer Verbindungen ebenso wie deine eigenen TSelf-Nachrichten —, eine neue Verbindung wartet also nie darauf, dass der Rückstau einer anderen abgearbeitet ist. Alles andere behält die Ankunftsreihenfolge, deshalb gilt die Reihenfolge pro Verbindung weiter: das onClientDisconnected einer Verbindung läuft nach ihren eigenen eingereihten Frames.

Eine Begrenzung verwirft den Rest, nie diese beiden. Begrenzt du den Hub mit withMailboxCapacity(), mit einem actor-ts.deployment-Eintrag für seinen Pfad ("/user/chat"), wo seine Spawn-Stelle nicht deine ist, oder lässt du actor-ts.mailbox.default.capacity ihn erreichen — in dieser Rangfolge —, gilt die Grenze für Frames, onClientDisconnected und deine TSelf-Nachrichten; das Spawn-Kommando und onClientConnected werden weder gezählt noch verworfen. Ein begrenzter Hub unter Last nimmt also weiterhin jedes Upgrade an und führt jeden neuen Client in this.clients, während eine Flut auf die Kapazität gekürzt wird. Verlieren kann er weiterhin ein Disconnect, und dann bleibt ein Client in this.clients, der längst weg ist — dieser Teil ist dein Protokoll, und nur du weißt, ob ein Verlust akzeptabel ist.

Das Spawn-Kommando ist dasjenige, das nicht verloren gehen darf. Es wird genau einmal gesendet — aus dem Upgrade-Callback des Backends — und trägt die einzige Referenz auf einen Socket, dessen Handshake bereits abgeschlossen ist. Es zu verlieren würde diesen Socket aufgewertet zurücklassen, ohne dass etwas daran hängt: keine Listener, eingehende Frames stapeln sich ungelesen, und sein maxConnections-Platz bleibt belegt, bis der Client aufgibt. Einen Hub, der aus einem anderen Grund nicht antworten kann — er ist gestoppt, oder er kommt nie zu dem Kommando —, fängt stattdessen das Aufbaufenster ab: es schließt den Socket und gibt den Platz zurück.

withMailbox(...) ersetzt die Queue und die Spur gleich mit. Ein Hub, der mit einer eigenen Mailbox gespawnt wurde, behält genau diese Mailbox und die Reihenfolge, die sie allem gibt: auf einer schlichten FIFO-Queue wartet das Spawn-Kommando hinter jedem Frame, der vor ihm eingereiht wurde. Verworfen werden kann es trotzdem nicht — es nimmt die Spur eines Terminated der Death-Watch, die drop-head, drop-new, reject und eine PriorityMailbox alle unangetastet lassen —, aber onClientConnected ist dort eine gewöhnliche Nachricht, und eine Grenze, die in diese Mailbox eingebaut ist, kann es verwerfen.

Für strikte Ankunftsreihenfolge bei allem gibst du dem Hub eine eigene FIFO-Mailbox — und begrenzt sie, denn der Hub ist der Actor, den seine Peers füttern:

const chatMailboxOptions = BoundedMailboxOptions.create()
.withCapacity(1_024)
.withOverflow('drop-head');
const chatOptions = ActorOptions.create().withMailbox(() => new BoundedMailbox(chatMailboxOptions));
const chat = system.spawn(ChatRoom, 'chat', chatOptions);

Eine Mailbox, die du mitgibst, bringt ihre eigene Grenze mit, und keine andere Grenze erreicht sie: ActorOptions lehnt withMailboxCapacity() neben withMailbox() ab, und weder actor-ts.mailbox.default.capacity noch ein Eintrag unter actor-ts.deployment gilt für sie. withMailbox(() => new Mailbox()) hält die Reihenfolge ebenfalls, aber unbegrenzt — ein Hub, der über den globalen Standard begrenzt war, verliert diese Grenze, ohne dass es irgendwo steht.

Der Hub ist nicht die einzige Queue im Spiel. Jede Verbindung hat eine eigene Mailbox — die des internen Connection-Actors —, und connection.tell, sendRaw und close laufen alle in diese. Standardmäßig ist sie unbegrenzt, und eine Route begrenzt sie mit withConnectionMailboxCapacity, dazu withConnectionMailboxOverflow für die Policy — oder, für jede Route, die nichts anderes sagt, mit den Blättern connection-mailbox-capacity und connection-mailbox-overflow unter actor-ts.http.websocket:

const chatRouteOptions = WebsocketRouteOptions.create()
.withConnectionMailboxCapacity(256)
.withConnectionMailboxOverflow('drop-head');
websocket('/chat', chat, chatRouteOptions);

Eine Route, die keins von beiden setzt, überlässt ihre Verbindungen der Konfiguration. Ein "/user/<hub>/ws-*"-Eintrag unter actor-ts.deployment begrenzt die Verbindungen eines Hubs — der Hub nennt sie ws-1, ws-2, … unterhalb seines eigenen Pfads —, und unter diesem Eintrag ist actor-ts.mailbox.default die Grenze, die jeden Anwendungs-Actor auf einmal erreicht. Ist diese globale Grenze eingeschaltet, bekommen die Verbindungen einer Route über den Routenwert eine eigene Größe, größer oder kleiner; ganz von einer Grenze ausnehmen kann er sie nicht, das mailbox-capacity = 0 eines Eintrags dagegen schon. Die Routenwerte stehen über beiden. Die Policy braucht eine Kapazität neben sich, aus der Route oder ihrem Blatt; eine konfigurierte Kapazität — global oder pro Pfad — zählt nicht, und die Route wird schon in bind() abgelehnt statt erst beim ersten Upgrade.

Eine Begrenzung verwirft ausgehende Frames, genau wie eine auf dem Hub eingehende verwirft. drop-head verwirft den ältesten eingereihten Frame, drop-new den ankommenden, und reject weist den ankommenden ab, indem es MailboxFullError auf dem Stack des Senders wirft. Bei reply und broadcast ist das der Stack des Hubs, deshalb fangen beide die Abweisung pro Verbindung ab: Der Frame geht nur für diese eine Verbindung verloren und wird so gezählt, wie drop-new ihn zählen würde, und broadcast macht mit dem nächsten Client weiter. Eine Verbindung, die zurückgefallen ist, kann den Hub nicht zu Fall bringen und mit ihm jede andere Verbindung. Ein connection.tell, das du selbst aufrufst, bekommt den MailboxFullError weiterhin — genau dafür ist reject da, für einen Sender, der es wissen will. Was eine Begrenzung nie verwirft, ist close(): es nimmt dieselbe ausgenommene Spur wie das Accept-Kommando. closeAll() kann also nicht zu einer Reihe von Sockets werden, die still offen bleiben, und reject kann nicht mitten aus dieser Schleife werfen und jeden Client nach dem ersten verbunden lassen. Ein verworfener Frame wird in actor_mailbox_dropped_total gezählt; zum Dead Letter wird er nicht.

Jede Verbindung ist eine WebsocketConnection<TOut>, die ActorRef<TOut> erweitert:

interface WebsocketConnection<TOut> extends ActorRef<TOut> {
readonly id: string;
readonly remoteAddress?: string;
readonly upgrade: WebsocketUpgradeInfo;
readonly isOpen: boolean;
tell(message: TOut): void; // encode via codec + send
sendRaw(frame: WebsocketFrame): void; // bypass the codec
close(code?: number, reason?: string): void; // after what is already queued
abort(code?: number, reason?: string): void; // now, dropping what is queued
}

close() ist eine Anforderung, keine Handlung: es reiht ein Kommando ein, das der Actor der Verbindung in einer späteren Runde ausführt — was davor schon in der Queue steht, etwa ein gerade ge-reply-tes Auf-Wiedersehen, geht also weiterhin zuerst raus. Diese Reihenfolge ist gewollt. Reply-then-close ist die Form, für die close() da ist, und ein Close, das sich vordrängelte, verlöre die Antwort, denn eine Verbindung schreibt nichts mehr, sobald sie geschlossen ist.

abort() ist das Close, das nicht wartet, für einen Peer, den du nicht mehr bedienst: close(1008) würde einem flutenden Client erst alles übergeben, was für ihn schon in der Queue steht. abort() handelt, bevor es zurückkehrt. Die Frames, die noch für die Verbindung in der Queue stehen, werden verworfen — sie werden zu Dead Letters, nie geschrieben — und der Socket wird auf der Stelle geschlossen. Wo das Backend einen Socket hart schließen kann, wie es die ws-basierten Backends Fastify und Express können und Hono unter Bun und Node, sieht der Peer die Verbindung ohne Close-Frame abreißen; auf Hono unter Deno, dessen Socket kein hartes Schließen kennt, erhält er einen Close-Frame mit deinem code und reason. Der Hub bekommt trotzdem genau ein onClientDisconnected, mit diesem code und reason und initiatedBy: 'server', und es kommt weiterhin als Letztes: Frames, die der Peer vor dem Abort geschickt hat und die schon für den Hub in der Queue stehen, erreichen onMessage zuerst. Auf einer Verbindung, die nicht mehr offen ist — nach close(), nach einem früheren abort() oder wenn der Client schon weg ist — tut abort() nichts; die erste Entscheidung über einen Socket bleibt stehen. Sein Code ist standardmäßig 1008 (Policy Violation), der von close() 1000.

Ein Close-Frame trägt einen Code aus einer festen Menge und höchstens 123 Byte Begründung, und beide Methoden senden nur das. Ein Code außerhalb von 1000–1014 und 3000–4999 oder einer der Codes, die dem Melden eines Close vorbehalten sind (1004, 1005, 1006), geht als Standardcode der jeweiligen Methode hinaus — 1000 bei close(), 1008 bei abort() —, und eine längere Begründung wird auf 123 UTF-8-Byte gekürzt, zwischen zwei Zeichen. onClientDisconnected meldet weiterhin den Code und die Begründung, die du übergeben hast. Direkt an den Transport gereicht, ließ beides den Socket auf manchen Backends offen, während der Hub hörte, er sei geschlossen: Das ws-Paket verweigert das Close, nachdem es schon damit begonnen hat, und Denos Socket verweigert es von vornherein. Schlägt das Close eines Backends dennoch fehl, wird der Socket hart geschlossen, wo das Backend es kann; wo nicht, nennt eine Warnung die Verbindung.

isOpen liest false, sobald close() oder abort() zurückkehrt — nach close() noch bevor der Socket tatsächlich zu ist. broadcast und deine eigenen if (client.isOpen)-Prüfungen wählen damit keinen Peer mehr aus, den du bereits trennen wolltest.

upgrade trägt den Handshake-Kontext:

type WebsocketUpgradeInfo = {
path: string;
params: Record<string, string>;
query: Record<string, string | string[] | undefined>;
headers: Record<string, string>;
remoteAddress?: string;
subprotocol?: string;
};

WebsocketCloseInfo (an onClientDisconnected übergeben) ist { code: number; reason: string; initiatedBy: 'client' | 'server' | 'error' }.

Der Route-Codec dekodiert eingehende Frames in TIn und kodiert TOut-Antworten. Der Default ist jsonCodec():

import { WebsocketRouteOptions, jsonCodec } from 'actor-ts/http';
const webSocketRouteOptions = WebsocketRouteOptions.create().withCodec(jsonCodec<ServerMessage, ClientMessage>({
validate: (v: unknown): ClientMessage => ClientMsgSchema.parse(v),
}));
websocket('/ws', chat, webSocketRouteOptions);

Für Binärprotokolle liefert rawCodec() rohe Frames (TOut = TIn = WebsocketFrame):

import { match } from 'ts-pattern';
import {
rawCodec,
WebsocketRouteOptions,
WebsocketServerActor,
type WebsocketFrame,
} from 'actor-ts/http';
const webSocketRouteOptions = WebsocketRouteOptions.create().withCodec(rawCodec());
class BinaryHub extends WebsocketServerActor<WebsocketFrame, WebsocketFrame> {
onMessage(frame: WebsocketFrame): void {
match(frame)
.with({ kind: 'binary' }, (f) => this.onBinary(f))
.otherwise(() => {});
}
private onBinary(frame: BinaryFrame): void {
this.reply({ kind: 'binary', data: process(frame.data) });
}
}
websocket('/stream', binaryHub, webSocketRouteOptions);

Dekodier-Fehler werfen WebsocketDecodeError und folgen der onInvalidMessage-Policy der Route.

websocket() funktioniert auf allen drei HTTP-Backends:

BackendPeer-DependencyRuntime-Hinweise
Fastify (Default)@fastify/websocketLäuft auf Bun und Node; auf Deno bevorzuge Hono.
Expressws—
HonoBun & Deno: in hono eingebaut. Hono-auf-Node: @hono/node-ws.Helfer pro Runtime.
Terminal-Fenster
npm install @fastify/websocket # Fastify (default)
npm install ws # Express
npm install @hono/node-ws # Hono on Node only, 1.2.0 or newer

Route-Defaults liegen unter actor-ts.http.websocket:

actor-ts.http.websocket {
max-frame-bytes = 1M
on-oversize-frame = "close"
on-invalid-message = "close"
max-buffered-bytes = 4M
on-backpressure = "drop"
max-pre-attach-frames = 256
max-pre-attach-bytes = 4M
accept-timeout = 10s
# Unset by default; a route's own value wins over both.
# connection-mailbox-capacity = 256
# connection-mailbox-overflow = "drop-head"
}

Präzedenz: Route-Optionen > HOCON > eingebaute Defaults. Die beiden Blätter connection-mailbox-* haben keinen eingebauten Default: ungesetzt fällt der Connection-Actor auf den actor-ts.deployment-Eintrag durch, der zu seinem Pfad passt ("/user/<hub>/ws-*"), dann auf actor-ts.mailbox.default.

Jedes Blatt ist das Feld aus WebsocketRouteOptions in kebab-case, ohne Einheiten-Suffix — das Feld bleibt acceptTimeoutMs, das Blatt heißt accept-timeout, und die Einheit steht im Wert. Die camelCase-Schreibweisen, die dieser Block früher hatte, werden in bind() mit einem ConfigError abgelehnt, der beide Namen nennt, statt ignoriert zu werden: Die meisten dieser Blätter sind Obergrenzen, die ein Deployment in einem halbwegs vertrauten Netz bewusst senkt, und eine Grenze, die still auf den Default zurückfiel, ist schlimmer als eine, die den Start verweigert.

Drei gute Einsatzfälle:

  1. Echtzeit-UIs — Updates an Browser-Clients pushen.
  2. Eigene Messaging-Protokolle — Game-Server, Chat-Backends.
  3. Binäres Streaming — nutze rawCodec() und behandle Frames direkt.

Für einseitige Streams vom Server zum Client ist SSE einfacher. Für Request/Reply-RPC ist einfaches HTTP die Norm.