From 5c311da52119cec34647a17c27beac02ed63bd9f Mon Sep 17 00:00:00 2001
From: Noah Petherbridge <root@kirsle.net>
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 `<video>` widget from the page (turning off the camera feed).
+* Also, a `who` update that says a person's videoActive went false will instruct all clients who had the video open, to close it (in case the PeerConnection closure didn't already do this).
+* If a user exits the room, e.g. exited their browser abruptly without gracefully closing PeerConnections, any client who had their video open will close it immediately.
+
+# WebSocket Message Actions
+
+Every message has an "action" and may have other fields depending on the action type.
+
+## Login
+
+Sent by: Client.
+
+Log in to the chat room. Looks like:
+
+```javascript
+// Client login
+{
+    "action": "login",
+    "username": "soandso",
+    "jwt": "jwt token string (if used)"
+}
+```
+
+If JWT authentication is enabled on the server, the ChatClient sends the JWT token to the server for validation.
+
+## Disconnect
+
+Sent by: Server.
+
+The server tells the client to disconnect and not come back, e.g.: they have been kicked or banned by an operator.
+
+```javascript
+// Server disconnect
+{
+    "action": "disconnect"
+}
+```
+
+## Ping
+
+Sent by: Server, Client.
+
+Just a keep-alive message to prevent the WebSocket connection from closing.
+
+```javascript
+{
+    "action": "ping"
+}
+```
+
+## Error
+
+Sent by: Server.
+
+Send an error message which will appear as a ChatServer error in chat.
+
+```javascript
+{
+    "action": "error",
+    "message": "Something went wrong!",
+    "username": "ChatServer",
+    "channel": "lobby"
+}
+```
+
+## Message
+
+Sent by: Client, Server.
+
+The client sends this to post a text message to a chat channel:
+
+```javascript
+// Client message to public channel
+{
+    "action": "message",
+    "channel": "lobby",
+    "message": "Hello everyone!"
+}
+
+// Client message to DM
+{
+    "action": "message",
+    "channel": "@target",
+    "message": "Hi"
+}
+```
+
+If this is a DM, the channel will begin with an `@` symbol followed by the username, like `"channel": "@target"`
+
+The server sends a similar message to push chats to the client:
+
+```javascript
+// Server message
+{
+    "action": "message",
+    "channel": "lobby",
+    "username": "senderName",
+    "message": "Hello!"
+}
+```
+
+If the message is a DM, the channel will be the username prepended by an @ symbol and the ChatClient will add it to the appropriate DM thread (creating a new DM thread if needed).
+
+## File
+
+Sent by: Client.
+
+The client is posting an image to share in chat.
+
+```javascript
+// Client file.
+{
+    "action": "file",
+    "channel": "lobby",
+    "bytes": new Uint8Array()
+}
+```
+
+The server will massage and validate the image data and then send it to others in the chat via a normal `message` containing an `<img>` tag with a data: URL - directly passing the image data to other chatters without needing to store it somewhere with a public URL.
+
+## Presence
+
+Sent by: Server.
+
+The `presence` message is just like a `message` but is designed for join/exit chat events.
+
+```javascript
+// Server message
+{
+    "action": "presence",
+    "username": "soandso",
+    "message": "has joined the room!"
+}
+```
+
+## Me
+
+Sent by: Client, Server.
+
+The "me" action communicates the user's current state and settings to the server. It will usually also trigger a "who" action to refresh the Who List for all chatters.
+
+The client sends "me" messages to send their webcam broadcast status and NSFW flag:
+
+```javascript
+// Client Me
+{
+    "action": "me",
+    "videoActive": true,
+    "nsfw": false
+}
+```
+
+The server may also push "me" messages to the user: for example if there is a conflict in username and the server has changed your username:
+
+```javascript
+// Server Me
+{
+    "action": "me",
+    "username": "soandso 12345",
+    "videoActive": true
+}
+```
+
+## Who
+
+Sent by: Server.
+
+The `who` action sends the Who Is Online list to all connected chatters.
+
+```javascript
+// Server Who
+{
+    "action": "who",
+    "whoList": [
+        {
+            "username": "soandso",
+            "op": false, // operator status
+            "avatar": "/picture/soandso.png",
+            "profileURL": "/u/soandso",
+            "videoActive": true,
+            "nsfW": false
+        }
+    ]
+}
+```
+
+## Open
+
+Sent by: Client, Server.
+
+This command is sent when a viewer wants to **open** the webcam of a broadcaster and see their video.
+
+```javascript
+// Client Open
+{
+    "action": "open",
+    "username": "target"
+}
+```
+
+The server echos the `open` command back at the person who initiated it:
+
+```javascript
+// Server Open
+{
+    "action": "open",
+    "username": "target",
+    "openSecret": "random string (not actually used)"
+}
+```
+
+And for the one sharing their webcam, sends a `ring` message.
+
+## Ring
+
+Sent by: Server.
+
+This is sent to the user who is sharing their webcam, to notify them that a viewer wants to connect.
+
+```javascript
+// Server Ring
+{
+    "action": "ring",
+    "username": "viewer",
+    "openSecret": "random string (not actually used)"
+}
+```
+
+The user will then initiate a WebRTC peer-to-peer connection with the viewer to share their video to them.
+
+## Watch, Unwatch
+
+Sent by: Client, Server.
+
+When a viewing client successfully receives video frames from the sender, they send a `watch` command to update the sender's Watching list, and will send an `unwatch` command when they close the video.
+
+The server passes the watch/unwatch message to the broadcaster.
+
+```javascript
+{
+    "action": "watch",
+    "username": "viewer"
+}
+```
+
+## Mute, Unmute
+
+Sent by: Client.
+
+The mute command tells the server that you are muting the user.
+
+```javascript
+// Client Mute
+{
+    "action": "mute",
+    "username": "target"
+}
+```
+
+When the user is muted:
+
+* The server will lie about your camera status on `who` messages to that user, always showing your camera as not active.
+* If they were already watching your camera, they see that you have turned your camera off and they disconnect.
+* The server will not send you any `message` from that user.
+
+The `unmute` action does the opposite and removes the mute status:
+
+```javascript
+// Client Unmute
+{
+    "action": "unmute",
+    "username": "target"
+}
+```
+
+## Boot
+
+Sent by: Client.
+
+This command is to kick a viewer off of your webcam and block them from opening your webcam again.
+
+```javascript
+// Client Boot
+{
+    "action": "boot",
+    "username": "target"
+}
+```
+
+When a user is booted:
+
+* They are kicked off your camera.
+* The chat server lies to them about your camera status on future `who` messages - showing that your camera is not running.
+
+Note: it is designed that the person being booted off can not detect that they have been booted. They will see your RTC PeerConnection close + get a Who List that says you are not sharing video - exactly the same as if you had simply turned off your camera completely.
+
+## WebRTC Signaling
+
+Sent by: Client, Server.
+
+The `candidate` and `sdp` actions are used as part of WebRTC signaling negotiations where the two browsers (the broadcaster and viewer) try and connect to share video.
+
+```javascript
+// Candidate
+{
+    "action": "candidate",
+    "username": "otherUser",
+    "candidate": "..."
+}
+
+// SDP
+{
+    "action": "sdp",
+    "username": "otherUser",
+    "description": "..."
+}
+```
+
+The server simply proxies the message between the two parties.
\ No newline at end of file