WebSocket Protocol

Endpoint: ws://<host>:8080/v1/ws
Transport: RFC 6455
Message format: JSON text frames (server may send gzip-compressed binary frames for larger payloads)

Connection And Authentication

Upgrade

Client opens GET /v1/ws.

Server can reject pre-upgrade for:

shutdown mode
origin policy failure
strict origin check with missing Origin header

Origin policy

Origin allow-list resolution:

security.allowed_ws_origins if non-empty
otherwise security.cors.allowed_origins

Post-connect auth (required)


{
  "type": "authenticate",
  "method": "jwt",
  "token": "<JWT_TOKEN>"
}

Success:


{
  "type": "auth_success",
  "user_id": "u_...",
  "role": "Dba"
}

Failure:


{
  "type": "auth_error",
  "message": "Invalid username or password"
}

Client Messages

authenticate
subscribe
next_batch
unsubscribe

`subscribe`


{
  "type": "subscribe",
  "subscription": {
    "id": "orders_live",
    "sql": "SELECT * FROM app.orders WHERE status = 'open'",
    "options": {
      "batch_size": 200,
      "last_rows": 100,
      "from_seq_id": 12345
    }
  }
}

`next_batch`


{
  "type": "next_batch",
  "subscription_id": "orders_live",
  "last_seq_id": 12345
}

`unsubscribe`


{
  "type": "unsubscribe",
  "subscription_id": "orders_live"
}

Server Messages

auth_success / auth_error
subscription_ack
initial_data_batch
change
error

`subscription_ack`


{
  "type": "subscription_ack",
  "subscription_id": "orders_live",
  "total_rows": 0,
  "batch_control": {
    "batch_num": 0,
    "has_more": true,
    "status": "loading",
    "last_seq_id": 12345,
    "snapshot_end_seq": 13000
  },
  "schema": [
    {"name":"id","data_type":"BigInt","index":0}
  ]
}

`initial_data_batch`


{
  "type": "initial_data_batch",
  "subscription_id": "orders_live",
  "rows": [{"id":1,"status":"open","_seq":12346}],
  "batch_control": {
    "batch_num": 0,
    "has_more": true,
    "status": "loading",
    "last_seq_id": 12346,
    "snapshot_end_seq": 13000
  }
}

`change`


{
  "type": "change",
  "subscription_id": "orders_live",
  "change_type": "insert",
  "rows": [{"id":2,"status":"open","_seq":13001}]
}

change_type values:

insert
update
delete

`error`


{
  "type": "error",
  "subscription_id": "orders_live",
  "code": "INVALID_SQL",
  "message": "..."
}

Limits

rate_limit.max_subscriptions_per_user (default 10)
hard cap per connection: 100
security.max_ws_message_size (default 1MB)
rate_limit.max_messages_per_sec (default 50)
auth timeout: websocket.auth_timeout_secs (default 3)

Error Codes

Common WebSocket protocol/error codes include:

AUTH_REQUIRED
INVALID_SUBSCRIPTION_ID
SUBSCRIPTION_LIMIT_EXCEEDED
INVALID_SQL
RATE_LIMIT_EXCEEDED
MESSAGE_TOO_LARGE
UNSUPPORTED_DATA
PROTOCOL

For endpoint auth matrix and SQL payload contracts, see HTTP API Reference.