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
Typed<"WebSocket">
Properties
type
readonly type: "WebSocket";
Defined in: packages/common/src/Type.ts:19326
Inherited from
url
readonly url: string & Brand<"Url"> & Brand<"WebSocketUrl">;
Defined in: packages/common/src/local-first/Owner.ts:535