PacketRelayDocs

Create the first bridge#

A bridge joins one desktop connection and one mobile connection. This procedure uses two websocat terminals to prove that the relay admits both roles and forwards text unchanged.

Before you start#

  • Start a local relay as described in Deploy.
  • Install websocat or another interactive WebSocket client.
  • Open two terminals.
  • Choose a session identifier containing only letters, digits, ., _, or -. Use an unguessable value outside local testing.

Connect the desktop#

  1. Open the first socket.

    websocat ws://127.0.0.1:8080/

  2. Send the desktop hello as the first text frame.

    {"type":"desktop_hello","session_id":"first-session"}

  3. Confirm that the relay answers:

    {"type":"session_ready","session_id":"first-session"}

Send the hello within five seconds of opening the socket. A binary hello or a late hello is not admitted.

Connect the mobile#

  1. Open the second socket against the same relay.

  2. Send a mobile hello with the same session identifier.

    {"type":"mobile_hello","session_id":"first-session"}

  3. Confirm that the mobile receives session_ready followed by:

    {"type":"peer_connected"}

The desktop also receives peer_connected when the mobile joins. A mobile hello cannot create a bridge; the desktop must establish it first.

Send a frame#

Type a text value into either terminal:

{"hello":"world"}

The other terminal receives the same text. The relay does not parse or wrap bridge payloads. The exact one-field envelope {"type":"ping"} is reserved as a keepalive on a bridge and is not forwarded to the peer. See Protocol for how the same envelope behaves on the other session kinds.

Verify#

The bridge is working when:

  • each hello receives session_ready;
  • both sides observe peer_connected;
  • a normal text frame crosses unchanged in each direction; and
  • closing either terminal causes the survivor to receive {"type":"peer_disconnected"}.

If it does not work#

Result Cause
session not found The mobile connected before the desktop created the bridge, or the desktop disconnected.
invalid session ID The identifier is empty, too long, or contains an unsupported character.
The socket closes without session_ready The hello was late, binary, or not a supported JSON hello.
A frame does not cross The second peer is absent, the frame is binary, or the frame is the reserved keepalive.

Next#