feat(spot): FreeDV Reporter as a live WebSocket source (FR-SPOT-08); drop WSPRnet

[dc0sk]

Stacked on #199 → #198 → #197 → #196.

What

Stations on the air right now on FreeDV Reporter (qso.freedv.org) appear as coral nameplates. WSPRnet is dropped, per your decision.

• Read-only. The source joins in the view role: you are not listed as a station, and nothing identifying is sent. The connect is exactly {"role":"view","protocol_version":2}; the request carries only the program name and version; the only other thing sent is a pong to each ping (FR-SPOT-12).
• Plain ws:// on port 80, as the reference client does. wss was not tried.
• It is a presence list, so a station's spot is re-stamped every 30 s while it stays on the roster and fades after it leaves. (A design choice — please overrule if you'd rather age from the last thing a station did; the events carry a last_update timestamp that I did not use.)

New in k4-spot, hand-written, dependency-free and bounded like the MQTT client: a strict JSON parser, a WebSocket client (RFC 6455, including SHA-1 and base64 for the accept key), Engine.IO/Socket.IO framing, the roster, and the source. App: a fifth worker slot, FreeDvPrefs, a Networks section, demo spots.

Checked against the real service

The format came from another client's public source. I then joined the real service five times for at most ten seconds each, read-only, printing counts and field shapes only — never a callsign or any text. The first build rejected 10–12 events per session as malformed. Both causes were my strictness, not the server's:

1. freq_change with freq 0 — a station with no frequency set. Normal.
2. message_update with non-ASCII text. Normal.

Hand-written test data had never contained either. The rule now: a field of the wrong type rejects the event; a well-typed value that can't be shown degrades that one field. The same probe then reported 0 rejected (42–45 stations on 14–16 distinct frequencies, 1 MHz to 10.49 GHz).

A review then caught that this fix had blinded the probe. The degrade path had no counter, so a probe printing only rejected would say "0" while every accented message was being cleared. There is now a separate degraded count with value-free shapes, and the fifth session read 0 rejected and 3 degraded — three non-ASCII messages that had been dropped all along. (I had also written that a nameplate "cannot" show non-ASCII text; it can — keeping only printable ASCII is a deliberate policy for untrusted text, and the docs now say so.) A clean live run only exonerates the parser against the shapes those seconds contained.

Findings beyond this feature

• Nearly every bound was unpinned. My tests built their boundary inputs from the constants under test, so MAX_DEPTH, MAX_NODES, MAX_STRING, the header limits, the ping limits, MAX_STATIONS… could each change by one and nothing failed — 22 survivors after the checks themselves had been mutation-tested. The same was true of the POTA parser in feat(spot): POTA as a polled spot source (FR-SPOT-08) #196 (six more). All are now numbers; the POTA fix is its own commit, also pushed to feat(spot): POTA as a polled spot source (FR-SPOT-08) #196's branch.
• SHA-1 vectors I wrote from memory were wrong in the last hex digit of one; replaced with values computed by hashlib.
• A JSON string reader that re-validated the whole remaining input per character (quadratic) — found by reading, now linear with a test.
• More than 250 mutations in all; redundant guards that masked each other were deleted, and one equivalent mutation (MAX_TOKEN) is documented in the code.

Verified

fmt, clippy --all-features, 479 workspace tests (bounded), cargo xtask OK. A scripted server whose frames are built and read by hand, independent of the crate's own codec, checks the wire.

Validation parked with DC0SK (not done here)

• Enable FreeDV Reporter in Networks with a 20 m or 40 m view. Do coral plates appear at plausible frequencies? Is the status line "connected"? — Confirmed 2026-09-22 on the live K4: real coral plates draw at plausible frequencies and click-to-tune lands on them correctly (status-line wording not specifically checked).
• Watch a station leave: does its plate stop being refreshed and fade?
• Is a 30 s presence refresh the right feel? (Constant DEFAULT_REFRESH in freedv_source.rs.)
• Confirm nothing about you shows up on the FreeDV Reporter map or list while this is on.

Not done

wss (TLS); what last_update's zone and precision are; SOTA (still blocked on API-consumers membership).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ma4bQKqGNFTYyVSEKPcXRk