Reconnection

Automatic reconnection with backoff

Crosslink automatically reconnects when a connection is lost. On a mobile client this is presented by Crosslink’s own reconnect screen — you do not build one, and crosslink.onConnected(rpc) fires again on the other side of it.

Reconnection reuses the device’s existing trust. Closing the desktop app, sleeping or restarting the machine, changing Wi-Fi or moving the phone between networks all reconnect silently. A new pairing code is required only when the trust relationship itself is invalid — revoked, removed, or unreadable.

A route the browser refuses is not retried as if the host were down. A page served over https cannot open a ws:// socket, so those endpoints are reported as blocked with the reason, rather than burning a dial timeout on each attempt. See Durable Origins.

How reconnection works

1. Transport lost detected (WebSocket close / timeout)
2. Client enters "reconnecting" state
3. Backoff timer: 500ms -> 1s -> 2s -> 4s -> 8s -> 16s -> 30s (capped), +/-30% jitter
4. Fresh CLX1 handshake with new ephemeral keys
5. Subscriptions restored
6. Queued idempotent calls replayed
7. Client returns to a connected state (direct / turn-relayed / crosslink-relayed)

Backoff strategy

Delay is min(30s, 500ms * 2^attempt), with random jitter of +/-30% applied on top:

Attempt 1: ~500ms
Attempt 2: ~1 second
Attempt 3: ~2 seconds
Attempt 4: ~4 seconds
Attempt 5: ~8 seconds
Attempt 6: ~16 seconds
Attempt 7+: ~30 seconds (capped)

The backoff resets after a successful connection.

Reconnection is a new session

Each reconnection performs a fresh CLX1 handshake with new ephemeral keys:

• Forward secrecy is maintained per-session
• No bearer tokens are reused
• Revocation is re-checked on every handshake
• Device identity is verified against stored records

Offline call queueing

Idempotent methods are queued during disconnection:

// This will be queued and replayed after reconnection
const result = await rpc.call("data.get", null, { idempotent: true });

Non-idempotent methods fail immediately:

// This fails with "not_connected" during disconnection
await rpc.call("data.create", { title: "New" });

Subscription restoration

Event subscriptions are automatically restored after reconnection:

// Subscribe once -- survives reconnections
rpc.subscribe("data.changed", (payload) => {
  console.log("Update:", payload);
});

Transport resilience

The client adapts to network changes:

Phone moves from WiFi to cellular:
  LAN connection lost
  -> Client falls back to relay
  -> Session re-established
  -> RPC continues

Desktop goes to sleep:
  All connections lost
  -> Clients enter reconnect state
  -> Desktop wakes up
  -> Clients reconnect automatically

Monitoring reconnection

const client = createCrosslinkClient({
  onStateChange: (state, detail) => {
    if (state === "reconnecting") {
      console.log("Reconnecting...", detail);
      // detail may include attempt count, backoff delay
    }
    if (state === "direct" || state === "crosslink-relayed" || state === "turn-relayed") {
      console.log("Reconnected!");
    }
  }
});

Relay channel recovery

If a relay channel expires (24h lifetime), the host:

1. Allocates a new channel
2. Publishes the new channel ID through signaling
3. Clients discover the new channel via presence lookup
4. Reconnection proceeds normally

This is transparent to the application.