Bridge transports
The frontend SDK exposes one bridge connection interface with three explicit transport modes. HTTP is the product default; WebSocket and hybrid remain explicit development diagnostic choices.
Create a bridge transport
import {
createBridgeConnectionTransport,
type BridgeTransportMode,
} from '@crystal-lattice/frontend-sdk';
const mode: BridgeTransportMode = 'http';
const bridge = createBridgeConnectionTransport({
bridgeUrl: 'bridge.example.com',
mode,
serverId: savedServerId,
pairingToken: savedPairingToken,
});
await bridge.connect();
Omitting mode selects http. Explicit websocket and hybrid preserve the
existing legacy implementations.
Modes
| Mode | Control and pairing | GET /events |
Other requests |
|---|---|---|---|
websocket |
WebSocket | WebSocket | WebSocket |
http |
HTTP | HTTP | HTTP |
hybrid |
HTTP | WebSocket | HTTP |
Hybrid matches only exact GET /events and GET /events?... paths. A
different method or a path such as /events/archive uses HTTP.
HTTP failures are never retried automatically over WebSocket. Reconstruct the
connection with mode: 'websocket' to roll back future requests.
Discover and pair
An unpaired transport uses the same interface in all modes:
await bridge.connect();
const servers = await bridge.listServers();
const server = servers[0];
await bridge.requestPairing(server.server_id);
// Ask the user for the six-digit code shown by the registered server.
await bridge.submitPairingCode(server.server_id, code);
const pairingToken = bridge.getPairingToken();
Persist the bridge URL, server ID, and pairing token. The optional historical record mode remains readable, but mobile reconstructs every saved record as HTTP unless an app-wide development override is active. New mobile records store HTTP independently of a diagnostic override.
Endpoint history is separate from paired server connections. The SDK exports
SavedBridgeUrl (url, optional label, and lastUsedAt in Unix milliseconds),
loadSavedBridgeUrls(store), saveSavedBridgeUrls(store, entries), and
SAVED_BRIDGES_STORAGE_KEY. They use KeyValueStore and
clc_saved_bridges_v1; removing an endpoint leaves connection credentials intact.
When serverId and pairingToken are supplied, connect() resumes or
validates the pairing:
- WebSocket and hybrid create a fresh ephemeral legacy session for the WebSocket path.
- HTTP validates the token and current server availability without opening a frontend WebSocket.
HTTP origin
Bridge factories accept bare domains, HTTP(S) origins, and existing WebSocket
bridge URLs. A bare domain defaults to HTTPS; use explicit http:// for a
plaintext local bridge.
normalizeBridgeAddress() validates the input and supplies the HTTPS scheme.
deriveBridgeWebSocketUrl() supplies the corresponding WS(S) endpoint for
explicit legacy diagnostic factories. Existing configured WS(S) endpoints
and query strings remain unchanged.
The SDK:
- converts
wstohttpandwsstohttps; - removes a trailing
/wsor/ws/websocket; - removes query and fragment data.
Use bridgeHttpBaseUrl when the deployment publishes different HTTP and
WebSocket origins:
const bridge = createBridgeConnectionTransport({
bridgeUrl: 'wss://socket.example/ws/websocket',
bridgeHttpBaseUrl: 'https://api.example',
mode: 'http',
});
Request and response bodies
Every bridge mode implements the normal SDK Transport.request() contract.
In HTTP/hybrid HTTP-routed requests:
- objects are JSON encoded unless a content type is supplied;
ArrayBuffer, typed-array views, andBlobbodies are sent as raw bytes;- JSON responses are parsed;
- text, XML, JavaScript, and form responses return text;
- other content types return
ArrayBuffer.
The frontend pairing token is sent as X-Crystal-Bridge-Token. An application
Authorization header remains available to the proxied backend.
Timeout and lifecycle
Bridge transports accept the shared default and path/method timeout rules.
HTTP requests use AbortController when available. disconnect() aborts
active HTTP work and closes an active WebSocket.
Call prepareForResume() before reconnecting after a frontend suspension. The
transport validates liveness or pairing before later work:
bridge.prepareForResume();
await bridge.connect();
Capability compatibility
HTTP and hybrid require bridge HTTP protocol version 1. connect() checks
/bridge/v1/capabilities and fails clearly if the bridge does not advertise
that version. Missing capability routes (404/405) also report protocol
incompatibility. Update an older bridge or explicitly select legacy WebSocket
for diagnostics. Mobile exposes that choice in Home → Development Settings,
where it applies to later connection construction and leaves open requests
untouched.