ERICADE Radio API v2 — Administrators' Alerts WebSocket

Overview

The API talks to its administrators through one function, sendAdminAlert() — until 2026-10-15 called sendDiscordWebhook(), because posting the alert to the station's Discord was all it did. Since 2026-10-15 every alert goes three ways at once, in this order:

1. it is stored in the table AdminAlerts — the record, which admindata/list and admindata/get hand out and radio.ericade.net/conelrad/alerts/ shows;
2. it is pushed to this socket as the event admin-alert, and the server hands it to every logged-in administrator at once — the purple box at the top of whatever page they have open;
3. it is posted to Discord through the station's webhook, as it always was.

None of the three may fail the caller, and none may fail the others: a database that is down costs the record, not the push and not Discord; a server that is not running costs the push alone.

Like the chat and unlike the station data feed, nobody is here without an account — and here only one kind of account gets in at all.

The privilege is read from the database, never from anything the socket is told: when a connection logs in, before every alert the server hands out, and for everybody connected every 30 seconds. A demotion, a ban and a “log out everywhere” therefore end a connection that is open — and an alert raised the moment after a demotion reaches the demoted account no more.

What an alert is

Whatever a job on the API's server has to say to the people who run the station. The nightly jobs each end with one (the track presence validation, the media file check, the ModArchive enrichment, the playlist build, the podcast integrity check, the log analysis, the performance analysis, the WebP conversion); the workers report what they measured (the song scan, the song tempo); the Shoutcast statistics sum up the listening day from the server's own logs at 23:30 (ShoutcastLogStats, red when the source dropped or the server crashed); the rate limiter says which address it throttled and when it let it go; the ingest says when it had to make an artist's card; and every notification — a new account, a changed profile, a privilege change, a comment, a star, a maintenance job started from the website — is one too; and so is every line of the changelog — a new track, a change the playout made to one, a listener request, a star (updatechangelog(): titled Changelog: <what happened>, in blue, the line's own words first, then the track, its id, the station, the time and the Guid; any IP address in it is taken out unless $RedactAdminAlerts in config.php is 0). An alert has a title, a text and a colour, the three things a Discord embed has, and the colour says how it went:

An alert is the station's own text about itself. It may name a log file's path on the server, an address the rate limiter saw, a person's public display name, a comment's first words — which is why only administrators see it, why the server never writes an alert's text to its own log, and why the website's box writes it with textContent. Nothing in it is ever a password, a token or a visitor's e-mail address: those go in the administrators' mail, as the notifications say.

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, exactly as for the chat:

1. The page asks its own site (POST https://radio.ericade.net/admindata/, with a CSRF token) — and only when the page has reason to think its visitor is an administrator; a visitor who is not logged in, or not an administrator, never asks.
2. The website's PHP checks the real login and the real privilege, then asks the API, server to server, with the visitor's user token: POST /radio/v2/admindata/ticket. The API answers an administrator with a ticket — 64 hexadecimal characters, good for one login within 60 seconds — and everybody else with 403. Only the ticket's 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: that it exists, that it is an administrator now, and that it 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). A chat ticket opens the chat and nothing else: the two sockets keep their tickets in two tables, and neither looks in the other's.

Connecting

Example (browser JavaScript)

// ticket and url come from the website's own /admindata/ 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":       console.log("listening as", data.You.Name); break;
    case "admin-alert": show(data.Payload); break;
    case "bye":         /* data.Code says whether to try again - see below */ break;
  }
};
function show(p) {
  box.querySelector(".title").textContent = p.Title;      // textContent. Always.
  box.querySelector(".text").textContent  = p.Message;
  box.dataset.level = p.Level;                            // ok | info | warnings | errors
  box.hidden = false;
  setTimeout(() => { box.hidden = true; }, 15000);
}

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: 2, 5, 10, 20, 30, then 60 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 4 kB are protocol errors and close the connection.

What the server says

welcome

ready

admin-alert

One alert, the moment it was raised. Everything about it is in Payload:

Example

{
  "Event": "admin-alert",
  "Timestamp": 1792018640,
  "Payload": {
    "AlertID": 1288,
    "Timestamp": 1792018640,
    "Title": "Media File Check - 2026-10-15",
    "Message": "Podcast episodes: 167 checked, 167 present.\nSongs (MP3): 3104 checked, 2 missing.\n\nMissing:\n  titles id 2231 - ...",
    "Truncated": 0,
    "Colour": 16776960,
    "Level": "warnings",
    "Source": "VerifyMediaFiles",
    "Origin": "tasks.php"
  }
}

you, 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": "auth", "Ticket": "5f0c...64 hexadecimal characters...a91e" }
{ "Action": "ping" }

That is all. A client can say who it is once, with a ticket the API made, and after that only that it is still there. Nothing a client sends reaches any other client, the API or Discord.

Security

Limits

Operations

The server listens on 127.0.0.1:8148 behind Apache, next to the station data relay (8146) and the chat (8147), and takes the alert datagrams on UDP 127.0.0.1:8149. It is kept alive by websocket/admindata-ws.sh from cron. It reads config.php once, when it starts: after changing an $AdminData… setting, run pkill -f 'admindata-server\.php' and the watchdog starts it again within the minute. Its log is /var/log/admindata-ws/admindata-ws.log. 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 alerts:

Used websockets: 3, Available websockets: 47, Total websockets: 50
Logged in: 2, Alerts relayed: 14, Last alert: 2026-10-15 03:12:40

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

Capacity event log

/var/log/websocket_admindata_events/<YYYY-MM-DD>.log, one file a day, each line [timestamp] [event-type] message, with the relay's event types (capacity-total-90, capacity-total-100, capacity-ip-90, capacity-ip-100, capacity-total-full, capacity-total-available, log-throttled) and the relay's rate limit. Each threshold fires once per crossing and is armed again when usage falls back under it.

When nothing arrives

Setting it up

1. Database: run objects/sql_admindata.sql (tables AdminAlerts and AdminDataTickets). Until then sendAdminAlert() pushes and posts to Discord without storing anything, admindata/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 and /ws/chat lines, then reload:

   ProxyPass        "/ws/admindata" "ws://127.0.0.1:8148/"
   ProxyPassReverse "/ws/admindata" "ws://127.0.0.1:8148/"

3. config.php: the block “Administrative alerts”. Everything has a default; the one thing worth deciding is $AdminDataEventKey — empty, the alert datagrams are signed with the relay's $WebSocketEventKey; for a key of its own, php -r 'echo bin2hex(random_bytes(32)), "\n";'.
4. cron (root): * * * * * /var/www/html/api.ericade.net/websocket/admindata-ws.sh — and chmod +x the script. Then tail /var/log/admindata-ws/admindata-ws.log: it says where it listens and where it takes the datagrams.
5. Logs: bash /var/www/html/api.ericade.net/logrotate/install.sh as root, once more, for the two new folders (admindata-ws/, websocket_admindata_events/) and their rotation.
6. The website: nothing to configure. Its header carries the box, js/legacy.js connects for an administrator, /admindata/ fetches the ticket, /conelrad/alerts/ shows the record.

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