docs: protocol audit 2026-05-25, update architecture + Obsidian vault
Audit: - docs/AUDIT-2026-05-25.md: full protocol audit covering 8 findings (4 critical, 2 high, 5 medium, 4 low) with code references and fix effort estimates - vault/Audit/Tasks.md: Obsidian Tasks plugin file tracking all audit items with priorities, due dates, and per-step checklists Architecture docs updated for Wire format v2 and Wave 5/6 features: - ARCHITECTURE.md: adds wzp-video to dependency graph and project structure; wire format updated to v2 (16B header, 5B MiniHeader); relay concurrency section corrected (DashMap+RwLock is current, not a future optimization); test count 571→702; Android note - PROGRESS.md: Wave 5 and Wave 6 sections appended; test count 372→702; current status and open blockers as of 2026-05-25 - ROAD-TO-VIDEO.md: implementation status table inserted (✅/🟡/🔴/🔲 per phase); 6-step critical path to first video call - WZP-SPEC.md: MediaHeader updated to v2 (16B byte-aligned); MiniHeader updated to 5B with seq_delta; codec IDs 9-12 added (H.264/H.265/AV1); version negotiation section added Obsidian vault (vault/): - 114 files across Architecture/, PRDs/, Reports/, Android/, Reference/, Audit/ with YAML frontmatter - 00 - Home.md index note with wiki links - .obsidian/app.json config Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
144
vault/PRDs/PRD-network-awareness.md
Normal file
144
vault/PRDs/PRD-network-awareness.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
tags: [prd, wzp]
|
||||
type: prd
|
||||
---
|
||||
|
||||
# PRD: Network Awareness
|
||||
|
||||
> Phase: Implemented (core path)
|
||||
> Status: Ready for testing
|
||||
> Platform: Android native Kotlin app (com.wzp)
|
||||
|
||||
## Problem
|
||||
|
||||
WarzonePhone's quality controller (`AdaptiveQualityController`) had a `signal_network_change()` API for proactive adaptation to WiFi↔cellular transitions, but nothing called it. Network handoffs during calls were only detected reactively via jitter spikes — by which time the user had already experienced degraded audio.
|
||||
|
||||
## Solution
|
||||
|
||||
Integrate Android's `ConnectivityManager.NetworkCallback` to detect network transport changes in real-time and feed them to the quality controller. This enables:
|
||||
|
||||
1. **Preemptive quality downgrade** when switching from WiFi to cellular
|
||||
2. **FEC boost** (10-second window with +0.2 ratio) after any network change
|
||||
3. **Faster downgrade thresholds** on cellular (2 consecutive reports vs 3 on WiFi)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Android │
|
||||
│ │
|
||||
│ ConnectivityManager │
|
||||
│ │ NetworkCallback │
|
||||
│ ▼ │
|
||||
│ NetworkMonitor.kt │
|
||||
│ │ onNetworkChanged(type, bandwidthKbps) │
|
||||
│ ▼ │
|
||||
│ CallViewModel.kt ──► WzpEngine.onNetworkChanged() │
|
||||
│ │ JNI │
|
||||
│ ▼ │
|
||||
│ jni_bridge.rs: nativeOnNetworkChanged(handle, type, bw) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ engine.rs: state.pending_network_type.store(type) │
|
||||
│ │ AtomicU8 (lock-free) │
|
||||
│ ▼ │
|
||||
│ recv task: quality_ctrl.signal_network_change(ctx) │
|
||||
│ │ │
|
||||
│ ├─ Preemptive downgrade (WiFi → cellular) │
|
||||
│ ├─ FEC boost 10s │
|
||||
│ └─ Faster cellular thresholds │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Network Classification
|
||||
|
||||
`NetworkMonitor` classifies the active transport without requiring `READ_PHONE_STATE` permission by using bandwidth heuristics:
|
||||
|
||||
| Downstream Bandwidth | Classification | Rust `NetworkContext` |
|
||||
|----------------------|---------------|----------------------|
|
||||
| N/A (WiFi transport) | WiFi | `WiFi` |
|
||||
| >= 100 Mbps | 5G NR | `Cellular5g` |
|
||||
| >= 10 Mbps | LTE | `CellularLte` |
|
||||
| < 10 Mbps | 3G or worse | `Cellular3g` |
|
||||
| Ethernet | WiFi (equivalent) | `WiFi` |
|
||||
| Network lost | None | `Unknown` |
|
||||
|
||||
## Cross-Task Signaling
|
||||
|
||||
The network type is communicated from the JNI thread to the recv task via `AtomicU8` — the same pattern used for `pending_profile` (adaptive quality profile switches):
|
||||
|
||||
```
|
||||
JNI thread recv task (tokio)
|
||||
│ │
|
||||
│ store(type, Release) │
|
||||
│──────────────────────────────►│
|
||||
│ │ swap(0xFF, Acquire)
|
||||
│ │ if != 0xFF:
|
||||
│ │ quality_ctrl.signal_network_change(ctx)
|
||||
│ │
|
||||
```
|
||||
|
||||
Sentinel value `0xFF` means "no change pending". The recv task polls on every received packet (~20-40ms), so latency is bounded by the inter-packet interval.
|
||||
|
||||
## Components
|
||||
|
||||
### New File
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `android/.../net/NetworkMonitor.kt` | ConnectivityManager callback, transport classification, deduplication |
|
||||
|
||||
### Modified Files
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `android/.../engine/WzpEngine.kt` | Added `onNetworkChanged()` method + `nativeOnNetworkChanged` external |
|
||||
| `android/.../ui/call/CallViewModel.kt` | Instantiates NetworkMonitor, wires callback, register/unregister lifecycle |
|
||||
| `crates/wzp-android/src/jni_bridge.rs` | Added `Java_com_wzp_engine_WzpEngine_nativeOnNetworkChanged` JNI entry |
|
||||
| `crates/wzp-android/src/engine.rs` | Added `pending_network_type: AtomicU8` to EngineState, recv task polls it |
|
||||
|
||||
### Unchanged (already implemented)
|
||||
|
||||
| File | API |
|
||||
|------|-----|
|
||||
| `crates/wzp-proto/src/quality.rs` | `AdaptiveQualityController::signal_network_change(NetworkContext)` |
|
||||
| `crates/wzp-transport/src/path_monitor.rs` | `PathMonitor::detect_handoff()` (available for future use) |
|
||||
|
||||
## Deferred Work
|
||||
|
||||
### Tauri Desktop App (com.wzp.desktop)
|
||||
|
||||
~~The Tauri engine doesn't use `AdaptiveQualityController` — quality is resolved once at call start.~~ **Update (2026-04-13):** Desktop now has `AdaptiveQualityController` wired into the recv task with `pending_profile` AtomicU8 bridge. Network monitoring on desktop is now feasible — the blocker was adaptive quality, which is done. Remaining work: platform-specific network change detection (macOS: `SCNetworkReachability` or `NWPathMonitor`; Linux: `netlink` socket).
|
||||
|
||||
### Mid-Call ICE Re-gathering — PARTIALLY IMPLEMENTED (2026-04-14)
|
||||
|
||||
When the device's IP address changes, the system now:
|
||||
1. Re-gather local host candidates (`local_host_candidates()`) ✅
|
||||
2. Re-probe STUN (`stun::discover_reflexive()` + `portmap::acquire_port_mapping()`) ✅
|
||||
3. Send updated candidates to the peer (`CandidateUpdate` signal message) ✅
|
||||
4. Relay forwards `CandidateUpdate` to peer (same pattern as `MediaPathReport`) ✅
|
||||
5. Peer receives and can parse via `IceAgent::apply_peer_update()` ✅
|
||||
6. Attempt new dual-path race for path upgrade — **NOT YET WIRED** (transport hot-swap)
|
||||
|
||||
`NetworkMonitor.onIpChanged` fires on `onLinkPropertiesChanged` — the hook is ready.
|
||||
The signaling plane is fully implemented via `IceAgent` + `CandidateUpdate`.
|
||||
Remaining: wire `onIpChanged` → JNI → `pending_ice_regather` AtomicBool → recv task → `ice_agent.re_gather()` → transport swap.
|
||||
|
||||
New modules added in Phase 8 (Tailscale-inspired):
|
||||
- `crates/wzp-client/src/ice_agent.rs` — candidate lifecycle management
|
||||
- `crates/wzp-client/src/stun.rs` — public STUN server probing (independent of relay)
|
||||
- `crates/wzp-client/src/portmap.rs` — NAT-PMP/PCP/UPnP port mapping
|
||||
- `crates/wzp-client/src/netcheck.rs` — comprehensive network diagnostic
|
||||
|
||||
## Testing
|
||||
|
||||
1. Build native APK
|
||||
2. Start a call on WiFi
|
||||
3. Verify logcat: `quality controller: network context updated` with `ctx=WiFi`
|
||||
4. Disable WiFi → device falls to cellular
|
||||
5. Verify logcat: `ctx=CellularLte` (or `Cellular5g`/`Cellular3g`)
|
||||
6. Verify FEC boost activates (check quality_ctrl logs)
|
||||
7. Verify preemptive quality downgrade (tier drops one level on WiFi→cellular)
|
||||
8. Re-enable WiFi → verify transition back
|
||||
9. Rapid WiFi toggle (5x in 10s) → verify no crashes, deduplication works
|
||||
10. Airplane mode → verify `onLost` fires with `TYPE_NONE`
|
||||
Reference in New Issue
Block a user