bolzo.net / brc

BRC: Realtime Broadcast Collaboration

Diese Seite ist eine externe Dokumentation fuer BRC und laeuft als statische Website auf Apache2. Sie ist bewusst von der BRC-Node-App getrennt.

WebSocket Socket.IO fuer Live-Updates

REST/curl Lesen und Schreiben per CLI

Persistenz Serverzustand in state.json

Was ist BRC?

Live-Synchronisierung pro Raum ueber WebSocket (Socket.IO)
Teilbare Raum-Links wie /team-alpha oder /12345678
Datei-Upload mit sofortiger Verteilung an aktive Teilnehmer
Persistenter Raumzustand auf dem Server (Text + letzte Dateien)
Ratenbegrenzung und Limits gegen Missbrauch

Schnellstart BRC

npm install
npm start
# Dann im Browser:
# http://127.0.0.1:3000

Hinweis: Diese Doku selbst wird separat ueber Apache2 ausgeliefert.

Architektur

Minimaler Datenpfad vom Browser bis zur Persistenz:

Browser Client
  -> Socket.IO Event (text-update / file-share)
  -> Raum-Logik auf Node Server
  -> In-Memory Zustand (roomState, roomFiles)
  -> Persistenz nach data/state.json
  -> Broadcast an alle Clients im Raum

State: roomState Map Files: roomFiles Map Rate Limit: pro Socket-ID Room Caps: maxClientsPerRoom

Ablauf im Raum

Client joined Raum: Server validiert Raumname und Teilnehmerlimit.
Server sendet initialen Zustand: aktueller Text, Dateien, Teilnehmerzahl.
Bei Texteingabe sendet Client text-update; Server verteilt an alle anderen.
Dateiupload wird als Base64 geprueft, gespeichert und als file-share verteilt.
Bei Disconnect sinkt der Counter; aktive Clients erhalten client-count.

API Matrix

Methode	Pfad	Zweck	Antwort
GET	/api/config	Client Limits und Defaults laden	JSON
GET	/curl/<room_id>	Aktuellen Raumtext lesen	text/plain
POST	/curl-write/<room_id>	Text in Raum schreiben	text/plain (OK)
GET	/curl-d/<room_id>?name=<file>	Datei-Metadaten und Base64 lesen	text/plain

Sicherheit und Limits

Rate Limiting pro Socket-ID reduziert Spam auf Event-Ebene.
Dateigroesse wird serverseitig begrenzt (Bytes, konfigurierbar).
Raumcode wird validiert und auf maximale Laenge geprueft.
Optionales HTML-Escaping neutralisiert Script/Tag-Inhalte im Text.
Maximale Teilnehmerzahl pro Raum verhindert Ueberlastung.

Deployment (BRC + externe Apache-Doku)

# BRC App (Node)
sudo systemctl enable --now brc-server

# Externe Doku (Apache)
sudo mkdir -p /var/www/bolzo-docs
sudo cp -r ./apache-docs/brc-site/* /var/www/bolzo-docs/

# Apache vHost (Beispiel)
DocumentRoot /var/www/bolzo-docs
DirectoryIndex index.html

Troubleshooting

Kein Live-Update

Pruefe WebSocket/Proxy Header und ob Socket.IO Route erreichbar ist.

Upload bricht ab

Limit fuer Dateigroesse, Proxy body size und Socket buffer vergleichen.

Raumfehler beim Join

Raumname auf ungueltige Zeichen, Slash und Laenge kontrollieren.

Hohe Latenz

CPU/IO Last, Teilnehmerzahl je Raum und Frequenz der Updates messen.

Glossar

Room: Isolierter Kanal mit eigenem Text und eigener Dateiliste.
Broadcast: Verteilung eines Events an alle Clients im selben Raum.
Persistenz: Speichern des aktuellen Zustands in data/state.json.
Sanitizing: Escapen von HTML/Script-Zeichenfolgen im Textinhalt.

curl Beispiele

curl https://brc.bolzo.net/curl/main

curl -X POST --data-binary @./notiz.txt \
  "https://brc.bolzo.net/curl-write/main"

curl "https://brc.bolzo.net/curl-d/main?name=abc.txt"