ERICADE Radio API v2 — Chat WebSocket

Overview

The chat is a WebSocket. Everything that can be done over it is done over it: reading, writing, knowing how many are there. The REST API only does what a socket cannot — hand out logins, and let an administrator see the server's state and who wrote what.

Unlike the station data feed, nobody is here without an account. Accounts made with a password and accounts made through SceneID are the same thing to the chat.

The privilege is read from the database, never from anything the socket is told: when a connection logs in, again for every message it sends, and for everybody connected every 30 seconds. A ban, a demotion and a “log out everywhere” therefore end a conversation that is going on, and an account that is accepted while it is reading along gets its text box without reconnecting.

Logging in: the ticket

A visitor's login on radio.ericade.net is a user token kept in an HttpOnly cookie on radio.ericade.net: no script can read it, and the browser never sends it to api.ericade.net. The socket can therefore never see it, and it is not supposed to. Instead:

1. The page asks its own site (POST https://radio.ericade.net/chat/, with a CSRF token).
2. The website's PHP asks the API, server to server, with the visitor's user token: POST /radio/v2/chat/ticket. The API answers with a ticket: 64 hexadecimal characters, good for one login within 60 seconds. Only its SHA-256 is stored.
3. The page opens the socket and says {"Action":"auth","Ticket":"…"} as its first message.
4. The server uses the ticket up — one UPDATE … WHERE Used IS NULL, so of two logins with the same ticket at the same instant exactly one gets in — and then reads the account it was made for: privilege, display name, and whether the account still has a login that is alive.

A ticket says who, and nothing else. What the account may do is decided by the server from the database, at that moment and all the time after. An account gets at most 10 tickets a minute (429 after that).

Connecting

Example (browser JavaScript)

// ticket and url come from the website's own /chat/ endpoint (see "Logging in")
const ws = new WebSocket(url);
ws.onopen = () => ws.send(JSON.stringify({ Action: "auth", Ticket: ticket }));
ws.onmessage = (e) => {
  const data = JSON.parse(e.data);
  switch (data.Event) {
    case "ready":   data.History.forEach(show); break;
    case "message": show(data); break;
    case "error":   if (data.Code === "throttled") waitSeconds(data.RetryAfter); break;
    case "bye":     /* data.Code says whether to try again - see below */ break;
  }
};
function show(m) {
  const li = document.createElement("li");
  li.textContent = m.Name + ": " + m.Text;      // textContent. Always.
  list.appendChild(li);
}
ws.send(JSON.stringify({ Action: "send", Text: "Hello!" }));

On a connection that closed without a bye, or with one that allows it, a client fetches a new ticket and connects again, waiting a little longer each time (the website: 1, 2, 5, 10, 20, then 30 seconds). A ticket cannot be used twice, so there is nothing to keep.

Message envelope

Every message is one JSON text frame. Everything the server sends has an Event and a Timestamp (Unix time); everything a client sends has an Action. Binary frames, fragmented messages, compressed frames and frames over 16 kB are protocol errors and close the connection.

What the server says

welcome

ready

message

Example

{
  "Event": "message",
  "Timestamp": 1789772127,
  "ID": "1418923377712345088",
  "Source": "discord",
  "Name": "ModFan [Discord]",
  "Bot": 0,
  "Text": "Found my old A1200 in the attic today",
  "Images": [
    { "URL": "https://media.discordapp.net/attachments/1/2/a1200.jpg?ex=...&width=400&height=300", "Width": 400, "Height": 300 }
  ]
}

history, users, you, bridge, pong

error

Something a client sent was refused. The connection stays. Message is a sentence for a person.

bye

The server is about to close the connection, and says why.

What a client may say

{ "Action": "send", "Text": "Evening all!" }

There is no action that names a user, a room or a message: a client can say who it is once, with a ticket the API made, and after that only what it says.

Names, text and pictures

The Discord bridge

Both run inside the server's event loop without ever waiting for Discord: a message crosses the website at once and reaches Discord when Discord takes it. A 429 is obeyed (retry_after), a failed delivery is tried three times, at most 100 messages wait. A bot that Discord refuses (401, 403, 404) is asked about again after five minutes, not every two seconds. When Discord cannot be reached, everybody gets a bridge event and the chat goes on among the website's users. After a restart the server reads the latest messages of #general, so the history survives it; messages the website posted come back as website messages, under the ID they had.

Limits

Operations

The server listens on 127.0.0.1:8147 behind Apache, next to the station data relay (8146), and is kept alive by websocket/chat-ws.sh from cron. It reads config.php once, when it starts: after changing a $Chat… setting or $CommentProfanityList, run pkill -f 'chat-server\.php' and the watchdog starts it again within the minute. Its log is /var/log/chat-ws.txt. The two reporting endpoints and the capacity log work exactly like the relay's.

GET /health

Liveness check. Returns 200 OK with the body OK as long as the event loop is running.

GET /status

Capacity as plain text — the first line is the relay's, word for word, the second is about the chat:

Used websockets: 42, Available websockets: 158, Total websockets: 200
Logged in: 40, Discord: connected, Waiting for Discord: 0

Both are only reachable on the server itself (curl http://127.0.0.1:8147/status); an administrator gets the same through chat/status. When every place is taken they answer 503 like any other connection.

Capacity event log

/var/log/websocket_chat_events/<YYYY-MM-DD>.log, one file a day, each line [timestamp] [event-type] message, with the relay's event types and the relay's rate limit:

Each threshold fires once per crossing and is armed again when usage falls back under it.

The visitor's address

Behind Apache every connection comes from 127.0.0.1. The visitor's address is the last entry of X-Forwarded-For — the one Apache added itself; what a client writes in front of it counts for nothing — and it is believed only when the peer is one of $ChatTrustedProxies. It is used for the per-address limit and stored with each logged message.

Setting it up

1. Database: run objects/sql_chat.sql (tables ChatTickets and ChatLog). Until then chat/ticket answers 503 and the server turns logins away; nothing else notices.
2. Apache, in the api.ericade.net virtual host, next to the /ws/stationdata lines, then reload:

   ProxyPass        "/ws/chat" "ws://127.0.0.1:8147/"
   ProxyPassReverse "/ws/chat" "ws://127.0.0.1:8147/"

3. Discord, reading — a bot. At discord.com/developers/applications: New Application → Bot → Reset Token (shown once: $ChatDiscordBotToken) → switch on Message Content Intent (without it Discord hands over messages with empty text) → switch Public Bot off. OAuth2 → URL Generator: scope bot, permissions View Channels and Read Message History; open the address, choose the server. In Discord: Settings → Advanced → Developer Mode, right-click #general → Copy Channel ID ($ChatDiscordChannelID).
4. Discord, writing — a webhook. Right-click #general → Edit Channel → Integrations → Webhooks → New Webhook → Copy Webhook URL ($ChatDiscordWebhookURL).
5. config.php: the three values, and $ChatEnabled = 1.
6. cron (root): * * * * * /var/www/html/api.ericade.net/websocket/chat-ws.sh — and chmod +x the script. Then tail /var/log/chat-ws.txt: it names the channel it reads and the webhook it writes through, and says “Discord is reachable”. HTTP 401 there means a wrong token, 403 a bot without the two permissions in #general, 404 a wrong channel id.

No package has to be installed: the server uses PHP's curl, mbstring and pdo_mysql extensions, which the API needs already.