Xudanu Wire Protocol API Reference

Protocol version: 2

Connection

Connect via WebSocket to:

ws://host:8080/xudanu?format=json&version=2

Query parameters: - format=json -- select the JSON codec (alternatively, omit for binary) - version=2 -- request protocol version 2

Handshake

Upon connection, the server sends a handshake frame:

{
  "v": 2,
  "type": "handshake",
  "id": 0,
  "server_version": 2,
  "negotiated_version": 2,
  "server_id": "xudanu-<pkg-version>",
  "server_capabilities": ["json", "binary", "detector_events", "admin"]
}

The client must wait for the handshake before sending requests.

Request Format

{"v": 2, "type": "request", "id": 1, "op": "<operation_name>", "payload": {...}}

Response Format

Success:

{"v": 2, "type": "response", "id": 1, "value": {"type": "<response_type>", "value": ...}}

Error:

{"v": 2, "type": "error", "id": 0, "code": "not_authorized", "message": "session not logged in"}

Error Codes

Common Types

BeId

A BeId is a u64 representing a unique entity identifier.

EditionPayload

{"type": "text", "value": "hello world"}

{"type": "entries", "value": [[0, {"type": "text", "text": "hello"}], [1, {"type": "text", "text": "world"}]]}

{"type": "empty"}

XnRegion

An interval region:

{"start": 0, "end": 10}

RangeElement

{"type": "text", "text": "hello"}

{"type": "label", "label_id": 123, "text": "content"}

HyperRefPayload

{
  "kind": "single",
  "work_context": 123,
  "original_context": null,
  "path_context": null,
  "excerpt": "matching text"
}

TextDeltaOp

Used by work_revise_delta for incremental text editing:

{"type": "retain", "count": 5}

{"type": "insert", "text": "new text"}

{"type": "delete", "count": 3}

RetrieveFlagsPayload

{
  "ignore_total_ordering": false,
  "ignore_array_ordering": false,
  "separate_owners": false
}

LockCredential

{"type": "boo"}

{"type": "password", "password": "secret"}

{"type": "challenge_response", "response": [1, 2, 3]}

Auth Levels

Session Operations

Server Operations

Club Operations

Work Operations

Edition Operations

Link Operations

Content Discovery Operations

Content Analysis Operations

Range Operations

Blob Operations

BlobMeta Response

{
  "type": "blob_meta",
  "value": {
    "content_hash": "a1b2c3d4e5f6a7b8",
    "byte_size": 4096,
    "mime_type": "image/png",
    "preview_hash": "e5f6a7b8a1b2c3d4",
    "width": 800,
    "height": 600
  }
}

Overlay Operations

Label Operations

Identity Operations

Endorsement Operations

Each endorsement is a [club_id, token_id] pair.

Crypto Operations

Federation Operations

All federation operations require federation to be enabled on the server.

Endorsement Sync Operations

Membership Operations

Governance Operations

Governance uses a PBFT-style consensus protocol among federation members.

Admin Operations

Admin Recorder Operations

Server Health Response Fields

Stats Operation

Events and Subscriptions

Clients can subscribe to server-pushed events. Send a subscribe frame:

{"v": 2, "type": "subscribe", "id": 1, "payload": {"detector_type": "revision", "target_id": 123}}

Detector types: status, revision, fill.

The server pushes event frames:

{"v": 2, "type": "event", "id": 1, "event": {"type": "work_revised", "payload": {"work_be_id": 123, "revision": 2, "session_id": 1}}}

Event Types

Unsubscribe:

{"v": 2, "type": "unsubscribe", "id": 1}

Heartbeat

Either side may send heartbeat frames to keep the connection alive:

{"v": 2, "type": "heartbeat", "id": 0}

Operation Code Reference (Binary Protocol)

For the binary protocol, operations are identified by u16 codes:

Note: Codes 0x1902 (membership_join_response) and 0x1906 (membership_sync_result) are server-only and cannot be sent by clients.

Binary Protocol

An alternative binary protocol uses postcard serialization with a compact frame layout:

[1B version][1B msg_type][2B request_id BE][payload...]

Message types: 0x00 handshake, 0x01 request, 0x02 response, 0x03 error, 0x04 event, 0x05 subscribe, 0x06 unsubscribe, 0x07 heartbeat.

Request payloads begin with a LEB128 varint-encoded operation code followed by a varint length prefix and postcard-serialized payload data. Response and error payloads similarly use varint-prefixed postcard encoding.

See src/server/transport/codec.rs for full encoding details.