Baradb/docs/de/protocol.md

Protokoll-Referenz

BaraDB unterstützt mehrere Protokolle für Client-Kommunikation:

• Binär Wire Protokoll — hochperformant, niedrige Latenz
• HTTP/REST API — sprachunabhängig, einfach zu debuggen
• WebSocket — Streaming und Pub/Sub

---

Binär Wire Protokoll

Das Binärprotokoll verwendet Big-Endian-Kodierung für alle Multi-Byte-Werte.

Verbindungslebenszyklus

Client                          Server
  |                               |
  |─── TCP connect ──────────────>|
  |<── TLS handshake (optional) ──|
  |─── Auth message ─────────────>|
  |<── Auth_OK / Error ───────────|
  |─── Query message ────────────>|
  |<── Data / Complete / Error ───|
  |─── Close message ────────────>|
  |<── TCP close ─────────────────|

Nachrichtenformat

Jede Nachricht beginnt mit einem 8-Byte-Header:

┌─────────────┬─────────────┬─────────────┬─────────────────────┐
│  Length     │  Type       │  Sequence   │  Payload            │
│  (4 bytes)  │  (1 byte)   │  (1 byte)   │  (Length - 6 bytes) │
│  uint32 BE  │  uint8      │  uint8      │                     │
└─────────────┴─────────────┴─────────────┴─────────────────────┘

Nachrichtentypen

Typ	ID	Richtung	Beschreibung
Query	0x01	C→S	Abfrage ausführen
Insert	0x02	C→S	Daten einfügen
Update	0x03	C→S	Daten aktualisieren
Delete	0x04	C→S	Daten löschen
Ready	0x05	S→C	Bereit für nächsten Befehl
Error	0x06	S→C	Fehlerantwort
Auth	0x07	C→S	Authentifizierungsanfrage
Batch	0x08	C→S	Batch-Operationen
Ping	0x09	C→S	Keepalive Ping
Data	0x81	S→C	Abfrageergebnis-Daten
Complete	0x82	S→C	Abfrage abgeschlossen
Auth_OK	0x83	S→C	Authentifizierung erfolgreich
Pong	0x84	S→C	Keepalive-Antwort

Query-Nachrichten-Payload

┌──────────────┬──────────────┬────────────────────────────┐
│ Result Format│ Query Length │ Query String               │
│ (1 byte)     │ (4 bytes)    │ (Query Length bytes)       │
│ 0x00=Binary │ uint32 BE    │ UTF-8                     │
│ 0x01=JSON   │              │                            │
│ 0x02=Text   │              │                            │
└──────────────┴──────────────┴────────────────────────────┘

Data-Nachrichten-Payload

┌──────────────┬─────────────────────────────────────────────┐
│ Column Count │ Column Definitions + Row Data               │
│ (2 bytes)    │                                             │
│ uint16 BE    │                                             │
└──────────────┴─────────────────────────────────────────────┘

Spaltendefinition

┌──────────────┬──────────────┬────────────────────────────┐
│ Name Length  │ Name         │ Type                       │
│ (2 bytes)    │ (N bytes)    │ (1 byte)                   │
│ uint16 BE    │ UTF-8        │ Siehe FieldKind-Tabelle    │
└──────────────┴──────────────┴────────────────────────────┘

Feldtypen

Typ	ID	Größe	Beschreibung
NULL	0x00	0	NULL-Wert
BOOL	0x01	1	true/false
INT8	0x02	1	Signed 8-bit Integer
INT16	0x03	2	Signed 16-bit Integer
INT32	0x04	4	Signed 32-bit Integer
INT64	0x05	8	Signed 64-bit Integer
FLOAT32	0x06	4	IEEE 754 Single Precision (Big-Endian)
FLOAT64	0x07	8	IEEE 754 Double Precision (Big-Endian)
STRING	0x08	variable	UTF-8 String (4-Byte Längenpräfix)
BYTES	0x09	variable	Raw Bytes (4-Byte Längenpräfix)
ARRAY	0x0A	variable	Array von Werten
OBJECT	0x0B	variable	Key-Value Objekt
VECTOR	0x0C	variable	Float32 Array (4-Byte Längenpräfix, Big-Endian Floats)

Fehler-Nachrichten-Payload

┌──────────────┬──────────────┬────────────────────────────┐
│ Error Code   │ Message Len  │ Error Message              │
│ (4 bytes)    │ (4 bytes)    │ (Message Len bytes)        │
│ uint32 BE    │ uint32 BE    │ UTF-8                     │
└──────────────┴──────────────┴────────────────────────────┘

Beispiel: Raw TCP-Session

# Verbinden
nc localhost 9472

# Senden: Auth-Anfrage (Token "mytoken")
# Header: length=15, type=0x07, seq=1
# Payload: token length=7, token="mytoken"
printf '\x00\x00\x00\x0f\x07\x01\x00\x00\x00\x07mytoken' > /dev/tcp/localhost/9472

# Empfangen: Auth_OK
# \x00\x00\x00\x06\x83\x01

# Senden: Query "SELECT 1"
printf '\x00\x00\x00\x12\x01\x02\x00\x00\x00\x00\x08SELECT 1' > /dev/tcp/localhost/9472

# Empfangen: Data + Complete

---

HTTP/REST API

Basis-URL: http://localhost:9470/api/v1

Endpoints

Health

GET /health

Antwort:

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 86400
}

Ready

GET /ready

Gibt 200 zurück wenn bereit, 503 während des Starts.

Query

POST /query
Content-Type: application/json
Authorization: Bearer <token>

{
  "query": "SELECT name, age FROM users WHERE age > 18",
  "params": [],
  "format": "json"
}

Batch

POST /batch
Content-Type: application/json

{
  "queries": [
    "INSERT users { name := 'Alice', age := 30 }",
    "INSERT users { name := 'Bob', age := 25 }"
  ]
}

HTTP-Statuscodes

Code	Bedeutung
200	Erfolg
400	Bad request (Syntaxfehler)
401	Unauthorized (Auth erforderlich)
403	Forbidden (ungenügende Berechtigungen)
404	Not found (Tabelle/Typ existiert nicht)
429	Too many requests (Rate limitiert)
500	Internal server error
503	Service unavailable (wird gestartet)

---

WebSocket-Protokoll

URL: ws://localhost:9471

Frame-Format

WebSocket Text-Frames enthalten JSON-Nachrichten:

{
  "id": 1,
  "type": "query",
  "query": "SELECT * FROM users"
}

Nachrichtentypen

Typ	Richtung	Beschreibung
query	C→S	Abfrage ausführen
subscribe	C→S	Änderungen abonnieren
unsubscribe	C→S	Abonnement beenden
ping	C→S	Keepalive
result	S→C	Abfrageergebnis
notification	S→C	Änderungsbenachrichtigung
error	S→C	Fehler
pong	S→C	Keepalive-Antwort