[Arch Review] WebSocket fan-out serializes each broadcast payload once per subscriber

[Pappet]

Severity

Medium — redundant CPU that scales with (message rate × connected viewers).

Problem

Every store event is broadcast to all WebSocket subscribers, and each subscriber's task serializes the same payload independently.

• MessageStore::insert sends one StoreEvent::NewMessage(Box<summary>) over the broadcast channel (src/store.rs:120).
• Each connected client runs its own handle_ws loop, and for every event calls send_ws_event (src/web.rs:230-243), which does serde_json::json!{...}.to_string() — a fresh JSON serialization of the identical summary, once per socket.

With N developers watching the same Orchestra feed (the documented multi-user scenario in CLAUDE.md), an incoming message is serialized N times into N identical strings.

Why it matters

The serialization is pure duplicated work on the hot ingest-broadcast path. At high message rates with several viewers it multiplies CPU and allocation for zero benefit, and competes with the parse/validate work already on that path (#180 / KB-4).

Suggested fix

Serialize each event payload once (e.g. in insert, or a small adapter that converts StoreEvent → pre-rendered JSON String/Arc<str> before broadcasting), then have each handle_ws task send the shared bytes verbatim. The broadcast channel can carry the already-serialized frame (or an Arc<str>) instead of the structured event, so per-socket work is just a send.

Found during the architecture review.

[Pappet]

Architektur-Review: #196 — WebSocket-Broadcast — N-fache Serialisierung

Root Cause

src/web.rs:190–218 (handle_ws → send_ws_event):

Jeder verbundene WebSocket-Client durchläuft bei jedem StoreEvent::NewMessage die Funktion send_ws_event:

// web.rs:send_ws_event (Zeile 119-128)
let payload = match data {
    Some(d) => serde_json::json!({"type": event_type, "data": d}),
    None => serde_json::json!({"type": event_type}),
};
socket.send(Message::Text(payload.to_string().into())).await

Problemaufriss:

• insert() (store.rs:68-83) sendet ein StoreEvent::NewMessage(Box<Hl7MessageSummary>) über broadcast::Sender.
• Jeder handle_ws-Task empfängt das Event und serialisiert identisch dieselbe Summary per serde_json::json!{} + .to_string().
• Bei N verbundenen Browsern = N× identische Serialisierungsarbeit auf dem Hot-Path (store.insert wird bei jeder eingehenden MLLP-Nachricht durchlaufen).
• MDM-Nachrichten mit Base64-Anhängen sind Daily Traffic → Summary enthält Metadaten, trotzdem entsteht Overhead durch wiederholtes JSON-Tokenizing und String-Allocation.

Zahlenbeispiel: N = 5 Viewer, 100 Msgs/s → 500 Serialisierungen/s von identischen Daten.

Lösungsvorschlag: Pre-Serialized Payload in StoreEvent

Statt StoreEvent::NewMessage(Box<Hl7MessageSummary>) ein vor-serialisiertes JSON-String mitliefern:

// store.rs — StoreEvent
pub enum StoreEvent {
    NewMessage(String),       // ✅ pre-serialized JSON: {"type":"new_message","data":{...}}
    TagsUpdated(String),      // ✅ analog
    BookmarkToggled(String),  // ✅ analog
    Cleared,
}

In store.insert():

pub async fn insert(&self, msg: Hl7Message) {
    let summary = Hl7MessageSummary::from(&msg);
    // ... write lock, insert ...

    // Einmal serialisieren — für alle Clients
    let payload = serde_json::json!({
        "type": "new_message",
        "data": &summary
    }).to_string();

    let _ = self.tx.send(StoreEvent::NewMessage(payload));
}

In handle_ws():

// Kein send_ws_event mehr nötig — nur noch String weiterreichen
Ok(StoreEvent::NewMessage(json_str)) => {
    if socket.send(Message::Text(json_str.into())).await.is_err() {
        break;
    }
}

Optimierung: Lazy Serialization mit OnceLock

Falls der Serialisierungs-Overhead im Store-Thread zu hoch erscheint (selten, da serde_json::json! schnell ist), alternativ:

pub enum StoreEvent {
    NewMessage {
        summary: Box<Hl7MessageSummary>,
        serialized: std::sync::OnceLock<String>,
    },
}

Jeder WS-Task ruft serialized.get_or_init(|| serde_json::json!(...).to_string()) auf → nur der erste Task serialisiert, alle anderen clonen das Ergebnis. Kein Overhead im Store-Thread, trotzdem nur 1× Serialisierung.

Das erhöht aber die Komplexität (OnceLock + &self-Semantik) — nicht empfohlen für dieses Issue.

Trade-offs

Aspekt	Aktuell (N× Serialisierung)	Vorschlag (Pre-Serialized)
CPU-Last pro eingehender Message	O(N) (N = WS-Clients)	O(1) (1× serialisieren, N× String-Clone)
Heap-Allokation pro Client	Vollständiger JSON-String	Nur Arc-Clone (Reference-Count + ggf. String-Clone)
Kopplung Store ↔ WS-Format	Gering (WS-Format in web.rs)	Höher (Store kennt WS-Format)
String-Größe im Broadcast	Nur Box<Summary> (~200 Bytes)	Kompletter JSON (~300-500 Bytes)

Risiken / Nebenwirkungen

1. Kopplung: StoreEvent bekommt eine Abhängigkeit zum Wire-Format. Bei Format-Änderungen (neue Felder in Summary) muss store.rs angepasst werden, nicht nur web.rs. Akzeptabel — das Projekt hat nur einen WS-Konsumenten.
2. Channel-Memory: broadcast::channel(4096) puffert Events für langsame Clients. String statt Struct = mehr Bytes pro Slot. Bei 4096 Slots × 500 Bytes ≈ 2 MB Puffer. Vertretbar.
3. Nicht-NewMessage Events: TagsUpdated und BookmarkToggled haben das gleiche Problem — sollten ebenfalls pre-serialisiert werden (auch wenn seltener).
4. Cleared-Event braucht keine Daten → kann als StoreEvent::Cleared bleiben (keine Serialisierung nötig).
5. Arc statt String: Alternativ Arc<String> im StoreEvent → Clone kostet nur Arc-Increment statt String-memcpy. Bei wenigen Clients egal, aber erwähnenswert.