Wire Protocol

The 140+ operation WebSocket API: message framing, JSON and binary codecs, connection lifecycle, subscription model, and rate limiting — the complete integration surface for building clients and tools.

1. Overview

Xudanu's wire protocol is a WebSocket-based request-response protocol with server-push subscriptions. Every operation has a typed request and response, identified by a numeric operation code.

The protocol is defined in src/server/transport/protocol.rs (~2,969 lines) with codecs in codec.rs (~2,902 lines) and dispatch in dispatch.rs (~2,667 lines). Together these ~8,500 lines define the entire API surface.

2. Transport Layer

• Protocol: WebSocket over HTTP (upgrade from GET request)
• Default port: 8080 (configurable via CLI)
• Path: /ws
• Content types: Text frames (JSON) or binary frames (postcard-encoded)
• Version negotiation: Client sends ?version=2 query parameter

3. Message Format

Every message follows a consistent structure:

{
  "op": "work_list",          // Operation name
  "request_id": 42,            // Client-assigned correlation ID
  "payload": { ... }           // Operation-specific parameters
}

Responses echo the request_id and include a value or error:

{
  "op": "work_list",
  "request_id": 42,
  "value": {
    "works": [
      { "work_be_id": 1004, "title": "Alice's Document", ... }
    ]
  }
}

4. Operation Categories

The 140+ operations are organized into these categories:

5. Codecs (JSON & Binary)

The protocol supports two wire formats:

{
  "op": "work_star",
  "request_id": 7,
  "payload": {
    "work_be_id": 1004
  }
}

[varint: op_code]
[varint: request_id]
[postcard: payload]

6. Connection Lifecycle

Figure 1: WebSocket connection lifecycle from upgrade through authentication to active session and cleanup.

7. Subscription Model

Beyond request-response, clients can subscribe to real-time events:

8. Security Features

• CSRF protection: Optional CSRF token validation (enabled via --csrf-token flag)
• Origin validation: WebSocket upgrade requests are checked against allowed origins
• Rate limiting: Per-IP rate limiting on login attempts and operation frequency
• Panic-safe dispatch: Operation handlers are wrapped in catch_unwind to prevent server crashes from client requests
• Input validation: All payloads are validated before dispatch; malformed messages are rejected with error responses