accidental.cc
podcast manager
webcrtc and webtorrent brainstorming
+165
readme-devlog.org
+165
readme-devlog.org
···
121
121
- sends invitation+registration token to server
122
122
- added to the realm
123
123
- go to subsequent runs
124
+
125
+
* WebRTC Full-Mesh Implementation Plan
126
+
127
+
** Overview
128
+
129
+
Implement a full-mesh WebRTC system where every client in a realm establishes direct
130
+
peer-to-peer connections with all other clients. The existing WebSocket infrastructure
131
+
serves as the signaling channel, leveraging the newly refactored broadcast protocol.
132
+
133
+
** Architecture Components
134
+
135
+
*** Protocol Extensions (src/common/protocol/messages-rtc.js)
136
+
137
+
Create new WebRTC message schemas:
138
+
- rtc.offer - SDP offer with connectionId
139
+
- rtc.answer - SDP answer with connectionId
140
+
- rtc.ice-candidate - ICE candidate exchange
141
+
- rtc.peer-state - Connection state updates
142
+
- rtc.request-connection - Initiate connection with polite flag
143
+
- rtc.peer-joined - Server message when peer joins (includes member list)
144
+
- rtc.peer-left - Server message when peer leaves
145
+
146
+
*** Server-Side Updates
147
+
148
+
**** broadcastToRealm Function Enhancement
149
+
150
+
Update the function signature to:
151
+
- Take complete messages instead of payloads
152
+
- Add skipSelf flag (default true)
153
+
- For rtc.peer-joined, set skipSelf=false to include sender
154
+
155
+
**** Handler Updates (handler-realm.js)
156
+
157
+
- On client join: Broadcast rtc.peer-joined to ALL members (including self)
158
+
- On client leave: Broadcast rtc.peer-left to remaining members
159
+
- Existing broadcast mechanism handles WebRTC signaling perfectly
160
+
161
+
*** WebRTC Utilities (src/common/webrtc.js)
162
+
163
+
Core utilities for WebRTC:
164
+
- RTC_CONFIG with STUN servers
165
+
- DATA_CHANNEL_CONFIG for reliable messaging
166
+
- PerfectNegotiation class for glare-free negotiation
167
+
- ConnectionHealthMonitor for ping/pong health checks
168
+
169
+
*** Client WebRTC Manager (src/client/webrtc-manager.js)
170
+
171
+
Main orchestrator that:
172
+
- Manages all peer connections
173
+
- Handles incoming RTC messages
174
+
- Routes signaling between peers
175
+
- Emits events for UI updates
176
+
- Provides public API for sending messages
177
+
178
+
*** Client Peer Connection (src/client/peer-connection.js)
179
+
180
+
Individual peer connection handler:
181
+
- RTCPeerConnection lifecycle management
182
+
- Perfect negotiation implementation
183
+
- Data channel setup and messaging
184
+
- Health monitoring with ping/pong
185
+
- Automatic reconnection with exponential backoff
186
+
- Connection state tracking
187
+
188
+
*** UI Components
189
+
190
+
**** PeerList Component
191
+
- Shows all realm members
192
+
- Connection status indicators
193
+
- Real-time state updates
194
+
195
+
**** MessageInterface Component
196
+
- Send messages via WebRTC or server broadcast
197
+
- Display incoming messages
198
+
- Mode selection (P2P vs server relay)
199
+
200
+
** Connection Flow
201
+
202
+
*** Initial Join
203
+
1. Client authenticates via WebSocket
204
+
2. Server sends realm.status
205
+
3. Server broadcasts rtc.peer-joined to ALL members
206
+
4. Client sees own join message with member list
207
+
5. Client initializes WebRTCManager
208
+
6. Client connects to all existing members
209
+
210
+
*** Peer-to-Peer Connection
211
+
1. Initiator creates RTCPeerConnection (polite=true)
212
+
2. Creates data channel, triggering negotiation
213
+
3. Sends offer via realm.broadcast to target peer
214
+
4. Target creates RTCPeerConnection (polite=false)
215
+
5. Exchanges answer and ICE candidates
216
+
6. Data channel opens, health monitoring starts
217
+
218
+
*** Reconnection
219
+
1. Health monitor detects issues or connection drops
220
+
2. Exponential backoff timer starts
221
+
3. New connection attempt with fresh connectionId
222
+
4. ICE restart or full renegotiation
223
+
224
+
** Key Design Decisions
225
+
226
+
*** Perfect Negotiation Pattern
227
+
Prevents glare when both peers try to connect simultaneously by using
228
+
polite/impolite roles.
229
+
230
+
*** Health Monitoring
231
+
Proactive ping/pong messages detect connection issues before browser APIs,
232
+
enabling faster recovery.
233
+
234
+
*** Connection ID Tracking
235
+
Each connection attempt has unique ID to ensure offer/answer pairs match
236
+
during concurrent connections.
237
+
238
+
*** Leveraging Existing Infrastructure
239
+
WebRTC signaling is just another payload type in the existing broadcast
240
+
system - no new server complexity.
241
+
242
+
** Implementation Order
243
+
244
+
*** Phase 1: Core Infrastructure
245
+
1. Create protocol message schemas
246
+
2. Update broadcastToRealm function
247
+
3. Add peer join/leave broadcasts
248
+
4. Create WebRTC utilities module
249
+
250
+
*** Phase 2: Client Connection Management
251
+
1. Implement WebRTCManager
252
+
2. Create PeerConnection class
253
+
3. Add perfect negotiation
254
+
4. Implement health monitoring
255
+
256
+
*** Phase 3: UI Integration
257
+
1. Update main app to initialize WebRTC
258
+
2. Create PeerList component
259
+
3. Add MessageInterface with dual modes
260
+
4. Style connection indicators
261
+
262
+
*** Phase 4: Robustness
263
+
1. Add reconnection logic
264
+
2. Implement ICE restart
265
+
3. Handle edge cases
266
+
4. Add comprehensive error handling
267
+
268
+
** Testing Strategy
269
+
270
+
*** Unit Tests
271
+
- Perfect negotiation scenarios
272
+
- Health monitoring logic
273
+
- Message routing
274
+
275
+
*** Integration Tests
276
+
- Full connection flow with mocks
277
+
- Signaling message flow
278
+
- State management
279
+
280
+
*** E2E Tests
281
+
- Real browser testing
282
+
- Network condition simulation
283
+
- Multi-peer scenarios
284
+
285
+
*** Load Tests
286
+
- Mesh scalability limits
287
+
- Message throughput
288
+
- Connection stability