The broker owns WebSocket connections and delegates app-specific logic to PHP over HTTP. It is optional; web-app-starter does not start it unless you configure a service for it.

Run

REALTIME_HOST=127.0.0.1 \
REALTIME_PORT=8009 \
REALTIME_BACKEND_URL=http://127.0.0.1/web-app-starter/?api/realtime \
REALTIME_COMMAND_TOKEN=change-me \
node server/realtime-broker/broker.js

Protocol

Browser events sent to the broker become POSTs to the PHP backend:

message: JSON message. Types are prefixed with client- unless already prefixed.
connection: JSON session info with cookies, IP, wskey, and fields merged by backend session commands.

PHP responds with an array of commands:

[
  {"type":"session","data":{"room":"demo"}},
  {"type":"send","match":{"room":"demo"},"message":{"type":"notice","text":"hello"}}
]

Supported commands:

session: merge data into matching connection sessions; without match, applies to the current connection.
send: send message/content to matching connections; without match, sends to current connection.
close: close matching connections.
list: return matching connection session info to command callers.
log: write a broker log message when logging is enabled.

Backend-initiated command POSTs can use:

data=<json-array>
token=<REALTIME_COMMAND_TOKEN> or Authorization: Bearer <token> or X-Realtime-Token: <token>

GET /status returns JSON health/counters.

Vendored dependency

vendor/ws is ws 8.14.2 (MIT). It is vendored so the starter does not need to trust a fresh npm install during normal development.