Add WebSocket protocol docs
This commit is contained in:
parent
6a2657ad49
commit
5c311da521
347
Protocol.md
Normal file
347
Protocol.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user