API reference › @evolu/common › local‑first/Owner › OwnerWebSocketTransport

Defined in: packages/common/src/local-first/Owner.ts:534

WebSocket transport configuration.

OwnerId in the URL

The OwnerId is passed as a URL query parameter, because browsers can't set custom headers on a WebSocket handshake. URLs often get logged, and whoever reads an OwnerId there can't decrypt changes but can download the owner's encrypted changes and timestamps from the relay and subscribe to new ones, as Privacy describes. On a relay that hasn't stored the owner's write key yet, they can also store their own and so lock the owner out of writing there.

See: HTTP headers in Websockets client API

Error Handling

When a relay rejects a connection (invalid OwnerId, unauthorized owner, or server error), the browser WebSocket API does not expose the specific HTTP status code or reason - it only reports a generic connection failure. The client automatically retries with exponential backoff and jitter, eventually succeeding once the configuration or server issue is resolved.

Legitimate clients will be properly configured with valid credentials, so automatic retry is OK.

Heartbeats

The WebSocket API answers a relay's pings without telling JavaScript, in browsers, React Native and Node alike, so a client cannot see whether an idle connection still works. A relay therefore sends an empty text frame as the first frame of every connection, and then at least every relayHeartbeatInterval while nothing else is queued for the connection and none of its requests is being served. Protocol messages are binary, so text frames are reserved for heartbeats: a relay that sends one on a connection promises them on that connection, and clients ignore their content. Clients before @evolu/common 8.26.0 drop them unread.

The client replaces a connection that has carried no frame for much longer than the interval, so a relay sends no unsolicited frame larger than 1 MB, and a proxy in front of it must allow more than one interval of idle time. A relay that sends no heartbeats still works, but a client notices its silent connections only through unanswered requests and system sleep.

See

Extends

Properties

type

readonly type: "WebSocket";

Defined in: packages/common/src/Type.ts:19326

Inherited from

Typed.type


url

readonly url: string & Brand<"Url"> & Brand<"WebSocketUrl">;

Defined in: packages/common/src/local-first/Owner.ts:535