WebSocket API

Open a persistent connection

Connect to /api/v1/ws with the qirava.v1 subprotocol. HTTPS instances use wss. Native clients can send the owner Bearer credential during upgrade; same-origin browsers can use the existing HttpOnly session. Cross-origin browser cookies never authenticate a connection.

The server sends a ready message with its session and limits. An unauthenticated client sends {type: "authenticate", token} within ten seconds and waits for authenticated ready. Browser origins must match the instance or its explicit --studio-origins list. Credentials never belong in URL parameters.

Correlate transactions

A result message carries type, id, status and response. The response uses the same success/error envelope as HTTP. Replies may arrive out of order. The correlation id is 1–64 ASCII letters, digits, hyphens or underscores, unique while outstanding. The inner requestId remains the durable receipt identity.

A dropped connection, timeout or connection-level error does not prove rejection. Retain the exact original transaction and resolve it over either transport. Previously admitted writes finish through the same custody lease even if their socket disconnects. An idle socket does not keep the database unlocked.

{
  "type": "execute",
  "id": "connection-request-1",
  "request": {
    "requestId": "durable-intent-1",
    "operations": [
      {
        "op": "get",
        "collection": "projects",
        "key": "first-project"
      }
    ]
  }
}

Use the shared TS/JS client

The client validates generated request and response contracts, freezes intent before awaiting credentials, and limits outstanding calls. It never automatically retries transactions. Omit token when using a same-origin browser session. Values that cannot be represented without changing their numeric precision are rejected.

import { QiravaWebSocketClient } from './websocket.js';

const db = new QiravaWebSocketClient({
  url: 'https://db.example.com',
  token: () => loadInstanceCredential()
});
const result = await db.execute(originalTransaction);
db.close();

Download browser WebSocket module

Download TypeScript WebSocket client

Complete client source dependencies →

Admission and scope

The current server permits eight outstanding requests per socket, at most 32 WebSocket connections and 32 global WebSocket requests, also subject to its ordinary connection/request limits. Frame and complete-message caps are 4 MiB + 64 KiB; the engine separately enforces 4 MiB transaction/result limits. Authentication text is limited to 1,024 bytes.

Socket writes have five-second deadlines. Heartbeats run every 30 seconds and input inactivity closes after 90 seconds. Compression is disabled. WebSocket carries execute operations; instance administration and binary transfers use HTTP.

Studio Connections selects HTTP keep-alive or WebSocket for each local/remote instance. Changing transport clears connection credentials. Full TLS/load-balanced database benchmarks, prolonged saturation, cluster behavior and custom role assignment remain production acceptance work.