Connection Establishment

Two-stage setup: identification handshake, then registration. Connections that fail either stage are dropped without creating a session.

---

Stage 1 — Identification Handshake

Both peers exchange a newline-terminated JSON object. The server enforces a 5-second timeout.

Client → Server

{"id":"woho-client","version":"1.0.0-rc.1"}

Server → Client

{"id":"woho-server","version":"1.0.0-rc.1"}

Field	Required	Description
id	Yes	Must be woho-client (client) or woho-server (server).
version	Yes	Binary version string reported by the peer.

Dropped on: invalid JSON, unexpected id, oversized payload, or timeout.

---

Stage 2 — Registration

After the handshake succeeds, the client sends a length-prefixed register message (4-byte big-endian length + JSON payload).

{
  "type": "register",
  "payload": {
    "client_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "client_name": "Production-Web-01",
    "hostname": "web-prod-01.example.com",
    "os": "linux",
    "arch": "amd64",
    "client_version": "1.0.0-rc.1"
  }
}

Field	Required	Description
client_uuid	Yes	Persistent identifier used to track reconnects.
client_name	Yes	Display name shown in the admin UI.
hostname	Yes	Machine hostname.
os	Yes	windows, linux, or darwin.
arch	Yes	amd64, arm64, or 386.
client_version	Yes	Client build version string.
auth_key	No	Pre-shared key. Omitted when authentication is disabled.

See Pre-Shared Keys for the full authentication flow.

---

Connection Flow

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: TCP connect
    C->>S: {"id":"woho-client","version":"..."}\n
    S-->>C: {"id":"woho-server","version":"..."}\n
    C->>S: [length] register { client_uuid, client_name, ... }

    alt Registration accepted
        S-->>C: registered
        Note over S: Session visible in admin UI
    else Auth failed / invalid
        S-->>C: AUTH_FAILED / AUTH_REQUIRED
        Note over S: No session created
    end

Only clients that complete both stages appear on the Sessions page.