feat(core): WebRTC TURN/ICE diagnostics and env-configurable Matrix VoIP

[webguru-hypha]

Summary

Implements deployment-friendly tracing for Matrix group calls after gc.enter(): TURN credential / ICE server shape, optional STUN gather probe when no TURN is configured, and optional Matrix JS SDK summary WebRTC stats (privacy-safe aggregates).

Also wires Matrix createClient VoIP options from NEXT_PUBLIC_MATRIX_WEBRTC_* so infra can force relay, enable public STUN fallback when the HS returns no ICE servers, or bump ICE candidate pooling without code changes.

Env vars (optional)

Variable	Effect
NEXT_PUBLIC_MATRIX_WEBRTC_FORCE_TURN	forceTURN — relay-only peer connections (iceTransportPolicy: relay).
NEXT_PUBLIC_MATRIX_WEBRTC_FALLBACK_ICE_ALLOWED	Allow matrix-js-sdk public STUN fallback when HS provides no ICE servers (default SDK behavior is false).
NEXT_PUBLIC_MATRIX_WEBRTC_ICE_POOL_SIZE	iceCandidatePoolSize for faster first candidate gather.
NEXT_PUBLIC_MATRIX_WEBRTC_GROUP_STATS_MS	If > 0, enables Matrix GroupCall periodic summary stats and logs hypha.group_call.webrtc_summary (dev console).

Telemetry events (development console, filter hypha.group_call)

• hypha.group_call.turn_probe — checkTurnServers() result, approximate TURN TTL, ICE entry/url counts, STUN/TURN/TURNS flags, short host hints (no URIs/passwords).
• hypha.group_call.ice_gather_probe — only when no TURN/TURNS and no fallback: quick RTCPeerConnection gather smoke test (state or timeout).
• hypha.group_call.webrtc_summary — when group stats interval > 0: SDK aggregate receive %, jitter, packet loss, peer connection counts vs opponents.

Notes

• Hard requirement for reliable NAT traversal remains homework GET /voip/turnServer returning TURN URIs + credentials; client-side logging helps prove when that path is broken or empty.
• Commit: feat(core): WebRTC diagnostics for Matrix group calls (TURN/ICE telemetry)

  

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e9dd26c5-f8c9-432c-8d10-8e1628f05655

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/webrtc-turn-ice-telemetry-3c15

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}