BareRTC/docs/API.md
Noah Petherbridge fd82a463f3 Deadlock detection, DND, and Frontend Fixes
* Deadlock detection: the chatbot handlers will spin off a background goroutine
  to ping DMs at itself and test for responsiveness. If the echoes don't return
  for a minute, issue a /api/shutdown command to the HTTP server to force a
  reboot.
* New admin API endpoint: /api/shutdown, equivalent to the operator '/shutdown'
  command sent in chat. Requires your AdminAPIKey to call it. Used by the chatbot
  as part of deadlock detection.
* Adjust some uses of mutexes to hopefully mitigate deadlocks a bit.
* Do Not Disturb: if users opt to "Ignore unsolicited DMs" they will set a DND
  status on the server which will grey-out their DM icon for other chatters.
* Bring back an option for ChatServer to notify you when somebody begins watching
  your camera (on by default).
* Automatically focus the message entry box when changing channels.
* Lower webcam resolution hints to 480p to test performance implications.
2023-08-29 15:54:40 -07:00

113 lines
3.2 KiB
Markdown

# BareRTC Web API
BareRTC provides some web API endpoints over HTTP to support better integration with your website.
Authentication to the API endpoints is gated by the `AdminAPIKey` value in your settings.toml file.
For better integration with your website, the chat server exposes some data via JSON APIs ready for cross-origin ajax requests. In your settings.toml set the `CORSHosts` to your list of website domains, such as "https://www.example.com", "http://localhost:8080" or so on.
Current API endpoints include:
## GET /api/statistics
Returns basic info about the count and usernames of connected chatters:
```json
{
"UserCount": 1,
"Usernames": ["admin"]
}
```
## POST /api/authentication
This endpoint can provide JWT authentication token signing on behalf of your website. The [Chatbot](Chatbot.md) program calls this endpoint for authentication.
Post your desired JWT claims to the endpoint to customize your user and it will return a signed token for the WebSocket protocol.
```json
{
"APIKey": "from settings.toml",
"Claims": {
"sub": "username",
"nick": "Display Name",
"op": false,
"img": "/static/photos/avatar.png",
"url": "/users/username",
"emoji": "🤖",
"gender": "m"
}
}
```
The return schema looks like:
```json
{
"OK": true,
"Error": "error string, omitted if none",
"JWT": "jwt token string"
}
```
## POST /api/shutdown
Shut down (and hopefully, reboot) the chat server. It is equivalent to the `/shutdown` operator command issued in chat, but callable from your web application. It is also used as part of deadlock detection on the BareBot chatbot.
It requires the AdminAPIKey to post:
```json
{
"APIKey": "from settings.toml"
}
```
The return schema looks like:
```json
{
"OK": true,
"Error": "error string, omitted if none"
}
```
The HTTP server will respond OK, and then shut down a couple of seconds later, attempting to send a ChatServer broadcast first (as in the `/shutdown` command). If the chat server is deadlocked, this broadcast won't go out but the program will still exit.
It is up to your process supervisor to automatically restart BareRTC when it exits.
## POST /api/blocklist
Your server may pre-cache the user's blocklist for them **before** they
enter the chat room. Your site will use the `AdminAPIKey` parameter that
matches the setting in BareRTC's settings.toml (by default, a random UUID
is generated the first time).
The request payload coming from your site will be an application/json
post body like:
```json
{
"APIKey": "from your settings.toml",
"Username": "soandso",
"Blocklist": [ "usernames", "that", "they", "block" ],
}
```
The server holds onto these in memory and when that user enters the chat
room (**JWT authentication only**) the front-end page will embed their
cached blocklist. When they connect to the WebSocket server, they send a
`blocklist` message to push their blocklist to the server -- it is
basically a bulk `mute` action that mutes all these users pre-emptively:
the user will not see their chat messages and the muted users can not see
the user's webcam when they broadcast later, the same as a regular `mute`
action.
The JSON response to this endpoint may look like:
```json
{
"OK": true,
"Error": "if error, or this key is omitted if OK"
}
```