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.
Die websocket()-Direktive
Abschnitt betitelt „Die websocket()-Direktive“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),);Optionen
Abschnitt betitelt „Optionen“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 DataDas 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.
Wo das Limit greift
Abschnitt betitelt „Wo das Limit greift“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.
Das Aufbaufenster einer Verbindung
Abschnitt betitelt „Das Aufbaufenster einer Verbindung“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/maxPreAttachBytesbegrenzen, 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 (maxFrameBytesbegrenzt ihn ohnehin bereits) — eine Route, diemaxFrameBytesüber 4 MiB hebt, mussmaxPreAttachBytesalso nur mitheben, wenn ihre Clients mehrere solcher Frames auf einmal senden.acceptTimeoutMsbegrenzt, wie lange das Fenster offen bleiben darf. Hat sich innerhalb dieser Frist kein Connection-Actor angehängt, wird der Socket mit 1013 geschlossen und seinmaxConnections-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.Infinityschaltet 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.
Origin-Prüfungen (CSWSH-Schutz)
Abschnitt betitelt „Origin-Prüfungen (CSWSH-Schutz)“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 — standardmäßig an
Abschnitt betitelt „requireSameOrigin — standardmäßig an“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 requiredVerglichen 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.
allowedOrigins — andere Origins benennen
Abschnitt betitelt „allowedOrigins — andere Origins benennen“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.
Abschalten
Abschnitt betitelt „Abschalten“const wsOptions = WebsocketRouteOptions.create() .withRequireSameOrigin(false);websocket('/ws', chat, wsOptions); // no origin check at allwithRequireSameOrigin(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.
Middleware läuft zur Upgrade-Zeit
Abschnitt betitelt „Middleware läuft zur Upgrade-Zeit“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.
Request-Attribute bleiben auf der HTTP-Seite
Abschnitt betitelt „Request-Attribute bleiben auf der HTTP-Seite“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.
Backend-eigene Middleware läuft ebenfalls
Abschnitt betitelt „Backend-eigene Middleware läuft ebenfalls“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:
| Backend | Was beim Handshake zusätzlich läuft |
|---|---|
| Fastify | Route-Hooks, inklusive preValidation |
| Express | alles, was mit app.use(...) registriert wurde |
| Hono | alles, 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).
WebsocketServerActor
Abschnitt betitelt „WebsocketServerActor“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:
| Member | Was er tut |
|---|---|
this.connection | Die 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.clients | ReadonlyMap<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}Reihenfolge pro Verbindung
Abschnitt betitelt „Reihenfolge pro Verbindung“Jedes Event einer gegebenen Verbindung wird über den einen Hub-Actor in dieser Reihenfolge serialisiert:
onClientConnected → onMessage* (in frame order) → onClientDisconnectedonClientConnected 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.
Die Mailbox des Hubs begrenzen
Abschnitt betitelt „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.
WebsocketConnection
Abschnitt betitelt „WebsocketConnection“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.
Backends und Runtimes
Abschnitt betitelt „Backends und Runtimes“websocket() funktioniert auf allen drei HTTP-Backends:
| Backend | Peer-Dependency | Runtime-Hinweise |
|---|---|---|
| Fastify (Default) | @fastify/websocket | Läuft auf Bun und Node; auf Deno bevorzuge Hono. |
| Express | ws | — |
| Hono | Bun & Deno: in hono eingebaut. Hono-auf-Node: @hono/node-ws. | Helfer pro Runtime. |
npm install @fastify/websocket # Fastify (default)npm install ws # Expressnpm install @hono/node-ws # Hono on Node only, 1.2.0 or newerHOCON-Config
Abschnitt betitelt „HOCON-Config“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.
Wann einsetzen
Abschnitt betitelt „Wann einsetzen“Drei gute Einsatzfälle:
- Echtzeit-UIs — Updates an Browser-Clients pushen.
- Eigene Messaging-Protokolle — Game-Server, Chat-Backends.
- 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.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- I/O-Übersicht — das große Bild.
- WebsocketClientActor — die ausgehende Client-Hälfte.
- Route-DSL —
path,concatund wiewebsocket()komponiert. - SSE — Server-Sent Events, die einseitige Alternative.
- HTTP-Übersicht — Backends, Middleware und Server-Binding.
