@bimetal/server-sync
Ein Node-Sync-Server-Skelett für @bimetal/sync. Es legt eine WebSocket-Schicht über einen
konsumenten-gelieferten http.Server und nutzt einen einsteckbaren EventStore als Autorität.
Bewusst minimal: kein HTTP-Framework. Das Paket kümmert sich um das WebSocket-Sync-Protokoll, das Weiterreichen an die EventStore-Autorität und — wenn der Konsument die Haken setzt — um die Befugnis je Verbindung (bimetal-304). Ohne die Haken darf jede Verbindung, die das Upgrade überlebt, jeden Strom lesen und in jeden schreiben; Auth gehört dann in eine HTTP-Middleware vor dem Upgrade.
Installation
npm install @bimetal/server-sync @bimetal/sync @bimetal/event-sourcing
Was das Paket liefert
| Export | Zweck |
|---|---|
createSyncWebSocketServer(options) | Hängt den Sync-WebSocket-Handler an einen bestehenden http.Server und bedient verbundene Clients gegen den als Autorität übergebenen EventStore (Append validiert über Optimistic Locking, Broadcast an Subscriber). |
SyncWebSocketServerOptions.undoDomain | Schaltet das Undo-Kommando frei (undo/redo aus @bimetal/sync): Stream lesen → expectFrame gegen die envelope.id des jüngsten Events dieser Entität prüfen → Aggregat falten → Umkehrung bauen → über eventStore.append anfügen. Kein Löschen, kein Rückspulen; jeder Subscriber sieht die Umkehrung als gewöhnliches Live-Event, weil sie den normalen Append-Weg nimmt. Der Typ ist SyncUndoDomain aus @bimetal/sync — ein Port (Aggregat + Kommando-Bauer), kein Domain-Import. Kollidiert expectFrame, kommt append-rejected mit Grund concurrency und der Stream wächst nicht. Ohne undoDomain antwortet der Server mit einer benannten Ablehnung (Grund unknown, der Text nennt undoDomain), damit ein wartender Client nicht in seine Zeitgrenze läuft. Ob der Server das Kommando trägt, sagt er jedem Client im ersten Frame der Verbindung (hello, bimetal-292); @bimetal/sync-ws setzt undo/redo nur bei Zusage. |
Catch-up in Frames begrenzter Grösse (bimetal-372)
Ein subscribe wird nicht mehr mit EINEM events-Frame über den ganzen Rückstand beantwortet. Die Autorität
liest den Stream seitenweise (EventStore.read(streamId, fromVersion, limit); ein Adapter ohne limit bleibt
korrekt und kostet nur die Vollkopie) und sendet events-Frames bis maxFrameBytes (Vorgabe
DEFAULT_MAX_FRAME_BYTES = 1 MiB, gemessen als UTF-8 der Events). Den nächsten Frame baut sie erst, wenn der
vorige an den Socket übergeben ist. Ein einzelnes Event über der Grenze geht als eigener Frame. Ordnung und
Versionen bleiben, caught-up folgt nach dem letzten Frame. Die Spitze beim Catch-up liegt damit in der
Grössenordnung eines Frames über dem gehaltenen Stand, statt beim Vielfachen des Streams (vorher rund das
8-fache des JSON, auf beiden Seiten). @bimetal/sync-ws dekodiert jeden Frame beim Eintreffen und wendet ihn je
Subscription der Reihe nach an (bimetal-373). Bewacht von __tests__/sync-server.test.ts (Frames, Ordnung, Seiten) und von @bimetal/sync-ws __tests__/catch-up-spitze.test.ts (maxRSS beider Seiten bei rund 90 MB JSON).
Befugnis je Verbindung (bimetal-304)
| Option | Wirkung |
|---|---|
authenticate(req) | Läuft beim Upgrade, bevor ein WebSocket entsteht. null/undefined → 401, kein Upgrade; ein Wurf → 500. Jeder andere Wert ist der principal dieser Verbindung. |
readOnly: true | Jedes Schreiben wird mit append-rejected, Grund auth, abgewiesen — append ebenso wie die Kommandos undo/redo. Der Store wird nicht berührt. Der Frame trägt bei auth keine Versionsfelder (expectedVersion/actualVersion): gemessen wurde keine Version, eine Zahl wäre erfunden (bimetal-323). Dasselbe gilt für jeden Grund ausser concurrency (bimetal-341). |
authorizeAppend(ctx) | ctx = { principal, connectionId, streamId, events, expectedVersion }; gefragt wird vor dem Store (bei undo/redo mit der gebauten Umkehrung). false → append-rejected/auth, ein Wurf → append-rejected/unknown. |
authorizeSubscribe(ctx) | ctx = { principal, connectionId, streamId, fromVersion }. false → der eigene Frame subscribe-rejected (Grund auth, bei einem Wurf unknown): kein Events-Frame, kein Snapshot, kein caught-up, am Store wird nichts abonniert. Die Verbindung bleibt stehen; @bimetal/sync-ws beendet die Subscription endgültig (kein Reconnect) und meldet sie über onRejected. |
Versionsfelder nur bei concurrency (bimetal-341). append-rejected trägt expectedVersion/actualVersion
nur, wo eine Version gemessen ist: beim Konflikt aus dem Store (ConcurrencyError) beide, bei der
expectFrame-Kollision eines undo/redo nur actualVersion (die Erwartung war eine Frame-Marke, keine
Version). Die Gründe auth, unknown (Wurf von authorizeAppend, Kommando ohne undoDomain) und validation
(unbekannter Store-Fehler, werfendes Aggregat) kommen ohne Versionsfelder. Der Decoder in @bimetal/sync lässt
die Felder eines älteren Servers bei diesen Gründen fallen.
Wire-Bruch in Gegenrichtung: Ein Client bis 0.38 an einem Server ab 0.39 verträgt das nicht. Sein Decoder
verlangt expectedVersion/actualVersion bei jedem Grund ausser auth als Zahl; der Frame zu validation/
unknown und die expectFrame-Kollision (ohne expectedVersion) gelten ihm als Protokollfehler — er schliesst
die Verbindung (4002) und verbindet neu, das offene Append endet als Abbruch statt mit dem benannten Grund.
Client und Server gehören zur selben Version.
principal und connectionId sind die Nachweisspur „wer hat über welche Verbindung was versucht" — geführt
wird sie im Haken des Konsumenten, der Server schreibt kein Protokoll.
Die Gegenseite im Browser ist @bimetal/sync-ws (SyncTransport-Adapter mit
Reconnect + transparenter Subscription-Wiederherstellung).
Architektur
Cross-cutting (Server-Seite von sync). Tiefe: Event-Sourcing-Konzept und Backend-Überblick — dort auch „Wie groß wird das?“, die Grenze des Log-im-Client.