You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(protocol): define bridge server commands and format spec
Updates the CL5.1 "Delta" specification to include initial Bridge
Server command definitions and improves overall document readability.
- Adds `LINK`, `UNLINK`, and `CLASSIC_ULIST` opcodes to bridge section
- Standardizes markdown list markers and table alignment
- Refines document structure and vertical spacing
CL5.1 "Delta" is a revision of the CloudLink 5 protocol that transitions to a **WebRTC-based peer-to-peer network** as its core data layer.
3
+
CL5.1 "Delta" is a revision of the CloudLink 5 protocol that transitions to a **WebRTC-based peer-to-peer network** as its core data layer.
4
4
5
5
While pure P2P data transfer is the primary goal, the protocol still requires a mandatory **Signaling Server** (e.g., a standard PeerJS server) to exchange initial connection parameters (ICE candidates, SDP offers/answers). Once connected, peers communicate directly.
6
6
7
7
To enhance this core, the protocol introduces optional, specialized server/client roles:
8
-
* A **Discovery Server** to help peers find each other, negotiate lobbies, and resolve `username@designation` identities (e.g. `discovery@SOMEWHERE-EARTH`).
9
-
* A **Bridge Server** (Reserved for future use) to translate communications between CL5.1 clients and clients running legacy CL2/3/4 protocols.
10
-
* A **Relay Server** (Reserved for future use) to optimize mesh networking and broadcasts.
8
+
9
+
- A **Discovery Server** to help peers find each other, negotiate lobbies, and resolve `username@designation` identities (e.g. `discovery@SOMEWHERE-EARTH`).
10
+
- A **Bridge Server** (Reserved for future use) to translate communications between CL5.1 clients and clients running legacy CL2/3/4 protocols.
11
+
- A **Relay Server** (Reserved for future use) to optimize mesh networking and broadcasts.
11
12
12
13
## Protocol Schema
13
14
@@ -26,37 +27,39 @@ All communication is formatted as "in-band" JSON payloads sent across WebRTC Dat
26
27
}
27
28
```
28
29
29
-
*`opcode`: **(Required)** A string that defines the packet's purpose.
30
-
*`payload`: Any arbitrary JSON-serializable data.
31
-
*`origin`: **(Required for bridge/relay/broadcasts)** The unique instance ID of the original peer that sent the message.
32
-
*`target`: **(Required for bridge/relay/broadcasts)** The unique instance ID of the final recipient. This can be a specific peer ID or a broadcast indicator (`*`).
33
-
*`ttl`: **(Required)** Time-To-Live. Included for forward-compatibility with multi-hop mesh routing. Currently, reference clients require `ttl >= 0` to accept a packet but execute 1-hop direct broadcasts without decrementing. The default value is `1`.
34
-
*`id` & `method`: Optional properties for variable/list synchronization and RPC handling.
35
-
*`listener`: Optional property to tag packets and await responses (used primarily in Mesh/RPC commands).
30
+
-`opcode`: **(Required)** A string that defines the packet's purpose.
31
+
-`payload`: Any arbitrary JSON-serializable data.
32
+
-`origin`: **(Required for bridge/relay/broadcasts)** The unique instance ID of the original peer that sent the message.
33
+
-`target`: **(Required for bridge/relay/broadcasts)** The unique instance ID of the final recipient. This can be a specific peer ID or a broadcast indicator (`*`).
34
+
-`ttl`: **(Required)** Time-To-Live. Included for forward-compatibility with multi-hop mesh routing. Currently, reference clients require `ttl >= 0` to accept a packet but execute 1-hop direct broadcasts without decrementing. The default value is `1`.
35
+
-`id` & `method`: Optional properties for variable/list synchronization and RPC handling.
36
+
-`listener`: Optional property to tag packets and await responses (used primarily in Mesh/RPC commands).
36
37
37
38
---
38
39
39
40
## Peer-to-Peer Commands
40
41
41
42
These commands are sent directly between connected peers.
42
43
43
-
|`opcode`| Description |
44
-
| :--- | :--- |
45
-
|**`NEGOTIATE`**| Sent immediately upon opening the default channel. Contains an object detailing the client's capabilities (version, plugins, roles). |
46
-
|**`G_MSG`** / **`P_MSG`**| Global/Private Message. `G_MSG` targets `*` (broadcast to all direct connections), while `P_MSG` targets a specific peer ID. |
47
-
|**`G_VAR`** / **`P_VAR`**| Variable Sync message. Synchronizes state across peers. |
48
-
|**`G_LIST`** / **`P_LIST`**| List Sync message. Synchronizes array states across peers using specific mutation methods. |
49
-
|**`G_MESH`** / **`P_MESH`**| RPC (Remote Procedure Call) broadcasts/unicasts. If the `method` is `req`, recipients must reply with an `ack`. |
50
-
|**`NEW_CHAN`**| Control message sent to negotiate a new, named WebRTC data channel. |
51
-
|**`PING`** / **`PONG`**| Control messages used for computing Round-Trip Time (RTT) and clock offset synchronization. |
52
-
|**`CALL`** / **`ANSWER`** / **`HANGUP`** / **`DECLINE`**| Voice call signaling used to orchestrate WebRTC MediaStreams. |
53
-
|**`WARNING`** / **`VIOLATION`**| State control messages. `WARNING`s are user-correctable. `VIOLATION`s trigger an immediate, mandatory client-side disconnect sequence. |
54
-
|**`HELLO`**| Advertises a peer's preferred name and designation. Used by the Discovery plugin to populate local identity caches. |
|**`NEGOTIATE`**| Sent immediately upon opening the default channel. Contains an object detailing the client's capabilities (version, plugins, roles).|
47
+
|**`G_MSG`** / **`P_MSG`**| Global/Private Message. `G_MSG` targets `*` (broadcast to all direct connections), while `P_MSG` targets a specific peer ID.|
48
+
|**`G_VAR`** / **`P_VAR`**| Variable Sync message. Synchronizes state across peers.|
49
+
|**`G_LIST`** / **`P_LIST`**| List Sync message. Synchronizes array states across peers using specific mutation methods.|
50
+
|**`G_MESH`** / **`P_MESH`**| RPC (Remote Procedure Call) broadcasts/unicasts. If the `method` is `req`, recipients must reply with an `ack`.|
51
+
|**`NEW_CHAN`**| Control message sent to negotiate a new, named WebRTC data channel.|
52
+
|**`PING`** / **`PONG`**| Control messages used for computing Round-Trip Time (RTT) and clock offset synchronization.|
53
+
|**`CALL`** / **`ANSWER`** / **`HANGUP`** / **`DECLINE`**| Voice call signaling used to orchestrate WebRTC MediaStreams. |
54
+
|**`WARNING`** / **`VIOLATION`**| State control messages. `WARNING`s are user-correctable. `VIOLATION`s trigger an immediate, mandatory client-side disconnect sequence. |
55
+
|**`HELLO`**| Advertises a peer's preferred name and designation. Used by the Discovery plugin to populate local identity caches.|
55
56
56
57
### Packet-Specific Syntax (P2P)
57
58
58
59
#### **`G_LIST` / `P_LIST`**
60
+
59
61
Used to synchronize global/local lists. `payload` depends on the `method`. The `id` must be a unique string (network tag).
62
+
60
63
```js
61
64
{
62
65
"opcode":"G_LIST"|"P_LIST",
@@ -68,7 +71,9 @@ Used to synchronize global/local lists. `payload` depends on the `method`. The `
68
71
```
69
72
70
73
#### **`G_MESH` / `P_MESH`**
74
+
71
75
Used for Remote Procedure Calls. May only be sent on the `default` data channel.
76
+
72
77
```js
73
78
{
74
79
"opcode":"G_MESH"|"P_MESH",
@@ -78,7 +83,9 @@ Used for Remote Procedure Calls. May only be sent on the `default` data channel.
78
83
"ttl":1
79
84
}
80
85
```
86
+
81
87
Recipients of a `req` method must execute the RPC and reply with:
88
+
82
89
```js
83
90
{
84
91
"opcode":"G_MESH"|"P_MESH",
@@ -93,51 +100,51 @@ Recipients of a `req` method must execute the RPC and reply with:
93
100
94
101
## Discovery Server Commands
95
102
96
-
Discovery features are optional. When enabled, clients connect to a designated server (e.g., `discovery@SOMEWHERE-EARTH`) to resolve user identities and negotiate matchmaking lobbies.
103
+
Discovery features are optional. When enabled, clients connect to a designated server (e.g., `discovery@SOMEWHERE-EARTH`) to resolve user identities and negotiate matchmaking lobbies.
97
104
98
105
### Client -> Server Requests
99
106
100
-
|`opcode`| Description |
101
-
| :--- | :--- |
102
-
|**`REGISTER`**| Registers the client's preferred username with the server. |
103
-
|**`QUERY`**| Requests the `username@designation` mapping for a specific instance ID. |
104
-
|**`LOBBY_LIST`**| Requests an array of all active, visible, unlocked lobbies. |
105
-
|**`LOBBY_INFO`**| Requests detailed metadata about a specific lobby ID. |
106
-
|**`CONFIG_HOST`**| Requests the creation of a new lobby. |
107
-
|**`CONFIG_PEER`**| Requests to join an existing lobby. |
108
-
|**`LOCK`** / **`UNLOCK`**| (Host) Toggles if new members can join. |
109
-
|**`HIDE`** / **`SHOW`**| (Host) Toggles visibility in the public `LOBBY_LIST`. |
110
-
|**`SIZE`**| (Host) Updates max capacity (`-1` for unlimited). |
111
-
|**`PASSWORD`**| (Host) Sets or updates the lobby password. |
112
-
|**`KICK`**| (Host) Forcefully removes a peer from the lobby. |
113
-
|**`TRANSFER`**| (Host) Transfers host privileges to another peer. |
114
-
|**`CLOSE`**| (Host) Shuts down the lobby, disconnecting all members. |
115
-
|**`LEAVE`**| (Peer) Gracefully exits the current lobby. |
|**`LOBBY_EXISTS`**| Error: Attempted to host a lobby ID that is already taken.|
134
+
|**`LOBBY_NOTFOUND`**| Error: Attempted to join or query a lobby that doesn't exist.|
135
+
|**`PASSWORD_ACK`**| Confirms a lobby password change was successful.|
136
+
|**`PASSWORD_REQUIRED`**| Error: Attempted to join a lobby without providing a required password.|
137
+
|**`PASSWORD_FAIL`**| Error: Provided an incorrect lobby password.|
138
+
|**`CONFIG_REQUIRED`**| Error: Attempted to perform a lobby action without being in a lobby.|
139
+
|**`NEW_LOBBY`**| Broadcasted to all peers when a new (public) lobby is created.|
140
+
|**`PEER_JOIN`**| Sent to lobby members when a new peer joins, prompting P2P connection attempts.|
141
+
|**`PEER_LEFT`**| Sent to lobby members when a peer leaves.|
142
+
|**`KICK_ACK`**| Sent to the Host to confirm a kick was successful/failed.|
143
+
|**`KICKED`**| Sent to a peer to notify them they have been forcefully removed.|
144
+
|**`TRANSITION`**| Informs a peer their role has changed (e.g., promoted to `host` or demoted to `peer`).|
145
+
|**`CLOSE_ACK`** / **`LOBBY_CLOSED`**| Confirms the lobby was shut down. |
146
+
|**`LEAVE_ACK`**| Confirms the client successfully exited the lobby.|
147
+
|**`AUTO_REGISTER`**| Confirms successful automatic username registration. Only implemented for bridge servers at this time.|
141
148
142
149
---
143
150
@@ -146,7 +153,14 @@ Discovery features are optional. When enabled, clients connect to a designated s
146
153
The following server types are reserved in the `NEGOTIATE` payload (`is_bridge`, `is_relay`) but are currently undocumented and lack implementation in the reference client architecture.
147
154
148
155
### Bridge Server Commands
149
-
Reserved for translating communication between CL5.1 clients and legacy CL2/3/4 protocols over WebSockets.
156
+
157
+
Translates communication between CL5.1 clients and legacy CL2/3/4 protocols over WebSockets.
|**`LINK`** / **`UNLINK`**| Sent to the bridge server to subscribe/unsubscribe from legacy CloudLink rooms. Replies with a corresponding **`_ACK`** packet. |
162
+
|**`CLASSIC_ULIST`**| Broadcasted to peers to synchronize the active userlist of connected legacy clients. The payload includes a `mode` (`set`, `add`, `remove`) and an array of `users`. |
150
163
151
164
### Relay Server Commands
165
+
152
166
Reserved for True Mesh capabilities, offloading bandwidth-heavy broadcasts from client connections to dedicated relay nodes utilizing `ttl` decrements.
0 commit comments