From 5c311da52119cec34647a17c27beac02ed63bd9f Mon Sep 17 00:00:00 2001 From: Noah Petherbridge Date: Thu, 23 Mar 2023 21:13:26 -0700 Subject: [PATCH] Add WebSocket protocol docs --- Protocol.md | 347 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 Protocol.md diff --git a/Protocol.md b/Protocol.md new file mode 100644 index 0000000..cc3310b --- /dev/null +++ b/Protocol.md @@ -0,0 +1,347 @@ +# Chat Protocol + +The primary communication channel for the chat is WebSockets between the ChatServer and ChatClient (the front-end web page). + +The protocol was made up as it went and here is some (hopefully current) documentation of what the different message types and contents look like. + +Messages are delivered as JSON objects in both directions. + +# WebRTC Workflow + +WebRTC only kicks in when a user wants to see the webcam stream shared by a broadcaster. Simply turning on your webcam doesn't start any WebRTC stuff - it's when somebody clicks to see your cam, or you click to see somebody else's. + +Since the WebRTC workflow is always triggered by _somebody_ clicking on the video icon to open a broadcaster's camera we will start there. + +The one who initiates the connection is called the **offerer** (they send the first offer to connect) and the one sharing video is the **answerer** in WebRTC parlance. + +1. The offerer clicks the video button to begin the process. This sends an [open](#open) message to the server. +2. The server echoes the [open](#open) back to the offerer and sends a [ring](#ring) to the answerer, to let them know that the offerer wants to connect. + * For the answerer, the `ring` message triggers the "has opened your camera" notice in chat. +3. Both the offerer and answerer will use the server to negotiate a WebRTC peer connection. + * WebRTC is a built-in browser standard and the two browsers will negotiate "ICE candidates" and "session description protocol" (SDP) messages. + * The [candidate](#candidate) and [sdp](#sdp) actions on the chat server allow simple relaying of these messages between browsers. + * The answerer adds their video stream to the RTC PeerConnection so that once they are established, the offerer receives the video. +4. When connectivity is established, the offerer sends a [watch](#watch) message which the server passes to the answerer, so that their username apprars in the Watching list. + +The video stream can be interrupted and closed via various methods: + +* When the answerer turns off their camera, they close all RTC PeerConnections with the offerers. +* When the PeerConnection is closed, the offerer deletes the `