arelchan 9bc8416e0d
fix(channels): stop whatsapp pairing after three unscanned qr rounds (#832)
## Summary

With WhatsApp enabled but never paired, the bridge re-paired forever.
Baileys shows about six codes per connection (~2m40s), closes with 408,
and the bridge reconnected five seconds later, so a fresh QR was printed
every 20s to the terminal and `web.log` indefinitely (one machine had
8000+ QR prints in `web.log`). An orphaned bridge kept doing it with no
raven attached, which is how a QR showed up in a terminal running
`./install.sh`.

- Bridge (`bridge/src/whatsapp.ts`, `bridge/src/server.ts`): a round
counts as unscanned only if it showed a code and closed with a 408
timeout; `isNewLogin` and `open` clear it, so a scan is never miscounted
(Baileys answers pair-success with `isNewLogin` and then a 515 close,
and its QR timer can still fire a 408 in between). After 3 unscanned
rounds the bridge stops reconnecting and reports `pairing_expired`. A
client authenticating while paused resumes pairing with fresh counters;
a failed resume goes back to paused and reports `pairing_expired` again.
- Adapter (`raven/channels/adapters/whatsapp/channel.py`): stops itself
on `pairing_expired`, so the Connections page shows its existing "It
started and then stopped - a code nobody scanned expires. Try again."
state, and its retry restarts pairing. `start()` now tears down the
bridge it spawned on every exit, including a cancel during the reconnect
wait.

No UI change; the page already handled a stopped QR channel.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `uv run --frozen pytest tests/test_channels_whatsapp.py -q`: 66
passed; ran 25x sequentially, 8x in shuffled order and 5x with `-n 4`,
no flakes. Each new test was mutation-checked (reverting its fix makes
it fail).
- `uv run --frozen pytest -q` on the 52
channel/gateway/rpc/onboard/serve test files: 1894 passed, 1 skipped.
Full suite: 27019 passed, 3 failed, all 3 also failing on a clean `main`
checkout (`test_rpc_files` LibreOffice 503, two `test_simulation_*`
macOS-specific).
- Diff coverage via `scripts/coverage_gate.py diff --base-ref
github/main --threshold 90`: passed.
- `ruff check`, `ruff format --check`, `ty check`, `lint-imports`,
`scripts/check_source_language.py`, bridge `tsc`, eslint and prettier:
pass.
- Bridge logic against a stubbed Baileys (compiled `dist/whatsapp.js`):
scan in round 3 does not pause; 3 unscanned rounds pause; failed resume
re-pauses and a later resume works; a paired session dropping with 408
never pauses; a non-408 close is not counted; a scan followed by a 408
drop is not counted. Each guard mutation-checked.
- Against the real WhatsApp servers, twice, nobody scanning: pause after
exactly 3 rounds (18 codes, all closes 408), then silence for 8+
minutes; a client connecting while paused gets a fresh code in ~1.5s
with no stale `pairing_expired` replay, and counters reset (second pause
after 3 more rounds); two clients at once trigger one reconnect; a
client joining mid-round only gets the current code; SIGTERM exits in
under 0.01s in every state; the real adapter returns from `start()`
after ~493s with running/connected false and leaves an external bridge
alone.
- Page, driven with Playwright against a gateway with a fake bridge: QR
shows, `pairing_expired` switches the panel to the stopped text with Try
again, retry opens a new bridge connection and shows a QR again,
`channels.status` / `channels.qr` agree, no console errors.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No docs describe the pairing retry behaviour, so none were changed.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

User-visible: an unpaired WhatsApp channel now stops after about 8
minutes instead of printing codes forever; pairing again is one click on
the Connections page or `raven channels login whatsapp`. A flaky network
during pairing also closes with 408, so it can bring the pause earlier;
the retry recovers it. Paired sessions are unaffected (no code is shown,
so no round is counted). No config or protocol change for other
channels. Rollback: revert this commit.

## Related Issues

N/A

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-30 16:24:02 +08:00
..
2026-06-29 00:23:07 +08:00