WebSocket performance: vectorized masking + zero-copy codec paths (large messages 0.4x -> 2.5x of 1.x)

[quinnj]

Addresses the report that 2.x WebSockets are slow vs 1.x (large binary messages — the Bonito/WGLMakie regime — were up to 2.3× slower). Full analysis in bench/websocket/REPORT.md.

Result (vs HTTP 1.11.0, macOS aarch64, -t 4, medians of 3)

cell	before this PR	after	vs 1.x
send_1m	433 MB/s (0.43× of 1.x)	2541 MB/s	2.54×
echo_64k	313 MB/s (0.61×)	888 MB/s	1.72×
send_4k	503 MB/s	862 MB/s	6.7×
small msgs (16B)	6–8× of 1.x	unchanged-to-better, allocs/msg 11–15 → 2–5
latency p50/p99	—	56 / 89 µs	0.73× / 0.63×

send_1m now allocates payload + ~5 KB per message — the user-owned payload (receive hands ownership) is the API floor.

What changed

Masking (_ws_mask_into!): 8 bytes/iteration with the key broadcast into a UInt64 (phase-aware for chunked delivery, in-place capable, fuzz-validated in bench/websocket/proto_mask.jl). Replaces byte-at-a-time XOR with a per-byte modulo — masked decode was the server's receive path for all client traffic and ran at 0.53 GiB/s; now 7.1 GiB/s.

Decode: explicit payload_received cursor; exact-size presize for frames ≤ 4 MiB (capped so a forged length header can't allocate unbounded memory); per-byte push! → copyto!/mask-into; frame payload ownership handoff instead of a copy per frame; reused frames_scratch; (buf, n) chunk API (no per-read view); callable-struct header guard (no boxed capture).

Encode: frames append directly into a persistent outgoing buffer (no per-frame buffer, no concat copy; capacity retained across flushes). The buffer has a leaf lock never held across socket I/O — this also fixes a latent race where the read task queued PONG/CLOSE replies into the outgoing queue unsynchronized with senders (socket writes stay serialized by the send lock as before). Masking key from rand(UInt32).

Correctness

• Codec 88/88, client 20/20, server 35/35, integration 42/42.
• Autobahn fuzzing suite: 463 cases, zero failures, run before and after the rewrite with identical verdicts (216 UNIMPLEMENTED = case 12/13.* permessage-deflate, not implemented by design).

Also in this PR

bench/websocket/: a version-agnostic benchmark suite that runs identically under 1.x and 2.x (send/push/echo throughput at 16B/4KiB/64KiB/1MiB, ping-pong latency, whole-process allocs+GC per message), codec microbenchmarks, the mask-kernel prototype + fuzz, baseline runner, comparison table, and REPORT.md with the full methodology and numbers.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 90.07092% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.09%. Comparing base (6022a9f) to head (c1ebf9f).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
src/http_websocket_codec.jl	89.92%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1304      +/-   ##
==========================================
+ Coverage   86.83%   87.09%   +0.26%     
==========================================
  Files          28       28              
  Lines       10799    10889      +90     
==========================================
+ Hits         9377     9484     +107     
+ Misses       1422     1405      -17     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.