283 lines
17 KiB
Markdown
283 lines
17 KiB
Markdown
# @flybrain/bridge (flybridge)
|
|
|
|
The Twitch integration service for the 24/7 fly stream: chat commands, rate limiting, template-only
|
|
replies, Channel Points "Sugar" redemptions, and `/health` + `/metrics`. Talks to `flysim`'s
|
|
localhost control API (`docs/control-api.md`) and to Twitch via `@twurple/*` over EventSub
|
|
WebSocket. Never touches the game: there is deliberately no button endpoint on the control API,
|
|
and this service never tries to add one.
|
|
|
|
Milestone **B1** (this package, as it stands): everything is testable offline against a fake sim
|
|
and fake Twitch clients. There are no real Twitch credentials yet — `tools/authorize.mts` is
|
|
written and ready for the day there are.
|
|
|
|
Binding design doc: [`docs/design/stage-bridge.md`](../../docs/design/stage-bridge.md) section B.
|
|
Binding contracts: [`docs/control-api.md`](../../docs/control-api.md) and
|
|
[`docs/feed-protocol.md`](../../docs/feed-protocol.md).
|
|
|
|
## What is in here
|
|
|
|
| File | What |
|
|
| --- | --- |
|
|
| `src/config.ts` | Env-driven config, validated at startup (`loadConfig`, throws `ConfigError` listing every problem). |
|
|
| `src/names.ts` | Re-exports `validateDisplayName` from `@flybrain/feed` — see "Display names" below. |
|
|
| `src/templates.ts` | Every outbound chat string as a typed constant (`renderTemplate`, `TEMPLATE_IDS`). |
|
|
| `src/duration.ts` | `formatDuration` for the `!stuck` reply. |
|
|
| `src/ratelimit.ts` | Token-bucket rate limiting (`RateLimiter`), clock-injected for deterministic tests. |
|
|
| `src/sim.ts` | Typed control API client (`HttpSimClient`/`SimClient`), timeouts, typed 429/403 handling. |
|
|
| `src/commands.ts` | `!fly` `!brain` `!how` `!stuck` `!sugar` dispatch. Twurple-free. |
|
|
| `src/chat.ts` | `ChatSender` interface, the `send()` template gate, `TwurpleChatSender`. |
|
|
| `src/scopes.ts` | The B1 scope table and startup scope assertion. |
|
|
| `src/auth.ts` | Loads `tokens.json`, builds one `RefreshingAuthProvider` per role plus the scope-routing provider for the one-account case, runs the scope assertion. |
|
|
| `src/onscreen-chat.ts` | Forwards AutoMod-passed chat to flysim's `POST /chat` for the on-screen CHAT panel. Twurple-free. |
|
|
| `src/eventsub.ts` | EventSub WS wiring: chat, follow, raid, redemption-add; one socket when both roles are one account. Twurple-facing glue. |
|
|
| `src/redemptions.ts` | Sugar reward creation, redemption state machine, persisted intent log. Behind `FEATURE_REDEMPTIONS`. |
|
|
| `src/predictions.ts` | Disabled stub. Behind `FEATURE_PREDICTIONS` (Affiliate-only; not on for either demo yet). |
|
|
| `src/explainer.ts` | Rotating explainer poster with the chat-silence rule. |
|
|
| `src/health.ts` | `node:http` `/health` (JSON) and `/metrics` (Prometheus text). |
|
|
| `src/subscription-health.ts` | The self-healing watchdog: exits non-zero when the chat subscription stays unconfirmed. Twurple-free. |
|
|
| `src/notice.ts` | Startup/recovery notice gate, rate-limited across restarts via a small state file. |
|
|
| `src/atomic-file.ts` | Atomic, 0600 JSON writes shared by `tokens.json` and the redemption intent log. |
|
|
| `src/index.ts` | Wires everything, posts the startup notice, graceful shutdown on SIGINT/SIGTERM. |
|
|
| `tools/authorize.mts` | One-time interactive OAuth authorization-code flow producing `tokens.json`. |
|
|
| `tools/mock-twitch.sh` | Documented Twitch CLI commands for manually exercising each handler. |
|
|
|
|
## Display names: the chokepoint
|
|
|
|
`validateDisplayName` (`^[\p{L}\p{N}_]{1,25}$`, else the literal `"a viewer"`) lives in
|
|
[`packages/feed/src/names.ts`](../../packages/feed/src/names.ts) so flybridge and flystage
|
|
validate viewer names identically — see `docs/design/stage-bridge.md` section C, "How viewer
|
|
names reach the ticker." `src/names.ts` here is a thin re-export so bridge code imports it like
|
|
every other local module. Every viewer name that reaches `sim.stimulate()` (`!sugar`, Sugar
|
|
redemptions) or a chat template (follow/raid thanks) goes through this function first — never raw
|
|
chat or raw Twitch profile data.
|
|
|
|
## Template-only chat
|
|
|
|
Every outbound chat string is a constant in `src/templates.ts`, keyed by `TemplateId`. `send()`
|
|
(`src/chat.ts`) only accepts a `TemplateId` plus a typed params object — never a plain string, and
|
|
never anything built from chat message text. `tests/templates.test.ts` includes a static-analysis
|
|
test asserting every `send(...)` call site in `src/` passes a string literal from `TEMPLATE_IDS`,
|
|
not a variable or template literal.
|
|
|
|
Game-specific words (the title, the channel) are never hardcoded in a template: they arrive as
|
|
params sourced from `BridgeConfig`, so the same code runs both demo channels.
|
|
|
|
## On-screen chat
|
|
|
|
The stream's right rail ends in a persistent CHAT panel (`docs/stream-mvp-plan.md`, "Rail layout
|
|
v2": last ~7 lines, AutoMod-passed, service-sanitized, deny-listed, kill switch). This service is
|
|
the middle of that path:
|
|
|
|
```
|
|
Twitch -> AutoMod -> flybridge (src/onscreen-chat.ts) -> POST /chat -> flysim (sanitize, deny
|
|
list, ring) -> feed -> page
|
|
```
|
|
|
|
**AutoMod comes first and nothing here replaces it.** `channel.chat.message` fires only for
|
|
messages that were delivered to chat: a message AutoMod held produces **no event at all**, so it
|
|
never reaches this service, and a message a moderator deletes afterwards produces a
|
|
`channel.chat.message_delete` we do not subscribe to. Everything below is what the bridge adds on
|
|
top of the channel's own moderation settings.
|
|
|
|
What `OnscreenChat` does with each message it sees:
|
|
|
|
| Case | Outcome |
|
|
| --- | --- |
|
|
| Starts with `!` | dropped (`command`) — it is an instruction to this bot, not chatter, and `!sugar` should not appear on the broadcast twice |
|
|
| From a known third-party bot (`KNOWN_BOT_LOGINS`, plus `BOT_USER`) | dropped (`bot`) |
|
|
| Display name fails `validateDisplayName` | dropped (`invalid_name`) — attributing a line to the literal `"a viewer"` would be putting words in a fiction's mouth |
|
|
| `sanitizeChatText` refuses it | dropped (`rejected`) — never trimmed, never partially cleaned |
|
|
| An echo of a reply this bridge just posted | dropped (`echo`), so nothing appears twice |
|
|
| Anything else | `POST /chat` (`sent`) |
|
|
|
|
The bridge's own template replies go on screen too, with `bot: true`: `wrapSendWithOnscreenEcho`
|
|
wraps `createSend` once in `src/index.ts`, so every reply that reaches Twitch also reaches the
|
|
panel, and no call site has to know. A reply longer than the sanitizer's 200-character cap is
|
|
shortened **for the panel only** (`shortenForPanel`, at a word boundary with an ellipsis); the
|
|
Twitch message goes out in full first. That trimming applies exclusively to text this service
|
|
wrote itself — a viewer's line over the cap is refused whole.
|
|
|
|
None of this is authoritative. flysim re-runs every rule, applies the operator deny list and
|
|
enforces its own rate limits (1 per name per 2 s, 5 per second globally) regardless of what this
|
|
service does — `docs/control-api.md` is explicit that the limits hold "regardless of what the
|
|
bridge does". The bridge's copy is the cheap first pass, so hostile text never leaves the process.
|
|
|
|
`FEATURE_ONSCREEN_CHAT=false` turns the forwarding off here; `[chat] enabled = false` in
|
|
`flysim.toml` (`FLY_CHAT_ENABLED=0`) turns the panel off at the source and makes `POST /chat`
|
|
answer 403. Either end is a working kill switch, and `flybridge_onscreen_chat_total{outcome}`
|
|
counts every decision above.
|
|
|
|
Why the paranoia: `docs/stream-mvp-plan.md` records the Nothing, Forever precedent — a 14-day ban
|
|
for generated text on stream — and the rule the research note draws from it, never render raw chat
|
|
into the frame. `tests/onscreen-chat.test.ts` ends with a static lint asserting that this module is
|
|
the *only* place in `src/` that reads a message body for anything but `parseCommand`, the only
|
|
place that calls `sanitizeChatText`, and the only place that calls `POST /chat`, and that the text
|
|
it posts is always the sanitizer's own output.
|
|
|
|
## Quiet mode
|
|
|
|
`FEATURE_QUIET=1` makes the bridge speak only when spoken to (the operator, 2026-09-17: "make bot less
|
|
chatty. speaks only when spoken to. doesn't greet."). Nothing self-initiated goes to chat:
|
|
|
|
| Off (default) | With `FEATURE_QUIET=1` |
|
|
| --- | --- |
|
|
| Startup / recovery notice on every allowed start (`src/notice.ts`) | none — `NoticeLog.decide()` authorises nothing and the state file is not written |
|
|
| Explainer rotation every `EXPLAINER_INTERVAL_MS` (`src/explainer.ts`) | none — no interval timer is armed |
|
|
| `Thanks for the follow` / `Thanks for the raid` (`src/eventsub.ts`) | none |
|
|
|
|
Unchanged either way: `!fly` `!brain` `!how` `!stuck` `!sugar`, the Sugar redemption replies, and
|
|
forwarding viewer chat to the on-screen CHAT panel. The `channel.follow` and `channel.raid`
|
|
subscriptions are still created, so `/health` reports the same subscription list and
|
|
`flybridge_follows_total` / `flybridge_raids_total` still count every one — only the chat line is
|
|
dropped.
|
|
|
|
`EXPLAINER_INTERVAL_MS=0` is the narrow version of the same idea: it turns off just the rotation,
|
|
on a channel that still greets and still posts notices. The two switches are independent.
|
|
|
|
## Scopes (B1 table)
|
|
|
|
Startup calls `getTokenInfo` on both the bot and broadcaster tokens and refuses to start if any
|
|
required scope is missing, naming exactly which ones (`src/scopes.ts`, `assertRequiredScopes`).
|
|
|
|
| Scope | Token | Needed for | Required |
|
|
| --- | --- | --- | --- |
|
|
| `user:read:chat` | bot | `channel.chat.message` over EventSub WS | always |
|
|
| `user:write:chat` | bot | Send Chat Message | always |
|
|
| `user:bot` | bot | send as bot | always |
|
|
| `channel:bot` | broadcaster | authorize the bot on the channel | always |
|
|
| `moderator:read:followers` | broadcaster | `channel.follow` v2 | always |
|
|
| `channel:read:redemptions` | broadcaster | `channel.channel_points_custom_reward_redemption.add` | `FEATURE_REDEMPTIONS=true` |
|
|
| `channel:manage:redemptions` | broadcaster | create the Sugar reward, fulfil/refund | `FEATURE_REDEMPTIONS=true` |
|
|
| `channel:manage:broadcast` | broadcaster | stream markers (future work) | `FEATURE_REDEMPTIONS=true` |
|
|
| `channel:manage:predictions` | broadcaster | predictions (Affiliate-gated, disabled in B1) | `FEATURE_PREDICTIONS=true` |
|
|
|
|
`channel.raid` needs no scope, just a user token and a `to_broadcaster_user_id` condition.
|
|
|
|
## Environment reference
|
|
|
|
Required, no default:
|
|
|
|
| Var | Notes |
|
|
| --- | --- |
|
|
| `TWITCH_CLIENT_ID` / `TWITCH_CLIENT_SECRET` | Or a `CREDENTIALS_DIRECTORY` with `twitch-client-id` / `twitch-client-secret` files (systemd `LoadCredential=`/`LoadCredentialEncrypted=`). |
|
|
| `CHANNEL` | Broadcaster channel login, no leading `#`. |
|
|
| `BOT_USER` | Bot account login. |
|
|
| `GAME_TITLE` | Substituted into templates — the only game-specific word in config. |
|
|
|
|
Optional, with defaults:
|
|
|
|
| Var | Default |
|
|
| --- | --- |
|
|
| `TOKENS_FILE` | `/var/lib/flybridge/tokens.json` |
|
|
| `REDEMPTION_STATE_FILE` | `/var/lib/flybridge/redemption-state.json` |
|
|
| `NOTICE_STATE_FILE` | `/var/lib/flybridge/notice-state.json` |
|
|
| `EVENTSUB_GRACE_MS` | `60000` (chat subscription unconfirmed this long ⇒ log one line and exit 75) |
|
|
| `NOTICE_MIN_INTERVAL_MS` | `600000` (at most one startup/recovery notice per 10 min, across restarts) |
|
|
| `SIM_CONTROL_URL` | `http://127.0.0.1:7401` |
|
|
| `SIM_TIMEOUT_MS` | `2000` |
|
|
| `FEATURE_REDEMPTIONS` | `false` |
|
|
| `FEATURE_PREDICTIONS` | `false` |
|
|
| `FEATURE_ONSCREEN_CHAT` | `true` (the only flag that defaults on — see "On-screen chat") |
|
|
| `FEATURE_QUIET` | `false` (speaks only when spoken to — see "Quiet mode") |
|
|
| `HEALTH_HOST` | `127.0.0.1` |
|
|
| `HEALTH_PORT` | `7410` |
|
|
| `EXPLAINER_INTERVAL_MS` | `1200000` (20 min; `0` turns the rotation off) |
|
|
| `EXPLAINER_SILENCE_MS` | `1200000` (20 min) |
|
|
| `RATE_LIMIT_PER_USER_PER_COMMAND_MS` | `60000` |
|
|
| `RATE_LIMIT_GLOBAL_REPLY_MS` | `5000` |
|
|
| `RATE_LIMIT_CHAT_MESSAGES_PER_30S` | `15` |
|
|
| `RATE_LIMIT_SUGAR_COOLDOWN_MS` | `10000` |
|
|
|
|
Two demos run this same service with different env (`CHANNEL`, `BOT_USER`, `GAME_TITLE`,
|
|
`HEALTH_PORT` if colocated) — no game-specific word belongs in code.
|
|
|
|
## Running against the fake sim
|
|
|
|
```sh
|
|
# terminal 1: a fake flysim on the real default ports
|
|
npx tsx packages/feed/src/fake/server.ts --scenario running
|
|
|
|
# terminal 2: flybridge, pointed at it, with dev-mode env credentials
|
|
TWITCH_CLIENT_ID=devclient TWITCH_CLIENT_SECRET=devsecret \
|
|
CHANNEL=flyplayspokemon BOT_USER=flybridgebot GAME_TITLE="Pokemon Red" \
|
|
TOKENS_FILE=/tmp/flybridge-tokens.json \
|
|
npx tsx services/bridge/src/index.ts
|
|
```
|
|
|
|
`src/index.ts` needs `tokens.json` to exist (run `tools/authorize.mts` first, against a real
|
|
Twitch app, once one exists) — there is currently no way to run `index.ts` end-to-end without
|
|
real Twitch credentials, which is expected for B1. Everything below `index.ts` (commands,
|
|
rate limits, templates, the sim client, the redemption state machine, scope assertion, the
|
|
explainer's silence rule) is exercised directly in `npm test` with `tests/fake-sim.ts` (a
|
|
fully scriptable 429/500/timeout control API fake) and fakes for `ChatSender`/`RedemptionApi`, so
|
|
none of it needs Twitch or a browser to verify.
|
|
|
|
## Twitch CLI mocks
|
|
|
|
`tools/mock-twitch.sh` documents the exact `twitch event trigger ...` commands for each handler
|
|
(chat commands, follow, raid, Sugar redemption, subscription revocation) against
|
|
`twitch event websocket start-server`. Reference only — `npm test` never requires the Twitch CLI.
|
|
|
|
## Authorizing (once a real Twitch app exists)
|
|
|
|
```sh
|
|
TWITCH_CLIENT_ID=... TWITCH_CLIENT_SECRET=... \
|
|
npx tsx tools/authorize.mts --role bot --tokens-file /var/lib/flybridge/tokens.json
|
|
|
|
TWITCH_CLIENT_ID=... TWITCH_CLIENT_SECRET=... \
|
|
npx tsx tools/authorize.mts --role broadcaster --tokens-file /var/lib/flybridge/tokens.json \
|
|
--with-redemptions --with-predictions
|
|
```
|
|
|
|
Opens a one-time authorization-code flow on `http://localhost:3000/callback`. Run once per
|
|
identity (bot and broadcaster are different Twitch accounts). Writes `tokens.json` atomically at
|
|
mode `0600`. `--with-redemptions`/`--with-predictions` add those features' scopes up front even
|
|
though B1 ships with both off, so the token does not need re-authorizing the day they switch on.
|
|
|
|
The device-code grant is the documented fallback for headless authorization; twurple's first-class
|
|
support for it is unverified as of this writing, so it is intentionally not implemented here — do
|
|
the one-time flow from a machine with a browser instead.
|
|
|
|
## systemd expectations
|
|
|
|
The unit itself lives in `infra/`, not here (W4 in `docs/stream-mvp-plan.md`). What it needs to
|
|
provide:
|
|
|
|
- `LoadCredentialEncrypted=twitch-client-id:...` and `...twitch-client-secret:...`, sourced from
|
|
`pass` (`twitch/fly-pokemon-client-{id,secret}`), giving `$CREDENTIALS_DIRECTORY` the two files
|
|
`src/config.ts` reads.
|
|
- A writable, persistent directory for `TOKENS_FILE`, `REDEMPTION_STATE_FILE` and
|
|
`NOTICE_STATE_FILE` (default `/var/lib/flybridge/`), owned by the service user.
|
|
- `After=`/`Requires=` on the `flysim` unit (this service calls `SIM_CONTROL_URL` on startup and
|
|
continuously; it degrades gracefully — commands that need the sim go quiet, `/health` reports
|
|
`simReachable: false` — but it is not useful without it).
|
|
- `Restart=always` with `RestartSec` of at least 15 s and NO start limit
|
|
(`StartLimitIntervalSec=0`). This is load-bearing, not hygiene: the bridge exits itself with
|
|
code 75 when its `channel.chat.message` subscription has been unconfirmed for
|
|
`EVENTSUB_GRACE_MS`, because that is the only way to get a fresh EventSub websocket transport
|
|
(`src/subscription-health.ts`). 15 s is how long Twitch needs to reap the stale transports; a
|
|
start limit would park the unit during exactly the outage it exists for.
|
|
- `/health` and `/healthz`-style checks are cheap enough to poll frequently. `chatSubscriptionHealthy`
|
|
is the field that answers "is chat actually working" — `eventSubConnected` was `true` throughout
|
|
the hour of dead chat on 2026-09-16.
|
|
|
|
## Testing
|
|
|
|
```sh
|
|
npm test --workspace @flybrain/bridge
|
|
npm run typecheck --workspace @flybrain/bridge
|
|
```
|
|
|
|
156 tests. `tests/fake-sim.ts` is a small, fully scriptable fake of the control API (429/500/
|
|
timeout on demand) — not `packages/feed`'s fake simulator, which is built for realistic feed data
|
|
rather than fault injection, though it is used indirectly wherever a test only needs a real
|
|
`/status`/`/stimulate` happy path. `src/eventsub.ts` and `src/chat.ts`'s twurple-backed pieces
|
|
(`TwurpleChatSender`, `TwurpleRedemptionApi`) are exercised manually via `tools/mock-twitch.sh`
|
|
rather than unit-tested — they are thin glue over small interfaces (`ChatSender`, `RedemptionApi`,
|
|
`SimClient`), and everything they call into *is* unit-tested with fakes.
|
|
|
|
`src/eventsub.ts` is the exception to that last sentence now: `tests/eventsub.test.ts` drives it
|
|
through its `createListener` seam with a hand-written `EventSubListenerLike`, which is how "one
|
|
websocket when both roles are one Twitch account, two when they are not" and the self-healing
|
|
grace period are asserted without a Twitch connection. `tests/selfheal-exit.test.ts` spawns a real
|
|
child process (`tests/fixtures/selfheal-exit.ts`) to prove the exit code systemd sees is non-zero.
|