manawenuz/wz-phone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: manawenuz:cc23e829b21d1c00f8b26ee769d7fd0a773aacdc
Branches Tags
manawenuz:main manawenuz:experimental-ui manawenuz:opus-DRED-v2 manawenuz:opus-DRED manawenuz:feat/desktop-audio-rewrite manawenuz:android-rewrite manawenuz:feat/android-voip-client manawenuz:debug/codec2-test manawenuz:build/last-working manawenuz:build/last-known-good manawenuz:feature/wzp-web-variants manawenuz:feature/ws-room-abstraction
..
compare: manawenuz:debug/codec2-test
Branches Tags
manawenuz:experimental-ui manawenuz:main manawenuz:opus-DRED-v2 manawenuz:opus-DRED manawenuz:feat/desktop-audio-rewrite manawenuz:android-rewrite manawenuz:feat/android-voip-client manawenuz:debug/codec2-test manawenuz:build/last-working manawenuz:build/last-known-good manawenuz:feature/wzp-web-variants manawenuz:feature/ws-room-abstraction

2 Commits
cc23e829b2 ... debug/code

Author SHA1 Message Date
Siavash Sameni
073756ed4b fix: auto-switch decoder codec to match incoming packets 
The CallDecoder now inspects each incoming packet's codec_id and
automatically switches the audio decoder if it differs from the
current profile. This enables cross-codec interop where one client
sends Opus and the other sends Codec2 — previously the receiver
would try to decode with the wrong codec, producing garbled audio.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-07 15:25:24 +04:00
Siavash Sameni
2fcc2d77cf feat: add --profile/--codec flag to CLI for forcing codec selection 
Enables debugging Codec2 by allowing forced codec selection from CLI.
Supports: good, degraded, catastrophic, codec2-3200, codec2-1200.
Frame size, timing, and jitter buffer are all adjusted dynamically
based on the selected profile.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-07 15:23:36 +04:00
160 changed files with 3391 additions and 42295 deletions
Expand all files Collapse all files

72
.agents/skills/caveman/SKILL.md
View File

@@ -1,72 +0,0 @@
---
name: caveman
description: >
Ultra-compressed communication mode. Slash token usage ~75% by speaking like caveman
while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman",
"use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers
when token efficiency is requested.
---
# Caveman Mode
## Core Rule
Respond like smart caveman. Cut articles, filler, pleasantries. Keep all technical substance.
## Grammar
- Drop articles (a, an, the)
- Drop filler (just, really, basically, actually, simply)
- Drop pleasantries (sure, certainly, of course, happy to)
- Short synonyms (big not extensive, fix not "implement a solution for")
- No hedging (skip "it might be worth considering")
- Fragments fine. No need full sentence
- Technical terms stay exact. "Polymorphism" stays "polymorphism"
- Code blocks unchanged. Caveman speak around code, not in code
- Error messages quoted exact. Caveman only for explanation
## Pattern
```
[thing] [action] [reason]. [next step].
```
Not:
> Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by...
Yes:
> Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:
## Examples
**User:** Why is my React component re-rendering?
**Normal (69 tokens):** "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object."
**Caveman (19 tokens):** "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
---
**User:** How do I set up a PostgreSQL connection pool?
**Caveman:**
```
Use `pg` pool:
```
```js
const pool = new Pool({
max: 20,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
})
```
```
max = concurrent connections. Keep under DB limit. idleTimeout kill stale conn.
```
## Boundaries
- Code: write normal. Caveman English only
- Git commits: normal
- PR descriptions: normal
- User say "stop caveman" or "normal mode": revert immediately

25
.gitignore vendored
View File

@@ -4,28 +4,3 @@
*.swp
*.swo
*~
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
dev-debug.log
# Dependency directories
node_modules/
# Environment variables
.env
# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
# OS specific
# Taskmaster (local workflow tool)
.taskmaster/
.env.example

1324
Cargo.lock generated
View File

File diff suppressed because it is too large Load Diff

24
Cargo.toml
View File

@@ -10,7 +10,6 @@ members = [
"crates/wzp-client",
"crates/wzp-web",
"crates/wzp-android",
"crates/wzp-native",
"desktop/src-tauri",
]
@@ -32,25 +31,17 @@ serde = { version = "1", features = ["derive"] }
# Transport
quinn = "0.11"
socket2 = "0.5"
# FEC
raptorq = "2"
# Codec
# opusic-c: high-level safe bindings over libopus 1.5.2 (encoder side).
# opusic-sys: raw FFI for the decoder side — we build our own DecoderHandle
# because opusic-c::Decoder.inner is pub(crate) and cannot be reached for the
# Phase 3 DRED reconstruction path. See docs/PRD-dred-integration.md.
# Pinned exactly (no caret) for reproducible libopus 1.5.2 across the fleet.
opusic-c = { version = "=1.5.5", default-features = false, features = ["bundled", "dred"] }
opusic-sys = { version = "=0.6.0", default-features = false, features = ["bundled"] }
bytemuck = "1"
audiopus = "0.3.0-rc.0"
codec2 = "0.3"
# Crypto
x25519-dalek = { version = "2", features = ["static_secrets"] }
ed25519-dalek = { version = "2", features = ["rand_core", "pkcs8"] }
ed25519-dalek = { version = "2", features = ["rand_core"] }
chacha20poly1305 = "0.10"
hkdf = "0.12"
sha2 = "0.10"
@@ -74,7 +65,9 @@ opt-level = 2
# real-time audio needs < 20ms per frame, impossible unoptimized.
[profile.dev.package.nnnoiseless]
opt-level = 3
[profile.dev.package.opusic-sys]
[profile.dev.package.audiopus_sys]
opt-level = 3
[profile.dev.package.audiopus]
opt-level = 3
[profile.dev.package.raptorq]
opt-level = 3
@@ -82,10 +75,3 @@ opt-level = 3
opt-level = 3
[profile.dev.package.wzp-fec]
opt-level = 3
# Phase 0 (opus-DRED): removed the [patch.crates-io] audiopus_sys = { path =
# "vendor/audiopus_sys" } block. That patch existed to fix a Windows clang-cl
# SIMD compile bug in libopus 1.3.1. With the swap to opusic-sys (libopus
# 1.5.2), the upstream SIMD gating was fixed and the vendor patch is
# obsolete. The vendor/audiopus_sys directory itself should be deleted as
# part of the same cleanup — see the commit that follows this Phase 0.

45
android/app/src/main/java/com/wzp/audio/AudioPipeline.kt
View File

@@ -19,8 +19,6 @@ import java.io.FileOutputStream
import java.io.OutputStreamWriter
import java.nio.ByteBuffer
import java.nio.ByteOrder
import java.util.concurrent.CountDownLatch
import java.util.concurrent.TimeUnit
import kotlin.math.pow
import kotlin.math.sqrt
@@ -57,23 +55,10 @@ class AudioPipeline(private val context: Context) {
/** Whether to attach hardware AEC. Must be set before start(). */
var aecEnabled: Boolean = true
/** Enable debug recording of PCM + RMS histogram to cache dir. */
var debugRecording: Boolean = false
var debugRecording: Boolean = true
private var captureThread: Thread? = null
private var playoutThread: Thread? = null
// DirectByteBuffers for zero-copy JNI audio transfer.
// Allocated as class fields (NOT locals) because ART's JIT OSR
// can null local variables when it replaces the stack frame mid-loop.
// These survive OSR because they're on the heap.
private val captureDirectBuf: ByteBuffer =
ByteBuffer.allocateDirect(FRAME_SAMPLES * 2).order(ByteOrder.LITTLE_ENDIAN)
private val playoutDirectBuf: ByteBuffer =
ByteBuffer.allocateDirect(FRAME_SAMPLES * 2).order(ByteOrder.LITTLE_ENDIAN)
/** Latch counted down by each audio thread after exiting its loop.
* stop() does NOT wait on this — teardown waits via awaitDrain(). */
private var drainLatch: CountDownLatch? = null
private val debugDir: File by lazy {
File(context.cacheDir, "wzp_debug").also { it.mkdirs() }
}
@@ -81,11 +66,9 @@ class AudioPipeline(private val context: Context) {
fun start(engine: WzpEngine) {
if (running) return
running = true
drainLatch = CountDownLatch(2) // one for capture, one for playout
captureThread = Thread({
runCapture(engine)
drainLatch?.countDown() // signal: capture loop exited, no more JNI calls
// Park thread forever — exiting triggers a libcrypto TLS destructor
// crash (SIGSEGV in OPENSSL_free) on Android when a JNI-calling thread exits.
parkThread()
@@ -97,7 +80,6 @@ class AudioPipeline(private val context: Context) {
playoutThread = Thread({
runPlayout(engine)
drainLatch?.countDown() // signal: playout loop exited
parkThread()
}, "wzp-playout").apply {
isDaemon = true
@@ -110,20 +92,10 @@ class AudioPipeline(private val context: Context) {
fun stop() {
running = false
// Don't join threads — they are parked as daemons to avoid native TLS crash.
// Don't null thread refs or drainLatch — teardown() needs awaitDrain().
Log.i(TAG, "audio pipeline stopped (running=false)")
}
/** Block until both audio threads have exited their loops (max 200ms).
* After this returns, no more JNI calls to the engine will be made. */
fun awaitDrain(): Boolean {
val ok = drainLatch?.await(200, TimeUnit.MILLISECONDS) ?: true
if (!ok) Log.w(TAG, "awaitDrain: audio threads did not drain in 200ms")
// Don't join — threads are parked as daemons to avoid native TLS crash
captureThread = null
playoutThread = null
drainLatch = null
return ok
Log.i(TAG, "audio pipeline stopped")
}
private fun applyGain(pcm: ShortArray, count: Int, db: Float) {
@@ -234,10 +206,7 @@ class AudioPipeline(private val context: Context) {
val read = recorder.read(pcm, 0, FRAME_SAMPLES)
if (read > 0) {
applyGain(pcm, read, captureGainDb)
// Zero-copy write via DirectByteBuffer (class field, survives JIT OSR)
captureDirectBuf.clear()
captureDirectBuf.asShortBuffer().put(pcm, 0, read)
engine.writeAudioDirect(captureDirectBuf, read)
engine.writeAudio(pcm)
// Debug: write raw PCM + RMS
if (pcmOut != null) {
@@ -316,12 +285,8 @@ class AudioPipeline(private val context: Context) {
}
try {
while (running) {
// Zero-copy read via DirectByteBuffer (class field, survives JIT OSR)
playoutDirectBuf.clear()
val read = engine.readAudioDirect(playoutDirectBuf, FRAME_SAMPLES)
val read = engine.readAudio(pcm)
if (read >= FRAME_SAMPLES) {
playoutDirectBuf.rewind()
playoutDirectBuf.asShortBuffer().get(pcm, 0, read)
applyGain(pcm, read, playoutGainDb)
track.write(pcm, 0, read)

62
android/app/src/main/java/com/wzp/data/SettingsRepository.kt
View File

@@ -28,9 +28,6 @@ class SettingsRepository(context: Context) {
private const val KEY_PREFER_IPV6 = "prefer_ipv6"
private const val KEY_IDENTITY_SEED = "identity_seed_hex"
private const val KEY_AEC_ENABLED = "aec_enabled"
private const val KEY_DEBUG_RECORDING = "debug_recording"
private const val KEY_RECENT_ROOMS = "recent_rooms"
private const val TOFU_PREFIX = "tofu_"
}
// --- Servers ---
@@ -121,16 +118,6 @@ class SettingsRepository(context: Context) {
fun saveAecEnabled(enabled: Boolean) { prefs.edit().putBoolean(KEY_AEC_ENABLED, enabled).apply() }
fun loadAecEnabled(): Boolean = prefs.getBoolean(KEY_AEC_ENABLED, true)
// --- Debug recording ---
fun saveDebugRecording(enabled: Boolean) { prefs.edit().putBoolean(KEY_DEBUG_RECORDING, enabled).apply() }
fun loadDebugRecording(): Boolean = prefs.getBoolean(KEY_DEBUG_RECORDING, false)
// --- Codec choice ---
// 0 = Opus (GOOD), 1 = Opus Low (DEGRADED), 2 = Codec2 (CATASTROPHIC)
fun saveCodecChoice(choice: Int) { prefs.edit().putInt("codec_choice", choice).apply() }
fun loadCodecChoice(): Int = prefs.getInt("codec_choice", 0)
// --- Identity seed ---
/**
@@ -151,53 +138,4 @@ class SettingsRepository(context: Context) {
fun saveSeedHex(hex: String) {
prefs.edit().putString(KEY_IDENTITY_SEED, hex).apply()
}
// --- Recent rooms ---
data class RecentRoom(val relay: String, val room: String)
fun addRecentRoom(relay: String, room: String) {
val rooms = loadRecentRooms().toMutableList()
rooms.removeAll { it.relay == relay && it.room == room }
rooms.add(0, RecentRoom(relay, room))
if (rooms.size > 5) rooms.subList(5, rooms.size).clear()
val arr = JSONArray()
rooms.forEach { arr.put(JSONObject().apply { put("relay", it.relay); put("room", it.room) }) }
prefs.edit().putString(KEY_RECENT_ROOMS, arr.toString()).apply()
}
fun loadRecentRooms(): List<RecentRoom> {
val json = prefs.getString(KEY_RECENT_ROOMS, null) ?: return emptyList()
return try {
val arr = JSONArray(json)
(0 until arr.length()).map { i ->
val o = arr.getJSONObject(i)
RecentRoom(o.getString("relay"), o.getString("room"))
}
} catch (_: Exception) { emptyList() }
}
fun clearRecentRooms() {
prefs.edit().remove(KEY_RECENT_ROOMS).apply()
}
// --- Server fingerprint TOFU ---
fun saveServerFingerprint(address: String, fingerprint: String) {
prefs.edit().putString("$TOFU_PREFIX$address", fingerprint).apply()
}
fun loadServerFingerprint(address: String): String? {
return prefs.getString("$TOFU_PREFIX$address", null)
}
// --- Ping RTT cache ---
fun savePingRtt(address: String, rttMs: Int) {
prefs.edit().putInt("ping_rtt_$address", rttMs).apply()
}
fun loadPingRtt(address: String): Int {
return prefs.getInt("ping_rtt_$address", -1)
}
}

44
android/app/src/main/java/com/wzp/debug/DebugReporter.kt
View File

@@ -46,14 +46,6 @@ class DebugReporter(private val context: Context) {
val zipFile = File(context.cacheDir, "wzp_debug_${timestamp}.zip")
ZipOutputStream(BufferedOutputStream(FileOutputStream(zipFile))).use { zos ->
// Phase 4: extract DRED / classical PLC counters from the
// stats JSON so they're visible in the meta preamble at a
// glance, not buried in the trailing JSON dump.
val dredReconstructions = extractLongField(finalStatsJson, "dred_reconstructions")
val classicalPlc = extractLongField(finalStatsJson, "classical_plc_invocations")
val framesDecoded = extractLongField(finalStatsJson, "frames_decoded")
val fecRecovered = extractLongField(finalStatsJson, "fec_recovered")
// 1. Call metadata
val meta = buildString {
appendLine("=== WZ Phone Debug Report ===")
@@ -66,18 +58,6 @@ class DebugReporter(private val context: Context) {
appendLine("Device: ${android.os.Build.MANUFACTURER} ${android.os.Build.MODEL}")
appendLine("Android: ${android.os.Build.VERSION.RELEASE} (API ${android.os.Build.VERSION.SDK_INT})")
appendLine()
appendLine("=== Loss Recovery ===")
appendLine("Frames decoded: $framesDecoded")
appendLine("DRED reconstructions: $dredReconstructions (Opus neural recovery)")
appendLine("Classical PLC: $classicalPlc (fallback)")
appendLine("RaptorQ FEC recovered: $fecRecovered (Codec2 only)")
if (framesDecoded > 0) {
val dredPct = 100.0 * dredReconstructions / framesDecoded
val plcPct = 100.0 * classicalPlc / framesDecoded
appendLine("DRED rate: ${"%.2f".format(dredPct)}%")
appendLine("Classical PLC rate: ${"%.2f".format(plcPct)}%")
}
appendLine()
appendLine("=== Final Stats ===")
appendLine(finalStatsJson)
}
@@ -215,28 +195,4 @@ class DebugReporter(private val context: Context) {
FileInputStream(file).use { it.copyTo(zos) }
zos.closeEntry()
}
/**
* Tiny JSON field extractor — pulls an integer value for a top-level
* field like `"dred_reconstructions":42`. We don't want to pull in a
* full JSON parser just for the debug preamble, and the CallStats
* output is a flat record with well-known field names.
*
* Returns 0 if the field is missing or unparseable.
*/
private fun extractLongField(json: String, field: String): Long {
val key = "\"$field\":"
val idx = json.indexOf(key)
if (idx < 0) return 0
var i = idx + key.length
// Skip whitespace
while (i < json.length && json[i].isWhitespace()) i++
val start = i
while (i < json.length && (json[i].isDigit() || json[i] == '-')) i++
return try {
json.substring(start, i).toLong()
} catch (_: NumberFormatException) {
0
}
}
}

29
android/app/src/main/java/com/wzp/engine/CallStats.kt
View File

@@ -33,24 +33,10 @@ data class CallStats(
val fecRecovered: Long = 0,
/** Current mic audio level (RMS, 0-32767). */
val audioLevel: Int = 0,
/** Our current outgoing codec (e.g. "Opus24k"). */
val currentCodec: String = "",
/** Last seen incoming codec from peers. */
val peerCodec: String = "",
/** Whether auto quality mode is active. */
val autoMode: Boolean = false,
/** Number of participants in the room. */
val roomParticipantCount: Int = 0,
/** Participants in the room (fingerprint + optional alias). */
val roomParticipants: List<RoomMember> = emptyList(),
/** SAS verification code (4-digit, null if not in a call). */
val sasCode: Int? = null,
/** Incoming call ID (or "relay|room" for CallSetup). */
val incomingCallId: String? = null,
/** Incoming caller's fingerprint. */
val incomingCallerFp: String? = null,
/** Incoming caller's alias. */
val incomingCallerAlias: String? = null,
) {
/** Human-readable quality label. */
val qualityLabel: String
@@ -68,8 +54,7 @@ data class CallStats(
val o = arr.getJSONObject(i)
RoomMember(
fingerprint = o.optString("fingerprint", ""),
alias = if (o.isNull("alias")) null else o.optString("alias", null),
relayLabel = if (o.isNull("relay_label")) null else o.optString("relay_label", null)
alias = if (o.isNull("alias")) null else o.optString("alias", null)
)
}
}
@@ -91,15 +76,8 @@ data class CallStats(
underruns = obj.optLong("underruns", 0),
fecRecovered = obj.optLong("fec_recovered", 0),
audioLevel = obj.optInt("audio_level", 0),
currentCodec = obj.optString("current_codec", ""),
peerCodec = obj.optString("peer_codec", ""),
autoMode = obj.optBoolean("auto_mode", false),
roomParticipantCount = obj.optInt("room_participant_count", 0),
roomParticipants = parseParticipants(obj.optJSONArray("room_participants")),
sasCode = if (obj.has("sas_code")) obj.optInt("sas_code") else null,
incomingCallId = if (obj.isNull("incoming_call_id")) null else obj.optString("incoming_call_id", null),
incomingCallerFp = if (obj.isNull("incoming_caller_fp")) null else obj.optString("incoming_caller_fp", null),
incomingCallerAlias = if (obj.isNull("incoming_caller_alias")) null else obj.optString("incoming_caller_alias", null),
roomParticipants = parseParticipants(obj.optJSONArray("room_participants"))
)
} catch (e: Exception) {
CallStats()
@@ -110,8 +88,7 @@ data class CallStats(
data class RoomMember(
val fingerprint: String,
val alias: String? = null,
val relayLabel: String? = null
val alias: String? = null
) {
/** Short display name: alias if set, otherwise first 8 chars of fingerprint. */
val displayName: String

94
android/app/src/main/java/com/wzp/engine/WzpEngine.kt
View File

@@ -38,12 +38,9 @@ class WzpEngine(private val callback: WzpCallback) {
* @param alias display name sent to relay for room participant list
* @return 0 on success, negative error code on failure
*/
/**
* @param profile 0 = Opus GOOD, 1 = Opus DEGRADED, 2 = Codec2 CATASTROPHIC
*/
fun startCall(relayAddr: String, room: String, seedHex: String = "", token: String = "", alias: String = "", profile: Int = 0): Int {
fun startCall(relayAddr: String, room: String, seedHex: String = "", token: String = "", alias: String = ""): Int {
check(nativeHandle != 0L) { "Engine not initialized" }
val result = nativeStartCall(nativeHandle, relayAddr, room, seedHex, token, alias, profile)
val result = nativeStartCall(nativeHandle, relayAddr, room, seedHex, token, alias)
if (result == 0) {
callback.onCallStateChanged(CallStateConstants.CONNECTING)
} else {
@@ -53,7 +50,6 @@ class WzpEngine(private val callback: WzpCallback) {
}
/** Stop the active call. Safe to call when no call is active. */
@Synchronized
fun stopCall() {
if (nativeHandle != 0L) {
nativeStopCall(nativeHandle)
@@ -77,7 +73,6 @@ class WzpEngine(private val callback: WzpCallback) {
*
* @return JSON-serialised [CallStats], or `"{}"` if the engine is not initialised.
*/
@Synchronized
fun getStats(): String {
if (nativeHandle == 0L) return "{}"
return try {
@@ -96,19 +91,7 @@ class WzpEngine(private val callback: WzpCallback) {
if (nativeHandle != 0L) nativeForceProfile(nativeHandle, profile)
}
/**
* Signal a network transport change (e.g. WiFi → LTE handoff).
*
* @param networkType matches Rust `NetworkContext` ordinals:
* 0=WiFi, 1=LTE, 2=5G, 3=3G, 4=Unknown, 5=None
* @param bandwidthKbps reported downstream bandwidth in kbps
*/
fun onNetworkChanged(networkType: Int, bandwidthKbps: Int) {
if (nativeHandle != 0L) nativeOnNetworkChanged(nativeHandle, networkType, bandwidthKbps)
}
/** Destroy the native engine and free all resources. The instance must not be reused. */
@Synchronized
fun destroy() {
if (nativeHandle != 0L) {
nativeDestroy(nativeHandle)
@@ -134,31 +117,11 @@ class WzpEngine(private val callback: WzpCallback) {
return nativeReadAudio(nativeHandle, pcm)
}
/**
* Write captured PCM from a DirectByteBuffer — zero JNI array copy.
* The buffer must be a direct ByteBuffer with native byte order containing i16 samples.
* Called from the AudioRecord capture thread.
*/
fun writeAudioDirect(buffer: java.nio.ByteBuffer, sampleCount: Int): Int {
if (nativeHandle == 0L) return 0
return nativeWriteAudioDirect(nativeHandle, buffer, sampleCount)
}
/**
* Read decoded PCM into a DirectByteBuffer — zero JNI array copy.
* The buffer must be a direct ByteBuffer with native byte order.
* Called from the AudioTrack playout thread.
*/
fun readAudioDirect(buffer: java.nio.ByteBuffer, maxSamples: Int): Int {
if (nativeHandle == 0L) return 0
return nativeReadAudioDirect(nativeHandle, buffer, maxSamples)
}
// -- JNI native methods --------------------------------------------------
private external fun nativeInit(): Long
private external fun nativeStartCall(
handle: Long, relay: String, room: String, seed: String, token: String, alias: String, profile: Int
handle: Long, relay: String, room: String, seed: String, token: String, alias: String
): Int
private external fun nativeStopCall(handle: Long)
private external fun nativeSetMute(handle: Long, muted: Boolean)
@@ -167,58 +130,7 @@ class WzpEngine(private val callback: WzpCallback) {
private external fun nativeForceProfile(handle: Long, profile: Int)
private external fun nativeWriteAudio(handle: Long, pcm: ShortArray): Int
private external fun nativeReadAudio(handle: Long, pcm: ShortArray): Int
private external fun nativeWriteAudioDirect(handle: Long, buffer: java.nio.ByteBuffer, sampleCount: Int): Int
private external fun nativeReadAudioDirect(handle: Long, buffer: java.nio.ByteBuffer, maxSamples: Int): Int
private external fun nativeDestroy(handle: Long)
private external fun nativePingRelay(handle: Long, relay: String): String?
private external fun nativeStartSignaling(handle: Long, relay: String, seed: String, token: String, alias: String): Int
private external fun nativePlaceCall(handle: Long, targetFp: String): Int
private external fun nativeAnswerCall(handle: Long, callId: String, mode: Int): Int
private external fun nativeOnNetworkChanged(handle: Long, networkType: Int, bandwidthKbps: Int)
/**
* Ping a relay server. Requires engine to be initialized.
* Returns JSON `{"rtt_ms":N,"server_fingerprint":"hex"}` or null.
*/
fun pingRelay(address: String): String? {
if (nativeHandle == 0L) return null
return nativePingRelay(nativeHandle, address)
}
/**
* Start persistent signaling connection for direct 1:1 calls.
* The engine registers on the relay and listens for incoming calls.
* Call state updates are available via [getStats].
*
* @return 0 on success, -1 on error
*/
fun startSignaling(relay: String, seed: String = "", token: String = "", alias: String = ""): Int {
check(nativeHandle != 0L) { "Engine not initialized" }
return nativeStartSignaling(nativeHandle, relay, seed, token, alias)
}
/**
* Place a direct call to a peer by fingerprint.
* Requires [startSignaling] to have been called first.
*
* @return 0 on success, -1 on error
*/
fun placeCall(targetFingerprint: String): Int {
check(nativeHandle != 0L) { "Engine not initialized" }
return nativePlaceCall(nativeHandle, targetFingerprint)
}
/**
* Answer an incoming direct call.
*
* @param callId The call ID from the incoming call (available in stats.incoming_call_id)
* @param mode 0=Reject, 1=AcceptTrusted (P2P in Phase 2), 2=AcceptGeneric (relay-mediated)
* @return 0 on success, -1 on error
*/
fun answerCall(callId: String, mode: Int = 2): Int {
check(nativeHandle != 0L) { "Engine not initialized" }
return nativeAnswerCall(nativeHandle, callId, mode)
}
companion object {
init {

141
android/app/src/main/java/com/wzp/net/NetworkMonitor.kt
View File

@@ -1,141 +0,0 @@
package com.wzp.net
import android.content.Context
import android.net.ConnectivityManager
import android.net.Network
import android.net.NetworkCapabilities
import android.net.NetworkRequest
import android.os.Handler
import android.os.Looper
/**
* Monitors network connectivity changes via [ConnectivityManager.NetworkCallback]
* and classifies the active transport (WiFi, LTE, 5G, 3G).
*
* Callbacks fire on the main looper so callers can safely update UI state or
* dispatch to a native engine from any callback.
*
* Usage:
* 1. Set [onNetworkChanged] to receive `(type: Int, downlinkKbps: Int)` events
* 2. Optionally set [onIpChanged] for IP address change events (mid-call ICE refresh)
* 3. Call [register] when the call starts
* 4. Call [unregister] when the call ends
*/
class NetworkMonitor(context: Context) {
private val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
private val mainHandler = Handler(Looper.getMainLooper())
/**
* Called when the network transport type or bandwidth changes.
* `type` constants match the Rust `NetworkContext` enum ordinals.
*/
var onNetworkChanged: ((type: Int, downlinkKbps: Int) -> Unit)? = null
/**
* Called when the device's IP address changes (link properties changed).
* Useful for triggering mid-call ICE candidate re-gathering.
*/
var onIpChanged: (() -> Unit)? = null
// Track the last emitted type to avoid redundant callbacks
@Volatile
private var lastEmittedType: Int = TYPE_UNKNOWN
private val callback = object : ConnectivityManager.NetworkCallback() {
override fun onAvailable(network: Network) {
classifyAndEmit(network)
}
override fun onCapabilitiesChanged(network: Network, caps: NetworkCapabilities) {
classifyFromCaps(caps)
}
override fun onLinkPropertiesChanged(
network: Network,
linkProperties: android.net.LinkProperties
) {
// IP address may have changed — notify for ICE refresh
onIpChanged?.invoke()
// Also re-classify in case the transport changed simultaneously
classifyAndEmit(network)
}
override fun onLost(network: Network) {
lastEmittedType = TYPE_NONE
onNetworkChanged?.invoke(TYPE_NONE, 0)
}
}
// -- Public API -----------------------------------------------------------
/** Register the network callback. Call when a call starts. */
fun register() {
val request = NetworkRequest.Builder()
.addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
.build()
cm.registerNetworkCallback(request, callback, mainHandler)
}
/** Unregister the network callback. Call when the call ends. */
fun unregister() {
try {
cm.unregisterNetworkCallback(callback)
} catch (_: IllegalArgumentException) {
// Already unregistered — safe to ignore
}
}
// -- Classification -------------------------------------------------------
private fun classifyAndEmit(network: Network) {
val caps = cm.getNetworkCapabilities(network) ?: return
classifyFromCaps(caps)
}
private fun classifyFromCaps(caps: NetworkCapabilities) {
val type = when {
caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) -> TYPE_WIFI
caps.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET) -> TYPE_WIFI // treat as WiFi
caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> classifyCellular(caps)
else -> TYPE_UNKNOWN
}
val bw = caps.getLinkDownstreamBandwidthKbps()
// Deduplicate: only emit when the transport type actually changes
if (type != lastEmittedType) {
lastEmittedType = type
onNetworkChanged?.invoke(type, bw)
}
}
/**
* Approximate cellular generation from reported downstream bandwidth.
* This avoids requiring READ_PHONE_STATE permission (needed for
* TelephonyManager.getNetworkType on API 30+).
*
* Thresholds are conservative — carriers over-report bandwidth, so we
* classify based on what's actually usable for VoIP:
* - >= 100 Mbps → 5G NR
* - >= 10 Mbps → LTE
* - < 10 Mbps → 3G or worse
*/
private fun classifyCellular(caps: NetworkCapabilities): Int {
val bw = caps.getLinkDownstreamBandwidthKbps()
return when {
bw >= 100_000 -> TYPE_CELLULAR_5G
bw >= 10_000 -> TYPE_CELLULAR_LTE
else -> TYPE_CELLULAR_3G
}
}
companion object {
/** Constants matching Rust `NetworkContext` enum ordinals. */
const val TYPE_WIFI = 0
const val TYPE_CELLULAR_LTE = 1
const val TYPE_CELLULAR_5G = 2
const val TYPE_CELLULAR_3G = 3
const val TYPE_UNKNOWN = 4
const val TYPE_NONE = 5
}
}

12
android/app/src/main/java/com/wzp/net/RelayPinger.kt
View File

@@ -1,12 +0,0 @@
package com.wzp.net
// Relay pinging is now done via WzpEngine.pingRelay() (instance method).
// This file kept for the data class only.
object RelayPinger {
data class PingResult(
val rttMs: Int,
val reachable: Boolean,
val serverFingerprint: String = "",
)
}

341
android/app/src/main/java/com/wzp/ui/call/CallViewModel.kt
View File

@@ -5,7 +5,6 @@ import android.util.Log
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.wzp.audio.AudioPipeline
import com.wzp.audio.AudioRoute
import com.wzp.audio.AudioRouteManager
import com.wzp.data.SettingsRepository
import com.wzp.debug.DebugReporter
@@ -13,8 +12,6 @@ import com.wzp.engine.CallStats
import com.wzp.service.CallService
import com.wzp.engine.WzpCallback
import com.wzp.engine.WzpEngine
import com.wzp.net.NetworkMonitor
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableStateFlow
@@ -22,8 +19,6 @@ import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import org.json.JSONObject
import java.io.File
import java.net.Inet4Address
import java.net.Inet6Address
@@ -31,21 +26,12 @@ import java.net.InetAddress
data class ServerEntry(val address: String, val label: String)
data class PingResult(
val rttMs: Int,
val serverFingerprint: String = "",
val reachable: Boolean = rttMs > 0,
)
enum class LockStatus { UNKNOWN, OFFLINE, NEW, VERIFIED, CHANGED }
class CallViewModel : ViewModel(), WzpCallback {
private var engine: WzpEngine? = null
private var engineInitialized = false
private var audioPipeline: AudioPipeline? = null
private var audioRouteManager: AudioRouteManager? = null
private var networkMonitor: NetworkMonitor? = null
private var audioStarted = false
private var appContext: Context? = null
private var settings: SettingsRepository? = null
@@ -63,9 +49,6 @@ class CallViewModel : ViewModel(), WzpCallback {
private val _isSpeaker = MutableStateFlow(false)
val isSpeaker: StateFlow<Boolean> = _isSpeaker.asStateFlow()
private val _audioRoute = MutableStateFlow(AudioRoute.EARPIECE)
val audioRoute: StateFlow<AudioRoute> = _audioRoute.asStateFlow()
private val _stats = MutableStateFlow(CallStats())
val stats: StateFlow<CallStats> = _stats.asStateFlow()
@@ -87,16 +70,6 @@ class CallViewModel : ViewModel(), WzpCallback {
private val _preferIPv6 = MutableStateFlow(false)
val preferIPv6: StateFlow<Boolean> = _preferIPv6.asStateFlow()
private val _recentRooms = MutableStateFlow<List<com.wzp.data.SettingsRepository.RecentRoom>>(emptyList())
val recentRooms: StateFlow<List<com.wzp.data.SettingsRepository.RecentRoom>> = _recentRooms.asStateFlow()
/** Ping results keyed by server address. */
private val _pingResults = MutableStateFlow<Map<String, PingResult>>(emptyMap())
val pingResults: StateFlow<Map<String, PingResult>> = _pingResults.asStateFlow()
/** Known server fingerprints (TOFU). */
private val _knownFingerprints = MutableStateFlow<Map<String, String>>(emptyMap())
private val _playoutGainDb = MutableStateFlow(0f)
val playoutGainDb: StateFlow<Float> = _playoutGainDb.asStateFlow()
@@ -112,18 +85,6 @@ class CallViewModel : ViewModel(), WzpCallback {
private val _aecEnabled = MutableStateFlow(true)
val aecEnabled: StateFlow<Boolean> = _aecEnabled.asStateFlow()
private val _debugRecording = MutableStateFlow(false)
val debugRecording: StateFlow<Boolean> = _debugRecording.asStateFlow()
// Quality profile index (matches JNI bridge profile_from_int)
private val _codecChoice = MutableStateFlow(0)
val codecChoice: StateFlow<Int> = _codecChoice.asStateFlow()
/** Key-change warning dialog state. */
data class KeyWarningInfo(val address: String, val oldFp: String, val newFp: String)
private val _keyWarning = MutableStateFlow<KeyWarningInfo?>(null)
val keyWarning: StateFlow<KeyWarningInfo?> = _keyWarning.asStateFlow()
/** True when a call just ended and debug report can be sent. */
private val _debugReportAvailable = MutableStateFlow(false)
val debugReportAvailable: StateFlow<Boolean> = _debugReportAvailable.asStateFlow()
@@ -138,91 +99,13 @@ class CallViewModel : ViewModel(), WzpCallback {
private var statsJob: Job? = null
// ── Direct calling state ──
/** 0=room mode, 1=direct call mode */
private val _callMode = MutableStateFlow(0)
val callMode: StateFlow<Int> = _callMode.asStateFlow()
/** Target fingerprint for direct call */
private val _targetFingerprint = MutableStateFlow("")
val targetFingerprint: StateFlow<String> = _targetFingerprint.asStateFlow()
/** Signal connection state: 0=idle, 5=registered, 6=ringing, 7=incoming */
private val _signalState = MutableStateFlow(0)
val signalState: StateFlow<Int> = _signalState.asStateFlow()
/** Incoming call info */
private val _incomingCallId = MutableStateFlow<String?>(null)
val incomingCallId: StateFlow<String?> = _incomingCallId.asStateFlow()
private val _incomingCallerFp = MutableStateFlow<String?>(null)
val incomingCallerFp: StateFlow<String?> = _incomingCallerFp.asStateFlow()
private val _incomingCallerAlias = MutableStateFlow<String?>(null)
val incomingCallerAlias: StateFlow<String?> = _incomingCallerAlias.asStateFlow()
fun setCallMode(mode: Int) { _callMode.value = mode }
fun setTargetFingerprint(fp: String) { _targetFingerprint.value = fp }
/** Register on relay for direct calls */
fun registerForCalls() {
if (engine == null) {
engine = WzpEngine(this).also { it.init() }
}
val serverIdx = _selectedServer.value
val serverList = _servers.value
if (serverIdx >= serverList.size) return
val relay = serverList[serverIdx].address
val seed = _seedHex.value
val alias = _alias.value
viewModelScope.launch(Dispatchers.IO) {
val resolvedRelay = resolveToIp(relay) ?: relay
val result = engine?.startSignaling(resolvedRelay, seed, "", alias)
if (result == 0) {
_signalState.value = 5 // Registered
startStatsPolling()
} else {
_errorMessage.value = "Failed to register on relay"
}
}
}
/** Place a direct call to the target fingerprint */
fun placeDirectCall() {
val target = _targetFingerprint.value.trim()
if (target.isEmpty()) {
_errorMessage.value = "Enter a fingerprint to call"
return
}
engine?.placeCall(target)
_signalState.value = 6 // Ringing
}
/** Answer an incoming direct call */
fun answerIncomingCall(mode: Int = 2) {
val callId = _incomingCallId.value ?: return
engine?.answerCall(callId, mode)
}
/** Reject an incoming direct call */
fun rejectIncomingCall() {
val callId = _incomingCallId.value ?: return
engine?.answerCall(callId, 0) // 0 = Reject
_signalState.value = 5 // Back to registered
_incomingCallId.value = null
_incomingCallerFp.value = null
_incomingCallerAlias.value = null
}
companion object {
private const val TAG = "WzpCall"
val DEFAULT_SERVERS = listOf(
ServerEntry("172.16.81.175:4433", "LAN (172.16.81.175)"),
ServerEntry("193.180.213.68:4433", "Pangolin (IP)"),
)
const val DEFAULT_ROOM = "general"
const val DEFAULT_ROOM = "android"
}
fun setContext(context: Context) {
@@ -232,19 +115,7 @@ class CallViewModel : ViewModel(), WzpCallback {
audioPipeline = AudioPipeline(appCtx)
}
if (audioRouteManager == null) {
audioRouteManager = AudioRouteManager(appCtx).also { arm ->
arm.onRouteChanged = { route ->
_audioRoute.value = route
_isSpeaker.value = (route == AudioRoute.SPEAKER)
}
}
}
if (networkMonitor == null) {
networkMonitor = NetworkMonitor(appCtx).also { nm ->
nm.onNetworkChanged = { type, bw ->
engine?.onNetworkChanged(type, bw)
}
}
audioRouteManager = AudioRouteManager(appCtx)
}
if (debugReporter == null) {
debugReporter = DebugReporter(appCtx)
@@ -268,9 +139,6 @@ class CallViewModel : ViewModel(), WzpCallback {
_captureGainDb.value = s.loadCaptureGain()
_seedHex.value = s.getOrCreateSeedHex()
_aecEnabled.value = s.loadAecEnabled()
_debugRecording.value = s.loadDebugRecording()
_codecChoice.value = s.loadCodecChoice()
_recentRooms.value = s.loadRecentRooms()
}
fun selectServer(index: Int) {
@@ -314,70 +182,6 @@ class CallViewModel : ViewModel(), WzpCallback {
settings?.saveSelectedServer(_selectedServer.value)
}
/**
* Ping all servers via native QUIC. Requires engine to be initialized.
* Creates engine if needed, pings, keeps engine alive for subsequent Connect.
*/
fun pingAllServers() {
viewModelScope.launch {
// Ensure engine exists
if (engine == null || engine?.isInitialized != true) {
try {
engine = WzpEngine(this@CallViewModel).also { it.init() }
engineInitialized = true
} catch (e: Exception) {
Log.w(TAG, "engine init for ping failed: $e")
return@launch
}
}
val eng = engine ?: return@launch
val results = mutableMapOf<String, PingResult>()
val known = mutableMapOf<String, String>()
_servers.value.forEach { server ->
val json = withContext(Dispatchers.IO) {
eng.pingRelay(server.address)
}
if (json != null) {
try {
val obj = JSONObject(json)
val rtt = obj.getInt("rtt_ms")
val fp = obj.optString("server_fingerprint", "")
results[server.address] = PingResult(rttMs = rtt, serverFingerprint = fp)
// TOFU
if (fp.isNotEmpty()) {
val saved = settings?.loadServerFingerprint(server.address)
if (saved == null) settings?.saveServerFingerprint(server.address, fp)
known[server.address] = saved ?: fp
}
} catch (_: Exception) {}
}
}
_pingResults.value = results
_knownFingerprints.value = known
}
}
/** Load saved TOFU fingerprints. */
fun loadSavedFingerprints() {
val known = mutableMapOf<String, String>()
_servers.value.forEach { server ->
settings?.loadServerFingerprint(server.address)?.let {
known[server.address] = it
}
}
_knownFingerprints.value = known
}
/** Get lock status for a server. */
fun lockStatus(address: String): LockStatus {
val pr = _pingResults.value[address] ?: return LockStatus.UNKNOWN
if (!pr.reachable) return LockStatus.OFFLINE
val known = _knownFingerprints.value[address] ?: return LockStatus.NEW
if (pr.serverFingerprint.isEmpty()) return LockStatus.NEW
return if (pr.serverFingerprint == known) LockStatus.VERIFIED else LockStatus.CHANGED
}
fun setRoomName(name: String) {
_roomName.value = name
settings?.saveRoom(name)
@@ -410,16 +214,6 @@ class CallViewModel : ViewModel(), WzpCallback {
settings?.saveAecEnabled(enabled)
}
fun setDebugRecording(enabled: Boolean) {
_debugRecording.value = enabled
settings?.saveDebugRecording(enabled)
}
fun setCodecChoice(choice: Int) {
_codecChoice.value = choice
settings?.saveCodecChoice(choice)
}
/**
* Resolve DNS hostname to IP address on the Kotlin/Android side,
* since Rust's DNS resolution may not work on Android.
@@ -460,17 +254,8 @@ class CallViewModel : ViewModel(), WzpCallback {
Log.i(TAG, "teardown: stopping audio, stopService=$stopService")
val hadCall = audioStarted
CallService.onStopFromNotification = null
stopAudio() // sets running=false (non-blocking)
stopAudio()
stopStatsPolling()
// Wait for audio threads to exit their loops before destroying the engine.
// This guarantees no in-flight JNI calls to writeAudio/readAudio.
val drained = audioPipeline?.awaitDrain() ?: true
if (!drained) {
Log.w(TAG, "teardown: audio threads did not drain in time")
}
audioPipeline = null
Log.i(TAG, "teardown: stopping engine")
try { engine?.stopCall() } catch (e: Exception) { Log.w(TAG, "stopCall err: $e") }
try { engine?.destroy() } catch (e: Exception) { Log.w(TAG, "destroy err: $e") }
@@ -486,82 +271,13 @@ class CallViewModel : ViewModel(), WzpCallback {
Log.i(TAG, "teardown: done")
}
/** Accept the new server key and proceed with the call. */
fun acceptNewFingerprint() {
val info = _keyWarning.value ?: return
_knownFingerprints.value = _knownFingerprints.value.toMutableMap().also {
it[info.address] = info.newFp
}
settings?.saveServerFingerprint(info.address, info.newFp)
_keyWarning.value = null
startCallInternal()
}
fun dismissKeyWarning() {
_keyWarning.value = null
}
fun startCall() {
val serverEntry = _servers.value[_selectedServer.value]
// Check for key change before connecting
val ls = lockStatus(serverEntry.address)
if (ls == LockStatus.CHANGED) {
val known = _knownFingerprints.value[serverEntry.address] ?: ""
val current = _pingResults.value[serverEntry.address]?.serverFingerprint ?: ""
_keyWarning.value = KeyWarningInfo(serverEntry.address, known, current)
return
}
startCallInternal()
}
/** Start a call to a specific relay + room (used by direct call setup). */
private fun startCallInternal(relay: String, room: String) {
Log.i(TAG, "startCallDirect: relay=$relay room=$room")
try {
// Don't teardown — keep the signal connection alive
engine = WzpEngine(this)
engine!!.init()
engineInitialized = true
_callState.value = 1
_errorMessage.value = null
try { appContext?.let { CallService.start(it) } } catch (e: Exception) {
Log.w(TAG, "service start err: $e")
}
startStatsPolling()
viewModelScope.launch(kotlinx.coroutines.Dispatchers.IO) {
try {
val seed = _seedHex.value
val name = _alias.value
val result = engine?.startCall(relay, room, seedHex = seed, alias = name, profile = _codecChoice.value) ?: -1
CallService.onStopFromNotification = { stopCall() }
if (result != 0) {
_callState.value = 0
_errorMessage.value = "Failed to connect to call room (code $result)"
appContext?.let { CallService.stop(it) }
}
} catch (e: Exception) {
Log.e(TAG, "startCallDirect error", e)
_callState.value = 0
_errorMessage.value = "Engine error: ${e.message}"
appContext?.let { CallService.stop(it) }
}
}
} catch (e: Exception) {
Log.e(TAG, "startCallDirect error", e)
_callState.value = 0
_errorMessage.value = "Engine error: ${e.message}"
}
}
private fun startCallInternal() {
val serverEntry = _servers.value[_selectedServer.value]
val room = _roomName.value
Log.i(TAG, "startCall: server=${serverEntry.address} room=$room")
_debugReportAvailable.value = false
_debugReportStatus.value = null
lastCallServer = serverEntry.address
settings?.addRecentRoom(serverEntry.address, room)
_recentRooms.value = settings?.loadRecentRooms() ?: emptyList()
debugReporter?.prepareForCall()
try {
// Teardown previous call but don't stop the service (we're about to restart it)
@@ -584,7 +300,7 @@ class CallViewModel : ViewModel(), WzpCallback {
val seed = _seedHex.value
val name = _alias.value
Log.i(TAG, "startCall: resolved=$relay, alias=$name, calling engine.startCall")
val result = engine?.startCall(relay, room, seedHex = seed, alias = name, profile = _codecChoice.value) ?: -1
val result = engine?.startCall(relay, room, seedHex = seed, alias = name) ?: -1
Log.i(TAG, "startCall: engine returned $result")
// Only wire up notification callback after engine is running
CallService.onStopFromNotification = { stopCall() }
@@ -625,27 +341,6 @@ class CallViewModel : ViewModel(), WzpCallback {
audioRouteManager?.setSpeaker(newSpeaker)
}
/** Cycle audio output: Earpiece → Speaker → Bluetooth (if available) → Earpiece. */
fun cycleAudioRoute() {
val routes = audioRouteManager?.availableRoutes() ?: return
val currentIdx = routes.indexOf(_audioRoute.value)
val next = routes[(currentIdx + 1) % routes.size]
when (next) {
AudioRoute.EARPIECE -> {
audioRouteManager?.setBluetoothSco(false)
audioRouteManager?.setSpeaker(false)
}
AudioRoute.SPEAKER -> {
audioRouteManager?.setSpeaker(true)
}
AudioRoute.BLUETOOTH -> {
audioRouteManager?.setBluetoothSco(true)
}
}
_audioRoute.value = next
_isSpeaker.value = (next == AudioRoute.SPEAKER)
}
fun clearError() { _errorMessage.value = null }
fun sendDebugReport() {
@@ -696,22 +391,19 @@ class CallViewModel : ViewModel(), WzpCallback {
it.playoutGainDb = _playoutGainDb.value
it.captureGainDb = _captureGainDb.value
it.aecEnabled = _aecEnabled.value
it.debugRecording = _debugRecording.value
it.start(e)
}
audioRouteManager?.register()
networkMonitor?.register()
audioStarted = true
}
private fun stopAudio() {
if (!audioStarted) return
audioPipeline?.stop() // sets running=false; DON'T null — teardown needs awaitDrain()
audioPipeline?.stop()
audioPipeline = null
audioRouteManager?.unregister()
networkMonitor?.unregister()
audioRouteManager?.setSpeaker(false)
_isSpeaker.value = false
_audioRoute.value = AudioRoute.EARPIECE
audioStarted = false
}
@@ -730,27 +422,6 @@ class CallViewModel : ViewModel(), WzpCallback {
if (s.state != 0) {
_callState.value = s.state
}
// Track signal state changes for direct calling
if (s.state in 5..7) {
_signalState.value = s.state
}
// Incoming call detection
if (s.state == 7) { // IncomingCall
_incomingCallId.value = s.incomingCallId
_incomingCallerFp.value = s.incomingCallerFp
_incomingCallerAlias.value = s.incomingCallerAlias
}
// CallSetup: auto-connect to media room
if (s.state == 1 && s.incomingCallId != null && s.incomingCallId.contains("|")) {
// Format: "relay_addr|room_name"
val parts = s.incomingCallId.split("|", limit = 2)
if (parts.size == 2) {
val mediaRelay = parts[0]
val mediaRoom = parts[1]
Log.i(TAG, "CallSetup: connecting to $mediaRelay room $mediaRoom")
startCallInternal(mediaRelay, mediaRoom)
}
}
if (s.state == 2 && !audioStarted) {
startAudio()
}

1238
android/app/src/main/java/com/wzp/ui/call/InCallScreen.kt
View File

File diff suppressed because it is too large Load Diff

141
android/app/src/main/java/com/wzp/ui/components/Identicon.kt
View File

@@ -1,141 +0,0 @@
package com.wzp.ui.components
import android.widget.Toast
import androidx.compose.foundation.Canvas
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.geometry.Size
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalClipboardManager
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import kotlin.math.min
/**
* Deterministic identicon — generates a unique 5x5 symmetric pattern
* from a hex fingerprint string. Identical algorithm to the desktop
* TypeScript implementation in identicon.ts.
*/
@Composable
fun Identicon(
fingerprint: String,
size: Dp = 36.dp,
clickToCopy: Boolean = true,
modifier: Modifier = Modifier,
) {
val clipboard = LocalClipboardManager.current
val context = LocalContext.current
val bytes = hashBytes(fingerprint)
val (bg, fg) = deriveColors(bytes)
val grid = buildGrid(bytes)
Canvas(
modifier = modifier
.size(size)
.clip(RoundedCornerShape(size * 0.12f))
.then(
if (clickToCopy && fingerprint.isNotEmpty()) {
Modifier.clickable {
clipboard.setText(AnnotatedString(fingerprint))
Toast.makeText(context, "Copied", Toast.LENGTH_SHORT).show()
}
} else Modifier
)
) {
val cellW = this.size.width / 5f
val cellH = this.size.height / 5f
// Background
drawRect(color = bg, size = this.size)
// Foreground cells
for (y in 0 until 5) {
for (x in 0 until 5) {
if (grid[y][x]) {
drawRect(
color = fg,
topLeft = Offset(x * cellW, y * cellH),
size = Size(cellW, cellH),
)
}
}
}
}
}
/**
* Fingerprint text that copies to clipboard on tap.
*/
@Composable
fun CopyableFingerprint(
fingerprint: String,
modifier: Modifier = Modifier,
style: androidx.compose.ui.text.TextStyle = androidx.compose.material3.MaterialTheme.typography.bodySmall,
color: Color = Color.Unspecified,
) {
val clipboard = LocalClipboardManager.current
val context = LocalContext.current
androidx.compose.material3.Text(
text = fingerprint,
style = style,
color = color,
modifier = modifier.clickable {
if (fingerprint.isNotEmpty()) {
clipboard.setText(AnnotatedString(fingerprint))
Toast.makeText(context, "Fingerprint copied", Toast.LENGTH_SHORT).show()
}
}
)
}
// --- Internal helpers (matching desktop identicon.ts) ---
private fun hashBytes(hex: String): List<Int> {
val clean = hex.filter { it.isLetterOrDigit() }
val bytes = mutableListOf<Int>()
var i = 0
while (i + 1 < clean.length) {
val b = clean.substring(i, i + 2).toIntOrNull(16) ?: 0
bytes.add(b)
i += 2
}
// Pad to at least 16 bytes
while (bytes.size < 16) bytes.add(0)
return bytes
}
private fun deriveColors(bytes: List<Int>): Pair<Color, Color> {
val hue1 = bytes[0] * 360f / 256f
val hue2 = (bytes[1] * 360f / 256f + 120f) % 360f
val bg = hslToColor(hue1, 0.65f, 0.35f)
val fg = hslToColor(hue2, 0.70f, 0.55f)
return bg to fg
}
private fun buildGrid(bytes: List<Int>): List<List<Boolean>> {
return (0 until 5).map { y ->
val left = (0 until 3).map { x ->
val idx = 2 + y * 3 + x
bytes[idx % bytes.size] > 128
}
// Mirror: col3 = col1, col4 = col0
listOf(left[0], left[1], left[2], left[1], left[0])
}
}
private fun hslToColor(h: Float, s: Float, l: Float): Color {
val k = { n: Float -> (n + h / 30f) % 12f }
val a = s * min(l, 1f - l)
val f = { n: Float ->
l - a * maxOf(-1f, minOf(k(n) - 3f, minOf(9f - k(n), 1f)))
}
return Color(f(0f), f(8f), f(4f))
}

73
android/app/src/main/java/com/wzp/ui/settings/SettingsScreen.kt
View File

@@ -1,6 +1,5 @@
package com.wzp.ui.settings
import androidx.compose.foundation.clickable
import android.content.ClipData
import android.content.ClipboardManager
import android.content.Context
@@ -23,7 +22,6 @@ import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Divider
import androidx.compose.material3.RadioButton
import androidx.compose.material3.FilledTonalButton
import androidx.compose.material3.FilledTonalIconButton
import androidx.compose.material3.IconButtonDefaults
@@ -160,30 +158,20 @@ fun SettingsScreen(
Spacer(modifier = Modifier.height(16.dp))
// Fingerprint display with identicon
// Fingerprint display
val fingerprint = if (draftSeedHex.length >= 16) draftSeedHex.take(16).uppercase() else "Not generated"
Text(
text = "Fingerprint",
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.onSurfaceVariant
)
Row(
verticalAlignment = Alignment.CenterVertically,
modifier = Modifier.padding(vertical = 4.dp)
) {
com.wzp.ui.components.Identicon(
fingerprint = draftSeedHex,
size = 40.dp,
)
Spacer(modifier = Modifier.width(12.dp))
com.wzp.ui.components.CopyableFingerprint(
fingerprint = fingerprint.chunked(4).joinToString(" "),
style = MaterialTheme.typography.bodyMedium.copy(
fontFamily = FontFamily.Monospace
),
color = MaterialTheme.colorScheme.onSurface,
)
}
Text(
text = fingerprint.chunked(4).joinToString(" "),
style = MaterialTheme.typography.bodyMedium.copy(
fontFamily = FontFamily.Monospace
),
color = MaterialTheme.colorScheme.onSurface
)
Spacer(modifier = Modifier.height(12.dp))
@@ -243,51 +231,6 @@ fun SettingsScreen(
)
}
Spacer(modifier = Modifier.height(12.dp))
// Quality selection — slider from best (studio 64k) to worst (codec2 1.2k) + auto
val qualityLabels = listOf(
"Studio 64k", "Studio 48k", "Studio 32k", "Auto",
"Opus 24k", "Opus 6k", "Codec2 3.2k", "Codec2 1.2k"
)
// Map slider position to JNI profile int:
// 0=Studio64k(6), 1=Studio48k(5), 2=Studio32k(4), 3=Auto(7),
// 4=Opus24k(0), 5=Opus6k(1), 6=Codec2_3.2k(3), 7=Codec2_1.2k(2)
val sliderToProfile = intArrayOf(6, 5, 4, 7, 0, 1, 3, 2)
val profileToSlider = mapOf(6 to 0, 5 to 1, 4 to 2, 7 to 3, 0 to 4, 1 to 5, 3 to 6, 2 to 7)
val qualityColors = listOf(
Color(0xFF22C55E), Color(0xFF4ADE80), Color(0xFF86EFAC), Color(0xFFA3E635),
Color(0xFFA3E635), Color(0xFFFACC15), Color(0xFFE97320), Color(0xFF991B1B)
)
val currentCodec by viewModel.codecChoice.collectAsState()
val sliderPos = profileToSlider[currentCodec] ?: 3
Text("Quality", style = MaterialTheme.typography.bodyMedium)
Text(
text = "Decode always accepts all codecs",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant
)
Spacer(modifier = Modifier.height(4.dp))
Text(
text = qualityLabels[sliderPos],
style = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold),
color = qualityColors[sliderPos]
)
Slider(
value = sliderPos.toFloat(),
onValueChange = { viewModel.setCodecChoice(sliderToProfile[it.toInt()]) },
valueRange = 0f..7f,
steps = 6,
modifier = Modifier.fillMaxWidth()
)
Row(
modifier = Modifier.fillMaxWidth(),
horizontalArrangement = Arrangement.SpaceBetween
) {
Text("Best", style = MaterialTheme.typography.labelSmall, color = Color(0xFF22C55E))
Text("Lowest", style = MaterialTheme.typography.labelSmall, color = Color(0xFF991B1B))
}
Spacer(modifier = Modifier.height(24.dp))
Divider()
Spacer(modifier = Modifier.height(16.dp))

2
crates/wzp-android/Cargo.toml
View File

@@ -17,7 +17,7 @@ wzp-crypto = { workspace = true }
wzp-transport = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
tracing-subscriber = { workspace = true, features = ["env-filter"] }
tracing-subscriber = { workspace = true }
bytes = { workspace = true }
serde = { workspace = true }
serde_json = "1"

113
crates/wzp-android/src/audio_ring.rs
View File

@@ -1,128 +1,91 @@
//! Lock-free SPSC ring buffer — "Reader-Detects-Lap" architecture.
//! Lock-free SPSC ring buffers for audio PCM transfer between
//! Kotlin AudioRecord/AudioTrack threads and the Rust engine.
//!
//! SPSC invariant: the producer ONLY writes `write_pos`, the consumer
//! ONLY writes `read_pos`. Neither thread touches the other's cursor.
//!
//! On overflow (writer laps the reader), the writer simply overwrites
//! old buffer data. The reader detects the lap via `available() >
//! RING_CAPACITY` and snaps its own `read_pos` forward.
//!
//! Capacity is a power of 2 for bitmask indexing (no modulo).
//! These use a simple spin-free design: the producer writes and advances
//! a write cursor, the consumer reads and advances a read cursor.
//! Both cursors are atomic so no mutex is needed.
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::sync::atomic::{AtomicUsize, Ordering};
/// Ring buffer capacity — power of 2 for bitmask indexing.
/// 16384 samples = 341.3ms at 48kHz mono. 70% more headroom
/// than the previous 9600 (200ms) for surviving Android GC pauses.
const RING_CAPACITY: usize = 16384; // 2^14
const RING_MASK: usize = RING_CAPACITY - 1;
/// Ring buffer capacity in i16 samples.
/// 960 samples * 10 frames = ~200ms of audio at 48kHz mono.
const RING_CAPACITY: usize = 960 * 10;
/// Lock-free single-producer single-consumer ring buffer for i16 PCM samples.
pub struct AudioRing {
buf: Box<[i16]>,
/// Monotonically increasing write cursor. ONLY written by producer.
buf: Box<[i16; RING_CAPACITY]>,
write_pos: AtomicUsize,
/// Monotonically increasing read cursor. ONLY written by consumer.
read_pos: AtomicUsize,
/// Incremented by reader when it detects it was lapped (overflow).
overflow_count: AtomicU64,
/// Incremented by reader when ring is empty (underrun).
underrun_count: AtomicU64,
}
// SAFETY: AudioRing is SPSC — one thread writes (producer), one reads (consumer).
// The producer only writes write_pos. The consumer only writes read_pos.
// Neither thread writes the other's cursor. Buffer indices are derived from
// the owning thread's cursor, ensuring no concurrent access to the same index.
// SAFETY: AudioRing is designed for SPSC — one thread writes, one reads.
// The atomics ensure visibility. The buffer itself is never accessed
// from the same index by both threads simultaneously because the
// producer only writes to positions between write_pos and read_pos,
// and the consumer only reads from positions between read_pos and write_pos.
unsafe impl Send for AudioRing {}
unsafe impl Sync for AudioRing {}
impl AudioRing {
pub fn new() -> Self {
debug_assert!(RING_CAPACITY.is_power_of_two());
Self {
buf: vec![0i16; RING_CAPACITY].into_boxed_slice(),
buf: Box::new([0i16; RING_CAPACITY]),
write_pos: AtomicUsize::new(0),
read_pos: AtomicUsize::new(0),
overflow_count: AtomicU64::new(0),
underrun_count: AtomicU64::new(0),
}
}
/// Number of samples available to read (clamped to capacity).
/// Number of samples available to read.
pub fn available(&self) -> usize {
let w = self.write_pos.load(Ordering::Acquire);
let r = self.read_pos.load(Ordering::Relaxed);
w.wrapping_sub(r).min(RING_CAPACITY)
let r = self.read_pos.load(Ordering::Acquire);
w.wrapping_sub(r)
}
/// Number of samples that can be written without overwriting unread data.
/// Number of samples that can be written without overwriting.
pub fn free_space(&self) -> usize {
RING_CAPACITY.saturating_sub(self.available())
RING_CAPACITY - self.available()
}
/// Write samples into the ring. Returns number of samples written.
///
/// If the ring is full, old data is silently overwritten. The reader
/// will detect the lap and self-correct. The writer NEVER touches
/// `read_pos` — this is the key invariant that prevents cursor desync.
/// Drops oldest samples if the ring is full.
pub fn write(&self, samples: &[i16]) -> usize {
let count = samples.len().min(RING_CAPACITY);
let w = self.write_pos.load(Ordering::Relaxed);
let count = samples.len().min(RING_CAPACITY);
for i in 0..count {
let idx = (w + i) % RING_CAPACITY;
// SAFETY: We're the only writer, and the reader won't read
// past read_pos which we haven't advanced past yet.
unsafe {
let ptr = self.buf.as_ptr() as *mut i16;
*ptr.add((w + i) & RING_MASK) = samples[i];
*ptr.add(idx) = samples[i];
}
}
self.write_pos.store(w.wrapping_add(count), Ordering::Release);
// If we overwrote unread data, advance read_pos
if self.available() > RING_CAPACITY {
let new_read = self.write_pos.load(Ordering::Relaxed).wrapping_sub(RING_CAPACITY);
self.read_pos.store(new_read, Ordering::Release);
}
count
}
/// Read samples from the ring into `out`. Returns number of samples read.
///
/// If the writer has lapped the reader (overflow), `read_pos` is snapped
/// forward to the oldest valid data. This is safe because only the
/// reader thread writes `read_pos`.
pub fn read(&self, out: &mut [i16]) -> usize {
let w = self.write_pos.load(Ordering::Acquire);
let mut r = self.read_pos.load(Ordering::Relaxed);
let mut avail = w.wrapping_sub(r);
// Lap detection: writer has overwritten our unread data.
// Snap read_pos forward to oldest valid data in the buffer.
if avail > RING_CAPACITY {
r = w.wrapping_sub(RING_CAPACITY);
avail = RING_CAPACITY;
self.overflow_count.fetch_add(1, Ordering::Relaxed);
}
let avail = self.available();
let count = out.len().min(avail);
if count == 0 {
if w == r {
self.underrun_count.fetch_add(1, Ordering::Relaxed);
}
return 0;
}
let r = self.read_pos.load(Ordering::Relaxed);
for i in 0..count {
out[i] = unsafe { *self.buf.as_ptr().add((r + i) & RING_MASK) };
let idx = (r + i) % RING_CAPACITY;
out[i] = unsafe { *self.buf.as_ptr().add(idx) };
}
self.read_pos.store(r.wrapping_add(count), Ordering::Release);
count
}
/// Number of overflow events (reader was lapped by writer).
pub fn overflow_count(&self) -> u64 {
self.overflow_count.load(Ordering::Relaxed)
}
/// Number of underrun events (reader found empty buffer).
pub fn underrun_count(&self) -> u64 {
self.underrun_count.load(Ordering::Relaxed)
}
}

9
crates/wzp-android/src/commands.rs
View File

@@ -12,13 +12,4 @@ pub enum EngineCommand {
ForceProfile(QualityProfile),
/// Stop the call and shut down the engine.
Stop,
/// Place a direct call to a fingerprint (requires signal connection).
PlaceCall { target_fingerprint: String },
/// Answer an incoming direct call.
AnswerCall {
call_id: String,
accept_mode: wzp_proto::CallAcceptMode,
},
/// Reject an incoming direct call.
RejectCall { call_id: String },
}

773
crates/wzp-android/src/engine.rs
View File

File diff suppressed because it is too large Load Diff

234
crates/wzp-android/src/jni_bridge.rs
View File

@@ -21,24 +21,11 @@ unsafe fn handle_ref(handle: jlong) -> &'static mut EngineHandle {
unsafe { &mut *(handle as *mut EngineHandle) }
}
/// 7 = auto (use relay's chosen profile)
const PROFILE_AUTO: jint = 7;
fn profile_from_int(value: jint) -> QualityProfile {
match value {
0 => QualityProfile::GOOD, // Opus 24k
1 => QualityProfile::DEGRADED, // Opus 6k
2 => QualityProfile::CATASTROPHIC, // Codec2 1.2k
3 => QualityProfile { // Codec2 3.2k
codec: wzp_proto::CodecId::Codec2_3200,
fec_ratio: 0.5,
frame_duration_ms: 20,
frames_per_block: 5,
},
4 => QualityProfile::STUDIO_32K, // Opus 32k
5 => QualityProfile::STUDIO_48K, // Opus 48k
6 => QualityProfile::STUDIO_64K, // Opus 64k
_ => QualityProfile::GOOD, // auto falls back to GOOD
1 => QualityProfile::DEGRADED,
2 => QualityProfile::CATASTROPHIC,
_ => QualityProfile::GOOD,
}
}
@@ -48,25 +35,11 @@ static INIT_LOGGING: Once = Once::new();
/// Safe to call multiple times — only the first call takes effect.
fn init_logging() {
INIT_LOGGING.call_once(|| {
// Wrap in catch_unwind — sharded_slab allocation inside
// tracing_subscriber::registry() can crash on some Android
// devices if scudo malloc fails during early initialization.
let _ = std::panic::catch_unwind(|| {
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;
use tracing_subscriber::EnvFilter;
if let Ok(layer) = tracing_android::layer("wzp_android") {
// Filter: INFO for our crates, WARN for everything else.
// The jni crate emits VERBOSE logs for every method lookup
// (~10 lines per JNI call, 100+ calls/sec) which floods logcat
// and causes the system to kill the app.
let filter = EnvFilter::new("warn,wzp_android=info,wzp_proto=info,wzp_transport=info,wzp_codec=info,wzp_fec=info,wzp_crypto=info");
let _ = tracing_subscriber::registry()
.with(layer)
.with(filter)
.try_init();
}
});
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;
if let Ok(layer) = tracing_android::layer("wzp_android") {
let _ = tracing_subscriber::registry().with(layer).try_init();
}
});
}
@@ -98,7 +71,6 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartCall(
seed_hex_j: JString,
token_j: JString,
alias_j: JString,
profile_j: jint,
) -> jint {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let relay_addr: String = env.get_string(&relay_addr_j).map(|s| s.into()).unwrap_or_default();
@@ -124,8 +96,7 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartCall(
}
let config = CallStartConfig {
profile: profile_from_int(profile_j),
auto_profile: profile_j == PROFILE_AUTO,
profile: QualityProfile::GOOD,
relay_addr,
room,
auth_token: if token.is_empty() { Vec::new() } else { token.into_bytes() },
@@ -222,29 +193,6 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeForceProfile(
}));
}
/// Signal a network transport change from the Android ConnectivityManager.
///
/// `network_type` matches the Rust `NetworkContext` enum:
/// 0=WiFi, 1=CellularLte, 2=Cellular5g, 3=Cellular3g, 4=Unknown, 5=None
///
/// The engine forwards this to the `AdaptiveQualityController` which:
/// - Preemptively downgrades one tier on WiFi→cellular
/// - Activates a 10-second FEC boost
/// - Uses faster downgrade thresholds on cellular
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeOnNetworkChanged(
_env: JNIEnv,
_class: JClass,
handle: jlong,
network_type: jint,
bandwidth_kbps: jint,
) {
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
h.engine.on_network_changed(network_type as u8, bandwidth_kbps as u32);
}));
}
/// Write captured PCM samples from Kotlin AudioRecord into the engine's capture ring.
/// pcm is a Java short[] array.
#[unsafe(no_mangle)]
@@ -261,6 +209,7 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeWriteAudio(
return 0;
}
let mut buf = vec![0i16; len];
// GetShortArrayRegion copies Java array into our buffer
if env.get_short_array_region(&pcm, 0, &mut buf).is_err() {
return 0;
}
@@ -294,56 +243,6 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeReadAudio(
result.unwrap_or(0)
}
/// Write captured PCM from a DirectByteBuffer — zero JNI array copies.
/// The ByteBuffer must contain little-endian i16 samples.
/// Called from the AudioRecord capture thread.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeWriteAudioDirect(
env: JNIEnv,
_class: JClass,
handle: jlong,
buffer: jni::objects::JByteBuffer,
sample_count: jint,
) -> jint {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let ptr = env.get_direct_buffer_address(&buffer).unwrap_or(std::ptr::null_mut());
if ptr.is_null() || sample_count <= 0 {
return 0;
}
let samples = unsafe {
std::slice::from_raw_parts(ptr as *const i16, sample_count as usize)
};
h.engine.write_audio(samples) as jint
}));
result.unwrap_or(0)
}
/// Read decoded PCM into a DirectByteBuffer — zero JNI array copies.
/// The ByteBuffer will be filled with little-endian i16 samples.
/// Called from the AudioTrack playout thread.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeReadAudioDirect(
env: JNIEnv,
_class: JClass,
handle: jlong,
buffer: jni::objects::JByteBuffer,
max_samples: jint,
) -> jint {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let ptr = env.get_direct_buffer_address(&buffer).unwrap_or(std::ptr::null_mut());
if ptr.is_null() || max_samples <= 0 {
return 0;
}
let samples = unsafe {
std::slice::from_raw_parts_mut(ptr as *mut i16, max_samples as usize)
};
h.engine.read_audio(samples) as jint
}));
result.unwrap_or(0)
}
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeDestroy(
_env: JNIEnv,
@@ -355,116 +254,3 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeDestroy(
drop(h);
}));
}
/// Ping a relay server — instance method, requires engine handle.
/// Returns JSON `{"rtt_ms":N,"server_fingerprint":"hex"}` or null on failure.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativePingRelay<'a>(
mut env: JNIEnv<'a>,
_class: JClass,
handle: jlong,
relay_j: JString,
) -> jstring {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let relay: String = env.get_string(&relay_j).map(|s| s.into()).unwrap_or_default();
match h.engine.ping_relay(&relay) {
Ok(json) => Some(json),
Err(_) => None,
}
}));
let json = match result {
Ok(Some(s)) => s,
_ => return JObject::null().into_raw(),
};
env.new_string(&json)
.map(|s| s.into_raw())
.unwrap_or(JObject::null().into_raw())
}
// ── Direct calling JNI functions ──
/// Start persistent signaling connection to relay for direct calls.
/// Returns 0 on success, -1 on error.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartSignaling<'a>(
mut env: JNIEnv<'a>,
_class: JClass,
handle: jlong,
relay_addr_j: JString,
seed_hex_j: JString,
token_j: JString,
alias_j: JString,
) -> jint {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let relay_addr: String = env.get_string(&relay_addr_j).map(|s| s.into()).unwrap_or_default();
let seed_hex: String = env.get_string(&seed_hex_j).map(|s| s.into()).unwrap_or_default();
let token: String = env.get_string(&token_j).map(|s| s.into()).unwrap_or_default();
let alias: String = env.get_string(&alias_j).map(|s| s.into()).unwrap_or_default();
h.engine.start_signaling(
&relay_addr,
&seed_hex,
if token.is_empty() { None } else { Some(&token) },
if alias.is_empty() { None } else { Some(&alias) },
)
}));
match result {
Ok(Ok(())) => 0,
Ok(Err(e)) => { error!("start_signaling failed: {e}"); -1 }
Err(_) => { error!("start_signaling panicked"); -1 }
}
}
/// Place a direct call to a target fingerprint.
/// Returns 0 on success, -1 on error.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativePlaceCall<'a>(
mut env: JNIEnv<'a>,
_class: JClass,
handle: jlong,
target_fp_j: JString,
) -> jint {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let target: String = env.get_string(&target_fp_j).map(|s| s.into()).unwrap_or_default();
h.engine.place_call(&target)
}));
match result {
Ok(Ok(())) => 0,
Ok(Err(e)) => { error!("place_call failed: {e}"); -1 }
Err(_) => { error!("place_call panicked"); -1 }
}
}
/// Answer an incoming direct call.
/// mode: 0=Reject, 1=AcceptTrusted, 2=AcceptGeneric
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeAnswerCall<'a>(
mut env: JNIEnv<'a>,
_class: JClass,
handle: jlong,
call_id_j: JString,
mode: jint,
) -> jint {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let call_id: String = env.get_string(&call_id_j).map(|s| s.into()).unwrap_or_default();
let accept_mode = match mode {
0 => wzp_proto::CallAcceptMode::Reject,
1 => wzp_proto::CallAcceptMode::AcceptTrusted,
_ => wzp_proto::CallAcceptMode::AcceptGeneric,
};
h.engine.answer_call(&call_id, accept_mode)
}));
match result {
Ok(Ok(())) => 0,
Ok(Err(e)) => { error!("answer_call failed: {e}"); -1 }
Err(_) => { error!("answer_call panicked"); -1 }
}
}

13
crates/wzp-android/src/lib.rs
View File

@@ -8,19 +8,6 @@
//!
//! On non-Android targets, the Oboe C++ layer compiles as a stub,
//! allowing `cargo check` and unit tests on the host.
//!
//! ## Status
//!
//! **Dead code as of the Tauri mobile rewrite.** The legacy Kotlin+JNI
//! Android app that consumed this crate was replaced by a Tauri 2.x
//! Mobile app (see `desktop/src-tauri/src/engine.rs` for the live
//! Android audio recv path and `crates/wzp-native/` for the Oboe
//! bridge). We keep this crate in the workspace for reference and to
//! preserve the commit history, but it is not built by any shipping
//! target. Allow the accumulated leftover warnings so CI/workspace
//! checks stay clean — any real cleanup should happen as part of
//! removing the crate entirely, not piecemeal.
#![allow(dead_code, unused_imports, unused_variables, unused_mut)]
pub mod audio_android;
pub mod audio_ring;

44
crates/wzp-android/src/stats.rs
View File

@@ -11,12 +11,6 @@ pub enum CallState {
Active,
Reconnecting,
Closed,
/// Connected to relay signal channel, registered for direct calls.
Registered,
/// Outgoing call ringing on callee's side.
Ringing,
/// Incoming call received, waiting for user to accept/reject.
IncomingCall,
}
impl serde::Serialize for CallState {
@@ -27,9 +21,6 @@ impl serde::Serialize for CallState {
CallState::Active => 2,
CallState::Reconnecting => 3,
CallState::Closed => 4,
CallState::Registered => 5,
CallState::Ringing => 6,
CallState::IncomingCall => 7,
};
serializer.serialize_u8(n)
}
@@ -58,46 +49,14 @@ pub struct CallStats {
pub frames_decoded: u64,
/// Number of playout underruns (buffer empty when audio needed).
pub underruns: u64,
/// Frames recovered by RaptorQ FEC (Codec2 tiers only; Opus bypasses
/// RaptorQ per Phase 2).
/// Frames recovered by FEC.
pub fec_recovered: u64,
/// Phase 3c: Opus frames reconstructed via DRED side-channel data.
/// Only increments on the Opus tiers; always zero for Codec2.
pub dred_reconstructions: u64,
/// Phase 3c: Opus frames filled via classical Opus PLC because no DRED
/// state covered the gap, plus any decode-error fallbacks. Codec2 loss
/// also increments this counter via the Codec2 PLC path.
pub classical_plc_invocations: u64,
/// Playout ring overflow count (reader was lapped by writer).
pub playout_overflows: u64,
/// Playout ring underrun count (reader found empty buffer).
pub playout_underruns: u64,
/// Capture ring overflow count.
pub capture_overflows: u64,
/// Current mic audio level (RMS of i16 samples, 0-32767).
pub audio_level: u32,
/// Our current outgoing codec name (e.g. "Opus24k", "Codec2_1200").
pub current_codec: String,
/// Last seen incoming codec from other participants.
pub peer_codec: String,
/// Whether auto quality mode is active.
pub auto_mode: bool,
/// Number of participants in the room (from last RoomUpdate).
pub room_participant_count: u32,
/// Participant list (fingerprint + optional alias) serialized as JSON array.
pub room_participants: Vec<RoomMember>,
/// SAS code for verbal verification (None if not in a call).
#[serde(skip_serializing_if = "Option::is_none")]
pub sas_code: Option<u32>,
/// Incoming call info (present when state == IncomingCall).
#[serde(skip_serializing_if = "Option::is_none")]
pub incoming_call_id: Option<String>,
/// Fingerprint of the caller (present when state == IncomingCall).
#[serde(skip_serializing_if = "Option::is_none")]
pub incoming_caller_fp: Option<String>,
/// Alias of the caller (present when state == IncomingCall).
#[serde(skip_serializing_if = "Option::is_none")]
pub incoming_caller_alias: Option<String>,
}
/// A room member entry, serialized into the stats JSON.
@@ -105,5 +64,4 @@ pub struct CallStats {
pub struct RoomMember {
pub fingerprint: String,
pub alias: Option<String>,
pub relay_label: Option<String>,
}

77
crates/wzp-client/Cargo.toml
View File

@@ -21,93 +21,20 @@ anyhow = "1"
serde = { workspace = true }
serde_json = "1"
chrono = "0.4"
clap = { version = "4", features = ["derive"] }
ratatui = "0.29"
crossterm = "0.28"
rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
cpal = { version = "0.15", optional = true }
libc = "0.2"
# Phase 5.5 — LAN host-candidate ICE: enumerate local network
# interface addresses for inclusion in DirectCallOffer/Answer so
# peers on the same LAN can direct-connect without NAT hairpinning
# through the WAN reflex addr (which many consumer NATs, including
# MikroTik's default masquerade, don't support).
if-addrs = "0.13"
rand = { workspace = true }
socket2 = "0.5"
# coreaudio-rs is Apple-framework-only; gate it to macOS so enabling
# the `vpio` feature from a non-macOS target builds cleanly instead of
# pulling in a crate that can only link against Apple frameworks.
[target.'cfg(target_os = "macos")'.dependencies]
coreaudio-rs = { version = "0.11", optional = true }
# Windows-only: direct WASAPI bindings for the `windows-aec` feature.
# `windows` is Microsoft's official Rust COM bindings crate. We pull in
# only the audio + COM subfeatures we need — the crate is organized as
# a massive optional-feature tree, so enabling just these keeps compile
# times reasonable (~5s for these features vs ~60s for the full crate).
[target.'cfg(target_os = "windows")'.dependencies]
windows = { version = "0.58", optional = true, features = [
"Win32_Foundation",
"Win32_Media_Audio",
"Win32_Security",
"Win32_System_Com",
"Win32_System_Com_StructuredStorage",
"Win32_System_Threading",
"Win32_System_Variant",
] }
# Linux-only: WebRTC AEC (Audio Processing Module) bindings for the
# `linux-aec` feature. This is the 0.3.x line of the `tonarino/
# webrtc-audio-processing` crate, which links against Debian's
# `libwebrtc-audio-processing-dev` apt package (0.3-1+b1 on Bookworm).
#
# Note: we attempted the 2.x line with its `bundled` sub-feature first
# (which would give us AEC3 instead of AEC2), but both the crates.io
# tarball AND the upstream git `main` branch of webrtc-audio-processing-sys
# 2.0.3 hit a `meson setup --reconfigure` bug where the build.rs passes
# --reconfigure unconditionally even on first-run empty build dirs,
# causing the bundled build to fail with "Directory does not contain a
# valid build tree". The 0.x line doesn't use bundled mode and sidesteps
# this entirely by linking the apt-provided library. AEC2 is older than
# AEC3 but still the same algorithm family — this is what PulseAudio's
# module-echo-cancel and PipeWire's filter-chain use by default on
# current Debian-family distros.
[target.'cfg(target_os = "linux")'.dependencies]
webrtc-audio-processing = { version = "0.3", optional = true }
libc = "0.2"
[features]
default = []
audio = ["cpal"]
# vpio enables coreaudio-rs but that dep is itself gated to macOS above,
# so enabling this feature on Windows/Linux is a no-op (the audio_vpio
# module is also #[cfg(target_os = "macos")] in lib.rs).
vpio = ["dep:coreaudio-rs"]
# windows-aec enables a direct WASAPI capture backend that opens the
# microphone under AudioCategory_Communications, turning on Windows's
# OS-level communications audio processing (AEC + noise suppression +
# AGC). The `windows` dep is itself target-gated to Windows above, so
# enabling this feature on non-Windows targets is a no-op (the
# audio_wasapi module is also #[cfg(target_os = "windows")] in lib.rs).
windows-aec = ["dep:windows"]
# linux-aec enables a CPAL + WebRTC AEC3 capture/playback backend that
# runs the WebRTC Audio Processing Module (same algo as Chrome / Zoom /
# Teams) in-process, using the playback PCM as the reference signal for
# echo cancellation. The webrtc-audio-processing dep is target-gated to
# Linux above, so enabling this feature on non-Linux targets is a no-op
# (the audio_linux_aec module is also #[cfg(target_os = "linux")] in
# lib.rs).
linux-aec = ["dep:webrtc-audio-processing"]
vpio = ["coreaudio-rs"]
[[bin]]
name = "wzp-client"
path = "src/cli.rs"
[[bin]]
name = "wzp-analyzer"
path = "src/analyzer.rs"
[[bin]]
name = "wzp-bench"
path = "src/bench_cli.rs"

952
crates/wzp-client/src/analyzer.rs
View File

@@ -1,952 +0,0 @@
//! WarzonePhone Protocol Analyzer — passive call quality observer.
//!
//! Joins a relay room as a passive participant (no media sent) and displays
//! real-time per-participant quality metrics in a terminal UI.
//!
//! Usage:
//! wzp-analyzer 127.0.0.1:4433 --room test
//! wzp-analyzer 1.2.3.4:4433 --room test --capture session.wzp
//! wzp-analyzer 1.2.3.4:4433 --room test --no-tui --duration 60
use std::io::Write;
use std::sync::Arc;
use std::time::{Duration, Instant};
use clap::Parser;
use tracing::info;
use wzp_proto::{CodecId, MediaPacket, MediaTransport};
// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------
/// WarzonePhone Protocol Analyzer — passive call quality observer
#[derive(Parser)]
#[command(name = "wzp-analyzer", version)]
struct Args {
/// Relay address (host:port) — required for live mode, ignored with --replay
relay: Option<String>,
/// Room name to observe — required for live mode, ignored with --replay
#[arg(short, long)]
room: Option<String>,
/// Auth token for relay
#[arg(long)]
token: Option<String>,
/// Identity seed (64-char hex)
#[arg(long)]
seed: Option<String>,
/// Capture packets to file
#[arg(long)]
capture: Option<String>,
/// Auto-stop after N seconds
#[arg(long)]
duration: Option<u64>,
/// Disable TUI (print stats to stdout instead)
#[arg(long)]
no_tui: bool,
/// Replay a captured .wzp file (offline analysis)
#[arg(long)]
replay: Option<String>,
/// Generate HTML report (from live session or replay)
#[arg(long)]
html: Option<String>,
/// Session key hex for decrypting payloads (enables audio decode)
// TODO(#17): Audio decode requires session key + nonce context.
// In SFU mode, payloads are E2E encrypted. Decoding requires
// either: (a) session key from both endpoints, or (b) running
// the analyzer as a trusted participant with its own key exchange.
// For now, header-only analysis provides loss%, jitter, codec stats.
#[arg(long)]
key: Option<String>,
}
// ---------------------------------------------------------------------------
// Per-participant statistics
// ---------------------------------------------------------------------------
struct ParticipantStats {
/// Stream identifier (index, assigned when we detect a new seq stream)
stream_id: usize,
/// Display name from RoomUpdate (if available)
alias: Option<String>,
/// Current codec
codec: CodecId,
/// Total packets received
packets: u64,
/// Detected lost packets (sequence gaps)
lost: u64,
/// Last seen sequence number
last_seq: u16,
/// Whether we've seen the first packet (for gap detection)
seq_initialized: bool,
/// EWMA jitter in ms
jitter_ms: f64,
/// Last packet arrival time
last_arrival: Option<Instant>,
/// Codec changes observed
codec_switches: u32,
/// First packet time
first_seen: Instant,
/// Last packet time
last_seen: Instant,
}
impl ParticipantStats {
fn new(id: usize, codec: CodecId) -> Self {
let now = Instant::now();
Self {
stream_id: id,
alias: None,
codec,
packets: 0,
lost: 0,
last_seq: 0,
seq_initialized: false,
jitter_ms: 0.0,
last_arrival: None,
codec_switches: 0,
first_seen: now,
last_seen: now,
}
}
fn ingest(&mut self, pkt: &MediaPacket, now: Instant) {
self.packets += 1;
self.last_seen = now;
// Codec switch detection
if pkt.header.codec_id != self.codec {
self.codec_switches += 1;
self.codec = pkt.header.codec_id;
}
// Loss detection from sequence gaps
if self.seq_initialized {
let expected = self.last_seq.wrapping_add(1);
let gap = pkt.header.seq.wrapping_sub(expected);
if gap > 0 && gap < 100 {
self.lost += gap as u64;
}
}
self.last_seq = pkt.header.seq;
self.seq_initialized = true;
// Jitter (inter-arrival time variance, EWMA)
if let Some(last) = self.last_arrival {
let interval_ms = now.duration_since(last).as_secs_f64() * 1000.0;
let expected_ms = pkt.header.codec_id.frame_duration_ms() as f64;
let diff = (interval_ms - expected_ms).abs();
self.jitter_ms = 0.1 * diff + 0.9 * self.jitter_ms;
}
self.last_arrival = Some(now);
}
fn loss_percent(&self) -> f64 {
let total = self.packets + self.lost;
if total == 0 {
0.0
} else {
(self.lost as f64 / total as f64) * 100.0
}
}
fn duration(&self) -> Duration {
self.last_seen.duration_since(self.first_seen)
}
fn display_name(&self) -> String {
self.alias
.as_deref()
.map(String::from)
.unwrap_or_else(|| format!("Stream {}", self.stream_id))
}
}
// ---------------------------------------------------------------------------
// Participant identification by sequence stream
// ---------------------------------------------------------------------------
/// Find the participant whose sequence counter is close to `seq`, or create a
/// new one. Each sender has an independent wrapping u16 counter, so we can
/// distinguish streams by proximity of consecutive sequence numbers.
fn find_or_create_participant(
participants: &mut Vec<ParticipantStats>,
seq: u16,
codec: CodecId,
) -> usize {
for (i, p) in participants.iter().enumerate() {
if p.seq_initialized {
let delta = seq.wrapping_sub(p.last_seq);
if delta > 0 && delta < 50 {
return i;
}
}
}
// New stream detected
let id = participants.len();
participants.push(ParticipantStats::new(id, codec));
id
}
// ---------------------------------------------------------------------------
// Capture writer (binary packet log for later replay)
// ---------------------------------------------------------------------------
struct CaptureWriter {
file: std::io::BufWriter<std::fs::File>,
start: Instant,
}
impl CaptureWriter {
fn new(path: &str, room: &str, relay: &str) -> anyhow::Result<Self> {
let file = std::fs::File::create(path)?;
let mut writer = std::io::BufWriter::new(file);
// Magic + version
writer.write_all(b"WZP\x01")?;
let header = serde_json::json!({
"room": room,
"relay": relay,
"start_time": chrono::Utc::now().to_rfc3339(),
"version": 1,
});
let header_bytes = serde_json::to_vec(&header)?;
writer.write_all(&(header_bytes.len() as u32).to_le_bytes())?;
writer.write_all(&header_bytes)?;
Ok(Self {
file: writer,
start: Instant::now(),
})
}
fn write_packet(&mut self, pkt: &MediaPacket, now: Instant) -> anyhow::Result<()> {
let elapsed_us = now.duration_since(self.start).as_micros() as u64;
self.file.write_all(&elapsed_us.to_le_bytes())?;
let raw = pkt.to_bytes();
self.file.write_all(&(raw.len() as u32).to_le_bytes())?;
self.file.write_all(&raw)?;
Ok(())
}
}
// ---------------------------------------------------------------------------
// Capture reader (for replay mode)
// ---------------------------------------------------------------------------
struct CaptureReader {
reader: std::io::BufReader<std::fs::File>,
header: serde_json::Value,
}
impl CaptureReader {
fn open(path: &str) -> anyhow::Result<Self> {
use std::io::Read;
let file = std::fs::File::open(path)?;
let mut reader = std::io::BufReader::new(file);
// Read magic
let mut magic = [0u8; 4];
reader.read_exact(&mut magic)?;
anyhow::ensure!(&magic == b"WZP\x01", "not a WZP capture file");
// Read header
let mut len_buf = [0u8; 4];
reader.read_exact(&mut len_buf)?;
let header_len = u32::from_le_bytes(len_buf) as usize;
let mut header_bytes = vec![0u8; header_len];
reader.read_exact(&mut header_bytes)?;
let header: serde_json::Value = serde_json::from_slice(&header_bytes)?;
Ok(Self { reader, header })
}
fn next_packet(&mut self) -> anyhow::Result<Option<(u64, MediaPacket)>> {
use std::io::Read;
// Read timestamp
let mut ts_buf = [0u8; 8];
match self.reader.read_exact(&mut ts_buf) {
Ok(()) => {}
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
Err(e) => return Err(e.into()),
}
let timestamp_us = u64::from_le_bytes(ts_buf);
// Read packet
let mut len_buf = [0u8; 4];
self.reader.read_exact(&mut len_buf)?;
let pkt_len = u32::from_le_bytes(len_buf) as usize;
let mut pkt_bytes = vec![0u8; pkt_len];
self.reader.read_exact(&mut pkt_bytes)?;
let pkt = MediaPacket::from_bytes(bytes::Bytes::from(pkt_bytes))
.ok_or_else(|| anyhow::anyhow!("malformed packet in capture"))?;
Ok(Some((timestamp_us, pkt)))
}
}
// ---------------------------------------------------------------------------
// Timeline entry (for HTML report generation)
// ---------------------------------------------------------------------------
struct TimelineEntry {
timestamp_us: u64,
stream_id: usize,
#[allow(dead_code)]
codec: CodecId,
#[allow(dead_code)]
seq: u16,
#[allow(dead_code)]
payload_len: usize,
loss_pct: f64,
jitter_ms: f64,
}
// ---------------------------------------------------------------------------
// Replay mode (#15)
// ---------------------------------------------------------------------------
async fn run_replay(path: &str, args: &Args) -> anyhow::Result<()> {
let mut reader = CaptureReader::open(path)?;
eprintln!(
"Replaying: {} (room: {})",
path,
reader
.header
.get("room")
.and_then(|v| v.as_str())
.unwrap_or("?")
);
let mut participants: Vec<ParticipantStats> = Vec::new();
let mut total_packets: u64 = 0;
let start = Instant::now();
let mut timeline: Vec<TimelineEntry> = Vec::new();
// Decrypt session from --key (optional)
let mut decrypt_session: Option<wzp_crypto::ChaChaSession> = args.key.as_ref().and_then(|hex| {
if hex.len() != 64 { return None; }
let mut key = [0u8; 32];
for (i, chunk) in hex.as_bytes().chunks(2).enumerate() {
let s = std::str::from_utf8(chunk).unwrap_or("00");
key[i] = u8::from_str_radix(s, 16).unwrap_or(0);
}
Some(wzp_crypto::ChaChaSession::new(key))
});
let mut decrypt_ok: u64 = 0;
let mut decrypt_fail: u64 = 0;
while let Some((ts_us, pkt)) = reader.next_packet()? {
let now = Instant::now();
let idx = find_or_create_participant(&mut participants, pkt.header.seq, pkt.header.codec_id);
participants[idx].ingest(&pkt, now);
total_packets += 1;
// Attempt decryption if key provided
if let Some(ref mut session) = decrypt_session {
use wzp_proto::CryptoSession;
let header_bytes = pkt.header.to_bytes();
let mut plaintext = Vec::new();
match session.decrypt(&header_bytes, &pkt.payload, &mut plaintext) {
Ok(()) => {
decrypt_ok += 1;
if decrypt_ok <= 5 || decrypt_ok % 100 == 0 {
eprintln!(
" decrypt ok: seq={} codec={:?} payload={}B → plaintext={}B",
pkt.header.seq, pkt.header.codec_id,
pkt.payload.len(), plaintext.len()
);
}
}
Err(_) => {
decrypt_fail += 1;
if decrypt_fail <= 3 {
eprintln!(
" decrypt FAIL: seq={} (key mismatch, wrong direction, or rekey boundary)",
pkt.header.seq
);
}
}
}
}
// Record for HTML timeline
timeline.push(TimelineEntry {
timestamp_us: ts_us,
stream_id: idx,
codec: pkt.header.codec_id,
seq: pkt.header.seq,
payload_len: pkt.payload.len(),
loss_pct: participants[idx].loss_percent(),
jitter_ms: participants[idx].jitter_ms,
});
}
if decrypt_session.is_some() {
eprintln!(
"Decrypt stats: {} ok, {} failed (total {})",
decrypt_ok, decrypt_fail, total_packets
);
}
print_summary(&participants, total_packets, start.elapsed());
// Generate HTML if requested
if let Some(html_path) = &args.html {
generate_html_report(html_path, &participants, &timeline, total_packets, &reader.header)?;
eprintln!("HTML report: {}", html_path);
}
Ok(())
}
// ---------------------------------------------------------------------------
// HTML report generation (#16)
// ---------------------------------------------------------------------------
fn generate_html_report(
path: &str,
participants: &[ParticipantStats],
timeline: &[TimelineEntry],
total_packets: u64,
capture_header: &serde_json::Value,
) -> anyhow::Result<()> {
use std::io::Write as _;
let mut f = std::fs::File::create(path)?;
let room = capture_header
.get("room")
.and_then(|v| v.as_str())
.unwrap_or("unknown");
let start_time = capture_header
.get("start_time")
.and_then(|v| v.as_str())
.unwrap_or("?");
// Build per-stream loss/jitter timeline data for Chart.js
// Sample every 1 second (group timeline entries by second)
let max_ts = timeline.last().map(|e| e.timestamp_us).unwrap_or(0);
let duration_secs = (max_ts / 1_000_000) + 1;
let mut loss_data: std::collections::HashMap<usize, Vec<f64>> =
std::collections::HashMap::new();
let mut jitter_data: std::collections::HashMap<usize, Vec<f64>> =
std::collections::HashMap::new();
for stream_id in 0..participants.len() {
loss_data.insert(stream_id, vec![0.0; duration_secs as usize]);
jitter_data.insert(stream_id, vec![0.0; duration_secs as usize]);
}
for entry in timeline {
let sec = (entry.timestamp_us / 1_000_000) as usize;
if sec < duration_secs as usize {
if let Some(losses) = loss_data.get_mut(&entry.stream_id) {
losses[sec] = entry.loss_pct;
}
if let Some(jitters) = jitter_data.get_mut(&entry.stream_id) {
jitters[sec] = entry.jitter_ms;
}
}
}
let colors = [
"#e74c3c", "#3498db", "#2ecc71", "#f39c12", "#9b59b6", "#1abc9c",
];
// Build dataset JSON for charts
let mut loss_datasets = String::new();
let mut jitter_datasets = String::new();
for (i, p) in participants.iter().enumerate() {
let name = p.display_name();
let color = colors[i % colors.len()];
let loss_vals = loss_data
.get(&i)
.map(|v| format!("{:?}", v))
.unwrap_or_default();
let jitter_vals = jitter_data
.get(&i)
.map(|v| format!("{:?}", v))
.unwrap_or_default();
loss_datasets.push_str(&format!(
"{{ label: '{}', data: {}, borderColor: '{}', fill: false }},\n",
name, loss_vals, color
));
jitter_datasets.push_str(&format!(
"{{ label: '{}', data: {}, borderColor: '{}', fill: false }},\n",
name, jitter_vals, color
));
}
let labels: Vec<String> = (0..duration_secs).map(|s| format!("{}s", s)).collect();
let labels_json = format!("{:?}", labels);
// Summary table rows
let mut summary_rows = String::new();
for p in participants {
summary_rows.push_str(&format!(
"<tr><td>{}</td><td>{:?}</td><td>{}</td><td>{:.1}%</td><td>{:.0}ms</td><td>{}</td></tr>\n",
p.display_name(),
p.codec,
p.packets,
p.loss_percent(),
p.jitter_ms,
p.codec_switches
));
}
write!(
f,
r#"<!DOCTYPE html>
<html><head>
<meta charset="utf-8">
<title>WZP Call Report — {room}</title>
<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
<style>
body {{ font-family: -apple-system, sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; background: #1a1a2e; color: #e0e0e0; }}
h1,h2 {{ color: #4a9eff; }}
table {{ border-collapse: collapse; width: 100%; margin: 20px 0; }}
th,td {{ border: 1px solid #333; padding: 8px 12px; text-align: left; }}
th {{ background: #16213e; }}
tr:nth-child(even) {{ background: #1a1a3e; }}
.chart-container {{ background: #16213e; border-radius: 8px; padding: 16px; margin: 20px 0; }}
canvas {{ max-height: 300px; }}
.meta {{ color: #888; font-size: 0.9em; }}
</style>
</head><body>
<h1>WZP Call Quality Report</h1>
<p class="meta">Room: <b>{room}</b> | Start: {start_time} | Packets: {total_packets} | Duration: {duration_secs}s</p>
<h2>Participant Summary</h2>
<table>
<tr><th>Name</th><th>Codec</th><th>Packets</th><th>Loss</th><th>Jitter</th><th>Codec Switches</th></tr>
{summary_rows}
</table>
<h2>Packet Loss Over Time</h2>
<div class="chart-container"><canvas id="lossChart"></canvas></div>
<h2>Jitter Over Time</h2>
<div class="chart-container"><canvas id="jitterChart"></canvas></div>
<script>
const labels = {labels_json};
new Chart(document.getElementById('lossChart'), {{
type: 'line',
data: {{ labels, datasets: [{loss_datasets}] }},
options: {{ responsive: true, scales: {{ y: {{ beginAtZero: true, title: {{ display: true, text: 'Loss %' }} }} }} }}
}});
new Chart(document.getElementById('jitterChart'), {{
type: 'line',
data: {{ labels, datasets: [{jitter_datasets}] }},
options: {{ responsive: true, scales: {{ y: {{ beginAtZero: true, title: {{ display: true, text: 'Jitter (ms)' }} }} }} }}
}});
</script>
</body></html>"#
)?;
Ok(())
}
// ---------------------------------------------------------------------------
// No-TUI mode (print stats to stdout periodically)
// ---------------------------------------------------------------------------
async fn run_no_tui(
transport: &wzp_transport::QuinnTransport,
participants: &mut Vec<ParticipantStats>,
total_packets: &mut u64,
deadline: Option<Instant>,
mut capture_writer: Option<&mut CaptureWriter>,
) -> anyhow::Result<()> {
let mut print_timer = Instant::now();
loop {
if let Some(dl) = deadline {
if Instant::now() > dl {
break;
}
}
match tokio::time::timeout(Duration::from_millis(100), transport.recv_media()).await {
Ok(Ok(Some(pkt))) => {
let now = Instant::now();
let idx =
find_or_create_participant(participants, pkt.header.seq, pkt.header.codec_id);
participants[idx].ingest(&pkt, now);
*total_packets += 1;
if let Some(ref mut w) = capture_writer {
w.write_packet(&pkt, now)?;
}
}
Ok(Ok(None)) => break, // connection closed
Ok(Err(e)) => {
tracing::warn!("recv error: {e}");
break;
}
Err(_) => {} // timeout, loop again
}
if print_timer.elapsed() >= Duration::from_secs(2) {
print_stats(participants, *total_packets);
print_timer = Instant::now();
}
}
Ok(())
}
fn print_stats(participants: &[ParticipantStats], total: u64) {
eprintln!("--- {} participants | {} total packets ---", participants.len(), total);
for p in participants {
eprintln!(
" {}: {} pkts, {:.1}% loss, {:.0}ms jitter, {:?}, {:.0}s",
p.display_name(),
p.packets,
p.loss_percent(),
p.jitter_ms,
p.codec,
p.duration().as_secs_f64(),
);
}
}
// ---------------------------------------------------------------------------
// TUI mode (ratatui + crossterm)
// ---------------------------------------------------------------------------
async fn run_tui(
transport: &wzp_transport::QuinnTransport,
participants: &mut Vec<ParticipantStats>,
total_packets: &mut u64,
start_time: Instant,
deadline: Option<Instant>,
mut capture_writer: Option<&mut CaptureWriter>,
) -> anyhow::Result<()> {
crossterm::terminal::enable_raw_mode()?;
let mut stdout = std::io::stdout();
crossterm::execute!(stdout, crossterm::terminal::EnterAlternateScreen)?;
let backend = ratatui::backend::CrosstermBackend::new(stdout);
let mut terminal = ratatui::Terminal::new(backend)?;
let mut redraw_timer = Instant::now();
let result: anyhow::Result<()> = async {
loop {
// Check for quit key (q or Ctrl+C)
if crossterm::event::poll(Duration::from_millis(0))? {
if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
use crossterm::event::{KeyCode, KeyModifiers};
if key.code == KeyCode::Char('q')
|| (key.code == KeyCode::Char('c')
&& key.modifiers.contains(KeyModifiers::CONTROL))
{
break;
}
}
}
if let Some(dl) = deadline {
if Instant::now() > dl {
break;
}
}
// Receive packets (non-blocking with short timeout)
match tokio::time::timeout(Duration::from_millis(20), transport.recv_media()).await {
Ok(Ok(Some(pkt))) => {
let now = Instant::now();
let idx = find_or_create_participant(
participants,
pkt.header.seq,
pkt.header.codec_id,
);
participants[idx].ingest(&pkt, now);
*total_packets += 1;
if let Some(ref mut w) = capture_writer {
w.write_packet(&pkt, now)?;
}
}
Ok(Ok(None)) => break,
Ok(Err(e)) => {
tracing::warn!("recv error: {e}");
break;
}
Err(_) => {}
}
// Redraw TUI at ~10 FPS
if redraw_timer.elapsed() >= Duration::from_millis(100) {
terminal.draw(|f| draw_ui(f, participants, *total_packets, start_time))?;
redraw_timer = Instant::now();
}
}
Ok(())
}
.await;
// Always restore terminal, even on error
crossterm::terminal::disable_raw_mode()?;
crossterm::execute!(
std::io::stdout(),
crossterm::terminal::LeaveAlternateScreen
)?;
result
}
fn draw_ui(
f: &mut ratatui::Frame,
participants: &[ParticipantStats],
total_packets: u64,
start_time: Instant,
) {
use ratatui::layout::{Constraint, Direction, Layout};
use ratatui::style::{Color, Modifier, Style};
use ratatui::widgets::{Block, Borders, Paragraph, Row, Table};
let elapsed = start_time.elapsed();
let elapsed_str = format!(
"{:02}:{:02}:{:02}",
elapsed.as_secs() / 3600,
(elapsed.as_secs() % 3600) / 60,
elapsed.as_secs() % 60
);
let chunks = Layout::default()
.direction(Direction::Vertical)
.constraints([
Constraint::Length(3), // header
Constraint::Min(5), // participant table
Constraint::Length(3), // footer
])
.split(f.area());
// Header
let header = Paragraph::new(format!(
" WZP Analyzer | {} participants | {} packets | {}",
participants.len(),
total_packets,
elapsed_str
))
.block(Block::default().borders(Borders::ALL).title(" Protocol Analyzer "));
f.render_widget(header, chunks[0]);
// Participant table
let header_row = Row::new(vec![
"#", "Name", "Codec", "Packets", "Loss%", "Jitter", "Switches", "Duration",
])
.style(Style::default().add_modifier(Modifier::BOLD));
let rows: Vec<Row> = participants
.iter()
.map(|p| {
let loss_color = if p.loss_percent() > 5.0 {
Color::Red
} else if p.loss_percent() > 1.0 {
Color::Yellow
} else {
Color::Green
};
Row::new(vec![
format!("{}", p.stream_id),
p.display_name(),
format!("{:?}", p.codec),
format!("{}", p.packets),
format!("{:.1}%", p.loss_percent()),
format!("{:.0}ms", p.jitter_ms),
format!("{}", p.codec_switches),
format!("{:.0}s", p.duration().as_secs_f64()),
])
.style(Style::default().fg(loss_color))
})
.collect();
let widths = [
Constraint::Length(3), // #
Constraint::Length(20), // Name
Constraint::Length(12), // Codec
Constraint::Length(10), // Packets
Constraint::Length(8), // Loss%
Constraint::Length(10), // Jitter
Constraint::Length(10), // Switches
Constraint::Length(10), // Duration
];
let table = Table::new(rows, widths)
.header(header_row)
.block(Block::default().borders(Borders::ALL).title(" Participants "));
f.render_widget(table, chunks[1]);
// Footer
let footer =
Paragraph::new(" Press 'q' to quit ").block(Block::default().borders(Borders::ALL));
f.render_widget(footer, chunks[2]);
}
// ---------------------------------------------------------------------------
// Summary (printed on exit)
// ---------------------------------------------------------------------------
fn print_summary(participants: &[ParticipantStats], total: u64, elapsed: Duration) {
eprintln!("\n=== Session Summary ===");
eprintln!(
"Duration: {:.1}s | Total packets: {} | Participants: {}",
elapsed.as_secs_f64(),
total,
participants.len()
);
for p in participants {
eprintln!(
" {}: {} pkts, {:.1}% loss, {:.0}ms jitter, {:?}, {} codec switches",
p.display_name(),
p.packets,
p.loss_percent(),
p.jitter_ms,
p.codec,
p.codec_switches,
);
}
}
// ---------------------------------------------------------------------------
// main
// ---------------------------------------------------------------------------
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let args = Args::parse();
// Only init tracing subscriber in no-tui mode (it would corrupt the TUI otherwise)
if args.no_tui || args.replay.is_some() {
tracing_subscriber::fmt().init();
}
let _crypto_session: Option<std::sync::Mutex<wzp_crypto::ChaChaSession>> =
if let Some(ref key_hex) = args.key {
if key_hex.len() != 64 {
eprintln!("Error: --key must be 64 hex characters (32 bytes). Got {} chars.", key_hex.len());
std::process::exit(1);
}
let mut key_bytes = [0u8; 32];
for (i, chunk) in key_hex.as_bytes().chunks(2).enumerate() {
let hex_str = std::str::from_utf8(chunk).unwrap_or("00");
key_bytes[i] = u8::from_str_radix(hex_str, 16).unwrap_or(0);
}
eprintln!("Encrypted payload decoding enabled (key loaded).");
Some(std::sync::Mutex::new(
wzp_crypto::ChaChaSession::new(key_bytes),
))
} else {
None
};
// Replay mode: offline analysis of a .wzp capture file
if let Some(ref replay_path) = args.replay {
return run_replay(replay_path, &args).await;
}
// Live mode requires relay and room
let relay = args
.relay
.as_deref()
.ok_or_else(|| anyhow::anyhow!("relay address required for live mode (use --replay for offline)"))?;
let room = args
.room
.as_deref()
.ok_or_else(|| anyhow::anyhow!("--room required for live mode (use --replay for offline)"))?;
// TLS crypto provider
let _ = rustls::crypto::ring::default_provider().install_default();
// Identity seed
let seed = match &args.seed {
Some(hex) => {
let s = wzp_crypto::Seed::from_hex(hex).map_err(|e| anyhow::anyhow!(e))?;
info!(fingerprint = %s.derive_identity().public_identity().fingerprint, "identity from --seed");
s
}
None => {
let s = wzp_crypto::Seed::generate();
info!(fingerprint = %s.derive_identity().public_identity().fingerprint, "generated ephemeral identity");
s
}
};
// Connect to relay
let relay_addr: std::net::SocketAddr = relay.parse()?;
let bind_addr: std::net::SocketAddr = if relay_addr.is_ipv6() {
"[::]:0".parse()?
} else {
"0.0.0.0:0".parse()?
};
let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
let client_config = wzp_transport::client_config();
let conn = wzp_transport::connect(&endpoint, relay_addr, room, client_config).await?;
let transport = Arc::new(wzp_transport::QuinnTransport::new(conn));
// Crypto handshake
let _crypto_session =
wzp_client::handshake::perform_handshake(&*transport, &seed.0, Some("analyzer")).await?;
// Auth if token provided
if let Some(ref token) = args.token {
let auth = wzp_proto::SignalMessage::AuthToken {
token: token.clone(),
};
transport.send_signal(&auth).await?;
}
// Capture file (optional)
let mut capture_writer = args
.capture
.as_ref()
.map(|path| CaptureWriter::new(path, room, relay))
.transpose()?;
// Duration timeout
let deadline = args
.duration
.map(|s| Instant::now() + Duration::from_secs(s));
// State
let mut participants: Vec<ParticipantStats> = Vec::new();
let mut total_packets: u64 = 0;
let start_time = Instant::now();
if args.no_tui {
run_no_tui(
&transport,
&mut participants,
&mut total_packets,
deadline,
capture_writer.as_mut(),
)
.await?;
} else {
run_tui(
&transport,
&mut participants,
&mut total_packets,
start_time,
deadline,
capture_writer.as_mut(),
)
.await?;
}
// Print summary
print_summary(&participants, total_packets, start_time.elapsed());
// Clean close
transport.close().await?;
Ok(())
}

537
crates/wzp-client/src/audio_linux_aec.rs
View File

@@ -1,537 +0,0 @@
//! Linux AEC backend: CPAL capture + playback wired through the WebRTC Audio
//! Processing Module (AEC3 + noise suppression + high-pass filter).
//!
//! This is the same algorithm used by Chrome WebRTC, Zoom, Teams, Jitsi, and
//! any other "serious" Linux VoIP app. It runs in-process — no dependency on
//! PulseAudio's module-echo-cancel or PipeWire's filter-chain, so it works
//! identically on ALSA / PulseAudio / PipeWire systems.
//!
//! ## Architecture
//!
//! A single module-level `Arc<Mutex<Processor>>` is shared between the
//! capture and playback paths. On each 20 ms frame (960 samples @ 48 kHz
//! mono):
//!
//! - **Playback path**: `LinuxAecPlayback::start` spawns the usual CPAL
//! output thread, but wraps each chunk in a call to
//! `Processor::process_render_frame` **before** handing it to CPAL. That
//! gives APM an authoritative reference of exactly what's going out to
//! the speakers (same approach Zoom/Teams/Jitsi use). The AEC then knows
//! what to cancel when it sees echo in the capture stream.
//!
//! - **Capture path**: `LinuxAecCapture::start` spawns the usual CPAL
//! input thread, and runs `Processor::process_capture_frame` on each
//! incoming mic chunk **in place** before pushing it into the ring
//! buffer. The AEC subtracts the echo using the render reference it
//! saw on the playback side.
//!
//! APM is strict about frame size: it requires exactly 10 ms = 480 samples
//! per call at 48 kHz. Our pipeline uses 20 ms = 960 samples, so each 20 ms
//! frame is split into two 480-sample halves, APM is called twice, and the
//! halves are stitched back together.
//!
//! APM only accepts f32 samples in `[-1.0, 1.0]`, so we convert i16 → f32
//! before the call and f32 → i16 after (with clamping on the return path).
//!
//! ## Stream delay
//!
//! AEC needs to know roughly how long it takes between a sample being passed
//! to `process_render_frame` and its echo showing up at `process_capture_frame`
//! — i.e. the round trip through CPAL playback → speaker → air → microphone
//! → CPAL capture. AEC3's internal estimator tracks this within a window
//! around whatever hint we give it. We hardcode 60 ms as a reasonable
//! starting point for typical Linux audio stacks; the delay estimator does
//! the fine-tuning automatically.
//!
//! ## Thread safety
//!
//! The 0.3.x line of `webrtc-audio-processing` takes `&mut self` on both
//! `process_capture_frame` and `process_render_frame`, so the `Processor`
//! needs a `Mutex` around it for cross-thread sharing. The capture and
//! playback threads each acquire the lock briefly (sub-millisecond per
//! 10 ms frame) so contention is minimal at our frame rates.
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use anyhow::{anyhow, Context};
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
use cpal::{SampleFormat, SampleRate, StreamConfig};
use tracing::{info, warn};
use webrtc_audio_processing::{
Config, EchoCancellation, EchoCancellationSuppressionLevel, InitializationConfig,
NoiseSuppression, NoiseSuppressionLevel, Processor, NUM_SAMPLES_PER_FRAME,
};
use crate::audio_ring::AudioRing;
/// 20 ms at 48 kHz, mono — matches the rest of the pipeline and the codec.
pub const FRAME_SAMPLES: usize = 960;
/// APM requires strict 10 ms frames at 48 kHz = 480 samples per call.
/// Imported from the webrtc-audio-processing crate so we can't drift out
/// of sync with whatever sample rate / frame length the C++ lib is using.
const APM_FRAME_SAMPLES: usize = NUM_SAMPLES_PER_FRAME as usize;
const APM_NUM_CHANNELS: usize = 1;
/// Round-trip delay hint passed to APM; the estimator refines from here.
/// 60 ms is a reasonable default for CPAL on ALSA / PulseAudio / PipeWire.
#[allow(dead_code)]
const STREAM_DELAY_MS: i32 = 60;
// ---------------------------------------------------------------------------
// Shared APM instance
// ---------------------------------------------------------------------------
/// Module-level lazily-initialized APM. Shared between capture and playback
/// so they operate on the same echo-cancellation state — the render frames
/// pushed by playback are what the capture path subtracts from the mic input.
/// Wrapped in a Mutex because the 0.3.x Processor takes `&mut self` on both
/// process_capture_frame and process_render_frame.
static PROCESSOR: OnceLock<Arc<Mutex<Processor>>> = OnceLock::new();
fn get_or_init_processor() -> anyhow::Result<Arc<Mutex<Processor>>> {
if let Some(p) = PROCESSOR.get() {
return Ok(p.clone());
}
let init_config = InitializationConfig {
num_capture_channels: APM_NUM_CHANNELS as i32,
num_render_channels: APM_NUM_CHANNELS as i32,
..Default::default()
};
let mut processor = Processor::new(&init_config)
.map_err(|e| anyhow!("webrtc APM init failed: {e:?}"))?;
let config = Config {
echo_cancellation: Some(EchoCancellation {
suppression_level: EchoCancellationSuppressionLevel::High,
stream_delay_ms: Some(STREAM_DELAY_MS),
enable_delay_agnostic: true,
enable_extended_filter: true,
}),
noise_suppression: Some(NoiseSuppression {
suppression_level: NoiseSuppressionLevel::High,
}),
enable_high_pass_filter: true,
// AGC left off for now — it can fight the Opus encoder's own gain
// staging and the adaptive-quality controller. Add later if users
// report low mic levels.
..Default::default()
};
processor.set_config(config);
let arc = Arc::new(Mutex::new(processor));
let _ = PROCESSOR.set(arc.clone());
info!(
stream_delay_ms = STREAM_DELAY_MS,
"webrtc APM initialized (AEC High + NS High + HPF, AGC off)"
);
Ok(arc)
}
// ---------------------------------------------------------------------------
// Helpers: i16 ↔ f32 and APM frame processing
// ---------------------------------------------------------------------------
#[inline]
fn i16_to_f32(s: i16) -> f32 {
s as f32 / 32768.0
}
#[inline]
fn f32_to_i16(s: f32) -> i16 {
(s.clamp(-1.0, 1.0) * 32767.0) as i16
}
/// Feed a 20 ms (960-sample) playback frame to APM as the render reference.
/// Splits into two 10 ms halves because APM is strict about frame size.
/// Takes the Mutex-wrapped Processor and locks briefly around each call.
fn push_render_frame_20ms(apm: &Mutex<Processor>, pcm: &[i16]) {
debug_assert_eq!(pcm.len(), FRAME_SAMPLES);
let mut buf = [0f32; APM_FRAME_SAMPLES];
for half in pcm.chunks_exact(APM_FRAME_SAMPLES) {
for (i, &s) in half.iter().enumerate() {
buf[i] = i16_to_f32(s);
}
match apm.lock() {
Ok(mut p) => {
if let Err(e) = p.process_render_frame(&mut buf) {
warn!("webrtc APM process_render_frame failed: {e:?}");
}
}
Err(_) => {
warn!("webrtc APM mutex poisoned in render path");
return;
}
}
}
}
/// Run a 20 ms (960-sample) capture frame through APM's echo cancellation
/// in place. Splits into two 10 ms halves, runs APM on each, stitches
/// results back into the caller's buffer. Briefly holds the Mutex once
/// per 10 ms half.
fn process_capture_frame_20ms(apm: &Mutex<Processor>, pcm: &mut [i16]) {
debug_assert_eq!(pcm.len(), FRAME_SAMPLES);
let mut buf = [0f32; APM_FRAME_SAMPLES];
for half in pcm.chunks_exact_mut(APM_FRAME_SAMPLES) {
for (i, &s) in half.iter().enumerate() {
buf[i] = i16_to_f32(s);
}
match apm.lock() {
Ok(mut p) => {
if let Err(e) = p.process_capture_frame(&mut buf) {
warn!("webrtc APM process_capture_frame failed: {e:?}");
}
}
Err(_) => {
warn!("webrtc APM mutex poisoned in capture path");
return;
}
}
for (i, d) in half.iter_mut().enumerate() {
*d = f32_to_i16(buf[i]);
}
}
}
// ---------------------------------------------------------------------------
// LinuxAecCapture — CPAL mic + WebRTC AEC capture-side processing
// ---------------------------------------------------------------------------
/// Microphone capture with WebRTC AEC3 applied in place before the codec
/// sees the samples. Mirrors the public API of `audio_io::AudioCapture` so
/// downstream code doesn't change.
pub struct LinuxAecCapture {
ring: Arc<AudioRing>,
running: Arc<AtomicBool>,
}
impl LinuxAecCapture {
pub fn start() -> Result<Self, anyhow::Error> {
// Eagerly init the APM so the playback side can find it already
// configured, and so init errors surface on the caller thread
// instead of silently failing inside the capture thread.
let apm = get_or_init_processor()?;
let ring = Arc::new(AudioRing::new());
let running = Arc::new(AtomicBool::new(true));
let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
let ring_cb = ring.clone();
let running_clone = running.clone();
let apm_capture = apm.clone();
std::thread::Builder::new()
.name("wzp-audio-capture-linuxaec".into())
.spawn(move || {
let result = (|| -> Result<(), anyhow::Error> {
let host = cpal::default_host();
let device = host
.default_input_device()
.ok_or_else(|| anyhow!("no default input audio device found"))?;
info!(device = %device.name().unwrap_or_default(), "LinuxAEC: using input device");
let config = StreamConfig {
channels: 1,
sample_rate: SampleRate(48_000),
buffer_size: cpal::BufferSize::Default,
};
let use_f32 = !supports_i16_input(&device)?;
let err_cb = |e: cpal::StreamError| {
warn!("LinuxAEC input stream error: {e}");
};
// Leftover buffer for when CPAL gives us partial frames.
// We need exactly 960-sample chunks to feed APM.
let leftover = std::sync::Mutex::new(Vec::<i16>::with_capacity(FRAME_SAMPLES * 4));
let stream = if use_f32 {
let ring = ring_cb.clone();
let running = running_clone.clone();
let apm = apm_capture.clone();
device.build_input_stream(
&config,
move |data: &[f32], _: &cpal::InputCallbackInfo| {
if !running.load(Ordering::Relaxed) {
return;
}
let mut lv = leftover.lock().unwrap();
lv.reserve(data.len());
for &s in data {
lv.push(f32_to_i16(s));
}
drain_frames_through_apm(&mut lv, &apm, &ring);
},
err_cb,
None,
)?
} else {
let ring = ring_cb.clone();
let running = running_clone.clone();
let apm = apm_capture.clone();
device.build_input_stream(
&config,
move |data: &[i16], _: &cpal::InputCallbackInfo| {
if !running.load(Ordering::Relaxed) {
return;
}
let mut lv = leftover.lock().unwrap();
lv.extend_from_slice(data);
drain_frames_through_apm(&mut lv, &apm, &ring);
},
err_cb,
None,
)?
};
stream.play().context("failed to start LinuxAEC input stream")?;
let _ = init_tx.send(Ok(()));
info!("LinuxAEC capture started (AEC3 active)");
while running_clone.load(Ordering::Relaxed) {
std::thread::park_timeout(std::time::Duration::from_millis(200));
}
drop(stream);
Ok(())
})();
if let Err(e) = result {
let _ = init_tx.send(Err(e.to_string()));
}
})?;
init_rx
.recv()
.map_err(|_| anyhow!("LinuxAEC capture thread exited before signaling"))?
.map_err(|e| anyhow!("{e}"))?;
Ok(Self { ring, running })
}
pub fn ring(&self) -> &Arc<AudioRing> {
&self.ring
}
pub fn stop(&self) {
self.running.store(false, Ordering::Relaxed);
}
}
impl Drop for LinuxAecCapture {
fn drop(&mut self) {
self.stop();
}
}
/// Pull whole 960-sample frames out of the leftover buffer, run them through
/// APM's capture-side processing, and push to the ring. Leaves any partial
/// sub-960 remainder in `leftover` for the next callback.
fn drain_frames_through_apm(leftover: &mut Vec<i16>, apm: &Mutex<Processor>, ring: &AudioRing) {
let mut frame = [0i16; FRAME_SAMPLES];
while leftover.len() >= FRAME_SAMPLES {
frame.copy_from_slice(&leftover[..FRAME_SAMPLES]);
process_capture_frame_20ms(apm, &mut frame);
ring.write(&frame);
leftover.drain(..FRAME_SAMPLES);
}
}
// ---------------------------------------------------------------------------
// LinuxAecPlayback — CPAL speaker output + WebRTC AEC render-side tee
// ---------------------------------------------------------------------------
/// Speaker playback with a render-side tee: each frame written to CPAL is
/// ALSO fed to APM via `process_render_frame` as the echo-cancellation
/// reference signal. This is the "tee the playback ring" approach (Zoom,
/// Teams, Jitsi) — deterministic, does not depend on PulseAudio loopback or
/// PipeWire monitor sources.
pub struct LinuxAecPlayback {
ring: Arc<AudioRing>,
running: Arc<AtomicBool>,
}
impl LinuxAecPlayback {
pub fn start() -> Result<Self, anyhow::Error> {
let apm = get_or_init_processor()?;
let ring = Arc::new(AudioRing::new());
let running = Arc::new(AtomicBool::new(true));
let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
let ring_cb = ring.clone();
let running_clone = running.clone();
let apm_render = apm.clone();
std::thread::Builder::new()
.name("wzp-audio-playback-linuxaec".into())
.spawn(move || {
let result = (|| -> Result<(), anyhow::Error> {
let host = cpal::default_host();
let device = host
.default_output_device()
.ok_or_else(|| anyhow!("no default output audio device found"))?;
info!(device = %device.name().unwrap_or_default(), "LinuxAEC: using output device");
let config = StreamConfig {
channels: 1,
sample_rate: SampleRate(48_000),
buffer_size: cpal::BufferSize::Default,
};
let use_f32 = !supports_i16_output(&device)?;
let err_cb = |e: cpal::StreamError| {
warn!("LinuxAEC output stream error: {e}");
};
// Same 960-sample batching approach as the capture side:
// CPAL may ask for N samples in a callback where N doesn't
// divide 960. We accumulate partial frames in a Vec and
// feed APM as soon as we have a whole 20 ms frame.
let carry = std::sync::Mutex::new(Vec::<i16>::with_capacity(FRAME_SAMPLES * 4));
let stream = if use_f32 {
let ring = ring_cb.clone();
let apm = apm_render.clone();
device.build_output_stream(
&config,
move |data: &mut [f32], _: &cpal::OutputCallbackInfo| {
fill_output_and_tee_f32(data, &ring, &apm, &carry);
},
err_cb,
None,
)?
} else {
let ring = ring_cb.clone();
let apm = apm_render.clone();
device.build_output_stream(
&config,
move |data: &mut [i16], _: &cpal::OutputCallbackInfo| {
fill_output_and_tee_i16(data, &ring, &apm, &carry);
},
err_cb,
None,
)?
};
stream.play().context("failed to start LinuxAEC output stream")?;
let _ = init_tx.send(Ok(()));
info!("LinuxAEC playback started (render tee active)");
while running_clone.load(Ordering::Relaxed) {
std::thread::park_timeout(std::time::Duration::from_millis(200));
}
drop(stream);
Ok(())
})();
if let Err(e) = result {
let _ = init_tx.send(Err(e.to_string()));
}
})?;
init_rx
.recv()
.map_err(|_| anyhow!("LinuxAEC playback thread exited before signaling"))?
.map_err(|e| anyhow!("{e}"))?;
Ok(Self { ring, running })
}
pub fn ring(&self) -> &Arc<AudioRing> {
&self.ring
}
pub fn stop(&self) {
self.running.store(false, Ordering::Relaxed);
}
}
impl Drop for LinuxAecPlayback {
fn drop(&mut self) {
self.stop();
}
}
fn fill_output_and_tee_i16(
data: &mut [i16],
ring: &AudioRing,
apm: &Mutex<Processor>,
carry: &std::sync::Mutex<Vec<i16>>,
) {
let read = ring.read(data);
for s in &mut data[read..] {
*s = 0;
}
tee_render_samples(data, apm, carry);
}
fn fill_output_and_tee_f32(
data: &mut [f32],
ring: &AudioRing,
apm: &Mutex<Processor>,
carry: &std::sync::Mutex<Vec<i16>>,
) {
let mut tmp = vec![0i16; data.len()];
let read = ring.read(&mut tmp);
for s in &mut tmp[read..] {
*s = 0;
}
for (d, &s) in data.iter_mut().zip(tmp.iter()) {
*d = i16_to_f32(s);
}
tee_render_samples(&tmp, apm, carry);
}
/// Push CPAL-bound samples into APM's render-side input for echo cancellation.
/// Uses a carry buffer to batch into exact 960-sample (20 ms) frames.
fn tee_render_samples(samples: &[i16], apm: &Mutex<Processor>, carry: &std::sync::Mutex<Vec<i16>>) {
let mut lv = carry.lock().unwrap();
lv.extend_from_slice(samples);
while lv.len() >= FRAME_SAMPLES {
let mut frame = [0i16; FRAME_SAMPLES];
frame.copy_from_slice(&lv[..FRAME_SAMPLES]);
push_render_frame_20ms(apm, &frame);
lv.drain(..FRAME_SAMPLES);
}
}
// ---------------------------------------------------------------------------
// CPAL format helpers (duplicated from audio_io.rs to keep the modules
// independent — each backend file is a self-contained unit)
// ---------------------------------------------------------------------------
fn supports_i16_input(device: &cpal::Device) -> Result<bool, anyhow::Error> {
let supported = device
.supported_input_configs()
.context("failed to query input configs")?;
for cfg in supported {
if cfg.sample_format() == SampleFormat::I16
&& cfg.min_sample_rate() <= SampleRate(48_000)
&& cfg.max_sample_rate() >= SampleRate(48_000)
&& cfg.channels() >= 1
{
return Ok(true);
}
}
Ok(false)
}
fn supports_i16_output(device: &cpal::Device) -> Result<bool, anyhow::Error> {
let supported = device
.supported_output_configs()
.context("failed to query output configs")?;
for cfg in supported {
if cfg.sample_format() == SampleFormat::I16
&& cfg.min_sample_rate() <= SampleRate(48_000)
&& cfg.max_sample_rate() >= SampleRate(48_000)
&& cfg.channels() >= 1
{
return Ok(true);
}
}
Ok(false)
}

332
crates/wzp-client/src/audio_wasapi.rs
View File

@@ -1,332 +0,0 @@
//! Direct WASAPI microphone capture with Windows's OS-level AEC enabled.
//!
//! Bypasses CPAL and opens the default capture endpoint directly via
//! `IMMDeviceEnumerator` + `IAudioClient2::SetClientProperties`, setting
//! `AudioClientProperties.eCategory = AudioCategory_Communications`. That's
//! the switch that tells Windows "this is a VoIP call" — the OS then
//! enables its communications audio processing chain (AEC, noise
//! suppression, automatic gain control) for the stream. AEC operates at
//! the OS level using the currently-playing audio as the reference
//! signal, so it cancels echo from our CPAL playback (and any other app's
//! audio) without us having to plumb a reference signal ourselves.
//!
//! Platform: Windows only, compiled only when the `windows-aec` feature
//! is enabled. Mirrors the public API of `audio_io::AudioCapture` so
//! `wzp-client`'s lib.rs can transparently re-export either one as
//! `AudioCapture`.
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use anyhow::{anyhow, Context};
use tracing::{info, warn};
use windows::core::{Interface, GUID};
use windows::Win32::Foundation::{CloseHandle, BOOL, WAIT_OBJECT_0};
use windows::Win32::Media::Audio::{
eCapture, eCommunications, AudioCategory_Communications, AudioClientProperties,
IAudioCaptureClient, IAudioClient, IAudioClient2, IMMDeviceEnumerator, MMDeviceEnumerator,
AUDCLNT_SHAREMODE_SHARED, AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM,
AUDCLNT_STREAMFLAGS_EVENTCALLBACK, AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY, WAVEFORMATEX,
WAVE_FORMAT_PCM,
};
use windows::Win32::System::Com::{
CoCreateInstance, CoInitializeEx, CoUninitialize, CLSCTX_ALL, COINIT_MULTITHREADED,
};
use windows::Win32::System::Threading::{CreateEventW, WaitForSingleObject, INFINITE};
use crate::audio_ring::AudioRing;
/// 20 ms at 48 kHz, mono. Matches the rest of the audio pipeline.
pub const FRAME_SAMPLES: usize = 960;
/// Microphone capture via WASAPI with Windows's communications AEC enabled.
///
/// The WASAPI capture stream runs on a dedicated OS thread. This handle is
/// `Send + Sync`. Dropping it stops the stream and joins the thread.
pub struct WasapiAudioCapture {
ring: Arc<AudioRing>,
running: Arc<AtomicBool>,
thread: Option<std::thread::JoinHandle<()>>,
}
impl WasapiAudioCapture {
/// Open the default communications microphone, enable OS AEC, and start
/// streaming PCM into a lock-free ring buffer.
///
/// Returns only after the capture thread has successfully initialized
/// the stream, or propagates the error back to the caller.
pub fn start() -> Result<Self, anyhow::Error> {
let ring = Arc::new(AudioRing::new());
let running = Arc::new(AtomicBool::new(true));
let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
let ring_cb = ring.clone();
let running_cb = running.clone();
let thread = std::thread::Builder::new()
.name("wzp-audio-capture-wasapi".into())
.spawn(move || {
let result = unsafe { capture_thread_main(ring_cb, running_cb.clone(), &init_tx) };
if let Err(e) = result {
warn!("wasapi capture thread exited with error: {e}");
// If we failed before signaling init, signal now so the
// caller unblocks. Double-send is harmless (channel is
// bounded to 1 and we only hit the second send path on
// late errors).
let _ = init_tx.send(Err(e.to_string()));
}
})
.context("failed to spawn WASAPI capture thread")?;
init_rx
.recv()
.map_err(|_| anyhow!("WASAPI capture thread exited before signaling init"))?
.map_err(|e| anyhow!("{e}"))?;
Ok(Self {
ring,
running,
thread: Some(thread),
})
}
/// Get a reference to the capture ring buffer for direct polling.
pub fn ring(&self) -> &Arc<AudioRing> {
&self.ring
}
/// Stop capturing.
pub fn stop(&self) {
self.running.store(false, Ordering::Relaxed);
}
}
impl Drop for WasapiAudioCapture {
fn drop(&mut self) {
self.stop();
if let Some(handle) = self.thread.take() {
// Join best-effort. The thread loop polls `running` every 200ms
// via a short WaitForSingleObject timeout, so it should exit
// within ~200ms of `stop()`.
let _ = handle.join();
}
}
}
// ---------------------------------------------------------------------------
// WASAPI thread entry point — everything below this line runs on the
// dedicated wzp-audio-capture-wasapi thread.
// ---------------------------------------------------------------------------
unsafe fn capture_thread_main(
ring: Arc<AudioRing>,
running: Arc<AtomicBool>,
init_tx: &std::sync::mpsc::SyncSender<Result<(), String>>,
) -> Result<(), anyhow::Error> {
// COM init for the capture thread. MULTITHREADED because we're not
// running a message pump. Must be balanced by CoUninitialize on exit.
CoInitializeEx(None, COINIT_MULTITHREADED)
.ok()
.context("CoInitializeEx failed")?;
// Use a guard struct so CoUninitialize runs even on early returns.
struct ComGuard;
impl Drop for ComGuard {
fn drop(&mut self) {
unsafe { CoUninitialize() };
}
}
let _com_guard = ComGuard;
let enumerator: IMMDeviceEnumerator =
CoCreateInstance(&MMDeviceEnumerator, None, CLSCTX_ALL)
.context("CoCreateInstance(MMDeviceEnumerator) failed")?;
// eCommunications role (not eConsole) — this picks the device the user
// has designated for communications in Sound Settings. It's the one
// Windows's AEC is actually tuned for and the one Teams/Zoom use.
let device = enumerator
.GetDefaultAudioEndpoint(eCapture, eCommunications)
.context("GetDefaultAudioEndpoint(eCapture, eCommunications) failed")?;
if let Ok(name) = device_name(&device) {
info!(device = %name, "opening WASAPI communications capture endpoint");
}
let audio_client: IAudioClient = device
.Activate(CLSCTX_ALL, None)
.context("IMMDevice::Activate(IAudioClient) failed")?;
// IAudioClient2 exposes SetClientProperties, which is the ONLY way to
// set AudioCategory_Communications pre-Initialize. Calling it on the
// base IAudioClient would not compile, and setting it after Initialize
// is a no-op.
let audio_client2: IAudioClient2 = audio_client
.cast()
.context("QueryInterface IAudioClient2 failed")?;
let mut props = AudioClientProperties {
cbSize: std::mem::size_of::<AudioClientProperties>() as u32,
bIsOffload: BOOL(0),
eCategory: AudioCategory_Communications,
// 0 = AUDCLNT_STREAMOPTIONS_NONE. The `windows` crate doesn't
// export the enum constant in all versions, so use 0 directly.
Options: Default::default(),
};
audio_client2
.SetClientProperties(&mut props as *mut _)
.context("SetClientProperties(AudioCategory_Communications) failed")?;
// Request 48 kHz mono i16 directly. AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM
// tells Windows to do any needed format conversion inside the audio
// engine rather than rejecting our format. SRC_DEFAULT_QUALITY picks
// the standard Windows resampler quality (fine for voice).
let wave_format = WAVEFORMATEX {
wFormatTag: WAVE_FORMAT_PCM as u16,
nChannels: 1,
nSamplesPerSec: 48_000,
nAvgBytesPerSec: 48_000 * 2, // 1 ch * 2 bytes/sample * 48000 Hz
nBlockAlign: 2, // 1 ch * 2 bytes/sample
wBitsPerSample: 16,
cbSize: 0,
};
// 1,000,000 hns = 100 ms buffer (hns = 100-nanosecond units). Windows
// treats this as the minimum; the engine may give us a larger one.
const BUFFER_DURATION_HNS: i64 = 1_000_000;
audio_client
.Initialize(
AUDCLNT_SHAREMODE_SHARED,
AUDCLNT_STREAMFLAGS_EVENTCALLBACK
| AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM
| AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY,
BUFFER_DURATION_HNS,
0,
&wave_format,
Some(&GUID::zeroed()),
)
.context("IAudioClient::Initialize failed — Windows rejected communications-mode 48k mono i16")?;
// Event-driven capture: Windows signals this handle each time a new
// audio packet is available. We wait on it from the loop below.
let event = CreateEventW(None, false, false, None)
.context("CreateEventW failed")?;
audio_client
.SetEventHandle(event)
.context("SetEventHandle failed")?;
let capture_client: IAudioCaptureClient = audio_client
.GetService()
.context("IAudioClient::GetService(IAudioCaptureClient) failed")?;
audio_client.Start().context("IAudioClient::Start failed")?;
// Signal to the parent thread that init succeeded before entering the
// hot loop. From this point on, errors get logged but don't propagate
// back to the caller (they'd just cause the ring buffer to stop
// filling, which the main thread detects as underruns).
let _ = init_tx.send(Ok(()));
info!("WASAPI communications-mode capture started with OS AEC enabled");
let mut logged_first_packet = false;
// Main capture loop. Exit when `running` goes false (from Drop or an
// explicit stop() call).
while running.load(Ordering::Relaxed) {
// 200 ms timeout so we check `running` regularly even if the audio
// engine stops delivering packets (e.g. device unplugged).
let wait = WaitForSingleObject(event, 200);
if wait.0 != WAIT_OBJECT_0.0 {
// Timeout or failure — just loop and re-check running.
continue;
}
// Drain all available packets. Windows may have queued more than
// one since we were last scheduled.
loop {
let packet_length = match capture_client.GetNextPacketSize() {
Ok(n) => n,
Err(e) => {
warn!("GetNextPacketSize failed: {e}");
break;
}
};
if packet_length == 0 {
break;
}
let mut buffer_ptr: *mut u8 = std::ptr::null_mut();
let mut num_frames: u32 = 0;
let mut flags: u32 = 0;
let mut device_position: u64 = 0;
let mut qpc_position: u64 = 0;
if let Err(e) = capture_client.GetBuffer(
&mut buffer_ptr,
&mut num_frames,
&mut flags,
Some(&mut device_position),
Some(&mut qpc_position),
) {
warn!("GetBuffer failed: {e}");
break;
}
if num_frames > 0 && !buffer_ptr.is_null() {
if !logged_first_packet {
info!(
frames = num_frames,
flags, "WASAPI capture: first packet received"
);
logged_first_packet = true;
}
// Because we asked for 48 kHz mono i16, each frame is
// exactly one i16. Windows's AUTOCONVERTPCM handles the
// conversion from whatever the engine mix format is.
let samples = std::slice::from_raw_parts(
buffer_ptr as *const i16,
num_frames as usize,
);
ring.write(samples);
}
if let Err(e) = capture_client.ReleaseBuffer(num_frames) {
warn!("ReleaseBuffer failed: {e}");
break;
}
}
}
info!("WASAPI capture thread stopping");
let _ = audio_client.Stop();
let _ = CloseHandle(event);
// _com_guard drops here, calling CoUninitialize.
// Silence INFINITE unused-import warning — it's referenced by the
// `windows` crate's WaitForSingleObject alternative but we use the
// 200 ms timeout variant instead. Explicit suppression for clarity.
let _ = INFINITE;
Ok(())
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/// Best-effort device ID string for logging. Grabbing the friendly name via
/// PKEY_Device_FriendlyName requires IPropertyStore + PROPVARIANT plumbing
/// that's far more ceremony than a log line justifies; the ID is already
/// sufficient to confirm we opened the right endpoint.
///
/// Rust 2024 edition's `unsafe_op_in_unsafe_fn` lint requires explicit
/// `unsafe { ... }` blocks inside `unsafe fn` bodies for each unsafe call,
/// even though the whole function is already marked unsafe.
unsafe fn device_name(
device: &windows::Win32::Media::Audio::IMMDevice,
) -> Result<String, anyhow::Error> {
let id = unsafe { device.GetId() }.context("IMMDevice::GetId failed")?;
Ok(unsafe { id.to_string() }.unwrap_or_else(|_| "<non-utf16>".to_string()))
}

350
crates/wzp-client/src/birthday.rs
View File

@@ -1,350 +0,0 @@
//! Birthday attack for hard NAT traversal.
//!
//! When both peers are behind symmetric NATs with random port
//! allocation, standard hole-punching fails because neither side
//! can predict the other's external port. This module implements
//! the birthday-paradox approach:
//!
//! 1. **Acceptor** opens N sockets, STUN-probes each to learn
//! their external ports, reports them to the Dialer.
//! 2. **Dialer** sprays QUIC connect attempts to the Acceptor's
//! reported ports + random ports on the Acceptor's IP.
//! 3. Birthday paradox: with N=64 ports and M=256 probes across
//! 65536 ports, collision probability is high.
//!
//! In practice, the Acceptor's STUN-probed ports are known
//! exactly (not random), so the Dialer targets them first —
//! making this more like "spray-and-pray with a hit list" than
//! a pure birthday attack.
use std::net::{Ipv4Addr, SocketAddr};
use std::time::{Duration, Instant};
use crate::stun;
/// Configuration for the birthday attack.
#[derive(Debug, Clone)]
pub struct BirthdayConfig {
/// Number of sockets the Acceptor opens (default: 32).
/// Each socket gets STUN-probed to learn its external port.
/// More = higher chance of collision, but more resource usage.
pub acceptor_ports: u16,
/// Number of QUIC connect attempts the Dialer makes (default: 128).
/// Spread across the Acceptor's known ports + random ports.
pub dialer_probes: u16,
/// Rate limit: ms between consecutive probes (default: 20ms = 50/s).
pub probe_interval_ms: u16,
/// Overall timeout for the birthday attack phase.
pub timeout: Duration,
/// STUN config for probing external ports.
pub stun_config: stun::StunConfig,
}
impl Default for BirthdayConfig {
fn default() -> Self {
Self {
acceptor_ports: 32,
dialer_probes: 128,
probe_interval_ms: 20,
timeout: Duration::from_secs(8),
stun_config: stun::StunConfig {
servers: vec!["stun.l.google.com:19302".into()],
timeout: Duration::from_secs(2),
},
}
}
}
/// Result of the Acceptor's port-opening phase.
#[derive(Debug, Clone, serde::Serialize)]
pub struct AcceptorPorts {
/// External IP (from STUN).
pub external_ip: Option<Ipv4Addr>,
/// List of (local_port, external_port) for each opened socket.
pub ports: Vec<PortMapping>,
/// How many sockets we attempted to open.
pub attempted: u16,
/// How many STUN probes succeeded.
pub succeeded: u16,
}
/// A single socket's local↔external port mapping.
#[derive(Debug, Clone, serde::Serialize)]
pub struct PortMapping {
pub local_port: u16,
pub external_port: u16,
}
/// Open N sockets and STUN-probe each to discover external ports.
///
/// Returns the set of known external ports that the Dialer should
/// target. Each socket stays open (bound) so the NAT mapping
/// remains active until the returned `PortGuard` is dropped.
///
/// The sockets are returned so the caller can keep them alive
/// during the attack. Dropping them closes the NAT pinholes.
pub async fn open_acceptor_ports(
config: &BirthdayConfig,
) -> (AcceptorPorts, Vec<tokio::net::UdpSocket>) {
let mut sockets = Vec::new();
let mut mappings = Vec::new();
let mut external_ip: Option<Ipv4Addr> = None;
let mut succeeded: u16 = 0;
let stun_server = match config.stun_config.servers.first() {
Some(s) => match stun::resolve_stun_server(s).await {
Ok(a) => Some(a),
Err(_) => None,
},
None => None,
};
for _ in 0..config.acceptor_ports {
// Bind to random port
let sock = match tokio::net::UdpSocket::bind("0.0.0.0:0").await {
Ok(s) => s,
Err(_) => continue,
};
let local_port = match sock.local_addr() {
Ok(a) => a.port(),
Err(_) => continue,
};
// STUN probe to learn external port
if let Some(stun_addr) = stun_server {
match stun::stun_reflect(&sock, stun_addr, config.stun_config.timeout).await {
Ok(ext_addr) => {
if external_ip.is_none() {
if let std::net::IpAddr::V4(ip) = ext_addr.ip() {
external_ip = Some(ip);
}
}
mappings.push(PortMapping {
local_port,
external_port: ext_addr.port(),
});
succeeded += 1;
}
Err(e) => {
tracing::debug!(local_port, error = %e, "birthday: STUN probe failed for socket");
}
}
}
sockets.push(sock);
}
tracing::info!(
attempted = config.acceptor_ports,
succeeded,
external_ip = ?external_ip,
"birthday: acceptor ports opened"
);
let result = AcceptorPorts {
external_ip,
ports: mappings,
attempted: config.acceptor_ports,
succeeded,
};
(result, sockets)
}
/// Generate the list of target addresses for the Dialer to spray.
///
/// Priority order:
/// 1. Acceptor's known external ports (from STUN probes) — highest hit rate
/// 2. Random ports on the Acceptor's IP — birthday paradox fill
pub fn generate_dialer_targets(
acceptor_ip: Ipv4Addr,
known_ports: &[u16],
total_probes: u16,
) -> Vec<SocketAddr> {
let mut targets = Vec::with_capacity(total_probes as usize);
// First: all known ports (guaranteed targets)
for &port in known_ports {
targets.push(SocketAddr::new(
std::net::IpAddr::V4(acceptor_ip),
port,
));
}
// Fill remaining with random ports (birthday attack)
let remaining = total_probes.saturating_sub(known_ports.len() as u16);
if remaining > 0 {
use rand::Rng;
let mut rng = rand::thread_rng();
for _ in 0..remaining {
let port = rng.gen_range(1024..=65535u16);
let addr = SocketAddr::new(
std::net::IpAddr::V4(acceptor_ip),
port,
);
if !targets.contains(&addr) {
targets.push(addr);
}
}
}
targets
}
/// Run the Dialer side of the birthday attack.
///
/// Sprays QUIC connection attempts at the target addresses.
/// Returns the first successful connection, or None on timeout.
pub async fn spray_dialer(
endpoint: &wzp_transport::Endpoint,
targets: &[SocketAddr],
call_sni: &str,
probe_interval: Duration,
timeout: Duration,
) -> Option<wzp_transport::QuinnTransport> {
let start = Instant::now();
let mut set = tokio::task::JoinSet::new();
tracing::info!(
target_count = targets.len(),
interval_ms = probe_interval.as_millis(),
timeout_s = timeout.as_secs(),
"birthday: dialer starting spray"
);
// Spray connects with rate limiting
for (idx, &target) in targets.iter().enumerate() {
if start.elapsed() >= timeout {
break;
}
let ep = endpoint.clone();
let sni = call_sni.to_string();
let client_cfg = wzp_transport::client_config();
set.spawn(async move {
let result = wzp_transport::connect(&ep, target, &sni, client_cfg).await;
(idx, target, result)
});
// Rate limit — don't blast the NAT
if idx < targets.len() - 1 {
tokio::time::sleep(probe_interval).await;
}
}
tracing::info!(
spawned = set.len(),
elapsed_ms = start.elapsed().as_millis(),
"birthday: all probes spawned, waiting for first success"
);
// Wait for first success or all failures
let deadline = start + timeout;
while let Some(join_res) = tokio::select! {
r = set.join_next() => r,
_ = tokio::time::sleep_until(tokio::time::Instant::from_std(deadline)) => None,
} {
match join_res {
Ok((idx, target, Ok(conn))) => {
tracing::info!(
idx,
%target,
remote = %conn.remote_address(),
elapsed_ms = start.elapsed().as_millis(),
"birthday: HIT! QUIC handshake succeeded"
);
set.abort_all();
return Some(wzp_transport::QuinnTransport::new(conn));
}
Ok((idx, target, Err(e))) => {
tracing::debug!(
idx,
%target,
error = %e,
"birthday: probe failed"
);
}
Err(_) => {}
}
}
tracing::info!(
elapsed_ms = start.elapsed().as_millis(),
"birthday: all probes failed or timed out"
);
None
}
// ── Tests ──────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn generate_targets_known_ports_first() {
let ip = Ipv4Addr::new(203, 0, 113, 5);
let known = vec![10000, 10001, 10002];
let targets = generate_dialer_targets(ip, &known, 10);
// Known ports should be first
assert_eq!(targets[0].port(), 10000);
assert_eq!(targets[1].port(), 10001);
assert_eq!(targets[2].port(), 10002);
// Rest are random
assert!(targets.len() <= 10);
// All target the right IP
assert!(targets.iter().all(|a| a.ip() == std::net::IpAddr::V4(ip)));
}
#[test]
fn generate_targets_no_known_all_random() {
let ip = Ipv4Addr::new(10, 0, 0, 1);
let targets = generate_dialer_targets(ip, &[], 50);
assert!(!targets.is_empty());
assert!(targets.len() <= 50);
// All ports in valid range
assert!(targets.iter().all(|a| a.port() >= 1024));
}
#[test]
fn generate_targets_more_known_than_total() {
let ip = Ipv4Addr::new(10, 0, 0, 1);
let known: Vec<u16> = (10000..10100).collect();
let targets = generate_dialer_targets(ip, &known, 50);
// All 100 known ports included even though total=50
assert_eq!(targets.len(), 100);
}
#[test]
fn generate_targets_dedup() {
let ip = Ipv4Addr::new(10, 0, 0, 1);
let targets = generate_dialer_targets(ip, &[], 100);
// No duplicates
let mut sorted = targets.clone();
sorted.sort();
sorted.dedup();
assert_eq!(sorted.len(), targets.len());
}
#[test]
fn default_config() {
let cfg = BirthdayConfig::default();
assert_eq!(cfg.acceptor_ports, 32);
assert_eq!(cfg.dialer_probes, 128);
assert!(cfg.timeout.as_secs() > 0);
}
#[test]
fn acceptor_ports_serializes() {
let result = AcceptorPorts {
external_ip: Some(Ipv4Addr::new(203, 0, 113, 5)),
ports: vec![PortMapping { local_port: 12345, external_port: 54321 }],
attempted: 32,
succeeded: 1,
};
let json = serde_json::to_string(&result).unwrap();
assert!(json.contains("54321"));
assert!(json.contains("203.0.113.5"));
}
}

754
crates/wzp-client/src/call.rs
View File

@@ -7,15 +7,14 @@ use std::time::{Duration, Instant};
use bytes::Bytes;
use tracing::{debug, info, warn};
use wzp_codec::dred_ffi::{DredDecoderHandle, DredState};
use wzp_codec::{
AdaptiveDecoder, AutoGainControl, ComfortNoise, EchoCanceller, NoiseSupressor, SilenceDetector,
};
use wzp_codec::{AutoGainControl, ComfortNoise, EchoCanceller, NoiseSupressor, SilenceDetector};
use wzp_fec::{RaptorQFecDecoder, RaptorQFecEncoder};
use wzp_proto::jitter::{JitterBuffer, PlayoutResult};
use wzp_proto::packet::{MediaHeader, MediaPacket, MiniFrameContext};
use wzp_proto::quality::AdaptiveQualityController;
use wzp_proto::traits::{AudioDecoder, AudioEncoder, FecDecoder, FecEncoder};
use wzp_proto::traits::{
AudioDecoder, AudioEncoder, FecDecoder, FecEncoder,
};
use wzp_proto::packet::QualityReport;
use wzp_proto::{CodecId, QualityProfile};
@@ -234,8 +233,6 @@ pub struct CallEncoder {
mini_frames_enabled: bool,
/// Frames encoded since the last full header was emitted.
frames_since_full: u32,
/// Pending quality report to attach to the next source packet.
pending_quality_report: Option<QualityReport>,
}
impl CallEncoder {
@@ -266,7 +263,6 @@ impl CallEncoder {
mini_context: MiniFrameContext::default(),
mini_frames_enabled: config.mini_frames_enabled,
frames_since_full: 0,
pending_quality_report: None,
}
}
@@ -348,39 +344,23 @@ impl CallEncoder {
let enc_len = self.audio_enc.encode(pcm, &mut encoded)?;
encoded.truncate(enc_len);
// Phase 2: Opus tiers bypass RaptorQ entirely (DRED handles loss
// recovery at the codec layer). Codec2 tiers keep RaptorQ unchanged.
// On Opus packets, zero the FEC header fields so old receivers
// can cleanly identify "no RaptorQ block to assemble" and new
// receivers can short-circuit their FEC ingest path.
let is_opus = self.profile.codec.is_opus();
let (fec_block, fec_symbol, fec_ratio_encoded) = if is_opus {
(0u8, 0u8, 0u8)
} else {
(
self.block_id,
self.frame_in_block,
MediaHeader::encode_fec_ratio(self.profile.fec_ratio),
)
};
// Build source media packet
let source_pkt = MediaPacket {
header: MediaHeader {
version: 0,
is_repair: false,
codec_id: self.profile.codec,
has_quality_report: self.pending_quality_report.is_some(),
fec_ratio_encoded,
has_quality_report: false,
fec_ratio_encoded: MediaHeader::encode_fec_ratio(self.profile.fec_ratio),
seq: self.seq,
timestamp: self.timestamp_ms,
fec_block,
fec_symbol,
fec_block: self.block_id,
fec_symbol: self.frame_in_block,
reserved: 0,
csrc_count: 0,
},
payload: Bytes::from(encoded.clone()),
quality_report: self.pending_quality_report.take(),
quality_report: None,
};
self.seq = self.seq.wrapping_add(1);
@@ -390,42 +370,39 @@ impl CallEncoder {
let mut output = vec![source_pkt];
// Codec2-only: feed RaptorQ and generate repair packets when the
// block is full. Opus tiers skip this entire block — DRED (active
// in Phase 1) provides codec-layer loss recovery.
if !is_opus {
self.fec_enc.add_source_symbol(&encoded)?;
self.frame_in_block += 1;
// Add to FEC encoder
self.fec_enc.add_source_symbol(&encoded)?;
self.frame_in_block += 1;
if self.frame_in_block >= self.profile.frames_per_block {
if let Ok(repairs) = self.fec_enc.generate_repair(self.profile.fec_ratio) {
for (sym_idx, repair_data) in repairs {
output.push(MediaPacket {
header: MediaHeader {
version: 0,
is_repair: true,
codec_id: self.profile.codec,
has_quality_report: false,
fec_ratio_encoded: MediaHeader::encode_fec_ratio(
self.profile.fec_ratio,
),
seq: self.seq,
timestamp: self.timestamp_ms,
fec_block: self.block_id,
fec_symbol: sym_idx,
reserved: 0,
csrc_count: 0,
},
payload: Bytes::from(repair_data),
quality_report: None,
});
self.seq = self.seq.wrapping_add(1);
}
// If block is full, generate repair and finalize
if self.frame_in_block >= self.profile.frames_per_block {
if let Ok(repairs) = self.fec_enc.generate_repair(self.profile.fec_ratio) {
for (sym_idx, repair_data) in repairs {
output.push(MediaPacket {
header: MediaHeader {
version: 0,
is_repair: true,
codec_id: self.profile.codec,
has_quality_report: false,
fec_ratio_encoded: MediaHeader::encode_fec_ratio(
self.profile.fec_ratio,
),
seq: self.seq,
timestamp: self.timestamp_ms,
fec_block: self.block_id,
fec_symbol: sym_idx,
reserved: 0,
csrc_count: 0,
},
payload: Bytes::from(repair_data),
quality_report: None,
});
self.seq = self.seq.wrapping_add(1);
}
let _ = self.fec_enc.finalize_block();
self.block_id = self.block_id.wrapping_add(1);
self.frame_in_block = 0;
}
let _ = self.fec_enc.finalize_block();
self.block_id = self.block_id.wrapping_add(1);
self.frame_in_block = 0;
}
Ok(output)
@@ -448,22 +425,6 @@ impl CallEncoder {
self.aec.feed_farend(farend);
}
/// Apply DRED tuning output to the encoder.
///
/// Called by the send loop after `DredTuner::update()` returns `Some`.
/// No-op when the active codec is Codec2 (DRED is Opus-only).
pub fn apply_dred_tuning(&mut self, tuning: wzp_proto::DredTuning) {
self.audio_enc.set_dred_duration(tuning.dred_frames);
self.audio_enc.set_expected_loss(tuning.expected_loss_pct);
}
/// Queue a quality report for attachment to the next source packet.
/// Used by the send task to embed locally-observed path quality so
/// the peer can drive adaptive quality switching.
pub fn set_pending_quality_report(&mut self, report: QualityReport) {
self.pending_quality_report = Some(report);
}
/// Enable or disable acoustic echo cancellation.
pub fn set_aec_enabled(&mut self, enabled: bool) {
self.aec.set_enabled(enabled);
@@ -477,12 +438,9 @@ impl CallEncoder {
/// Manages the recv/decode side of a call.
pub struct CallDecoder {
/// Audio decoder. Concrete `AdaptiveDecoder` (not `Box<dyn AudioDecoder>`)
/// because Phase 3b calls the inherent `reconstruct_from_dred` method,
/// which cannot live on the `AudioDecoder` trait without dragging libopus
/// types into `wzp-proto`.
audio_dec: AdaptiveDecoder,
/// FEC decoder (Codec2 tiers only; Opus bypasses RaptorQ per Phase 2).
/// Audio decoder.
audio_dec: Box<dyn AudioDecoder>,
/// FEC decoder.
fec_dec: RaptorQFecDecoder,
/// Jitter buffer.
jitter: JitterBuffer,
@@ -496,24 +454,6 @@ pub struct CallDecoder {
last_was_cn: bool,
/// Mini-frame decompression context (tracks last full header baseline).
mini_context: MiniFrameContext,
// ─── Phase 3b: DRED reconstruction state ──────────────────────────────
/// DRED side-channel parser (a separate libopus object from the decoder).
dred_decoder: DredDecoderHandle,
/// Scratch buffer used by `dred_decoder.parse_into` on every arriving
/// Opus packet. Reused across calls to avoid 10 KB alloc churn per packet.
dred_parse_scratch: DredState,
/// Cached "most recently parsed valid" DRED state, swapped with
/// `dred_parse_scratch` on successful parse. Used by `decode_next` when
/// the jitter buffer reports a gap.
last_good_dred: DredState,
/// Sequence number of the packet that produced `last_good_dred`. `None`
/// if no packet has yielded DRED state yet (cold start or legacy sender).
last_good_dred_seq: Option<u16>,
/// Phase 4 telemetry counter: gaps recovered via DRED reconstruction.
pub dred_reconstructions: u64,
/// Phase 4 telemetry counter: gaps filled via classical Opus PLC
/// (because no DRED state covered the gap, or the active codec is Codec2).
pub classical_plc_invocations: u64,
}
impl CallDecoder {
@@ -523,19 +463,8 @@ impl CallDecoder {
} else {
JitterBuffer::new(config.jitter_target, config.jitter_max, config.jitter_min)
};
// Phase 3b: build the DRED parser + state buffers. These allocate
// libopus state (~10 KB each) once per call, not per packet — the
// scratch and last-good buffers are reused via std::mem::swap on
// every successful parse.
let dred_decoder =
DredDecoderHandle::new().expect("opus_dred_decoder_create failed at call setup");
let dred_parse_scratch =
DredState::new().expect("opus_dred_alloc failed at call setup (scratch)");
let last_good_dred =
DredState::new().expect("opus_dred_alloc failed at call setup (good state)");
Self {
audio_dec: AdaptiveDecoder::new(config.profile)
.expect("failed to create adaptive decoder"),
audio_dec: wzp_codec::create_decoder(config.profile),
fec_dec: wzp_fec::create_decoder(&config.profile),
jitter,
quality: AdaptiveQualityController::new(),
@@ -543,12 +472,6 @@ impl CallDecoder {
comfort_noise: ComfortNoise::new(50),
last_was_cn: false,
mini_context: MiniFrameContext::default(),
dred_decoder,
dred_parse_scratch,
last_good_dred,
last_good_dred_seq: None,
dred_reconstructions: 0,
classical_plc_invocations: 0,
}
}
@@ -563,54 +486,15 @@ impl CallDecoder {
/// Feed a received media packet into the decode pipeline.
pub fn ingest(&mut self, packet: MediaPacket) {
// Phase 2: Opus packets bypass RaptorQ. Codec2 packets still feed
// the FEC decoder for recovery. This also cleanly drops any stray
// Opus repair packets from an old sender (we don't push repair
// packets to the jitter buffer either, so they're effectively
// ignored — a graceful mixed-version degradation).
if !packet.header.codec_id.is_opus() {
let _ = self.fec_dec.add_symbol(
packet.header.fec_block,
packet.header.fec_symbol,
packet.header.is_repair,
&packet.payload,
);
}
// Feed to FEC decoder
let _ = self.fec_dec.add_symbol(
packet.header.fec_block,
packet.header.fec_symbol,
packet.header.is_repair,
&packet.payload,
);
// Phase 3b: Opus source packets carry DRED side-channel data in
// libopus 1.5. Parse it into the scratch state and, on success,
// swap with the cached `last_good_dred` so later gap reconstruction
// has fresh neural redundancy to draw from. Parsing happens before
// the jitter push because the jitter buffer consumes the packet.
if packet.header.codec_id.is_opus() && !packet.header.is_repair {
match self
.dred_decoder
.parse_into(&mut self.dred_parse_scratch, &packet.payload)
{
Ok(available) if available > 0 => {
// Swap the freshly parsed state into `last_good_dred`.
// The old good state (now in scratch) is about to be
// overwritten on the next parse — its contents are
// not needed after this swap.
std::mem::swap(&mut self.dred_parse_scratch, &mut self.last_good_dred);
self.last_good_dred_seq = Some(packet.header.seq);
}
Ok(_) => {
// Packet had no DRED data (return 0). Leave the cached
// state untouched — it may still cover upcoming gaps
// from a warm-up period where the encoder was producing
// DRED bytes. The scratch buffer was potentially written
// but its `samples_available` is 0 so it's harmless.
}
Err(e) => {
debug!("DRED parse error (ignored): {e}");
}
}
}
// Source packets (Opus or Codec2) go to the jitter buffer for decode.
// Repair packets never reach the jitter buffer; for Codec2 they're
// used by the FEC decoder above, for Opus they're dropped here.
// If not a repair packet, also feed directly to jitter buffer
if !packet.header.is_repair {
self.jitter.push(packet);
}
@@ -648,9 +532,6 @@ impl CallDecoder {
frames_per_block: 5,
},
CodecId::Opus6k => QualityProfile::DEGRADED,
CodecId::Opus32k => QualityProfile::STUDIO_32K,
CodecId::Opus48k => QualityProfile::STUDIO_48K,
CodecId::Opus64k => QualityProfile::STUDIO_64K,
CodecId::Codec2_3200 => QualityProfile {
codec: CodecId::Codec2_3200,
fec_ratio: 0.5,
@@ -693,72 +574,19 @@ impl CallDecoder {
result
}
PlayoutResult::Missing { seq } => {
// Only attempt recovery if there are still packets buffered ahead.
// Only generate PLC if there are still packets buffered ahead.
// Otherwise we've drained everything — return None to stop.
if self.jitter.depth() == 0 {
self.jitter.record_underrun();
return None;
}
// Phase 3b: try DRED reconstruction first. If we have a
// recent DRED state from a packet whose seq > missing seq,
// and the seq delta (in samples) fits within the state's
// available window, libopus can synthesize a plausible
// replacement for the lost frame. Fall back to classical
// PLC when no state covers the gap, when the active codec
// is Codec2, or when the reconstruction itself errors.
if self.profile.codec.is_opus() {
if let Some(last_seq) = self.last_good_dred_seq {
// How many frames ahead of the missing seq is the
// last-good packet? Use wrapping arithmetic for the
// u16 seq space.
let seq_delta = last_seq.wrapping_sub(seq);
// Reject stale or backward state. u16 wraparound
// would make a "seq went backward" delta very large;
// cap at a sane forward-looking window.
const MAX_SEQ_DELTA: u16 = 128;
if seq_delta > 0 && seq_delta <= MAX_SEQ_DELTA {
let frame_samples =
(48_000 * self.profile.frame_duration_ms as i32) / 1000;
let offset_samples = seq_delta as i32 * frame_samples;
let available = self.last_good_dred.samples_available();
if offset_samples > 0 && offset_samples <= available {
match self.audio_dec.reconstruct_from_dred(
&self.last_good_dred,
offset_samples,
pcm,
) {
Ok(n) => {
self.dred_reconstructions += 1;
self.jitter.record_decode();
debug!(
seq,
last_seq,
offset_samples,
available,
"DRED reconstruction for gap"
);
return Some(n);
}
Err(e) => {
// Reconstruction failed — fall
// through to classical PLC below.
debug!(seq, "DRED reconstruct error: {e}");
}
}
}
}
if self.jitter.depth() > 0 {
debug!(seq, "packet loss, generating PLC");
let result = self.audio_dec.decode_lost(pcm).ok();
if result.is_some() {
self.jitter.record_decode();
}
result
} else {
self.jitter.record_underrun();
None
}
// Classical PLC fallback (also the Codec2 path).
debug!(seq, "packet loss, generating classical PLC");
self.classical_plc_invocations += 1;
let result = self.audio_dec.decode_lost(pcm).ok();
if result.is_some() {
self.jitter.record_decode();
}
result
}
PlayoutResult::NotReady => {
self.jitter.record_underrun();
@@ -781,19 +609,6 @@ impl CallDecoder {
pub fn reset_stats(&mut self) {
self.jitter.reset_stats();
}
/// Phase 3b introspection: sequence number of the most recently parsed
/// valid DRED state, or `None` if no Opus packet has yielded DRED data
/// yet. Used by tests to debug reconstruction eligibility.
pub fn last_good_dred_seq(&self) -> Option<u16> {
self.last_good_dred_seq
}
/// Phase 3b introspection: samples of audio history currently available
/// in the cached DRED state.
pub fn last_good_dred_samples_available(&self) -> i32 {
self.last_good_dred.samples_available()
}
}
/// Periodic telemetry logger for jitter buffer statistics.
@@ -855,83 +670,18 @@ mod tests {
assert!(!packets[0].header.is_repair);
}
/// Phase 2: Opus packets have zero FEC header fields — no block, no
/// symbol index, no repair ratio. The RaptorQ layer is bypassed
/// entirely on the Opus tiers.
#[test]
fn opus_source_packets_have_zero_fec_header_fields() {
fn encoder_generates_repair_on_full_block() {
let config = CallConfig {
profile: QualityProfile::GOOD, // Opus 24k
suppression_enabled: false, // skip silence gate for this test
profile: QualityProfile::GOOD, // 5 frames/block
..Default::default()
};
let mut enc = CallEncoder::new(&config);
// Non-silent sine wave so silence detection doesn't suppress us
// even with suppression_enabled=false (belt and braces).
let pcm: Vec<i16> = (0..960)
.map(|i| ((i as f32 * 0.1).sin() * 10_000.0) as i16)
.collect();
let packets = enc.encode_frame(&pcm).unwrap();
assert_eq!(packets.len(), 1, "Opus must emit exactly 1 source packet");
let hdr = &packets[0].header;
assert!(hdr.codec_id.is_opus());
assert!(!hdr.is_repair);
assert_eq!(hdr.fec_block, 0, "Opus fec_block must be 0");
assert_eq!(hdr.fec_symbol, 0, "Opus fec_symbol must be 0");
assert_eq!(hdr.fec_ratio_encoded, 0, "Opus fec_ratio_encoded must be 0");
}
let pcm = vec![0i16; 960];
/// Phase 2: Opus never emits repair packets, regardless of how many
/// source frames are fed in. DRED (Phase 1) provides loss recovery at
/// the codec layer; RaptorQ is disabled on Opus tiers.
#[test]
fn opus_encoder_never_emits_repair_packets() {
let config = CallConfig {
profile: QualityProfile::GOOD, // 5 frames/block in the Codec2 sense
suppression_enabled: false,
..Default::default()
};
let mut enc = CallEncoder::new(&config);
let pcm: Vec<i16> = (0..960)
.map(|i| ((i as f32 * 0.1).sin() * 10_000.0) as i16)
.collect();
// Encode well beyond a block boundary to prove no repair ever comes out.
let mut total_packets = 0usize;
let mut repair_count = 0usize;
for _ in 0..20 {
let packets = enc.encode_frame(&pcm).unwrap();
total_packets += packets.len();
repair_count += packets.iter().filter(|p| p.header.is_repair).count();
}
assert_eq!(repair_count, 0, "Opus must emit zero repair packets");
assert_eq!(
total_packets, 20,
"20 source frames → 20 source packets (1:1, no RaptorQ expansion)"
);
}
/// Phase 2: Codec2 still emits repair packets with RaptorQ ratio unchanged.
/// DRED is libopus-only and does not apply here, so RaptorQ is still the
/// primary loss-recovery mechanism on Codec2 tiers.
#[test]
fn codec2_encoder_generates_repair_on_full_block() {
let config = CallConfig {
profile: QualityProfile::CATASTROPHIC, // Codec2 1200, 8 frames/block, ratio 1.0
suppression_enabled: false,
..Default::default()
};
let mut enc = CallEncoder::new(&config);
// Codec2 takes 48 kHz samples and downsamples internally.
// CATASTROPHIC uses 40 ms frames → 1920 samples.
let pcm: Vec<i16> = (0..1920)
.map(|i| ((i as f32 * 0.1).sin() * 10_000.0) as i16)
.collect();
let mut total_packets = 0usize;
let mut repair_count = 0usize;
// Run long enough to cross the 8-frame block boundary and see repairs.
for _ in 0..16 {
let mut total_packets = 0;
let mut repair_count = 0;
for _ in 0..5 {
let packets = enc.encode_frame(&pcm).unwrap();
for p in &packets {
if p.header.is_repair {
@@ -940,10 +690,8 @@ mod tests {
}
total_packets += packets.len();
}
assert!(
repair_count > 0,
"Codec2 must still emit repair packets (got {repair_count} repairs, {total_packets} total)"
);
assert!(repair_count > 0, "should have repair packets after full block");
assert!(total_packets > 5, "total {total_packets} should exceed 5 source");
}
#[test]
@@ -974,219 +722,6 @@ mod tests {
assert!(dec.decode_next(&mut pcm).is_none());
}
// ─── Phase 3b — DRED reconstruction on packet loss ────────────────────
/// Helper: create a CallEncoder/CallDecoder pair with the given profile
/// and silence suppression disabled so silence-detection doesn't drop
/// our synthetic test frames.
fn encoder_decoder_pair(profile: QualityProfile) -> (CallEncoder, CallDecoder) {
let config = CallConfig {
profile,
suppression_enabled: false,
// Small jitter buffer so decode_next drains quickly in tests.
jitter_min: 2,
jitter_target: 3,
jitter_max: 20,
adaptive_jitter: false,
..Default::default()
};
(CallEncoder::new(&config), CallDecoder::new(&config))
}
/// Helper: generate a non-silent 20 ms frame of 300 Hz sine at the
/// given sample offset so consecutive frames form a continuous tone.
fn voice_frame_20ms(sample_offset: usize) -> Vec<i16> {
(0..960)
.map(|i| {
let t = (sample_offset + i) as f64 / 48_000.0;
(8000.0 * (2.0 * std::f64::consts::PI * 300.0 * t).sin()) as i16
})
.collect()
}
/// Phase 3b probe: sweep packet_loss_perc values to find the minimum
/// that produces a samples_available ≥ 960 (enough to reconstruct a
/// single 20 ms Opus frame). This guides the production loss floor.
#[test]
#[ignore] // diagnostic only — run with `cargo test ... -- --ignored --nocapture`
fn probe_dred_samples_available_by_loss_floor() {
use wzp_codec::opus_enc::OpusEncoder;
use wzp_proto::traits::AudioEncoder;
for loss_pct in [5u8, 10, 15, 20, 25, 40, 60, 80].iter().copied() {
let mut enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
enc.set_expected_loss(loss_pct);
let (_drop_enc, mut dec) = encoder_decoder_pair(QualityProfile::GOOD);
for i in 0..60u16 {
let pcm = voice_frame_20ms(i as usize * 960);
let mut encoded = vec![0u8; 512];
let n = enc.encode(&pcm, &mut encoded).unwrap();
encoded.truncate(n);
let pkt = MediaPacket {
header: MediaHeader {
version: 0,
is_repair: false,
codec_id: CodecId::Opus24k,
has_quality_report: false,
fec_ratio_encoded: 0,
seq: i,
timestamp: (i as u32) * 20,
fec_block: 0,
fec_symbol: 0,
reserved: 0,
csrc_count: 0,
},
payload: Bytes::from(encoded),
quality_report: None,
};
dec.ingest(pkt);
}
eprintln!(
"[phase3b probe] loss_pct={loss_pct} samples_available={}",
dec.last_good_dred_samples_available()
);
}
}
/// Phase 3b: simulated single-packet loss on an Opus call triggers a
/// DRED reconstruction rather than a classical PLC fill. Runs the full
/// encode → ingest → decode_next pipeline.
#[test]
fn opus_single_packet_loss_is_recovered_via_dred() {
let (mut enc, mut dec) = encoder_decoder_pair(QualityProfile::GOOD);
// Warm-up: encode and ingest 60 frames (1.2 s) so the DRED emitter
// has had time to fill its 200 ms window and at least one
// successful DRED parse has happened on the decoder side.
let warmup_frames = 60;
for i in 0..warmup_frames {
let pcm = voice_frame_20ms(i * 960);
let packets = enc.encode_frame(&pcm).unwrap();
for pkt in packets {
dec.ingest(pkt);
}
}
// Drain the warm-up frames through the decoder to advance the
// jitter buffer cursor past them.
let mut out = vec![0i16; 960];
while dec.decode_next(&mut out).is_some() {}
// Encode the next three frames but skip ingesting the middle one.
let base_offset = warmup_frames * 960;
let pcm_a = voice_frame_20ms(base_offset);
let pcm_b = voice_frame_20ms(base_offset + 960);
let pcm_c = voice_frame_20ms(base_offset + 1920);
let pkts_a = enc.encode_frame(&pcm_a).unwrap();
let pkts_b = enc.encode_frame(&pcm_b).unwrap(); // DROP THIS ONE
let pkts_c = enc.encode_frame(&pcm_c).unwrap();
for pkt in pkts_a {
dec.ingest(pkt);
}
// Skip pkts_b entirely — this is the "packet loss".
drop(pkts_b);
for pkt in pkts_c {
dec.ingest(pkt);
}
// Drain again. Somewhere in here decode_next will hit Missing()
// for the dropped packet and attempt DRED reconstruction.
let baseline_dred = dec.dred_reconstructions;
let baseline_plc = dec.classical_plc_invocations;
eprintln!(
"[phase3b probe] pre-drain: last_good_seq={:?} samples_available={}",
dec.last_good_dred_seq(),
dec.last_good_dred_samples_available()
);
while dec.decode_next(&mut out).is_some() {}
let dred_delta = dec.dred_reconstructions - baseline_dred;
let plc_delta = dec.classical_plc_invocations - baseline_plc;
eprintln!(
"[phase3b probe] post-drain: dred_delta={dred_delta} plc_delta={plc_delta}"
);
assert!(
dred_delta >= 1,
"expected ≥1 DRED reconstruction on single-packet loss, \
got dred_delta={dred_delta} plc_delta={plc_delta}"
);
}
/// Phase 3b: lossless stream never triggers DRED reconstruction or PLC.
/// Baseline behavior — verifies the Missing() branch is not spuriously taken.
#[test]
fn opus_lossless_ingest_never_triggers_dred_or_plc() {
let (mut enc, mut dec) = encoder_decoder_pair(QualityProfile::GOOD);
// Encode + ingest 40 frames with no drops.
for i in 0..40 {
let pcm = voice_frame_20ms(i * 960);
let packets = enc.encode_frame(&pcm).unwrap();
for pkt in packets {
dec.ingest(pkt);
}
}
let mut out = vec![0i16; 960];
while dec.decode_next(&mut out).is_some() {}
assert_eq!(
dec.dred_reconstructions, 0,
"lossless stream should not reconstruct"
);
assert_eq!(
dec.classical_plc_invocations, 0,
"lossless stream should not PLC"
);
}
/// Phase 3b: Codec2 calls fall through to classical PLC on loss.
/// DRED is libopus-only, so even if the decoder's DRED state were
/// populated (it won't be — Codec2 packets don't carry DRED bytes),
/// `reconstruct_from_dred` rejects Codec2 at the AdaptiveDecoder
/// level. This test guards the Codec2 side of the protection split.
#[test]
fn codec2_loss_falls_through_to_classical_plc() {
let (mut enc, mut dec) = encoder_decoder_pair(QualityProfile::CATASTROPHIC);
// Codec2 1200 uses 40 ms frames → 1920 samples at 48 kHz (before
// the downsample inside the codec). Encode 20 frames (~0.8 s).
let make_frame = |offset: usize| -> Vec<i16> {
(0..1920)
.map(|i| {
let t = (offset + i) as f64 / 48_000.0;
(8000.0 * (2.0 * std::f64::consts::PI * 300.0 * t).sin()) as i16
})
.collect()
};
for i in 0..20 {
let pcm = make_frame(i * 1920);
let packets = enc.encode_frame(&pcm).unwrap();
for pkt in packets {
// Drop every 5th source packet to simulate loss.
if !pkt.header.is_repair && i % 5 == 3 {
continue;
}
dec.ingest(pkt);
}
}
let mut out = vec![0i16; 1920];
while dec.decode_next(&mut out).is_some() {}
assert_eq!(
dec.dred_reconstructions, 0,
"Codec2 must never reconstruct via DRED"
);
// classical_plc_invocations may or may not trigger depending on
// whether the jitter buffer sees Missing before draining — the key
// assertion is that DRED is not used. PLC count is advisory.
}
// ---- QualityAdapter tests ----
/// Helper: build a QualityReport from human-readable loss% and RTT ms.
@@ -1461,155 +996,4 @@ mod tests {
"frames_suppressed should be > 0"
);
}
// ---- DredTuner integration tests ----
/// End-to-end test: DredTuner reacts to simulated network degradation
/// and adjusts the encoder's DRED parameters via `apply_dred_tuning`.
#[test]
fn dred_tuner_adjusts_encoder_on_loss() {
use wzp_proto::DredTuner;
let mut enc = CallEncoder::new(&CallConfig {
profile: QualityProfile::GOOD,
suppression_enabled: false,
..Default::default()
});
let mut tuner = DredTuner::new(QualityProfile::GOOD.codec);
// Baseline: good network → baseline DRED (20 frames = 200 ms).
let baseline = tuner.current();
assert_eq!(baseline.dred_frames, 20);
// Warm up the tuner — first few updates may return Some as the
// EWMA initializes and expected_loss settles from the initial 15%.
for _ in 0..10 {
tuner.update(0.0, 50, 5);
}
// After settling, the tuning should be at baseline.
assert_eq!(tuner.current().dred_frames, 20);
// Simulate network degradation: 30% loss, 300ms RTT.
// The tuner should increase DRED frames above baseline.
let tuning = tuner.update(30.0, 300, 15);
assert!(tuning.is_some(), "loss spike should trigger tuning change");
let t = tuning.unwrap();
assert!(
t.dred_frames > 20,
"30% loss should increase DRED above baseline 20, got {}",
t.dred_frames
);
// Apply to encoder — should not panic.
enc.apply_dred_tuning(t);
// Verify the encoder still works after tuning.
let pcm = voice_frame_20ms(0);
let packets = enc.encode_frame(&pcm).unwrap();
assert!(!packets.is_empty(), "encoder must still produce packets after DRED tuning");
}
/// DredTuner jitter spike triggers pre-emptive DRED boost to ceiling.
#[test]
fn dred_tuner_spike_boosts_to_ceiling() {
use wzp_proto::DredTuner;
let mut tuner = DredTuner::new(CodecId::Opus24k);
// Establish low-jitter baseline.
for _ in 0..20 {
tuner.update(0.0, 50, 5);
}
assert!(!tuner.spike_boost_active());
// Jitter spikes to 40ms (8x baseline of ~5ms).
let tuning = tuner.update(0.0, 50, 40);
assert!(tuner.spike_boost_active(), "jitter spike should activate boost");
assert!(tuning.is_some());
// Ceiling for Opus24k is 50 frames = 500 ms.
assert_eq!(
tuning.unwrap().dred_frames, 50,
"spike should push to ceiling"
);
}
/// DredTuner is a no-op for Codec2 profiles.
#[test]
fn dred_tuner_noop_for_codec2() {
use wzp_proto::DredTuner;
let mut tuner = DredTuner::new(CodecId::Codec2_1200);
// Even extreme conditions produce no tuning output.
assert!(tuner.update(50.0, 800, 100).is_none());
assert_eq!(tuner.current().dred_frames, 0);
}
/// DredTuner + CallEncoder: full cycle through profile switch.
#[test]
fn dred_tuner_handles_profile_switch() {
use wzp_proto::DredTuner;
let mut enc = CallEncoder::new(&CallConfig {
profile: QualityProfile::GOOD,
suppression_enabled: false,
..Default::default()
});
let mut tuner = DredTuner::new(QualityProfile::GOOD.codec);
// Apply initial tuning on good network.
if let Some(t) = tuner.update(0.0, 50, 5) {
enc.apply_dred_tuning(t);
}
// Switch to degraded profile.
enc.set_profile(QualityProfile::DEGRADED).unwrap();
tuner.set_codec(QualityProfile::DEGRADED.codec);
// Opus6k baseline is 50 frames (500 ms), ceiling is 104 (1040 ms).
let baseline = tuner.current();
// After set_codec, the cached tuning should reflect old state;
// a fresh update gives the new codec's mapping.
let tuning = tuner.update(20.0, 200, 10);
assert!(tuning.is_some());
let t = tuning.unwrap();
assert!(
t.dred_frames >= 50,
"Opus6k with 20% loss should be at least baseline 50, got {}",
t.dred_frames
);
enc.apply_dred_tuning(t);
// Encode a 40ms frame (Opus6k uses 40ms frames = 1920 samples).
let pcm: Vec<i16> = (0..1920)
.map(|i| ((i as f32 * 0.1).sin() * 10_000.0) as i16)
.collect();
let packets = enc.encode_frame(&pcm).unwrap();
assert!(!packets.is_empty());
}
#[test]
fn encoder_attaches_quality_report() {
let mut enc = CallEncoder::new(&CallConfig {
profile: QualityProfile::GOOD,
suppression_enabled: false,
..Default::default()
});
// Set a quality report
enc.set_pending_quality_report(QualityReport::from_path_stats(5.0, 80, 10));
// Encode a frame — should have quality_report attached
let pcm = voice_frame_20ms(0);
let packets = enc.encode_frame(&pcm).unwrap();
assert!(!packets.is_empty());
assert!(packets[0].header.has_quality_report, "first packet should have quality report");
assert!(packets[0].quality_report.is_some());
// Next frame should NOT have quality_report (it was consumed)
let packets2 = enc.encode_frame(&voice_frame_20ms(960)).unwrap();
assert!(!packets2[0].header.has_quality_report, "second packet should not have quality report");
assert!(packets2[0].quality_report.is_none());
}
}

1070
crates/wzp-client/src/cli.rs
View File

File diff suppressed because it is too large Load Diff

960
crates/wzp-client/src/dual_path.rs
View File

@@ -1,960 +0,0 @@
//! Phase 3.5 — dual-path QUIC connect race for P2P hole-punching.
//!
//! When both peers advertised reflex addrs in the
//! DirectCallOffer/Answer flow, the relay cross-wires them into
//! `CallSetup.peer_direct_addr`. This module races a direct QUIC
//! handshake against the existing relay dial and returns whichever
//! completes first — with automatic drop of the loser via
//! `tokio::select!`.
//!
//! Role determination is deterministic and symmetric
//! (`wzp_client::reflect::determine_role`): whichever peer has the
//! lexicographically smaller reflex addr becomes the **Acceptor**
//! (listens on a server-capable endpoint), the other becomes the
//! **Dialer** (dials the peer's addr). Because the rule is
//! identical on both sides, the Acceptor's inbound QUIC session
//! and the Dialer's outbound are the SAME connection — no
//! negotiation needed, no two-conns-per-call confusion.
//!
//! Timeout policy:
//! - Direct path: 2s from the start of `race`. Cone-NAT hole-punch
//! typically completes in < 500ms on a LAN; 2s gives us tolerance
//! for a single QUIC Initial retry on unreliable networks.
//! - Relay path: 10s (existing behavior elsewhere in the codebase).
//! - Overall: `tokio::select!` returns as soon as either succeeds.
use std::net::SocketAddr;
use std::sync::Arc;
use std::time::Duration;
use crate::reflect::Role;
use wzp_transport::QuinnTransport;
/// Which path won the race. Used by the `connect` command for
/// logging + (in the future) metrics.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WinningPath {
Direct,
Relay,
}
/// Diagnostic info for a single candidate dial attempt.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CandidateDiag {
pub index: usize,
pub addr: String,
pub result: String, // "ok", "skipped:ipv6", "error:..."
pub elapsed_ms: Option<u32>,
}
/// Phase 6: the race now returns BOTH transports (when available)
/// so the connect command can negotiate with the peer before
/// committing. The negotiation decides which transport to use
/// based on whether BOTH sides report `direct_ok = true`.
pub struct RaceResult {
/// The direct P2P transport, if the direct path completed.
/// `None` if the direct dial/accept failed or timed out.
pub direct_transport: Option<Arc<QuinnTransport>>,
/// The relay transport, if the relay dial completed.
/// `None` if the relay dial failed (shouldn't happen in
/// practice since relay is always reachable).
pub relay_transport: Option<Arc<QuinnTransport>>,
/// Which future completed first in the local race.
/// Informational — the actual path used is decided by the
/// Phase 6 negotiation after both sides exchange reports.
pub local_winner: WinningPath,
/// Per-candidate diagnostic info for debugging.
pub candidate_diags: Vec<CandidateDiag>,
}
/// Attempt a direct QUIC connection to the peer in parallel with
/// the relay dial and return the winning `QuinnTransport`.
///
/// `role` selects the direction of the direct attempt:
/// - `Role::Acceptor` creates a server-capable endpoint and waits
/// for the peer to dial in.
/// - `Role::Dialer` creates a client-only endpoint and dials
/// `peer_direct_addr`.
///
/// The relay path is always attempted in parallel as a fallback so
/// the race ALWAYS produces a working transport unless both paths
/// genuinely fail (network partition). Returns
/// `Err(anyhow::anyhow!(...))` if both paths fail within the
/// timeout.
/// Phase 5.5 candidate bundle — full ICE-ish candidate list for
/// the peer. The race tries them all in parallel alongside the
/// relay path. At minimum this should contain the peer's
/// server-reflexive address; `local_addrs` carries LAN host
/// candidates gathered from their physical interfaces.
///
/// Empty is valid: the D-role has nothing to dial and the race
/// reduces to "relay only" + (if A-role) accepting on the
/// shared endpoint.
#[derive(Debug, Clone, Default)]
pub struct PeerCandidates {
/// Peer's server-reflexive address (Phase 3). `None` if the
/// peer didn't advertise one.
pub reflexive: Option<SocketAddr>,
/// Peer's LAN host addresses (Phase 5.5). Tried first on
/// same-LAN pairs — direct dials to these bypass the NAT
/// entirely.
pub local: Vec<SocketAddr>,
/// Phase 8 (Tailscale-inspired): peer's port-mapped external
/// address from NAT-PMP/PCP/UPnP. When the router supports
/// port mapping, this gives a stable external address even
/// behind symmetric NATs.
pub mapped: Option<SocketAddr>,
}
impl PeerCandidates {
/// Flatten into the list of addrs the D-role should dial.
/// Order: LAN host candidates first (fastest when they
/// work), then port-mapped (stable even behind symmetric
/// NATs), then reflexive (covers the non-LAN case).
pub fn dial_order(&self) -> Vec<SocketAddr> {
let mut out = Vec::with_capacity(self.local.len() + 2);
out.extend(self.local.iter().copied());
// Port-mapped address goes before reflexive — it's
// more reliable on symmetric NATs where the reflexive
// addr might not match what the peer actually sees.
if let Some(a) = self.mapped {
if !out.contains(&a) {
out.push(a);
}
}
if let Some(a) = self.reflexive {
if !out.contains(&a) {
out.push(a);
}
}
out
}
/// Smart dial order: filters out candidates that can't possibly
/// work given our own reflexive address.
///
/// - **LAN candidates**: only included if peer's public IP
/// matches ours (same network). Private IPs are unreachable
/// cross-network.
/// - **IPv6 candidates**: stripped entirely (Phase 7 disabled).
/// - **Reflexive + mapped**: always included.
pub fn smart_dial_order(&self, own_reflexive: Option<&SocketAddr>) -> Vec<SocketAddr> {
let own_public_ip = own_reflexive.map(|a| a.ip());
let peer_public_ip = self.reflexive.map(|a| a.ip());
let same_network = match (own_public_ip, peer_public_ip) {
(Some(a), Some(b)) => a == b,
_ => false,
};
let mut out = Vec::with_capacity(self.local.len() + 2);
// LAN candidates only when on the same network.
if same_network {
for addr in &self.local {
if !addr.is_ipv6() {
out.push(*addr);
}
}
}
// Port-mapped (always useful — it's a public addr).
if let Some(a) = self.mapped {
if !a.is_ipv6() && !out.contains(&a) {
out.push(a);
}
}
// Reflexive (always useful — it's the peer's public addr).
if let Some(a) = self.reflexive {
if !a.is_ipv6() && !out.contains(&a) {
out.push(a);
}
}
out
}
/// Is there anything for the D-role to dial? If not, the
/// race reduces to relay-only.
pub fn is_empty(&self) -> bool {
self.reflexive.is_none() && self.local.is_empty() && self.mapped.is_none()
}
}
#[allow(clippy::too_many_arguments)]
pub async fn race(
role: Role,
peer_candidates: PeerCandidates,
relay_addr: SocketAddr,
room_sni: String,
call_sni: String,
// Our own reflexive address — used to filter LAN candidates
// that can't work cross-network.
own_reflexive: Option<SocketAddr>,
// Phase 5: when `Some`, reuse this endpoint for BOTH the
// direct-path branch AND the relay dial. Pass the signal
// endpoint. The endpoint MUST be server-capable (created
// with a server config) for the A-role accept branch to
// work.
//
// When `None`, falls back to fresh endpoints per role.
// Used by tests.
shared_endpoint: Option<wzp_transport::Endpoint>,
// Phase 7: dedicated IPv6 endpoint with IPV6_V6ONLY=1.
// When `Some`, A-role accepts on both v4+v6, D-role routes
// each candidate to its matching-AF endpoint. When `None`,
// IPv6 candidates are skipped (IPv4-only, pre-Phase-7).
ipv6_endpoint: Option<wzp_transport::Endpoint>,
) -> anyhow::Result<RaceResult> {
// Rustls provider must be installed before any quinn endpoint
// is created. Install attempt is idempotent.
let _ = rustls::crypto::ring::default_provider().install_default();
// Shared diagnostic collector for per-candidate results.
let diags_collector: Arc<std::sync::Mutex<Vec<CandidateDiag>>> =
Arc::new(std::sync::Mutex::new(Vec::new()));
// Build the direct-path endpoint + future based on role.
//
// A-role: one accept future on the shared endpoint. The
// first incoming QUIC connection wins — we don't care
// which peer candidate the dialer used to reach us.
//
// D-role: N parallel dial futures, one per peer candidate
// (all LAN host addrs + the reflex addr), consolidated
// into a single direct_fut via FuturesUnordered-style
// "first OK wins" semantics. The first successful dial
// becomes the direct path; the losers are dropped (quinn
// will abort the in-flight handshakes via the dropped
// Connecting futures).
//
// Either way, direct_fut resolves to a single QuinnTransport
// (or an error) and is raced against the relay_fut by the
// outer tokio::select!.
let direct_ep: wzp_transport::Endpoint;
let direct_fut: std::pin::Pin<
Box<dyn std::future::Future<Output = anyhow::Result<QuinnTransport>> + Send>,
>;
match role {
Role::Acceptor => {
let ep = match shared_endpoint.clone() {
Some(ep) => {
tracing::info!(
local_addr = ?ep.local_addr().ok(),
"dual_path: A-role reusing shared endpoint for accept"
);
ep
}
None => {
let (sc, _cert_der) = wzp_transport::server_config();
// 0.0.0.0:0 = IPv4 socket. [::]:0 dual-stack was
// tried but breaks on Android devices where
// IPV6_V6ONLY=1 (default on some kernels) —
// IPv4 candidates silently fail. IPv6 host
// candidates are skipped for now; they need a
// dedicated IPv6 socket alongside the v4 one
// (like WebRTC's dual-socket approach).
let bind: SocketAddr = "0.0.0.0:0".parse().unwrap();
let fresh = wzp_transport::create_endpoint(bind, Some(sc))?;
tracing::info!(
local_addr = ?fresh.local_addr().ok(),
"dual_path: A-role fresh endpoint up, awaiting peer dial"
);
fresh
}
};
let ep_for_fut = ep.clone();
// Phase 7: IPv6 accept temporarily disabled (same reason
// as dial — IPv6 connections die on datagram send).
// Accept on IPv4 shared endpoint only.
let _v6_ep_unused = ipv6_endpoint.clone();
// Collect peer addrs for NAT tickle (Acceptor-side).
let tickle_addrs: Vec<SocketAddr> = peer_candidates
.smart_dial_order(own_reflexive.as_ref())
.into_iter()
.filter(|a| !a.ip().is_loopback() && !a.ip().is_unspecified())
.collect();
direct_fut = Box::pin(async move {
// NAT tickle: send a small UDP packet to each of the
// Dialer's candidate addresses FROM our shared endpoint.
// This opens our NAT's pinhole for return traffic from
// those IPs — critical for address-restricted NATs that
// only allow inbound from IPs they've seen outbound
// traffic to. Without this, the Dialer's QUIC Initial
// gets dropped by our NAT.
if !tickle_addrs.is_empty() {
if let Ok(local_addr) = ep_for_fut.local_addr() {
// Send a tickle to each peer candidate address
// to open our NAT for return traffic from that IP.
//
// We use a socket2 socket with SO_REUSEADDR +
// SO_REUSEPORT on the SAME port as the quinn
// endpoint. This is necessary because quinn
// already holds the port — a plain bind() would
// fail with EADDRINUSE.
let tickle_result: Result<(), String> = (|| {
use std::net::UdpSocket as StdUdpSocket;
let sock = socket2::Socket::new(
socket2::Domain::IPV4,
socket2::Type::DGRAM,
Some(socket2::Protocol::UDP),
).map_err(|e| format!("socket: {e}"))?;
sock.set_reuse_address(true).map_err(|e| format!("reuseaddr: {e}"))?;
// macOS/BSD/Linux also need SO_REUSEPORT
#[cfg(any(target_os = "macos", target_os = "linux", target_os = "android"))]
{
// socket2 exposes set_reuse_port on unix
unsafe {
let optval: libc::c_int = 1;
libc::setsockopt(
std::os::unix::io::AsRawFd::as_raw_fd(&sock),
libc::SOL_SOCKET,
libc::SO_REUSEPORT,
&optval as *const _ as *const libc::c_void,
std::mem::size_of::<libc::c_int>() as libc::socklen_t,
);
}
}
sock.set_nonblocking(true).map_err(|e| format!("nonblock: {e}"))?;
let bind_addr: SocketAddr = SocketAddr::new(
std::net::IpAddr::V4(std::net::Ipv4Addr::UNSPECIFIED),
local_addr.port(),
);
sock.bind(&bind_addr.into()).map_err(|e| format!("bind :{}: {e}", local_addr.port()))?;
let std_sock: StdUdpSocket = sock.into();
for addr in &tickle_addrs {
let _ = std_sock.send_to(&[0u8; 1], addr);
tracing::info!(
%addr,
local_port = local_addr.port(),
"dual_path: A-role sent NAT tickle"
);
}
Ok(())
})();
if let Err(e) = tickle_result {
tracing::warn!(error = %e, "dual_path: A-role NAT tickle failed");
}
}
}
// Accept loop: retry if we get a stale/closed
// connection from a previous call. Max 3 retries
// to avoid spinning until the race timeout.
const MAX_STALE: usize = 3;
let mut stale_count: usize = 0;
loop {
let conn = wzp_transport::accept(&ep_for_fut)
.await
.map_err(|e| anyhow::anyhow!("direct accept: {e}"))?;
if let Some(reason) = conn.close_reason() {
// Explicitly close so the peer gets a
// close frame instead of idle timeout.
conn.close(0u32.into(), b"stale");
stale_count += 1;
tracing::warn!(
remote = %conn.remote_address(),
stable_id = conn.stable_id(),
stale_count,
?reason,
"dual_path: A-role skipping stale connection"
);
if stale_count >= MAX_STALE {
return Err(anyhow::anyhow!(
"A-role: {stale_count} stale connections, aborting"
));
}
continue;
}
let has_dgram = conn.max_datagram_size().is_some();
tracing::info!(
remote = %conn.remote_address(),
stable_id = conn.stable_id(),
has_dgram,
"dual_path: A-role accepted direct connection"
);
break Ok(QuinnTransport::new(conn));
}
});
direct_ep = ep;
}
Role::Dialer => {
let ep = match shared_endpoint.clone() {
Some(ep) => {
tracing::info!(
local_addr = ?ep.local_addr().ok(),
candidates = ?peer_candidates.dial_order(),
"dual_path: D-role reusing shared endpoint to dial peer candidates"
);
ep
}
None => {
// 0.0.0.0:0 = IPv4 socket. [::]:0 dual-stack was
// tried but breaks on Android devices where
// IPV6_V6ONLY=1 (default on some kernels) —
// IPv4 candidates silently fail. IPv6 host
// candidates are skipped for now; they need a
// dedicated IPv6 socket alongside the v4 one
// (like WebRTC's dual-socket approach).
let bind: SocketAddr = "0.0.0.0:0".parse().unwrap();
let fresh = wzp_transport::create_endpoint(bind, None)?;
tracing::info!(
local_addr = ?fresh.local_addr().ok(),
candidates = ?peer_candidates.dial_order(),
"dual_path: D-role fresh endpoint up, dialing peer candidates"
);
fresh
}
};
let ep_for_fut = ep.clone();
let _v6_ep_for_dial = ipv6_endpoint.clone();
let dial_order = peer_candidates.smart_dial_order(own_reflexive.as_ref());
let sni = call_sni.clone();
let diags = diags_collector.clone();
direct_fut = Box::pin(async move {
if dial_order.is_empty() {
// No candidates — the race reduces to
// relay-only. Surface a stable error so the
// outer select falls through to relay_fut
// without a spurious "direct failed" warning.
// Use a pending future that never resolves so
// the select's "other side wins" branch is
// the natural outcome.
std::future::pending::<anyhow::Result<QuinnTransport>>().await
} else {
// Fan out N parallel dials via JoinSet. First
// `Ok` wins; `Err` from a single candidate is
// not fatal — we wait for the others. Only
// when ALL have failed do we return Err.
let mut set = tokio::task::JoinSet::new();
for (idx, candidate) in dial_order.iter().enumerate() {
// Phase 7: route each candidate to the
// endpoint matching its address family.
let candidate = *candidate;
// Phase 7: IPv6 dials temporarily disabled.
// IPv6 QUIC handshakes succeed but the
// connection dies immediately on datagram
// send ("connection lost"). Root cause is
// likely router-level IPv6 UDP filtering.
// Re-enable once IPv6 datagram delivery is
// verified on target networks.
if candidate.is_ipv6() {
tracing::info!(
%candidate,
candidate_idx = idx,
"dual_path: skipping IPv6 candidate (disabled)"
);
if let Ok(mut d) = diags.lock() {
d.push(CandidateDiag {
index: idx,
addr: candidate.to_string(),
result: "skipped:ipv6".into(),
elapsed_ms: None,
});
}
continue;
}
let ep = ep_for_fut.clone();
let client_cfg = wzp_transport::client_config();
let sni = sni.clone();
let diags_inner = diags.clone();
set.spawn(async move {
let start = std::time::Instant::now();
tracing::info!(
%candidate,
candidate_idx = idx,
"dual_path: dialing candidate"
);
let result = wzp_transport::connect(
&ep,
candidate,
&sni,
client_cfg,
)
.await;
let elapsed = start.elapsed().as_millis() as u32;
let diag_result = match &result {
Ok(_) => "ok".to_string(),
Err(e) => format!("error:{e}"),
};
if let Ok(mut d) = diags_inner.lock() {
d.push(CandidateDiag {
index: idx,
addr: candidate.to_string(),
result: diag_result,
elapsed_ms: Some(elapsed),
});
}
(idx, candidate, result)
});
}
let mut last_err: Option<String> = None;
while let Some(join_res) = set.join_next().await {
let (idx, candidate, dial_res) = match join_res {
Ok(t) => t,
Err(e) => {
last_err = Some(format!("join {e}"));
continue;
}
};
match dial_res {
Ok(conn) => {
tracing::info!(
%candidate,
candidate_idx = idx,
remote = %conn.remote_address(),
stable_id = conn.stable_id(),
"dual_path: direct dial succeeded on candidate"
);
// Abort the remaining in-flight
// dials so they don't complete
// and leak QUIC sessions.
set.abort_all();
return Ok(QuinnTransport::new(conn));
}
Err(e) => {
tracing::info!(
%candidate,
candidate_idx = idx,
error = %e,
"dual_path: direct dial failed, trying others"
);
last_err = Some(format!("candidate {candidate}: {e}"));
}
}
}
Err(anyhow::anyhow!(
"all {} direct candidates failed; last: {}",
dial_order.len(),
last_err.unwrap_or_else(|| "n/a".into())
))
}
});
direct_ep = ep;
}
}
// Relay path: classic dial to the relay's media room. Phase 5:
// reuse the shared endpoint here too so MikroTik-style NATs
// keep a stable external port across all flows from this
// client. Falls back to a fresh endpoint when not shared.
let relay_ep = match shared_endpoint.clone() {
Some(ep) => ep,
None => {
let relay_bind: SocketAddr = "[::]:0".parse().unwrap();
wzp_transport::create_endpoint(relay_bind, None)?
}
};
let relay_ep_for_fut = relay_ep.clone();
let relay_client_cfg = wzp_transport::client_config();
let relay_sni = room_sni.clone();
// Phase 5.5 direct-path head-start: hold the relay dial for
// 500ms before attempting it. On same-LAN cone-NAT pairs the
// direct dial finishes in ~30-100ms, so giving direct a 500ms
// head start means direct reliably wins when it's going to
// work at all. The worst case adds 500ms to the fall-back-
// to-relay scenario, which is imperceptible for users on
// setups where direct isn't available anyway.
//
// Prior behavior (immediate race) caused the relay to win
// ~105ms races on a MikroTik LAN because:
// - Acceptor role's direct_fut = accept() can only fire
// when the peer has completed its outbound LAN dial
// - Dialer role's parallel LAN dials need the peer's
// CallSetup processed + the race started on the other
// side before they can reach us
// - Meanwhile relay_fut is a plain dial that completes in
// whatever the client→relay RTT is (often <100ms)
//
// The 500ms head start is the minimum that empirically makes
// same-LAN direct reliably beat relay, without penalizing
// users who genuinely need the relay path.
const DIRECT_HEAD_START: Duration = Duration::from_millis(500);
let relay_fut = async move {
tokio::time::sleep(DIRECT_HEAD_START).await;
let conn =
wzp_transport::connect(&relay_ep_for_fut, relay_addr, &relay_sni, relay_client_cfg)
.await
.map_err(|e| anyhow::anyhow!("relay dial: {e}"))?;
Ok::<_, anyhow::Error>(QuinnTransport::new(conn))
};
// Phase 6: run both paths concurrently via tokio::spawn and
// collect BOTH results. The old tokio::select! approach dropped
// the loser, which meant the connect command couldn't negotiate
// with the peer — it had to commit to whichever path won locally.
//
// Now we spawn both as tasks, wait for the first to complete
// (that determines `local_winner`), then give the loser a short
// grace period to also complete. The connect command gets a
// RaceResult with both transports (when available) and uses the
// Phase 6 MediaPathReport exchange to decide which one to
// actually use for media.
let smart_order = peer_candidates.smart_dial_order(own_reflexive.as_ref());
tracing::info!(
?role,
raw_candidates = ?peer_candidates.dial_order(),
filtered_candidates = ?smart_order,
?own_reflexive,
%relay_addr,
"dual_path: racing direct vs relay"
);
let mut direct_task = tokio::spawn(
tokio::time::timeout(Duration::from_secs(4), direct_fut),
);
let mut relay_task = tokio::spawn(async move {
// Keep the 500ms head start so direct has a chance
tokio::time::sleep(Duration::from_millis(500)).await;
tokio::time::timeout(Duration::from_secs(5), relay_fut).await
});
// Wait for the first one to complete. This tells us the
// local_winner — but we DON'T commit to it yet. Phase 6
// negotiation decides the actual path.
let (mut direct_result, mut relay_result): (
Option<anyhow::Result<QuinnTransport>>,
Option<anyhow::Result<QuinnTransport>>,
) = (None, None);
let local_winner;
tokio::select! {
biased;
d = &mut direct_task => {
match d {
Ok(Ok(Ok(t))) => {
tracing::info!("dual_path: direct completed first");
direct_result = Some(Ok(t));
local_winner = WinningPath::Direct;
}
Ok(Ok(Err(e))) => {
tracing::warn!(error = %e, "dual_path: direct failed");
direct_result = Some(Err(anyhow::anyhow!("{e}")));
local_winner = WinningPath::Relay; // direct failed → relay is our only hope
}
Ok(Err(_)) => {
tracing::warn!("dual_path: direct timed out (4s)");
direct_result = Some(Err(anyhow::anyhow!("direct timeout")));
local_winner = WinningPath::Relay;
// Record timeout diag for candidates that were
// still in-flight when the timeout fired.
if let Ok(mut d) = diags_collector.lock() {
let recorded_indices: std::collections::HashSet<usize> =
d.iter().map(|diag| diag.index).collect();
for (idx, addr) in smart_order.iter().enumerate() {
if !recorded_indices.contains(&idx) {
d.push(CandidateDiag {
index: idx,
addr: addr.to_string(),
result: "timeout:4s".into(),
elapsed_ms: Some(4000),
});
}
}
}
}
Err(e) => {
tracing::warn!(error = %e, "dual_path: direct task panicked");
direct_result = Some(Err(anyhow::anyhow!("direct task panic")));
local_winner = WinningPath::Relay;
}
}
}
r = &mut relay_task => {
match r {
Ok(Ok(Ok(t))) => {
tracing::info!("dual_path: relay completed first");
relay_result = Some(Ok(t));
local_winner = WinningPath::Relay;
}
Ok(Ok(Err(e))) => {
tracing::warn!(error = %e, "dual_path: relay failed");
relay_result = Some(Err(anyhow::anyhow!("{e}")));
local_winner = WinningPath::Direct;
}
Ok(Err(_)) => {
tracing::warn!("dual_path: relay timed out");
relay_result = Some(Err(anyhow::anyhow!("relay timeout")));
local_winner = WinningPath::Direct;
}
Err(e) => {
relay_result = Some(Err(anyhow::anyhow!("relay task panic: {e}")));
local_winner = WinningPath::Direct;
}
}
}
}
// Give the loser a short grace period (1s) to also complete.
// If it does, we have both transports for Phase 6 negotiation.
// If it doesn't, we still proceed with just the winner.
if direct_result.is_none() {
match tokio::time::timeout(Duration::from_secs(1), direct_task).await {
Ok(Ok(Ok(Ok(t)))) => { direct_result = Some(Ok(t)); }
Ok(Ok(Ok(Err(e)))) => { direct_result = Some(Err(anyhow::anyhow!("{e}"))); }
_ => {
direct_result = Some(Err(anyhow::anyhow!("direct: no result in grace period")));
// Fill timeout diags for candidates that never reported.
if let Ok(mut d) = diags_collector.lock() {
let recorded: std::collections::HashSet<usize> =
d.iter().map(|diag| diag.index).collect();
for (idx, addr) in smart_order.iter().enumerate() {
if !recorded.contains(&idx) {
d.push(CandidateDiag {
index: idx,
addr: addr.to_string(),
result: "timeout:grace".into(),
elapsed_ms: None,
});
}
}
}
}
}
}
if relay_result.is_none() {
match tokio::time::timeout(Duration::from_secs(1), relay_task).await {
Ok(Ok(Ok(Ok(t)))) => { relay_result = Some(Ok(t)); }
Ok(Ok(Ok(Err(e)))) => { relay_result = Some(Err(anyhow::anyhow!("{e}"))); }
_ => { relay_result = Some(Err(anyhow::anyhow!("relay: no result in grace period"))); }
}
}
let direct_ok = direct_result.as_ref().map(|r| r.is_ok()).unwrap_or(false);
let relay_ok = relay_result.as_ref().map(|r| r.is_ok()).unwrap_or(false);
tracing::info!(
?local_winner,
direct_ok,
relay_ok,
"dual_path: race finished, both results collected for Phase 6 negotiation"
);
if !direct_ok && !relay_ok {
return Err(anyhow::anyhow!("both paths failed: no media transport available"));
}
let _ = (direct_ep, relay_ep, ipv6_endpoint);
let candidate_diags = diags_collector.lock()
.map(|d| d.clone())
.unwrap_or_default();
Ok(RaceResult {
direct_transport: direct_result
.and_then(|r| r.ok())
.map(|t| Arc::new(t)),
relay_transport: relay_result
.and_then(|r| r.ok())
.map(|t| Arc::new(t)),
local_winner,
candidate_diags,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn peer_candidates_dial_order_all_types() {
let candidates = PeerCandidates {
reflexive: Some("203.0.113.5:4433".parse().unwrap()),
local: vec![
"192.168.1.10:4433".parse().unwrap(),
"10.0.0.5:4433".parse().unwrap(),
],
mapped: Some("198.51.100.42:12345".parse().unwrap()),
};
let order = candidates.dial_order();
// Order: local first, then mapped, then reflexive
assert_eq!(order.len(), 4);
assert_eq!(order[0], "192.168.1.10:4433".parse::<SocketAddr>().unwrap());
assert_eq!(order[1], "10.0.0.5:4433".parse::<SocketAddr>().unwrap());
assert_eq!(order[2], "198.51.100.42:12345".parse::<SocketAddr>().unwrap());
assert_eq!(order[3], "203.0.113.5:4433".parse::<SocketAddr>().unwrap());
}
#[test]
fn peer_candidates_dial_order_no_mapped() {
let candidates = PeerCandidates {
reflexive: Some("203.0.113.5:4433".parse().unwrap()),
local: vec!["192.168.1.10:4433".parse().unwrap()],
mapped: None,
};
let order = candidates.dial_order();
assert_eq!(order.len(), 2);
assert_eq!(order[0], "192.168.1.10:4433".parse::<SocketAddr>().unwrap());
assert_eq!(order[1], "203.0.113.5:4433".parse::<SocketAddr>().unwrap());
}
#[test]
fn peer_candidates_dial_order_only_mapped() {
let candidates = PeerCandidates {
reflexive: None,
local: vec![],
mapped: Some("198.51.100.42:12345".parse().unwrap()),
};
let order = candidates.dial_order();
assert_eq!(order.len(), 1);
assert_eq!(order[0], "198.51.100.42:12345".parse::<SocketAddr>().unwrap());
}
#[test]
fn peer_candidates_dial_order_dedup_mapped_equals_reflexive() {
let addr: SocketAddr = "203.0.113.5:4433".parse().unwrap();
let candidates = PeerCandidates {
reflexive: Some(addr),
local: vec![],
mapped: Some(addr), // same as reflexive
};
let order = candidates.dial_order();
// Should be deduped to 1
assert_eq!(order.len(), 1);
assert_eq!(order[0], addr);
}
#[test]
fn peer_candidates_dial_order_dedup_mapped_in_local() {
let addr: SocketAddr = "192.168.1.10:4433".parse().unwrap();
let candidates = PeerCandidates {
reflexive: None,
local: vec![addr],
mapped: Some(addr), // same as a local addr
};
let order = candidates.dial_order();
assert_eq!(order.len(), 1);
assert_eq!(order[0], addr);
}
#[test]
fn peer_candidates_is_empty() {
let empty = PeerCandidates::default();
assert!(empty.is_empty());
let with_reflexive = PeerCandidates {
reflexive: Some("1.2.3.4:5".parse().unwrap()),
..Default::default()
};
assert!(!with_reflexive.is_empty());
let with_local = PeerCandidates {
local: vec!["10.0.0.1:5".parse().unwrap()],
..Default::default()
};
assert!(!with_local.is_empty());
let with_mapped = PeerCandidates {
mapped: Some("1.2.3.4:5".parse().unwrap()),
..Default::default()
};
assert!(!with_mapped.is_empty());
}
#[test]
fn peer_candidates_empty_dial_order() {
let empty = PeerCandidates::default();
assert!(empty.dial_order().is_empty());
}
#[test]
fn winning_path_debug() {
// Just verify Debug impl doesn't panic
let _ = format!("{:?}", WinningPath::Direct);
let _ = format!("{:?}", WinningPath::Relay);
}
// ── smart_dial_order tests ─────────────────────────────────
#[test]
fn smart_dial_order_same_network_includes_lan() {
let candidates = PeerCandidates {
reflexive: Some("203.0.113.5:4433".parse().unwrap()),
local: vec![
"192.168.1.10:4433".parse().unwrap(),
"10.0.0.5:4433".parse().unwrap(),
],
mapped: None,
};
let own: SocketAddr = "203.0.113.5:12345".parse().unwrap();
let order = candidates.smart_dial_order(Some(&own));
// Same public IP → LAN candidates included
assert!(order.contains(&"192.168.1.10:4433".parse().unwrap()));
assert!(order.contains(&"10.0.0.5:4433".parse().unwrap()));
assert!(order.contains(&"203.0.113.5:4433".parse().unwrap()));
}
#[test]
fn smart_dial_order_different_network_strips_lan() {
let candidates = PeerCandidates {
reflexive: Some("150.228.49.65:4433".parse().unwrap()),
local: vec![
"172.16.81.126:4433".parse().unwrap(),
"10.0.0.5:4433".parse().unwrap(),
],
mapped: None,
};
// Different public IP → LAN candidates stripped
let own: SocketAddr = "185.115.4.212:12345".parse().unwrap();
let order = candidates.smart_dial_order(Some(&own));
assert!(!order.contains(&"172.16.81.126:4433".parse().unwrap()));
assert!(!order.contains(&"10.0.0.5:4433".parse().unwrap()));
// Reflexive still included
assert!(order.contains(&"150.228.49.65:4433".parse().unwrap()));
}
#[test]
fn smart_dial_order_strips_ipv6() {
let candidates = PeerCandidates {
reflexive: Some("150.228.49.65:4433".parse().unwrap()),
local: vec![
"[2a0d:3344:692c::1]:4433".parse().unwrap(),
"172.16.81.126:4433".parse().unwrap(),
],
mapped: None,
};
// Same network, but IPv6 should be stripped
let own: SocketAddr = "150.228.49.65:5555".parse().unwrap();
let order = candidates.smart_dial_order(Some(&own));
assert!(!order.iter().any(|a| a.is_ipv6()));
assert!(order.contains(&"172.16.81.126:4433".parse().unwrap()));
}
#[test]
fn smart_dial_order_no_own_reflexive_strips_lan() {
let candidates = PeerCandidates {
reflexive: Some("150.228.49.65:4433".parse().unwrap()),
local: vec!["172.16.81.126:4433".parse().unwrap()],
mapped: Some("198.51.100.42:12345".parse().unwrap()),
};
// No own reflexive → can't determine same network → strip LAN
let order = candidates.smart_dial_order(None);
assert!(!order.contains(&"172.16.81.126:4433".parse().unwrap()));
assert!(order.contains(&"198.51.100.42:12345".parse().unwrap()));
assert!(order.contains(&"150.228.49.65:4433".parse().unwrap()));
}
#[test]
fn smart_dial_order_mapped_always_included() {
let candidates = PeerCandidates {
reflexive: Some("150.228.49.65:4433".parse().unwrap()),
local: vec![],
mapped: Some("198.51.100.42:12345".parse().unwrap()),
};
let own: SocketAddr = "185.115.4.212:12345".parse().unwrap();
let order = candidates.smart_dial_order(Some(&own));
assert_eq!(order.len(), 2); // mapped + reflexive
assert!(order.contains(&"198.51.100.42:12345".parse().unwrap()));
assert!(order.contains(&"150.228.49.65:4433".parse().unwrap()));
}
}

32
crates/wzp-client/src/featherchat.rs
View File

@@ -96,7 +96,6 @@ pub fn signal_to_call_type(signal: &SignalMessage) -> CallSignalType {
SignalMessage::Hangup { .. } => CallSignalType::Hangup,
SignalMessage::Rekey { .. } => CallSignalType::Offer, // reuse
SignalMessage::QualityUpdate { .. } => CallSignalType::Offer, // reuse
SignalMessage::LossRecoveryUpdate { .. } => CallSignalType::Offer, // reuse (telemetry)
SignalMessage::Ping { .. } | SignalMessage::Pong { .. } => CallSignalType::Offer,
SignalMessage::AuthToken { .. } => CallSignalType::Offer,
SignalMessage::Hold => CallSignalType::Hold,
@@ -111,35 +110,7 @@ pub fn signal_to_call_type(signal: &SignalMessage) -> CallSignalType {
SignalMessage::SessionForward { .. } => CallSignalType::Offer, // reuse
SignalMessage::SessionForwardAck { .. } => CallSignalType::Offer, // reuse
SignalMessage::RoomUpdate { .. } => CallSignalType::Offer, // reuse
SignalMessage::FederationHello { .. }
| SignalMessage::GlobalRoomActive { .. }
| SignalMessage::GlobalRoomInactive { .. } => CallSignalType::Offer, // relay-only
SignalMessage::DirectCallOffer { .. } => CallSignalType::Offer,
SignalMessage::DirectCallAnswer { .. } => CallSignalType::Answer,
SignalMessage::CallSetup { .. } => CallSignalType::Offer, // relay-only
SignalMessage::CallRinging { .. } => CallSignalType::Ringing,
SignalMessage::RegisterPresence { .. }
| SignalMessage::RegisterPresenceAck { .. } => CallSignalType::Offer, // relay-only
// NAT reflection is a client↔relay control exchange that
// never crosses the featherChat bridge — if it ever reaches
// this mapper something is wrong, but we still have to give
// an answer. "Offer" is the generic catch-all.
SignalMessage::Reflect
| SignalMessage::ReflectResponse { .. } => CallSignalType::Offer, // control-plane
// Phase 4 cross-relay forwarding envelope — strictly a
// relay-to-relay message, never rides the featherChat
// bridge. Catch-all mapping for completeness.
SignalMessage::FederatedSignalForward { .. } => CallSignalType::Offer,
SignalMessage::MediaPathReport { .. } => CallSignalType::Offer, // control-plane
SignalMessage::CandidateUpdate { .. } => CallSignalType::IceCandidate, // mid-call re-gather
SignalMessage::HardNatProbe { .. } => CallSignalType::IceCandidate, // hard NAT coordination
SignalMessage::HardNatBirthdayStart { .. } => CallSignalType::IceCandidate, // birthday attack
SignalMessage::UpgradeProposal { .. }
| SignalMessage::UpgradeResponse { .. }
| SignalMessage::UpgradeConfirm { .. }
| SignalMessage::QualityCapability { .. } => CallSignalType::Offer, // quality negotiation
SignalMessage::PresenceList { .. } => CallSignalType::Offer, // lobby presence
SignalMessage::QualityDirective { .. } => CallSignalType::Offer, // relay-initiated
SignalMessage::SetAlias { .. } => CallSignalType::Offer, // reuse
}
}
@@ -179,7 +150,6 @@ mod tests {
let hangup = SignalMessage::Hangup {
reason: wzp_proto::HangupReason::Normal,
call_id: None,
};
assert!(matches!(signal_to_call_type(&hangup), CallSignalType::Hangup));

3
crates/wzp-client/src/handshake.rs
View File

@@ -38,9 +38,6 @@ pub async fn perform_handshake(
ephemeral_pub,
signature,
supported_profiles: vec![
QualityProfile::STUDIO_64K,
QualityProfile::STUDIO_48K,
QualityProfile::STUDIO_32K,
QualityProfile::GOOD,
QualityProfile::DEGRADED,
QualityProfile::CATASTROPHIC,

444
crates/wzp-client/src/ice_agent.rs
View File

@@ -1,444 +0,0 @@
//! Phase 8 (Tailscale-inspired): ICE agent for candidate lifecycle
//! management and mid-call re-gathering.
//!
//! The `IceAgent` owns the state of all candidate discovery
//! mechanisms (STUN, port mapping, host candidates) and provides:
//!
//! - `gather()`: initial candidate gathering during call setup
//! - `re_gather()`: triggered on network change, produces a
//! `CandidateUpdate` to send to the peer
//! - `apply_peer_update()`: processes peer's candidate updates
//!
//! This is NOT a full ICE agent (RFC 8445). It's the Tailscale-style
//! "gather all candidates, race them all in parallel, pick the
//! winner" approach, adapted for QUIC transport.
use std::net::SocketAddr;
use std::sync::atomic::{AtomicU32, Ordering};
use std::time::Duration;
use wzp_proto::SignalMessage;
use crate::dual_path::PeerCandidates;
use crate::portmap;
use crate::reflect;
use crate::stun;
/// All candidates gathered for the local side.
#[derive(Debug, Clone)]
pub struct CandidateSet {
/// STUN-discovered server-reflexive address.
pub reflexive: Option<SocketAddr>,
/// LAN host candidates from local interfaces.
pub local: Vec<SocketAddr>,
/// Port-mapped address from NAT-PMP/PCP/UPnP.
pub mapped: Option<SocketAddr>,
/// Generation counter (monotonically increasing per call).
pub generation: u32,
}
/// Configuration for the ICE agent.
#[derive(Debug, Clone)]
pub struct IceAgentConfig {
/// STUN servers to use for reflexive discovery.
pub stun_config: stun::StunConfig,
/// Whether to attempt port mapping.
pub enable_portmap: bool,
/// Timeout for each discovery mechanism.
pub gather_timeout: Duration,
/// The QUIC endpoint's local port (for host candidate pairing).
pub local_v4_port: u16,
/// Optional IPv6 port.
pub local_v6_port: Option<u16>,
}
impl Default for IceAgentConfig {
fn default() -> Self {
Self {
stun_config: stun::StunConfig::default(),
enable_portmap: true,
gather_timeout: Duration::from_secs(3),
local_v4_port: 0,
local_v6_port: None,
}
}
}
/// ICE agent managing candidate lifecycle.
pub struct IceAgent {
config: IceAgentConfig,
generation: AtomicU32,
call_id: String,
/// Last-seen peer generation (to filter stale updates).
peer_generation: AtomicU32,
}
impl IceAgent {
pub fn new(call_id: String, config: IceAgentConfig) -> Self {
Self {
config,
generation: AtomicU32::new(0),
call_id,
peer_generation: AtomicU32::new(0),
}
}
/// Initial candidate gathering. Runs all discovery mechanisms
/// in parallel and returns the full candidate set.
pub async fn gather(&self) -> CandidateSet {
let generation = self.generation.fetch_add(1, Ordering::Relaxed);
// Run STUN + port mapping + host candidates in parallel.
let stun_fut = stun::discover_reflexive(&self.config.stun_config);
let portmap_fut = async {
if self.config.enable_portmap && self.config.local_v4_port > 0 {
portmap::acquire_port_mapping(self.config.local_v4_port, None)
.await
.ok()
} else {
None
}
};
let (stun_result, portmap_result) = tokio::join!(
tokio::time::timeout(self.config.gather_timeout, stun_fut),
tokio::time::timeout(self.config.gather_timeout, portmap_fut),
);
let reflexive = stun_result.ok().and_then(|r| r.ok());
let mapped = portmap_result
.ok()
.flatten()
.map(|m| m.external_addr);
let local = reflect::local_host_candidates(
self.config.local_v4_port,
self.config.local_v6_port,
);
tracing::info!(
generation,
reflexive = ?reflexive,
mapped = ?mapped,
local_count = local.len(),
"ice_agent: gathered candidates"
);
CandidateSet {
reflexive,
local,
mapped,
generation,
}
}
/// Re-gather candidates after a network change. Increments the
/// generation counter and returns a `CandidateUpdate` signal
/// message to send to the peer.
pub async fn re_gather(&self) -> (CandidateSet, SignalMessage) {
let candidates = self.gather().await;
let update = SignalMessage::CandidateUpdate {
call_id: self.call_id.clone(),
reflexive_addr: candidates.reflexive.map(|a| a.to_string()),
local_addrs: candidates.local.iter().map(|a| a.to_string()).collect(),
mapped_addr: candidates.mapped.map(|a| a.to_string()),
generation: candidates.generation,
};
(candidates, update)
}
/// Process a peer's candidate update. Returns `Some(PeerCandidates)`
/// if the update is newer than the last-seen generation, `None`
/// if it's stale.
pub fn apply_peer_update(
&self,
update: &SignalMessage,
) -> Option<PeerCandidates> {
let (reflexive_addr, local_addrs, mapped_addr, generation) = match update {
SignalMessage::CandidateUpdate {
reflexive_addr,
local_addrs,
mapped_addr,
generation,
..
} => (reflexive_addr, local_addrs, mapped_addr, *generation),
_ => return None,
};
// Only accept if newer than last-seen generation.
let prev = self.peer_generation.fetch_max(generation, Ordering::AcqRel);
if generation <= prev {
tracing::debug!(
generation,
prev,
"ice_agent: ignoring stale CandidateUpdate"
);
return None;
}
let reflexive = reflexive_addr
.as_deref()
.and_then(|s| s.parse().ok());
let local: Vec<SocketAddr> = local_addrs
.iter()
.filter_map(|s| s.parse().ok())
.collect();
let mapped = mapped_addr
.as_deref()
.and_then(|s| s.parse().ok());
tracing::info!(
generation,
reflexive = ?reflexive,
mapped = ?mapped,
local_count = local.len(),
"ice_agent: applied peer candidate update"
);
Some(PeerCandidates {
reflexive,
local,
mapped,
})
}
/// Get the current generation counter.
pub fn generation(&self) -> u32 {
self.generation.load(Ordering::Relaxed)
}
}
// ── Tests ──────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn apply_peer_update_rejects_stale() {
let agent = IceAgent::new("test-call".into(), IceAgentConfig::default());
// First update (gen=1) should succeed.
let update1 = SignalMessage::CandidateUpdate {
call_id: "test-call".into(),
reflexive_addr: Some("203.0.113.5:4433".into()),
local_addrs: vec!["192.168.1.10:4433".into()],
mapped_addr: None,
generation: 1,
};
let result = agent.apply_peer_update(&update1);
assert!(result.is_some());
let candidates = result.unwrap();
assert_eq!(
candidates.reflexive,
Some("203.0.113.5:4433".parse().unwrap())
);
assert_eq!(candidates.local.len(), 1);
// Same generation (gen=1) should be rejected.
let update1b = SignalMessage::CandidateUpdate {
call_id: "test-call".into(),
reflexive_addr: Some("198.51.100.9:4433".into()),
local_addrs: vec![],
mapped_addr: None,
generation: 1,
};
assert!(agent.apply_peer_update(&update1b).is_none());
// Older generation (gen=0) should be rejected.
let update0 = SignalMessage::CandidateUpdate {
call_id: "test-call".into(),
reflexive_addr: Some("10.0.0.1:4433".into()),
local_addrs: vec![],
mapped_addr: None,
generation: 0,
};
assert!(agent.apply_peer_update(&update0).is_none());
// Newer generation (gen=2) should succeed.
let update2 = SignalMessage::CandidateUpdate {
call_id: "test-call".into(),
reflexive_addr: Some("198.51.100.9:5555".into()),
local_addrs: vec![],
mapped_addr: Some("203.0.113.5:12345".into()),
generation: 2,
};
let result = agent.apply_peer_update(&update2);
assert!(result.is_some());
let candidates = result.unwrap();
assert_eq!(
candidates.reflexive,
Some("198.51.100.9:5555".parse().unwrap())
);
assert_eq!(
candidates.mapped,
Some("203.0.113.5:12345".parse().unwrap())
);
}
#[test]
fn apply_wrong_signal_returns_none() {
let agent = IceAgent::new("test-call".into(), IceAgentConfig::default());
let wrong = SignalMessage::Reflect;
assert!(agent.apply_peer_update(&wrong).is_none());
}
#[test]
fn generation_increments() {
let agent = IceAgent::new("test".into(), IceAgentConfig::default());
assert_eq!(agent.generation(), 0);
// Simulate what gather() does internally
let g1 = agent.generation.fetch_add(1, Ordering::Relaxed);
assert_eq!(g1, 0);
assert_eq!(agent.generation(), 1);
let g2 = agent.generation.fetch_add(1, Ordering::Relaxed);
assert_eq!(g2, 1);
assert_eq!(agent.generation(), 2);
}
#[test]
fn apply_peer_update_parses_all_fields() {
let agent = IceAgent::new("test-call".into(), IceAgentConfig::default());
let update = SignalMessage::CandidateUpdate {
call_id: "test-call".into(),
reflexive_addr: Some("203.0.113.5:4433".into()),
local_addrs: vec![
"192.168.1.10:4433".into(),
"10.0.0.5:4433".into(),
],
mapped_addr: Some("198.51.100.42:12345".into()),
generation: 1,
};
let candidates = agent.apply_peer_update(&update).unwrap();
assert_eq!(
candidates.reflexive,
Some("203.0.113.5:4433".parse().unwrap())
);
assert_eq!(candidates.local.len(), 2);
assert_eq!(
candidates.local[0],
"192.168.1.10:4433".parse::<SocketAddr>().unwrap()
);
assert_eq!(
candidates.mapped,
Some("198.51.100.42:12345".parse().unwrap())
);
}
#[test]
fn apply_peer_update_handles_empty_fields() {
let agent = IceAgent::new("test".into(), IceAgentConfig::default());
let update = SignalMessage::CandidateUpdate {
call_id: "test".into(),
reflexive_addr: None,
local_addrs: vec![],
mapped_addr: None,
generation: 1,
};
let candidates = agent.apply_peer_update(&update).unwrap();
assert!(candidates.reflexive.is_none());
assert!(candidates.local.is_empty());
assert!(candidates.mapped.is_none());
}
#[test]
fn apply_peer_update_skips_unparseable_addrs() {
let agent = IceAgent::new("test".into(), IceAgentConfig::default());
let update = SignalMessage::CandidateUpdate {
call_id: "test".into(),
reflexive_addr: Some("not-an-addr".into()),
local_addrs: vec![
"192.168.1.10:4433".into(),
"garbage".into(),
"10.0.0.5:4433".into(),
],
mapped_addr: Some("also-bad".into()),
generation: 1,
};
let candidates = agent.apply_peer_update(&update).unwrap();
assert!(candidates.reflexive.is_none()); // unparseable
assert_eq!(candidates.local.len(), 2); // garbage filtered
assert!(candidates.mapped.is_none()); // unparseable
}
#[test]
fn default_config_values() {
let cfg = IceAgentConfig::default();
assert!(cfg.enable_portmap);
assert!(cfg.gather_timeout.as_secs() > 0);
assert!(!cfg.stun_config.servers.is_empty());
assert_eq!(cfg.local_v4_port, 0);
assert!(cfg.local_v6_port.is_none());
}
#[tokio::test]
async fn gather_returns_candidates_even_with_no_stun() {
// With default config (port 0 = no portmap, STUN will timeout
// quickly on loopback), gather should still return host candidates.
let agent = IceAgent::new("test".into(), IceAgentConfig {
stun_config: stun::StunConfig {
servers: vec![], // no servers = quick failure
timeout: Duration::from_millis(100),
},
enable_portmap: false,
gather_timeout: Duration::from_millis(200),
local_v4_port: 12345,
local_v6_port: None,
});
let candidates = agent.gather().await;
assert_eq!(candidates.generation, 0);
// Reflexive should be None (no STUN servers)
assert!(candidates.reflexive.is_none());
// Mapped should be None (portmap disabled)
assert!(candidates.mapped.is_none());
// Local candidates depend on the machine's interfaces
// but gather() should not panic.
}
#[tokio::test]
async fn re_gather_produces_signal_message() {
let agent = IceAgent::new("call-42".into(), IceAgentConfig {
stun_config: stun::StunConfig {
servers: vec![],
timeout: Duration::from_millis(50),
},
enable_portmap: false,
gather_timeout: Duration::from_millis(100),
local_v4_port: 4433,
local_v6_port: None,
});
let (candidates, signal) = agent.re_gather().await;
assert_eq!(candidates.generation, 0);
match signal {
SignalMessage::CandidateUpdate {
call_id,
generation,
..
} => {
assert_eq!(call_id, "call-42");
assert_eq!(generation, 0);
}
_ => panic!("expected CandidateUpdate"),
}
// Second re_gather increments generation
let (candidates2, signal2) = agent.re_gather().await;
assert_eq!(candidates2.generation, 1);
match signal2 {
SignalMessage::CandidateUpdate { generation, .. } => {
assert_eq!(generation, 1);
}
_ => panic!("expected CandidateUpdate"),
}
}
}

69
crates/wzp-client/src/lib.rs
View File

@@ -10,81 +10,18 @@
pub mod audio_io;
#[cfg(feature = "audio")]
pub mod audio_ring;
// VoiceProcessingIO is an Apple Core Audio API — only compile the module
// when the `vpio` feature is on AND we're targeting macOS. Enabling the
// feature on Windows/Linux was previously silently broken.
#[cfg(all(feature = "vpio", target_os = "macos"))]
#[cfg(feature = "vpio")]
pub mod audio_vpio;
// WASAPI-direct capture with Windows's OS-level AEC (AudioCategory_Communications).
// Only compiled when `windows-aec` feature is on AND target is Windows. The
// `windows` dependency is itself gated to Windows in Cargo.toml, so enabling
// this feature on non-Windows targets is a no-op.
#[cfg(all(feature = "windows-aec", target_os = "windows"))]
pub mod audio_wasapi;
// WebRTC AEC3 (Audio Processing Module) wrapper around CPAL capture + playback
// on Linux. Only compiled when `linux-aec` feature is on AND target is Linux.
// The webrtc-audio-processing dep is itself gated to Linux in Cargo.toml.
#[cfg(all(feature = "linux-aec", target_os = "linux"))]
pub mod audio_linux_aec;
pub mod bench;
pub mod call;
pub mod drift_test;
pub mod echo_test;
pub mod featherchat;
pub mod handshake;
pub mod dual_path;
pub mod metrics;
pub mod birthday;
pub mod ice_agent;
pub mod netcheck;
pub mod portmap;
pub mod reflect;
pub mod relay_map;
pub mod stun;
pub mod sweep;
// AudioPlayback: three possible backends depending on feature flags.
// 1. Default CPAL (`audio_io::AudioPlayback`) — baseline on every platform.
// 2. Linux AEC (`audio_linux_aec::LinuxAecPlayback`) — CPAL + WebRTC APM
// render-side tee, so echo from speakers gets cancelled from the mic.
//
// On macOS and Windows we always use the default CPAL playback because:
// - macOS: VoiceProcessingIO handles AEC at the capture side (Apple's
// native hardware AEC uses its own reference signal handling).
// - Windows: WASAPI AudioCategory_Communications AEC uses the system
// render mix as reference — no per-process plumbing needed.
//
// Linux is the only platform where the in-app approach is necessary, so
// the AEC playback path is gated to target_os = "linux".
#[cfg(all(
feature = "audio",
any(not(feature = "linux-aec"), not(target_os = "linux"))
))]
pub use audio_io::AudioPlayback;
#[cfg(all(feature = "linux-aec", target_os = "linux"))]
pub use audio_linux_aec::LinuxAecPlayback as AudioPlayback;
// AudioCapture: three possible backends depending on feature flags.
// 1. Default CPAL (`audio_io::AudioCapture`) — baseline on every platform.
// 2. Windows AEC (`audio_wasapi::WasapiAudioCapture`) — direct WASAPI
// with AudioCategory_Communications, OS APO chain does AEC.
// 3. Linux AEC (`audio_linux_aec::LinuxAecCapture`) — CPAL + WebRTC APM
// capture-side echo cancellation using the playback tee as reference.
// All three expose the same public API (`start`, `ring`, `stop`, `Drop`).
#[cfg(all(
feature = "audio",
any(not(feature = "windows-aec"), not(target_os = "windows")),
any(not(feature = "linux-aec"), not(target_os = "linux"))
))]
pub use audio_io::AudioCapture;
#[cfg(all(feature = "windows-aec", target_os = "windows"))]
pub use audio_wasapi::WasapiAudioCapture as AudioCapture;
#[cfg(all(feature = "linux-aec", target_os = "linux"))]
pub use audio_linux_aec::LinuxAecCapture as AudioCapture;
#[cfg(feature = "audio")]
pub use audio_io::{AudioCapture, AudioPlayback};
pub use call::{CallConfig, CallDecoder, CallEncoder};
pub use handshake::perform_handshake;

524
crates/wzp-client/src/netcheck.rs
View File

@@ -1,524 +0,0 @@
//! Phase 8 (Tailscale-inspired): Comprehensive network diagnostic.
//!
//! Probes STUN servers, relay infrastructure, port mapping
//! capabilities, IPv6 reachability, and NAT hairpinning in parallel
//! to produce a `NetcheckReport` that captures the client's network
//! environment at a point in time.
//!
//! Used for:
//! - Troubleshooting connectivity issues
//! - Automatic relay selection (Phase 5)
//! - Pre-call NAT assessment
//! - Quality prediction
use std::net::SocketAddr;
use std::time::{Duration, Instant};
use serde::Serialize;
use crate::portmap::{self, PortMapProtocol};
use crate::reflect::{self, NatType};
use crate::stun::{self, StunConfig};
/// Complete network diagnostic report.
#[derive(Debug, Clone, Serialize)]
pub struct NetcheckReport {
/// NAT type classification (from combined STUN + relay probes).
pub nat_type: NatType,
/// Server-reflexive address (consensus from probes).
pub reflexive_addr: Option<String>,
/// Whether IPv4 connectivity is available.
pub ipv4_reachable: bool,
/// Whether IPv6 connectivity is available.
pub ipv6_reachable: bool,
/// Whether the NAT supports hairpinning (loopback to own
/// reflexive address).
pub hairpin_works: Option<bool>,
/// Which port mapping protocol is available (if any).
pub port_mapping: Option<PortMapProtocol>,
/// Per-relay latency measurements.
pub relay_latencies: Vec<RelayLatency>,
/// Preferred relay (lowest latency).
pub preferred_relay: Option<String>,
/// STUN latency to first responding server (ms).
pub stun_latency_ms: Option<u32>,
/// Whether UPnP is available on the gateway.
pub upnp_available: bool,
/// Whether PCP is available on the gateway.
pub pcp_available: bool,
/// Whether NAT-PMP is available on the gateway.
pub nat_pmp_available: bool,
/// Default gateway address.
pub gateway: Option<String>,
/// Total time taken for the diagnostic (ms).
pub duration_ms: u32,
/// Individual STUN probe results.
pub stun_probes: Vec<reflect::NatProbeResult>,
/// NAT port allocation pattern (sequential vs random).
pub port_allocation: Option<stun::PortAllocation>,
}
/// Latency to a specific relay.
#[derive(Debug, Clone, Serialize)]
pub struct RelayLatency {
pub name: String,
pub addr: String,
pub rtt_ms: Option<u32>,
pub error: Option<String>,
}
/// Configuration for the netcheck run.
#[derive(Debug, Clone)]
pub struct NetcheckConfig {
/// STUN servers to probe.
pub stun_config: StunConfig,
/// Relay servers to probe (name, address pairs).
pub relays: Vec<(String, SocketAddr)>,
/// Per-probe timeout.
pub timeout: Duration,
/// Whether to test port mapping.
pub test_portmap: bool,
/// Whether to test IPv6.
pub test_ipv6: bool,
/// Local port for port mapping test (0 = skip).
pub local_port: u16,
}
impl Default for NetcheckConfig {
fn default() -> Self {
Self {
stun_config: StunConfig::default(),
relays: Vec::new(),
timeout: Duration::from_secs(5),
test_portmap: true,
test_ipv6: true,
local_port: 0,
}
}
}
/// Run a comprehensive network diagnostic.
///
/// Probes run in parallel for speed — the total time is bounded
/// by the slowest individual probe, not the sum.
pub async fn run_netcheck(config: &NetcheckConfig) -> NetcheckReport {
let start = Instant::now();
// Run all probes in parallel.
let stun_fut = stun::probe_stun_servers(&config.stun_config);
let relay_fut = probe_relays(&config.relays, config.timeout);
let portmap_fut = probe_portmap(config.test_portmap, config.local_port);
let gateway_fut = portmap::default_gateway();
let ipv6_fut = test_ipv6(config.test_ipv6, config.timeout);
let port_alloc_fut = stun::detect_port_allocation(&config.stun_config);
let (stun_probes, relay_latencies, portmap_result, gateway_result, ipv6_reachable, port_alloc_result) =
tokio::join!(stun_fut, relay_fut, portmap_fut, gateway_result_fut(gateway_fut), ipv6_fut, port_alloc_fut);
// Classify NAT from STUN probes.
let (nat_type, consensus_addr) = reflect::classify_nat(&stun_probes);
// Determine STUN latency (first successful probe).
let stun_latency_ms = stun_probes
.iter()
.filter_map(|p| p.latency_ms)
.min();
// IPv4 reachable if any STUN probe succeeded.
let ipv4_reachable = stun_probes
.iter()
.any(|p| p.observed_addr.is_some());
// Preferred relay = lowest RTT.
let preferred_relay = relay_latencies
.iter()
.filter_map(|r| r.rtt_ms.map(|rtt| (r.name.clone(), rtt)))
.min_by_key(|(_, rtt)| *rtt)
.map(|(name, _)| name);
// Port mapping availability.
let (port_mapping, nat_pmp_available, pcp_available, upnp_available) = match portmap_result {
Some(mapping) => {
let proto = mapping.protocol;
(
Some(proto),
proto == PortMapProtocol::NatPmp,
proto == PortMapProtocol::Pcp,
proto == PortMapProtocol::UPnP,
)
}
None => (None, false, false, false),
};
let gateway = match gateway_result {
Ok(gw) => Some(gw.to_string()),
Err(_) => None,
};
NetcheckReport {
nat_type,
reflexive_addr: consensus_addr,
ipv4_reachable,
ipv6_reachable,
hairpin_works: None, // TODO: implement hairpin test
port_mapping,
relay_latencies,
preferred_relay,
stun_latency_ms,
upnp_available,
pcp_available,
nat_pmp_available,
gateway,
duration_ms: start.elapsed().as_millis() as u32,
stun_probes,
port_allocation: Some(port_alloc_result.allocation),
}
}
/// Probe relay latencies via reflect.
async fn probe_relays(
relays: &[(String, SocketAddr)],
timeout: Duration,
) -> Vec<RelayLatency> {
if relays.is_empty() {
return Vec::new();
}
let timeout_ms = timeout.as_millis() as u64;
let mut set = tokio::task::JoinSet::new();
for (name, addr) in relays {
let name = name.clone();
let addr = *addr;
set.spawn(async move {
let start = Instant::now();
match reflect::probe_reflect_addr(addr, timeout_ms, None).await {
Ok((_observed, _latency)) => RelayLatency {
name,
addr: addr.to_string(),
rtt_ms: Some(start.elapsed().as_millis() as u32),
error: None,
},
Err(e) => RelayLatency {
name,
addr: addr.to_string(),
rtt_ms: None,
error: Some(e),
},
}
});
}
let mut results = Vec::with_capacity(relays.len());
while let Some(join_result) = set.join_next().await {
match join_result {
Ok(r) => results.push(r),
Err(_) => {}
}
}
// Sort by RTT (lowest first).
results.sort_by_key(|r| r.rtt_ms.unwrap_or(u32::MAX));
results
}
/// Attempt port mapping and return the mapping if successful.
async fn probe_portmap(
enabled: bool,
local_port: u16,
) -> Option<portmap::PortMapping> {
if !enabled || local_port == 0 {
return None;
}
portmap::acquire_port_mapping(local_port, None).await.ok()
}
/// Wrap the gateway future to handle the Result.
async fn gateway_result_fut(
fut: impl std::future::Future<Output = Result<std::net::Ipv4Addr, portmap::PortMapError>>,
) -> Result<std::net::Ipv4Addr, portmap::PortMapError> {
fut.await
}
/// Test IPv6 connectivity by attempting to bind and send on an IPv6 socket.
async fn test_ipv6(enabled: bool, timeout: Duration) -> bool {
if !enabled {
return false;
}
// Try to resolve and connect to an IPv6 STUN server.
let result = tokio::time::timeout(timeout, async {
let sock = tokio::net::UdpSocket::bind("[::]:0").await.ok()?;
// Try Google's IPv6 STUN — if DNS resolves to an AAAA record
// and we can send a packet, IPv6 is working.
let addr = stun::resolve_stun_server("stun.l.google.com:19302").await.ok()?;
if addr.is_ipv6() {
sock.send_to(&[0u8; 1], addr).await.ok()?;
Some(true)
} else {
// Server resolved to IPv4 — try binding to [::] at least
Some(false)
}
})
.await;
match result {
Ok(Some(true)) => true,
_ => {
// Fallback: can we at least bind an IPv6 socket?
tokio::net::UdpSocket::bind("[::]:0").await.is_ok()
}
}
}
/// Format a netcheck report as a human-readable string.
pub fn format_report(report: &NetcheckReport) -> String {
let mut out = String::new();
out.push_str(&format!("=== WarzonePhone Netcheck ===\n\n"));
out.push_str(&format!(
"NAT Type: {:?}\n",
report.nat_type
));
out.push_str(&format!(
"Reflexive Addr: {}\n",
report.reflexive_addr.as_deref().unwrap_or("(unknown)")
));
out.push_str(&format!(
"IPv4: {}\n",
if report.ipv4_reachable { "yes" } else { "no" }
));
out.push_str(&format!(
"IPv6: {}\n",
if report.ipv6_reachable { "yes" } else { "no" }
));
out.push_str(&format!(
"Gateway: {}\n",
report.gateway.as_deref().unwrap_or("(unknown)")
));
if let Some(ref alloc) = report.port_allocation {
out.push_str(&format!(
"Port Alloc: {alloc}\n"
));
}
out.push_str(&format!("\n--- Port Mapping ---\n"));
out.push_str(&format!(
"NAT-PMP: {} PCP: {} UPnP: {}\n",
if report.nat_pmp_available { "yes" } else { "no" },
if report.pcp_available { "yes" } else { "no" },
if report.upnp_available { "yes" } else { "no" },
));
if let Some(proto) = &report.port_mapping {
out.push_str(&format!("Active mapping: {:?}\n", proto));
}
if !report.stun_probes.is_empty() {
out.push_str(&format!("\n--- STUN Probes ---\n"));
for p in &report.stun_probes {
out.push_str(&format!(
" {} → {} ({}ms){}\n",
p.relay_name,
p.observed_addr.as_deref().unwrap_or("failed"),
p.latency_ms.map(|ms| ms.to_string()).unwrap_or_else(|| "-".into()),
p.error.as_ref().map(|e| format!(" [{e}]")).unwrap_or_default(),
));
}
}
if !report.relay_latencies.is_empty() {
out.push_str(&format!("\n--- Relay Latencies ---\n"));
for r in &report.relay_latencies {
out.push_str(&format!(
" {} ({}) → {}ms{}\n",
r.name,
r.addr,
r.rtt_ms.map(|ms| ms.to_string()).unwrap_or_else(|| "-".into()),
r.error.as_ref().map(|e| format!(" [{e}]")).unwrap_or_default(),
));
}
if let Some(ref pref) = report.preferred_relay {
out.push_str(&format!(" Preferred: {pref}\n"));
}
}
out.push_str(&format!("\nCompleted in {}ms\n", report.duration_ms));
out
}
// ── Tests ──────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn default_config_has_stun_servers() {
let config = NetcheckConfig::default();
assert!(!config.stun_config.servers.is_empty());
}
#[test]
fn format_report_produces_output() {
let report = NetcheckReport {
nat_type: NatType::Cone,
reflexive_addr: Some("203.0.113.5:4433".into()),
ipv4_reachable: true,
ipv6_reachable: false,
hairpin_works: None,
port_mapping: None,
relay_latencies: vec![RelayLatency {
name: "relay-1".into(),
addr: "10.0.0.1:4433".into(),
rtt_ms: Some(25),
error: None,
}],
preferred_relay: Some("relay-1".into()),
stun_latency_ms: Some(15),
upnp_available: false,
pcp_available: false,
nat_pmp_available: false,
gateway: Some("192.168.1.1".into()),
duration_ms: 1500,
stun_probes: vec![],
port_allocation: None,
};
let text = format_report(&report);
assert!(text.contains("Cone"));
assert!(text.contains("203.0.113.5:4433"));
assert!(text.contains("relay-1"));
assert!(text.contains("1500ms"));
}
#[test]
fn report_serializes_to_json() {
let report = NetcheckReport {
nat_type: NatType::Cone,
reflexive_addr: Some("203.0.113.5:4433".into()),
ipv4_reachable: true,
ipv6_reachable: false,
hairpin_works: None,
port_mapping: Some(PortMapProtocol::NatPmp),
relay_latencies: vec![],
preferred_relay: None,
stun_latency_ms: Some(25),
upnp_available: false,
pcp_available: false,
nat_pmp_available: true,
gateway: Some("192.168.1.1".into()),
duration_ms: 500,
stun_probes: vec![],
port_allocation: Some(stun::PortAllocation::Sequential { delta: 1 }),
};
let json = serde_json::to_string(&report).unwrap();
assert!(json.contains("Cone"));
assert!(json.contains("203.0.113.5:4433"));
assert!(json.contains("NatPmp"));
// Roundtrip
let decoded: serde_json::Value = serde_json::from_str(&json).unwrap();
assert_eq!(decoded["ipv4_reachable"], true);
assert_eq!(decoded["ipv6_reachable"], false);
assert_eq!(decoded["stun_latency_ms"], 25);
}
#[test]
fn relay_latency_serializes() {
let lat = RelayLatency {
name: "eu-west".into(),
addr: "10.0.0.1:4433".into(),
rtt_ms: Some(42),
error: None,
};
let json = serde_json::to_string(&lat).unwrap();
assert!(json.contains("eu-west"));
assert!(json.contains("42"));
}
#[test]
fn format_report_empty_relays() {
let report = NetcheckReport {
nat_type: NatType::Unknown,
reflexive_addr: None,
ipv4_reachable: false,
ipv6_reachable: false,
hairpin_works: None,
port_mapping: None,
relay_latencies: vec![],
preferred_relay: None,
stun_latency_ms: None,
upnp_available: false,
pcp_available: false,
nat_pmp_available: false,
gateway: None,
duration_ms: 100,
stun_probes: vec![],
port_allocation: None,
};
let text = format_report(&report);
assert!(text.contains("Unknown"));
assert!(text.contains("(unknown)")); // reflexive addr
assert!(text.contains("100ms"));
}
#[test]
fn format_report_with_stun_probes() {
let report = NetcheckReport {
nat_type: NatType::SymmetricPort,
reflexive_addr: None,
ipv4_reachable: true,
ipv6_reachable: true,
hairpin_works: Some(false),
port_mapping: Some(PortMapProtocol::UPnP),
relay_latencies: vec![
RelayLatency {
name: "us-east".into(),
addr: "10.0.0.1:4433".into(),
rtt_ms: Some(15),
error: None,
},
RelayLatency {
name: "eu-west".into(),
addr: "10.0.0.2:4433".into(),
rtt_ms: None,
error: Some("timeout".into()),
},
],
preferred_relay: Some("us-east".into()),
stun_latency_ms: Some(20),
upnp_available: true,
pcp_available: false,
nat_pmp_available: false,
gateway: Some("192.168.0.1".into()),
duration_ms: 3000,
stun_probes: vec![reflect::NatProbeResult {
relay_name: "stun:google".into(),
relay_addr: "74.125.250.129:19302".into(),
observed_addr: Some("203.0.113.5:12345".into()),
latency_ms: Some(20),
error: None,
}],
port_allocation: Some(stun::PortAllocation::Random),
};
let text = format_report(&report);
assert!(text.contains("SymmetricPort"));
assert!(text.contains("us-east"));
assert!(text.contains("eu-west"));
assert!(text.contains("Preferred: us-east"));
assert!(text.contains("UPnP: yes"));
assert!(text.contains("stun:google"));
assert!(text.contains("3000ms"));
}
/// Integration test: run actual netcheck (requires network).
#[tokio::test]
#[ignore]
async fn integration_netcheck() {
let config = NetcheckConfig::default();
let report = run_netcheck(&config).await;
println!("{}", format_report(&report));
assert!(report.duration_ms > 0);
}
}

1163
crates/wzp-client/src/portmap.rs
View File

File diff suppressed because it is too large Load Diff

713
crates/wzp-client/src/reflect.rs
View File

@@ -1,713 +0,0 @@
//! Multi-relay NAT reflection ("STUN for QUIC" — Phase 2).
//!
//! Phase 1 (`SignalMessage::Reflect` / `ReflectResponse`) lets a
//! client ask a single relay "what source address do you see for
//! me?". Phase 2 queries N relays in parallel and classifies the
//! results into a NAT type so the future P2P hole-punching path
//! can decide whether a direct QUIC handshake is viable:
//!
//! - All relays return the same `(ip, port)` → **Cone NAT**.
//! Endpoint-independent mapping, P2P hole-punching viable,
//! `consensus_addr` is the one address to advertise.
//! - Same ip, different ports → **Symmetric port-dependent NAT**.
//! The mapping changes per destination, so the advertised addr
//! wouldn't match what a peer actually sees; fall back to
//! relay-mediated path.
//! - Different ips → multi-homed / anycast / broken DNS, treat as
//! `Multiple` and do not attempt P2P.
//! - 0 or 1 successful probes → `Unknown`, not enough data.
//!
//! A probe is a throwaway QUIC signal connection: open endpoint,
//! connect, RegisterPresence (with a zero identity — the relay
//! accepts this exactly like the main signaling path does), send
//! Reflect, read ReflectResponse, close. Each probe gets its own
//! ephemeral quinn::Endpoint so the OS assigns a fresh source port
//! per relay — if we shared one endpoint across probes, a
//! symmetric NAT in front of the client would map every probe to
//! the same port and we couldn't detect it.
use std::net::SocketAddr;
use std::time::{Duration, Instant};
use serde::Serialize;
use wzp_proto::{MediaTransport, SignalMessage};
use wzp_transport::{client_config, create_endpoint, QuinnTransport};
/// Result of one probe against one relay. Always returned so the
/// UI can render per-relay status even when some fail.
#[derive(Debug, Clone, Serialize)]
pub struct NatProbeResult {
pub relay_name: String,
pub relay_addr: String,
/// `Some` on successful probe, `None` on failure.
pub observed_addr: Option<String>,
/// End-to-end wall-clock from connect start to ReflectResponse
/// received, in milliseconds. `Some` only on success.
pub latency_ms: Option<u32>,
/// Human-readable error on failure.
pub error: Option<String>,
}
/// Aggregated classification over N `NatProbeResult`s.
#[derive(Debug, Clone, Serialize)]
pub struct NatDetection {
pub probes: Vec<NatProbeResult>,
pub nat_type: NatType,
/// When `nat_type == Cone`, the one address all probes agreed
/// on. `None` for every other case.
pub consensus_addr: Option<String>,
}
/// NAT classification. See module doc for semantics.
#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
pub enum NatType {
Cone,
SymmetricPort,
Multiple,
Unknown,
}
/// Probe a single relay with a QUIC connection.
///
/// # Endpoint reuse (Phase 5 — Nebula-style architecture)
///
/// If `existing_endpoint` is `Some`, the probe uses that socket
/// instead of creating a fresh one. This is the desired mode in
/// production: a port-preserving NAT (MikroTik masquerade, most
/// consumer routers) gives a **stable** external port for the
/// one socket, so the reflex addr observed by ANY relay is the
/// SAME addr and matches what a peer would see on a direct dial.
/// Pass the signal endpoint here.
///
/// If `None`, creates a fresh one-shot endpoint. Kept for:
/// - tests that spin up isolated probes
/// - the "I'm not registered yet" case where there's no signal
/// endpoint to reuse
///
/// NOTE on NAT-type detection: the pre-Phase-5 behavior of
/// forcing a fresh endpoint per probe was wrong — it made every
/// port-preserving NAT look symmetric because the classifier saw
/// a different external port for each fresh source port. With
/// one shared socket, the classifier reflects the REAL NAT
/// behavior.
pub async fn probe_reflect_addr(
relay: SocketAddr,
timeout_ms: u64,
existing_endpoint: Option<wzp_transport::Endpoint>,
) -> Result<(SocketAddr, u32), String> {
// Install rustls provider idempotently — a second install on the
// same thread is a no-op.
let _ = rustls::crypto::ring::default_provider().install_default();
let endpoint = match existing_endpoint {
Some(ep) => ep,
None => {
let bind: SocketAddr = "0.0.0.0:0".parse().unwrap();
create_endpoint(bind, None).map_err(|e| format!("endpoint: {e}"))?
}
};
let start = Instant::now();
let probe = async {
// Open the signal connection.
let conn =
wzp_transport::connect(&endpoint, relay, "_signal", client_config())
.await
.map_err(|e| format!("connect: {e}"))?;
let transport = QuinnTransport::new(conn);
// The relay signal handler waits for a RegisterPresence
// before entering its main dispatch loop (see
// wzp-relay/src/main.rs). So a transient probe has to
// register with a zero identity first — the relay accepts
// the empty-signature form exactly as the main signaling
// path does in desktop/src-tauri/src/lib.rs register_signal.
transport
.send_signal(&SignalMessage::RegisterPresence {
identity_pub: [0u8; 32],
signature: vec![],
alias: None,
})
.await
.map_err(|e| format!("send RegisterPresence: {e}"))?;
// Drain the RegisterPresenceAck so the response to our
// Reflect doesn't land on an unexpected stream order.
match transport.recv_signal().await {
Ok(Some(SignalMessage::RegisterPresenceAck { success: true, .. })) => {}
Ok(Some(other)) => {
return Err(format!(
"unexpected pre-reflect signal: {:?}",
std::mem::discriminant(&other)
));
}
Ok(None) => return Err("connection closed before RegisterPresenceAck".into()),
Err(e) => return Err(format!("recv RegisterPresenceAck: {e}")),
}
// Send Reflect and await response.
transport
.send_signal(&SignalMessage::Reflect)
.await
.map_err(|e| format!("send Reflect: {e}"))?;
match transport.recv_signal().await {
Ok(Some(SignalMessage::ReflectResponse { observed_addr })) => {
let parsed: SocketAddr = observed_addr
.parse()
.map_err(|e| format!("parse observed_addr {observed_addr:?}: {e}"))?;
let latency_ms = start.elapsed().as_millis() as u32;
// Clean close so the relay's per-connection cleanup
// runs promptly and we don't leak file descriptors.
let _ = transport.close().await;
Ok((parsed, latency_ms))
}
Ok(Some(other)) => Err(format!(
"expected ReflectResponse, got {:?}",
std::mem::discriminant(&other)
)),
Ok(None) => Err("connection closed before ReflectResponse".into()),
Err(e) => Err(format!("recv ReflectResponse: {e}")),
}
};
let out = tokio::time::timeout(Duration::from_millis(timeout_ms), probe)
.await
.map_err(|_| format!("probe timeout ({timeout_ms}ms)"))??;
// `endpoint` is a quinn::Endpoint clone — an Arc under the
// hood. Letting it drop at end-of-scope is correct whether it
// was fresh (last ref → socket closes) or shared (ref count
// decrements, socket stays alive for the signal loop).
Ok(out)
}
/// Detect the client's NAT type by probing N relays in parallel and
/// classifying the returned addresses. Never errors — failing
/// probes surface via `NatProbeResult.error`; aggregate is always
/// returned.
///
/// # Endpoint reuse (Phase 5)
///
/// If `shared_endpoint` is `Some`, every probe reuses it. This is
/// the PRODUCTION behavior: all probes source from the same UDP
/// port, so port-preserving NATs map them to the same external
/// port, and the classifier reflects the real NAT type. Pass the
/// signal endpoint.
///
/// If `None`, each probe creates its own fresh endpoint — useful
/// in tests that don't have a signal endpoint, but produces
/// spurious `SymmetricPort` classifications against NATs that
/// would otherwise look cone-like.
pub async fn detect_nat_type(
relays: Vec<(String, SocketAddr)>,
timeout_ms: u64,
shared_endpoint: Option<wzp_transport::Endpoint>,
) -> NatDetection {
// Parallel probes via tokio::task::JoinSet so the wall-clock is
// bounded by the slowest probe, not the sum. JoinSet keeps the
// dep surface at just tokio — we already depend on it.
let mut set = tokio::task::JoinSet::new();
for (name, addr) in relays {
let ep = shared_endpoint.clone();
set.spawn(async move {
let result = probe_reflect_addr(addr, timeout_ms, ep).await;
(name, addr, result)
});
}
let mut probes = Vec::new();
while let Some(join_result) = set.join_next().await {
let (name, addr, result) = match join_result {
Ok(tuple) => tuple,
// Task panicked — surface as a synthetic failed probe so
// the aggregate still returns a reasonable shape. This
// shouldn't happen but we don't want one bad probe to
// poison the whole detection.
Err(join_err) => {
probes.push(NatProbeResult {
relay_name: "<panicked>".into(),
relay_addr: "unknown".into(),
observed_addr: None,
latency_ms: None,
error: Some(format!("probe task panicked: {join_err}")),
});
continue;
}
};
probes.push(match result {
Ok((observed, latency_ms)) => NatProbeResult {
relay_name: name,
relay_addr: addr.to_string(),
observed_addr: Some(observed.to_string()),
latency_ms: Some(latency_ms),
error: None,
},
Err(e) => NatProbeResult {
relay_name: name,
relay_addr: addr.to_string(),
observed_addr: None,
latency_ms: None,
error: Some(e),
},
});
}
let (nat_type, consensus_addr) = classify_nat(&probes);
NatDetection {
probes,
nat_type,
consensus_addr,
}
}
/// Enumerate LAN-local host candidates this client is reachable
/// on, paired with the given port (typically the signal
/// endpoint's bound port so that incoming dials land on the same
/// socket the advertised reflex addr points to).
///
/// Gathers BOTH IPv4 and IPv6 candidates:
///
/// - **IPv4**: RFC1918 private ranges (10/8, 172.16/12, 192.168/16)
/// and CGNAT shared-transition (100.64/10). Public IPv4 is
/// skipped because the reflex-addr path already covers it.
/// Loopback and link-local (169.254/16) are skipped.
///
/// - **IPv6**: ALL global-unicast addresses (2000::/3 — the real
/// routable IPv6 space) AND unique-local (fc00::/7). These
/// are directly dialable from a peer on the same LAN, and on
/// true dual-stack LANs (which most consumer ISPs now provide,
/// including Starlink) IPv6 often gives a direct path even
/// when IPv4 can't hairpin. Loopback (::1), unspecified (::),
/// and link-local (fe80::/10) are skipped — link-local would
/// require a scope ID to be useful and is basically never
/// reachable across interface boundaries.
///
/// The port must come from the caller — typically
/// `signal_endpoint.local_addr()?.port()`, so that the peer's
/// dials to these addresses land on the same socket that's
/// already listening (Phase 5 shared-endpoint architecture).
///
/// Safe to call from any thread; no I/O, no async. The `if-addrs`
/// crate reads the kernel's interface table via a single
/// getifaddrs(3) syscall.
pub fn local_host_candidates(v4_port: u16, v6_port: Option<u16>) -> Vec<SocketAddr> {
let Ok(ifaces) = if_addrs::get_if_addrs() else {
return Vec::new();
};
let mut out = Vec::new();
for iface in ifaces {
if iface.is_loopback() {
continue;
}
match iface.ip() {
std::net::IpAddr::V4(v4) => {
if v4.is_link_local() {
continue;
}
// Keep RFC1918 private ranges and CGNAT — those
// are the LAN-dialable addrs we actually want.
// Skip public v4 because the reflex addr already
// covers that path.
if v4.is_private() {
out.push(SocketAddr::new(std::net::IpAddr::V4(v4), v4_port));
} else if v4.octets()[0] == 100 && (v4.octets()[1] & 0xc0) == 0x40 {
// 100.64/10 CGNAT — rare but valid if two
// phones are on the same CGNAT-hairpinned
// carrier LAN (some hotspot setups).
out.push(SocketAddr::new(std::net::IpAddr::V4(v4), v4_port));
}
}
std::net::IpAddr::V6(v6) => {
// Phase 7: IPv6 host candidates via dedicated
// IPv6 socket. When v6_port is None, no IPv6
// endpoint exists — skip silently.
let Some(port) = v6_port else { continue };
if v6.is_loopback() || v6.is_unspecified() {
continue;
}
// fe80::/10 link-local — needs scope ID, not
// routable across interfaces.
if (v6.segments()[0] & 0xffc0) == 0xfe80 {
continue;
}
// Accept global unicast (2000::/3) and
// unique-local (fc00::/7).
let first_seg = v6.segments()[0];
let is_global = (first_seg & 0xe000) == 0x2000;
let is_ula = (first_seg & 0xfe00) == 0xfc00;
if is_global || is_ula {
out.push(SocketAddr::new(std::net::IpAddr::V6(v6), port));
}
}
}
}
out
}
/// Role assignment for the Phase 3.5 dual-path QUIC race.
///
/// Both peers already know two strings at CallSetup time: their
/// own server-reflexive address (queried via Phase 1 Reflect) and
/// the peer's (carried in `CallSetup.peer_direct_addr`). To avoid
/// a negotiation round-trip, both sides compare the two strings
/// lexicographically and agree on a deterministic role:
///
/// - **Acceptor** — lexicographically smaller addr. Listens for
/// an incoming direct connection from the peer. Does NOT dial.
/// - **Dialer** — lexicographically larger addr. Dials the
/// peer's direct addr. Does NOT listen.
///
/// Both roles ALSO dial the relay in parallel as a fallback.
/// Whichever future (direct or relay) completes first is used as
/// the media transport. Because the role is deterministic and
/// symmetric, both peers end up holding the same underlying QUIC
/// session on the direct path — A's accepted conn and D's dialed
/// conn are literally the same connection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Role {
/// This peer listens for the direct incoming connection.
Acceptor,
/// This peer dials the peer's direct address.
Dialer,
}
/// Compute the deterministic role for this peer in the dual-path
/// race. Returns `None` when no direct attempt is possible —
/// either peer didn't advertise a reflex addr, or the two addrs
/// are identical (same host on loopback / mis-advertised).
///
/// The caller should treat `None` as "skip direct, relay-only".
pub fn determine_role(
own_reflex_addr: Option<&str>,
peer_reflex_addr: Option<&str>,
) -> Option<Role> {
let (own, peer) = match (own_reflex_addr, peer_reflex_addr) {
(Some(o), Some(p)) => (o, p),
_ => return None,
};
match own.cmp(peer) {
std::cmp::Ordering::Less => Some(Role::Acceptor),
std::cmp::Ordering::Greater => Some(Role::Dialer),
// Equal addrs should never happen in production (both
// peers behind the same NAT mapping + same port would be
// a degenerate case). Guard against it so we don't infinite-
// loop waiting for a connection to ourselves.
std::cmp::Ordering::Equal => None,
}
}
/// Returns `true` if the address is in an RFC1918 / link-local /
/// loopback range and therefore cannot possibly be a post-NAT
/// reflex address from the public internet's point of view.
///
/// A probe against a relay ON THE SAME LAN as the client will
/// naturally report the client's LAN IP back (because there's no
/// NAT between them) — that observation is real but says nothing
/// about the client's public-internet-facing NAT state. Mixing
/// LAN reflex addrs with public-internet reflex addrs in
/// `classify_nat` would always report `Multiple` (different IPs)
/// and falsely warn about symmetric NAT. Filter them out before
/// classifying.
fn is_private_or_loopback(addr: &SocketAddr) -> bool {
match addr.ip() {
std::net::IpAddr::V4(v4) => {
let o = v4.octets();
v4.is_loopback()
|| v4.is_private() // 10/8, 172.16/12, 192.168/16
|| v4.is_link_local() // 169.254/16
|| (o[0] == 100 && (o[1] & 0xc0) == 0x40) // 100.64/10 CGNAT shared
}
std::net::IpAddr::V6(v6) => {
v6.is_loopback() || v6.is_unspecified() || (v6.segments()[0] & 0xffc0) == 0xfe80 // fe80::/10 link-local
}
}
}
/// Pure-function NAT classifier — split out for unit testing
/// without touching the network.
///
/// Only considers probes whose reflex addr is a **public-internet**
/// address. LAN / private / loopback reflex addrs are dropped
/// because they reflect the same-network path rather than the
/// real NAT state. CGNAT (100.64/10) is also treated as private
/// because the post-CGNAT address would be what we actually want
/// to classify on — but CGNAT is unreachable from outside the
/// carrier, so a relay seeing the CGNAT addr is on the same
/// carrier network and again not useful for classification.
pub fn classify_nat(probes: &[NatProbeResult]) -> (NatType, Option<String>) {
// First: parse every successful probe's observed addr.
let parsed: Vec<SocketAddr> = probes
.iter()
.filter_map(|p| p.observed_addr.as_deref().and_then(|s| s.parse().ok()))
.collect();
// Then: drop LAN / private / loopback reflex addrs. Those are
// legitimate observations by same-network relays, but they
// don't contribute to NAT-type classification because the
// client's real public-facing NAT mapping is not involved on
// that path. A relay on the same LAN always sees the client's
// LAN IP, regardless of whether the NAT beyond it is cone or
// symmetric.
let successes: Vec<SocketAddr> = parsed
.into_iter()
.filter(|a| !is_private_or_loopback(a))
.collect();
if successes.len() < 2 {
return (NatType::Unknown, None);
}
let first = successes[0];
let same_ip = successes.iter().all(|a| a.ip() == first.ip());
if !same_ip {
return (NatType::Multiple, None);
}
let same_port = successes.iter().all(|a| a.port() == first.port());
if same_port {
(NatType::Cone, Some(first.to_string()))
} else {
(NatType::SymmetricPort, None)
}
}
/// Enhanced NAT detection that combines relay-based reflection with
/// public STUN server probes for more robust classification.
///
/// Runs both probe sets concurrently:
/// 1. Relay probes via `detect_nat_type` (existing behavior)
/// 2. Public STUN probes via `probe_stun_servers`
///
/// Merges all results and classifies. More probes = higher confidence
/// in the NAT type classification. Falls back gracefully: if STUN
/// servers are unreachable, relay probes still work (and vice versa).
pub async fn detect_nat_type_with_stun(
relays: Vec<(String, SocketAddr)>,
timeout_ms: u64,
shared_endpoint: Option<wzp_transport::Endpoint>,
stun_config: &crate::stun::StunConfig,
) -> NatDetection {
// Run relay probes and STUN probes concurrently.
let relay_fut = detect_nat_type(relays, timeout_ms, shared_endpoint);
let stun_fut = crate::stun::probe_stun_servers(stun_config);
let (relay_detection, stun_probes) = tokio::join!(relay_fut, stun_fut);
// Merge all probes and re-classify.
let mut all_probes = relay_detection.probes;
all_probes.extend(stun_probes);
let (nat_type, consensus_addr) = classify_nat(&all_probes);
NatDetection {
probes: all_probes,
nat_type,
consensus_addr,
}
}
// ── Unit tests for the pure classifier ───────────────────────────
#[cfg(test)]
mod tests {
use super::*;
fn mk(addr: Option<&str>) -> NatProbeResult {
NatProbeResult {
relay_name: "test".into(),
relay_addr: "0.0.0.0:0".into(),
observed_addr: addr.map(|s| s.to_string()),
latency_ms: addr.map(|_| 10),
error: None,
}
}
#[test]
fn classify_empty_is_unknown() {
let (nt, addr) = classify_nat(&[]);
assert_eq!(nt, NatType::Unknown);
assert!(addr.is_none());
}
#[test]
fn classify_single_success_is_unknown() {
let probes = vec![mk(Some("192.0.2.1:4433"))];
let (nt, addr) = classify_nat(&probes);
assert_eq!(nt, NatType::Unknown);
assert!(addr.is_none());
}
#[test]
fn classify_two_identical_is_cone() {
let probes = vec![
mk(Some("192.0.2.1:4433")),
mk(Some("192.0.2.1:4433")),
];
let (nt, addr) = classify_nat(&probes);
assert_eq!(nt, NatType::Cone);
assert_eq!(addr.as_deref(), Some("192.0.2.1:4433"));
}
#[test]
fn classify_same_ip_different_ports_is_symmetric() {
let probes = vec![
mk(Some("192.0.2.1:4433")),
mk(Some("192.0.2.1:51234")),
];
let (nt, addr) = classify_nat(&probes);
assert_eq!(nt, NatType::SymmetricPort);
assert!(addr.is_none());
}
#[test]
fn classify_different_ips_is_multiple() {
let probes = vec![
mk(Some("192.0.2.1:4433")),
mk(Some("198.51.100.9:4433")),
];
let (nt, addr) = classify_nat(&probes);
assert_eq!(nt, NatType::Multiple);
assert!(addr.is_none());
}
#[test]
fn classify_drops_private_ip_probes() {
// One LAN probe + one public probe should behave like a
// single public probe — i.e. Unknown (not enough data to
// classify). This is the common real-world case: the user
// has a LAN relay + an internet relay configured, the LAN
// relay sees the LAN IP, the internet relay sees the WAN
// IP, and the old classifier would flag "Multiple" and
// falsely warn about symmetric NAT.
let probes = vec![
mk(Some("192.168.1.100:4433")), // LAN — must be dropped
mk(Some("203.0.113.5:4433")), // public (TEST-NET-3)
];
let (nt, _) = classify_nat(&probes);
assert_eq!(nt, NatType::Unknown);
}
#[test]
fn classify_drops_loopback_probes() {
let probes = vec![
mk(Some("127.0.0.1:4433")), // loopback — must be dropped
mk(Some("203.0.113.5:4433")), // public
mk(Some("203.0.113.5:4433")), // public, same addr
];
let (nt, addr) = classify_nat(&probes);
// Two public probes with identical addrs → Cone.
assert_eq!(nt, NatType::Cone);
assert_eq!(addr.as_deref(), Some("203.0.113.5:4433"));
}
#[test]
fn classify_drops_cgnat_probes() {
// 100.64.0.0/10 is the CGNAT shared-transition range.
// Filter treats it like RFC1918 — a relay that sees the
// client with a 100.64/10 addr is on the same CGNAT
// network and can't contribute to public NAT classification.
let probes = vec![
mk(Some("100.64.0.42:4433")), // CGNAT — dropped
mk(Some("203.0.113.5:4433")), // public
mk(Some("203.0.113.5:12345")), // public, different port
];
let (nt, _) = classify_nat(&probes);
// Two public probes same IP different port → SymmetricPort.
assert_eq!(nt, NatType::SymmetricPort);
}
#[test]
fn classify_two_lan_probes_is_unknown_not_cone() {
// Even if both probes come back from LAN relays, we can't
// say anything useful about the public NAT state. Unknown,
// not Cone.
let probes = vec![
mk(Some("192.168.1.100:4433")),
mk(Some("192.168.1.100:4433")),
];
let (nt, addr) = classify_nat(&probes);
assert_eq!(nt, NatType::Unknown);
assert!(addr.is_none());
}
#[test]
fn classify_mix_of_success_and_failure() {
let probes = vec![
mk(Some("192.0.2.1:4433")),
mk(None), // failed probe
mk(Some("192.0.2.1:4433")),
];
let (nt, addr) = classify_nat(&probes);
// Two successes both agree → Cone, ignore the failure row.
assert_eq!(nt, NatType::Cone);
assert_eq!(addr.as_deref(), Some("192.0.2.1:4433"));
}
#[test]
fn determine_role_smaller_is_acceptor() {
// Lexicographic: "192.0.2.1:4433" < "198.51.100.9:4433"
assert_eq!(
determine_role(Some("192.0.2.1:4433"), Some("198.51.100.9:4433")),
Some(Role::Acceptor)
);
}
#[test]
fn determine_role_larger_is_dialer() {
assert_eq!(
determine_role(Some("198.51.100.9:4433"), Some("192.0.2.1:4433")),
Some(Role::Dialer)
);
}
#[test]
fn determine_role_port_difference_matters() {
// Same ip, different ports — string compare still works
// because "4433" < "54321".
assert_eq!(
determine_role(Some("127.0.0.1:4433"), Some("127.0.0.1:54321")),
Some(Role::Acceptor)
);
assert_eq!(
determine_role(Some("127.0.0.1:54321"), Some("127.0.0.1:4433")),
Some(Role::Dialer)
);
}
#[test]
fn determine_role_equal_addrs_is_none() {
assert_eq!(
determine_role(Some("192.0.2.1:4433"), Some("192.0.2.1:4433")),
None
);
}
#[test]
fn determine_role_missing_side_is_none() {
assert_eq!(determine_role(None, Some("192.0.2.1:4433")), None);
assert_eq!(determine_role(Some("192.0.2.1:4433"), None), None);
assert_eq!(determine_role(None, None), None);
}
#[test]
fn determine_role_is_symmetric_across_peers() {
// Both peers compute roles independently; they must end
// up with opposite assignments (one Acceptor, one Dialer)
// so that each side ends up talking to the other.
let a = "192.0.2.1:4433";
let b = "198.51.100.9:4433";
let alice_role = determine_role(Some(a), Some(b));
let bob_role = determine_role(Some(b), Some(a));
assert_eq!(alice_role, Some(Role::Acceptor));
assert_eq!(bob_role, Some(Role::Dialer));
}
#[test]
fn classify_one_success_one_failure_is_unknown() {
let probes = vec![mk(Some("192.0.2.1:4433")), mk(None)];
let (nt, addr) = classify_nat(&probes);
assert_eq!(nt, NatType::Unknown);
assert!(addr.is_none());
}
}

339
crates/wzp-client/src/relay_map.rs
View File

@@ -1,339 +0,0 @@
//! Phase 8 (Tailscale-inspired): Relay map for automatic relay
//! selection based on latency.
//!
//! Maintains a sorted list of known relays with their measured
//! latencies. Used during call setup to pick the lowest-latency
//! relay, and by netcheck to report relay health.
use std::net::SocketAddr;
use std::time::{Duration, Instant};
use serde::Serialize;
/// A known relay endpoint with measured latency.
#[derive(Debug, Clone, Serialize)]
pub struct RelayEntry {
/// Human-readable name (e.g., "us-east", "eu-west").
pub name: String,
/// Relay address.
pub addr: SocketAddr,
/// Geographic region (from RegisterPresenceAck).
pub region: Option<String>,
/// Last measured RTT (ms).
pub rtt_ms: Option<u32>,
/// When the RTT was last measured.
#[serde(skip)]
pub last_probed: Option<Instant>,
/// Whether this relay is currently reachable.
pub reachable: bool,
}
/// Sorted relay map. Entries are ordered by RTT (lowest first).
#[derive(Debug, Clone, Default)]
pub struct RelayMap {
entries: Vec<RelayEntry>,
}
impl RelayMap {
pub fn new() -> Self {
Self {
entries: Vec::new(),
}
}
/// Add or update a relay entry.
pub fn upsert(&mut self, name: &str, addr: SocketAddr, region: Option<String>) {
if let Some(entry) = self.entries.iter_mut().find(|e| e.addr == addr) {
entry.name = name.to_string();
if region.is_some() {
entry.region = region;
}
} else {
self.entries.push(RelayEntry {
name: name.to_string(),
addr,
region,
rtt_ms: None,
last_probed: None,
reachable: false,
});
}
}
/// Update RTT measurement for a relay.
pub fn update_rtt(&mut self, addr: SocketAddr, rtt_ms: u32) {
if let Some(entry) = self.entries.iter_mut().find(|e| e.addr == addr) {
entry.rtt_ms = Some(rtt_ms);
entry.last_probed = Some(Instant::now());
entry.reachable = true;
}
self.sort();
}
/// Mark a relay as unreachable.
pub fn mark_unreachable(&mut self, addr: SocketAddr) {
if let Some(entry) = self.entries.iter_mut().find(|e| e.addr == addr) {
entry.reachable = false;
entry.last_probed = Some(Instant::now());
}
self.sort();
}
/// Get the preferred (lowest-latency, reachable) relay.
pub fn preferred(&self) -> Option<&RelayEntry> {
self.entries
.iter()
.find(|e| e.reachable && e.rtt_ms.is_some())
}
/// Get all entries, sorted by RTT.
pub fn entries(&self) -> &[RelayEntry] {
&self.entries
}
/// Populate from a `RegisterPresenceAck.available_relays` list.
/// Each entry is "name|addr" format.
pub fn populate_from_ack(&mut self, relays: &[String], relay_region: Option<&str>) {
for entry_str in relays {
if let Some((name, addr_str)) = entry_str.split_once('|') {
if let Ok(addr) = addr_str.parse::<SocketAddr>() {
self.upsert(name, addr, None);
}
}
}
// If the ack included a region for the current relay, we
// could tag it — but we'd need to know which relay we're
// connected to. Left for the caller to handle.
let _ = relay_region;
}
/// Check if any entry has a stale probe (older than `max_age`).
pub fn needs_reprobe(&self, max_age: Duration) -> bool {
self.entries.iter().any(|e| {
match e.last_probed {
None => true,
Some(t) => t.elapsed() > max_age,
}
})
}
/// Get entries that need reprobing.
pub fn stale_entries(&self, max_age: Duration) -> Vec<(String, SocketAddr)> {
self.entries
.iter()
.filter(|e| match e.last_probed {
None => true,
Some(t) => t.elapsed() > max_age,
})
.map(|e| (e.name.clone(), e.addr))
.collect()
}
fn sort(&mut self) {
self.entries.sort_by_key(|e| {
if e.reachable {
e.rtt_ms.unwrap_or(u32::MAX)
} else {
u32::MAX
}
});
}
}
// ── Tests ──────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn preferred_returns_lowest_rtt() {
let mut map = RelayMap::new();
let a1: SocketAddr = "10.0.0.1:4433".parse().unwrap();
let a2: SocketAddr = "10.0.0.2:4433".parse().unwrap();
let a3: SocketAddr = "10.0.0.3:4433".parse().unwrap();
map.upsert("slow", a1, None);
map.upsert("fast", a2, None);
map.upsert("mid", a3, None);
map.update_rtt(a1, 200);
map.update_rtt(a2, 15);
map.update_rtt(a3, 80);
let pref = map.preferred().unwrap();
assert_eq!(pref.addr, a2);
assert_eq!(pref.rtt_ms, Some(15));
}
#[test]
fn unreachable_not_preferred() {
let mut map = RelayMap::new();
let a1: SocketAddr = "10.0.0.1:4433".parse().unwrap();
let a2: SocketAddr = "10.0.0.2:4433".parse().unwrap();
map.upsert("fast-dead", a1, None);
map.upsert("slow-alive", a2, None);
map.update_rtt(a1, 5);
map.update_rtt(a2, 200);
map.mark_unreachable(a1);
let pref = map.preferred().unwrap();
assert_eq!(pref.addr, a2);
}
#[test]
fn populate_from_ack() {
let mut map = RelayMap::new();
map.populate_from_ack(
&[
"us-east|203.0.113.5:4433".into(),
"eu-west|198.51.100.9:4433".into(),
],
Some("us-east"),
);
assert_eq!(map.entries().len(), 2);
assert_eq!(map.entries()[0].name, "us-east");
assert_eq!(map.entries()[1].name, "eu-west");
}
#[test]
fn upsert_updates_existing() {
let mut map = RelayMap::new();
let addr: SocketAddr = "10.0.0.1:4433".parse().unwrap();
map.upsert("old-name", addr, None);
map.upsert("new-name", addr, Some("us-west".into()));
assert_eq!(map.entries().len(), 1);
assert_eq!(map.entries()[0].name, "new-name");
assert_eq!(map.entries()[0].region, Some("us-west".into()));
}
#[test]
fn upsert_preserves_region_when_none() {
let mut map = RelayMap::new();
let addr: SocketAddr = "10.0.0.1:4433".parse().unwrap();
map.upsert("relay", addr, Some("eu-west".into()));
map.upsert("relay", addr, None); // region is None
// Should keep the original region
assert_eq!(map.entries()[0].region, Some("eu-west".into()));
}
#[test]
fn preferred_returns_none_on_empty() {
let map = RelayMap::new();
assert!(map.preferred().is_none());
}
#[test]
fn preferred_returns_none_when_all_unreachable() {
let mut map = RelayMap::new();
let addr: SocketAddr = "10.0.0.1:4433".parse().unwrap();
map.upsert("relay", addr, None);
// Not update_rtt'd, so reachable=false
assert!(map.preferred().is_none());
}
#[test]
fn needs_reprobe_empty_is_false() {
let map = RelayMap::new();
// No entries → nothing to reprobe
assert!(!map.needs_reprobe(Duration::from_secs(60)));
}
#[test]
fn needs_reprobe_never_probed() {
let mut map = RelayMap::new();
map.upsert("relay", "10.0.0.1:4433".parse().unwrap(), None);
assert!(map.needs_reprobe(Duration::from_secs(60)));
}
#[test]
fn needs_reprobe_fresh_is_false() {
let mut map = RelayMap::new();
let addr: SocketAddr = "10.0.0.1:4433".parse().unwrap();
map.upsert("relay", addr, None);
map.update_rtt(addr, 50);
// Just probed, so 60s max_age should not trigger
assert!(!map.needs_reprobe(Duration::from_secs(60)));
}
#[test]
fn stale_entries_returns_unprobed() {
let mut map = RelayMap::new();
let a1: SocketAddr = "10.0.0.1:4433".parse().unwrap();
let a2: SocketAddr = "10.0.0.2:4433".parse().unwrap();
map.upsert("probed", a1, None);
map.upsert("stale", a2, None);
map.update_rtt(a1, 50);
let stale = map.stale_entries(Duration::from_secs(60));
assert_eq!(stale.len(), 1);
assert_eq!(stale[0].1, a2);
}
#[test]
fn sort_stability_with_equal_rtt() {
let mut map = RelayMap::new();
let a1: SocketAddr = "10.0.0.1:4433".parse().unwrap();
let a2: SocketAddr = "10.0.0.2:4433".parse().unwrap();
map.upsert("first", a1, None);
map.upsert("second", a2, None);
map.update_rtt(a1, 50);
map.update_rtt(a2, 50);
// Both have same RTT — sort should be stable (insertion order)
assert_eq!(map.entries().len(), 2);
// Both are valid preferred relays
assert!(map.preferred().is_some());
}
#[test]
fn populate_from_ack_skips_malformed() {
let mut map = RelayMap::new();
map.populate_from_ack(
&[
"good|10.0.0.1:4433".into(),
"no-pipe-separator".into(),
"bad-addr|not-a-socket-addr".into(),
"also-good|10.0.0.2:4433".into(),
],
None,
);
assert_eq!(map.entries().len(), 2);
}
#[test]
fn mark_unreachable_sorts_to_end() {
let mut map = RelayMap::new();
let a1: SocketAddr = "10.0.0.1:4433".parse().unwrap();
let a2: SocketAddr = "10.0.0.2:4433".parse().unwrap();
map.upsert("fast", a1, None);
map.upsert("slow", a2, None);
map.update_rtt(a1, 10);
map.update_rtt(a2, 200);
assert_eq!(map.preferred().unwrap().addr, a1);
map.mark_unreachable(a1);
assert_eq!(map.preferred().unwrap().addr, a2);
}
#[test]
fn relay_entry_serializes() {
let entry = RelayEntry {
name: "test".into(),
addr: "10.0.0.1:4433".parse().unwrap(),
region: Some("us-east".into()),
rtt_ms: Some(42),
last_probed: Some(Instant::now()),
reachable: true,
};
let json = serde_json::to_string(&entry).unwrap();
assert!(json.contains("test"));
assert!(json.contains("us-east"));
assert!(json.contains("42"));
// last_probed is #[serde(skip)]
assert!(!json.contains("last_probed"));
}
}

1436
crates/wzp-client/src/stun.rs
View File

File diff suppressed because it is too large Load Diff

222
crates/wzp-client/tests/dual_path.rs
View File

@@ -1,222 +0,0 @@
//! Phase 3.5 integration tests for the dual-path QUIC race.
//!
//! The race takes a role (Acceptor or Dialer), a peer_direct_addr,
//! a relay_addr, and two SNI strings, then returns whichever QUIC
//! handshake completes first wrapped in a `QuinnTransport`. These
//! tests validate that:
//!
//! 1. On loopback with two real clients playing A + D roles, the
//! direct path wins (fewer hops than relay).
//! 2. When the direct peer is dead (nothing listening) but the
//! relay is up, the relay wins within the fallback window.
//! 3. When both paths are dead, the race errors cleanly rather
//! than hanging forever.
//!
//! The "relay" in these tests is a minimal mock that just accepts
//! an incoming QUIC connection and drops it — we don't need any
//! protocol handling, just a TCP-ish listen-and-accept.
use std::net::{Ipv4Addr, SocketAddr};
use std::time::Duration;
use wzp_client::dual_path::{race, PeerCandidates, WinningPath};
use wzp_client::reflect::Role;
use wzp_transport::{create_endpoint, server_config};
/// Spin up a "relay-ish" mock server on loopback that accepts
/// incoming QUIC connections and does nothing with them. Used to
/// give the relay branch of the race a real target to dial.
/// Returns the bound address + a join handle (kept alive to keep
/// the endpoint up).
async fn spawn_mock_relay() -> (SocketAddr, tokio::task::JoinHandle<()>) {
let _ = rustls::crypto::ring::default_provider().install_default();
let (sc, _cert_der) = server_config();
let bind: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let ep = create_endpoint(bind, Some(sc)).expect("relay endpoint");
let addr = ep.local_addr().expect("local_addr");
let handle = tokio::spawn(async move {
// Accept loop — hold the connection alive for a short
// while so the race result isn't killed by the peer
// closing before the winning transport is returned.
while let Some(incoming) = ep.accept().await {
if let Ok(_conn) = incoming.await {
tokio::time::sleep(Duration::from_secs(5)).await;
}
}
});
(addr, handle)
}
// -----------------------------------------------------------------------
// Test 1: direct path wins when both sides are up
// -----------------------------------------------------------------------
//
// Spawn a mock relay, then set up a two-client test where one
// client plays the Acceptor role and the other plays the Dialer
// role. The Dialer's `peer_direct_addr` is the Acceptor's listen
// address. Because the direct path is a single loopback hop and
// the relay dial also terminates on loopback, both complete
// essentially instantly — the `biased` tokio::select in race()
// should pick direct.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn dual_path_direct_wins_on_loopback() {
let _ = rustls::crypto::ring::default_provider().install_default();
let (relay_addr, _relay_handle) = spawn_mock_relay().await;
// Acceptor task: run race(Role::Acceptor, peer_addr_placeholder, ...).
// Since the acceptor doesn't dial, the peer_direct_addr arg is
// unused on the direct branch but we still pass a placeholder
// because the API takes one. Use a stub addr that would error
// if it were ever dialed — proving the Acceptor really doesn't
// reach it.
let unused_addr: SocketAddr = "127.0.0.1:2".parse().unwrap();
// We can't race both sides in the same task because each race
// call has its own direct endpoint that needs to talk to the
// OTHER side's endpoint. So spawn the Acceptor in a task and
// let it expose its listen addr via a oneshot back to the test,
// then run the Dialer in the test's main task.
//
// There's a chicken-and-egg issue: the Acceptor's listen addr
// is only known after race() creates its endpoint. To avoid
// reaching into race()'s internals, we instead play a slight
// trick: create the Acceptor's endpoint ourselves (outside
// race()) to learn its addr, spin up an accept loop on it
// ourselves, and pass THAT addr as the Dialer's peer addr.
// This tests the Dialer->Acceptor handshake end-to-end without
// running the full race() on both sides.
let (sc, _cert_der) = server_config();
let acceptor_bind: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let acceptor_ep = create_endpoint(acceptor_bind, Some(sc)).expect("acceptor ep");
let acceptor_listen_addr = acceptor_ep.local_addr().expect("acceptor addr");
// Drop the external acceptor after the test finishes, not
// before — spawn a dedicated accept task.
let acceptor_accept_task = tokio::spawn(async move {
// Accept one connection and hold it for a while so the
// Dialer side can complete its QUIC handshake.
if let Some(incoming) = acceptor_ep.accept().await {
if let Ok(_conn) = incoming.await {
tokio::time::sleep(Duration::from_secs(5)).await;
}
}
});
// Now run the Dialer in the race — peer_direct_addr = acceptor's
// listen addr. The relay is the mock from above. Direct path
// should win.
let result = race(
Role::Dialer,
PeerCandidates {
reflexive: Some(acceptor_listen_addr),
local: Vec::new(),
mapped: None,
},
relay_addr,
"test-room".into(),
"call-test".into(),
None, // own_reflexive: not needed in tests
None, // Phase 5: tests use fresh endpoints (no shared signal)
None, // Phase 7: no IPv6 endpoint in tests
)
.await
.expect("race must succeed");
assert!(result.direct_transport.is_some(), "direct transport should be available");
assert_eq!(result.local_winner, WinningPath::Direct, "direct should win on loopback");
// Cancel the acceptor accept task so the test finishes.
acceptor_accept_task.abort();
// Suppress unused-var warning for the placeholder.
let _ = unused_addr;
}
// -----------------------------------------------------------------------
// Test 2: relay wins when the direct peer is dead
// -----------------------------------------------------------------------
//
// Dialer role, peer_direct_addr = a port nothing is listening on,
// relay is the working mock. Direct dial will sit waiting for a
// QUIC handshake that never comes; the 2s direct timeout kicks in
// and the relay path wins the fallback.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn dual_path_relay_wins_when_direct_is_dead() {
let _ = rustls::crypto::ring::default_provider().install_default();
let (relay_addr, _relay_handle) = spawn_mock_relay().await;
// A port that nothing is listening on — dead direct target.
// Port 1 on loopback is almost never bound and UDP packets to
// it will be dropped silently, so the QUIC handshake times out.
let dead_peer: SocketAddr = "127.0.0.1:1".parse().unwrap();
let result = race(
Role::Dialer,
PeerCandidates {
reflexive: Some(dead_peer),
local: Vec::new(),
mapped: None,
},
relay_addr,
"test-room".into(),
"call-test".into(),
None, // own_reflexive: not needed in tests
None, // Phase 5: tests use fresh endpoints (no shared signal)
None, // Phase 7: no IPv6 endpoint in tests
)
.await
.expect("race must succeed via relay fallback");
assert!(result.relay_transport.is_some(), "relay transport should be available");
assert_eq!(
result.local_winner,
WinningPath::Relay,
"relay should win when direct dial has nowhere to land"
);
}
// -----------------------------------------------------------------------
// Test 3: race errors cleanly when both paths are dead
// -----------------------------------------------------------------------
//
// Dialer role, peer_direct_addr = dead, relay_addr = dead.
// Expected: race returns an Err within ~7s (2s direct timeout +
// 5s relay timeout fallback).
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn dual_path_errors_cleanly_when_both_paths_dead() {
let _ = rustls::crypto::ring::default_provider().install_default();
let dead_peer: SocketAddr = "127.0.0.1:1".parse().unwrap();
let dead_relay: SocketAddr = "127.0.0.1:2".parse().unwrap();
let start = std::time::Instant::now();
let result = race(
Role::Dialer,
PeerCandidates {
reflexive: Some(dead_peer),
local: Vec::new(),
mapped: None,
},
dead_relay,
"test-room".into(),
"call-test".into(),
None, // own_reflexive: not needed in tests
None, // Phase 5: tests use fresh endpoints (no shared signal)
None, // Phase 7: no IPv6 endpoint in tests
)
.await;
let elapsed = start.elapsed();
assert!(result.is_err(), "both-dead must return Err");
// Upper bound: direct 2s timeout + relay 5s fallback + small
// slack for scheduling. If this blows, something is looping.
assert!(
elapsed < Duration::from_secs(10),
"race took too long to give up: {:?}",
elapsed
);
}

5
crates/wzp-client/tests/handshake_integration.rs
View File

@@ -83,12 +83,12 @@ async fn full_handshake_both_sides_derive_same_session() {
// Run client and relay handshakes concurrently.
let (client_result, relay_result) = tokio::join!(
wzp_client::handshake::perform_handshake(client_transport_clone.as_ref(), &client_seed, None),
wzp_client::handshake::perform_handshake(client_transport_clone.as_ref(), &client_seed),
wzp_relay::handshake::accept_handshake(relay_transport_clone.as_ref(), &relay_seed),
);
let mut client_session = client_result.expect("client handshake should succeed");
let (mut relay_session, chosen_profile, _caller_fp, _caller_alias) =
let (mut relay_session, chosen_profile) =
relay_result.expect("relay handshake should succeed");
// Verify a profile was chosen.
@@ -151,7 +151,6 @@ async fn handshake_rejects_tampered_signature() {
ephemeral_pub,
signature: bad_signature,
supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
alias: None,
};
client_transport_clone
.send_signal(&offer)

13
crates/wzp-codec/Cargo.toml
View File

@@ -10,17 +10,8 @@ description = "WarzonePhone audio codec layer — Opus + Codec2 encoding/decodin
wzp-proto = { workspace = true }
tracing = { workspace = true }
# Opus bindings — libopus 1.5.2.
# opusic-c for the encoder (set_dred_duration lives here in Phase 1).
# opusic-sys for the decoder — we wrap the raw *mut OpusDecoder ourselves
# because opusic-c::Decoder.inner is pub(crate), blocking the unified
# decoder + DRED path we need in Phase 3.
opusic-c = { workspace = true }
opusic-sys = { workspace = true }
# Zero-cost slice reinterpretation for the i16 ↔ u16 boundary between
# our PCM buffers and opusic-c's encode API.
bytemuck = { workspace = true }
# Opus bindings
audiopus = { workspace = true }
# Pure-Rust Codec2 implementation
codec2 = { workspace = true }

29
crates/wzp-codec/src/adaptive.rs
View File

@@ -116,14 +116,6 @@ impl AudioEncoder for AdaptiveEncoder {
fn set_dtx(&mut self, enabled: bool) {
self.opus.set_dtx(enabled);
}
fn set_expected_loss(&mut self, loss_pct: u8) {
self.opus.set_expected_loss(loss_pct);
}
fn set_dred_duration(&mut self, frames: u8) {
self.opus.set_dred_duration(frames);
}
}
// ─── AdaptiveDecoder ─────────────────────────────────────────────────────────
@@ -207,27 +199,6 @@ impl AdaptiveDecoder {
fn codec2_frame_samples(&self) -> usize {
self.codec2.frame_samples()
}
/// Reconstruct a lost frame from a previously parsed DRED state.
///
/// Phase 3b entry point for gap reconstruction. Dispatches to the
/// inner Opus decoder when active. Returns an error if the active
/// codec is Codec2 — DRED is libopus-only and has no Codec2 equivalent,
/// so callers must fall back to classical PLC on Codec2 tiers.
pub fn reconstruct_from_dred(
&mut self,
state: &crate::dred_ffi::DredState,
offset_samples: i32,
output: &mut [i16],
) -> Result<usize, CodecError> {
if is_codec2(self.active) {
return Err(CodecError::DecodeFailed(
"DRED reconstruction is Opus-only; Codec2 must use classical PLC".into(),
));
}
self.opus
.reconstruct_from_dred(state, offset_samples, output)
}
}
// ─── Tests ───────────────────────────────────────────────────────────────────

585
crates/wzp-codec/src/dred_ffi.rs
View File

@@ -1,585 +0,0 @@
//! Raw opusic-sys FFI wrappers for libopus 1.5.2 decoder + DRED reconstruction.
//!
//! # Why this module exists
//!
//! We cannot use `opusic_c::Decoder` because its inner `*mut OpusDecoder`
//! pointer is `pub(crate)` — not reachable from outside the opusic-c crate.
//! Phase 3 of the DRED integration needs to hand that same pointer to
//! `opus_decoder_dred_decode`, and running two parallel decoders (one from
//! opusic-c for normal audio, another from opusic-sys for DRED) would cause
//! the DRED-only decoder's internal state to drift out of sync with the
//! audio stream because it would not see normal decode calls.
//!
//! The fix is to own the raw decoder ourselves and use the same handle for
//! both normal decode AND DRED reconstruction. This module is the single
//! owner of `*mut OpusDecoder`, `*mut OpusDREDDecoder`, and `*mut OpusDRED`
//! in the WZP workspace.
//!
//! # Phase 3a scope
//!
//! Phase 0 added `DecoderHandle` (normal decode). Phase 3a adds:
//! - [`DredDecoderHandle`] — wraps `*mut OpusDREDDecoder` for parsing DRED
//! side-channel data out of arriving Opus packets.
//! - [`DredState`] — wraps `*mut OpusDRED` (a fixed 10,592-byte buffer
//! allocated by libopus) that holds parsed DRED state between the parse
//! and reconstruct steps.
//! - [`DredDecoderHandle::parse_into`] — wraps `opus_dred_parse`.
//! - [`DecoderHandle::reconstruct_from_dred`] — wraps `opus_decoder_dred_decode`.
//!
//! The pattern is: on every arriving Opus packet, the receiver calls
//! `parse_into` with a reusable `DredState`, then stores (seq, state_clone)
//! in a ring. On detected loss, the receiver computes the offset from the
//! freshest reachable DRED state and calls `reconstruct_from_dred` to
//! synthesize the missing audio.
use std::ptr::NonNull;
use opusic_sys::{
OPUS_OK, OpusDRED, OpusDREDDecoder, OpusDecoder as RawOpusDecoder, opus_decode,
opus_decoder_create, opus_decoder_destroy, opus_decoder_dred_decode, opus_dred_alloc,
opus_dred_decoder_create, opus_dred_decoder_destroy, opus_dred_free, opus_dred_parse,
};
use wzp_proto::CodecError;
/// libopus operates at 48 kHz for all Opus variants we use.
const SAMPLE_RATE_HZ: i32 = 48_000;
/// Mono.
const CHANNELS: i32 = 1;
/// Safe owner of a `*mut OpusDecoder` allocated via `opus_decoder_create`.
///
/// Releases the decoder in `Drop`. All FFI access goes through `&mut self`
/// methods, so there is no aliasing or race. The raw pointer is exposed via
/// [`Self::as_raw_ptr`] at a crate-internal visibility for the future Phase 3
/// DRED reconstruction path — external crates cannot reach it.
pub struct DecoderHandle {
inner: NonNull<RawOpusDecoder>,
}
impl DecoderHandle {
/// Allocate a new Opus decoder at 48 kHz mono.
pub fn new() -> Result<Self, CodecError> {
let mut error: i32 = OPUS_OK;
// SAFETY: opus_decoder_create writes to `error` and returns either a
// valid heap pointer or null. We check both before constructing the
// NonNull wrapper.
let ptr = unsafe { opus_decoder_create(SAMPLE_RATE_HZ, CHANNELS, &mut error) };
if error != OPUS_OK {
// Even if ptr is non-null on error, libopus contracts guarantee
// it is unusable — do not attempt to free it.
return Err(CodecError::DecodeFailed(format!(
"opus_decoder_create failed: err={error}"
)));
}
let inner = NonNull::new(ptr).ok_or_else(|| {
CodecError::DecodeFailed("opus_decoder_create returned null".into())
})?;
Ok(Self { inner })
}
/// Decode an Opus packet into PCM samples.
///
/// `pcm` must have enough capacity for the frame (960 for 20 ms, 1920
/// for 40 ms at 48 kHz mono). Returns the number of decoded samples
/// per channel — for mono streams this equals the total sample count.
pub fn decode(&mut self, packet: &[u8], pcm: &mut [i16]) -> Result<usize, CodecError> {
if packet.is_empty() {
return Err(CodecError::DecodeFailed("empty packet".into()));
}
if pcm.is_empty() {
return Err(CodecError::DecodeFailed("empty output buffer".into()));
}
// SAFETY: self.inner is a valid *mut OpusDecoder owned by this struct.
// `data` / `pcm` are live Rust slices, so their pointers and lengths
// are valid for the duration of the call. libopus reads len bytes
// from data and writes up to frame_size samples (per channel) to pcm.
let n = unsafe {
opus_decode(
self.inner.as_ptr(),
packet.as_ptr(),
packet.len() as i32,
pcm.as_mut_ptr(),
pcm.len() as i32,
/* decode_fec = */ 0,
)
};
if n < 0 {
return Err(CodecError::DecodeFailed(format!(
"opus_decode failed: err={n}"
)));
}
Ok(n as usize)
}
/// Generate packet-loss concealment audio for a missing frame.
///
/// Implemented via `opus_decode` with a null data pointer, per the
/// libopus API contract. `pcm` should be sized for the expected frame.
pub fn decode_lost(&mut self, pcm: &mut [i16]) -> Result<usize, CodecError> {
if pcm.is_empty() {
return Err(CodecError::DecodeFailed("empty output buffer".into()));
}
// SAFETY: same invariants as decode(). libopus documents that passing
// a null data pointer with len=0 triggers PLC synthesis into pcm.
let n = unsafe {
opus_decode(
self.inner.as_ptr(),
std::ptr::null(),
0,
pcm.as_mut_ptr(),
pcm.len() as i32,
/* decode_fec = */ 0,
)
};
if n < 0 {
return Err(CodecError::DecodeFailed(format!(
"opus_decode PLC failed: err={n}"
)));
}
Ok(n as usize)
}
/// Reconstruct audio from a `DredState` into the `output` buffer.
///
/// `offset_samples` is the sample position (positive, measured backward
/// from the packet anchor that produced `state`) where reconstruction
/// begins. `output.len()` must match the number of samples to synthesize.
///
/// The libopus API: `opus_decoder_dred_decode(st, dred, dred_offset, pcm,
/// frame_size)` where `dred_offset` is "position of the redundancy to
/// decode, in samples before the beginning of the real audio data in the
/// packet." Valid values: `0 < offset_samples < state.samples_available()`.
///
/// Returns the number of samples actually written (should equal
/// `output.len()` on success).
pub fn reconstruct_from_dred(
&mut self,
state: &DredState,
offset_samples: i32,
output: &mut [i16],
) -> Result<usize, CodecError> {
if output.is_empty() {
return Err(CodecError::DecodeFailed(
"empty reconstruction output buffer".into(),
));
}
if offset_samples <= 0 {
return Err(CodecError::DecodeFailed(format!(
"DRED offset must be positive (got {offset_samples})"
)));
}
if offset_samples > state.samples_available() {
return Err(CodecError::DecodeFailed(format!(
"DRED offset {offset_samples} exceeds available samples {}",
state.samples_available()
)));
}
// SAFETY: self.inner is a valid *mut OpusDecoder, state.inner is a
// valid *const OpusDRED populated by a prior parse_into call, and
// output is a live mutable slice. libopus reads from dred and writes
// exactly frame_size samples (the output.len()) to pcm.
let n = unsafe {
opus_decoder_dred_decode(
self.inner.as_ptr(),
state.inner.as_ptr(),
offset_samples,
output.as_mut_ptr(),
output.len() as i32,
)
};
if n < 0 {
return Err(CodecError::DecodeFailed(format!(
"opus_decoder_dred_decode failed: err={n}"
)));
}
Ok(n as usize)
}
}
impl Drop for DecoderHandle {
fn drop(&mut self) {
// SAFETY: we own the pointer and no further access happens after
// this call because Drop consumes self.
unsafe { opus_decoder_destroy(self.inner.as_ptr()) };
}
}
// SAFETY: The underlying OpusDecoder is a plain heap allocation with no
// thread-local or lock-free state. It is safe to move between threads
// (Send), and all method access is gated by &mut self so Rust's borrow
// checker prevents simultaneous access from multiple threads (Sync).
unsafe impl Send for DecoderHandle {}
unsafe impl Sync for DecoderHandle {}
// ─── DRED decoder (parser) ──────────────────────────────────────────────────
/// Safe owner of a `*mut OpusDREDDecoder` allocated via
/// `opus_dred_decoder_create`.
///
/// The DRED decoder is a **separate** libopus object from the regular
/// `OpusDecoder`. It's used exclusively for parsing DRED side-channel data
/// out of arriving Opus packets via [`Self::parse_into`]. Actual audio
/// reconstruction from the parsed state uses the regular `DecoderHandle`
/// via [`DecoderHandle::reconstruct_from_dred`].
pub struct DredDecoderHandle {
inner: NonNull<OpusDREDDecoder>,
}
impl DredDecoderHandle {
/// Allocate a new DRED decoder.
pub fn new() -> Result<Self, CodecError> {
let mut error: i32 = OPUS_OK;
// SAFETY: opus_dred_decoder_create writes to `error` and returns
// either a valid heap pointer or null. Both are checked.
let ptr = unsafe { opus_dred_decoder_create(&mut error) };
if error != OPUS_OK {
return Err(CodecError::DecodeFailed(format!(
"opus_dred_decoder_create failed: err={error}"
)));
}
let inner = NonNull::new(ptr).ok_or_else(|| {
CodecError::DecodeFailed("opus_dred_decoder_create returned null".into())
})?;
Ok(Self { inner })
}
/// Parse DRED side-channel data from an Opus packet into `state`.
///
/// Returns the number of samples of audio history available for
/// reconstruction, or 0 if the packet carries no DRED data. Subsequent
/// `DecoderHandle::reconstruct_from_dred` calls using this `state` can
/// reconstruct any sample position in `(0, samples_available]`.
///
/// libopus API: `opus_dred_parse(dred_dec, dred, data, len,
/// max_dred_samples, sampling_rate, dred_end, defer_processing)`. We
/// pass `max_dred_samples = 48000` (1 s at 48 kHz, the DRED maximum),
/// `sampling_rate = 48000`, `defer_processing = 0` (process immediately).
/// The `dred_end` output is the silence gap at the tail of the DRED
/// window; we subtract it from the total offset to give callers the
/// truly usable sample count.
pub fn parse_into(
&mut self,
state: &mut DredState,
packet: &[u8],
) -> Result<i32, CodecError> {
if packet.is_empty() {
state.samples_available = 0;
return Ok(0);
}
let mut dred_end: i32 = 0;
// SAFETY: self.inner is a valid *mut OpusDREDDecoder; state.inner is
// a valid *mut OpusDRED allocated via opus_dred_alloc; packet is a
// live slice; dred_end is a stack int. libopus reads packet bytes
// and writes parsed DRED state into *state.inner.
let ret = unsafe {
opus_dred_parse(
self.inner.as_ptr(),
state.inner.as_ptr(),
packet.as_ptr(),
packet.len() as i32,
/* max_dred_samples = */ 48_000, // 1s max per libopus 1.5
/* sampling_rate = */ 48_000,
&mut dred_end,
/* defer_processing = */ 0,
)
};
if ret < 0 {
state.samples_available = 0;
return Err(CodecError::DecodeFailed(format!(
"opus_dred_parse failed: err={ret}"
)));
}
// ret is the positive offset of the first decodable DRED sample,
// or 0 if no DRED is present. dred_end is the silence gap at the
// tail. The usable sample range is (dred_end, ret], so the count
// of usable samples is ret - dred_end. We store `ret` as the max
// usable offset — callers should pass dred_offset values in the
// range (dred_end, ret] to reconstruct_from_dred. For simplicity
// we expose just samples_available = ret and let callers treat
// the full window as valid (the silence gap is small and libopus
// handles minor boundary cases gracefully).
state.samples_available = ret;
Ok(ret)
}
}
impl Drop for DredDecoderHandle {
fn drop(&mut self) {
// SAFETY: we own the pointer and no further access happens after
// this call because Drop consumes self.
unsafe { opus_dred_decoder_destroy(self.inner.as_ptr()) };
}
}
// SAFETY: same reasoning as DecoderHandle — heap allocation with no
// thread-local state, &mut self access discipline prevents races.
unsafe impl Send for DredDecoderHandle {}
unsafe impl Sync for DredDecoderHandle {}
// ─── DRED state buffer ──────────────────────────────────────────────────────
/// Safe owner of a `*mut OpusDRED` allocated via `opus_dred_alloc`.
///
/// Holds a fixed-size (10,592-byte per libopus 1.5) buffer that
/// `DredDecoderHandle::parse_into` populates from an Opus packet. The state
/// is reusable — the caller can call `parse_into` again on the same
/// `DredState` to overwrite it with a fresh packet's data.
///
/// `samples_available` tracks the last-parsed result so reconstruction
/// callers don't need to thread the return value separately. A fresh
/// state (before any `parse_into`) has `samples_available == 0`.
pub struct DredState {
inner: NonNull<OpusDRED>,
samples_available: i32,
}
impl DredState {
/// Allocate a new DRED state buffer.
pub fn new() -> Result<Self, CodecError> {
let mut error: i32 = OPUS_OK;
// SAFETY: opus_dred_alloc writes to `error` and returns either a
// valid heap pointer or null.
let ptr = unsafe { opus_dred_alloc(&mut error) };
if error != OPUS_OK {
return Err(CodecError::DecodeFailed(format!(
"opus_dred_alloc failed: err={error}"
)));
}
let inner = NonNull::new(ptr)
.ok_or_else(|| CodecError::DecodeFailed("opus_dred_alloc returned null".into()))?;
Ok(Self {
inner,
samples_available: 0,
})
}
/// How many samples of audio history this state currently covers.
///
/// Returns 0 if the state is fresh or the last parse found no DRED
/// data. Otherwise returns the positive offset set by the most recent
/// `DredDecoderHandle::parse_into` call — the maximum valid
/// `offset_samples` value for `DecoderHandle::reconstruct_from_dred`.
pub fn samples_available(&self) -> i32 {
self.samples_available
}
/// Reset the state to "fresh" without freeing the underlying buffer.
/// The next `parse_into` will overwrite the contents.
pub fn reset(&mut self) {
self.samples_available = 0;
}
}
impl Drop for DredState {
fn drop(&mut self) {
// SAFETY: we own the pointer and no further access happens after
// this call because Drop consumes self.
unsafe { opus_dred_free(self.inner.as_ptr()) };
}
}
// SAFETY: same reasoning as DecoderHandle.
unsafe impl Send for DredState {}
unsafe impl Sync for DredState {}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn decoder_handle_creates_and_drops() {
let handle = DecoderHandle::new().expect("decoder create");
// Dropping the handle must not panic or leak — validated by miri
// and the absence of sanitizer complaints in CI.
drop(handle);
}
#[test]
fn decode_lost_produces_full_frame_of_silence_on_cold_start() {
let mut handle = DecoderHandle::new().unwrap();
// 20 ms @ 48 kHz mono.
let mut pcm = vec![0i16; 960];
let n = handle.decode_lost(&mut pcm).unwrap();
assert_eq!(n, 960);
// On a fresh decoder, PLC output is silence (no past audio to extend).
assert!(pcm.iter().all(|&s| s == 0));
}
#[test]
fn decode_empty_packet_errors() {
let mut handle = DecoderHandle::new().unwrap();
let mut pcm = vec![0i16; 960];
let err = handle.decode(&[], &mut pcm);
assert!(err.is_err());
}
// ─── Phase 3a — DRED decoder + state ────────────────────────────────────
#[test]
fn dred_decoder_handle_creates_and_drops() {
let h = DredDecoderHandle::new().expect("dred decoder create");
drop(h);
}
#[test]
fn dred_state_creates_and_drops() {
let s = DredState::new().expect("dred state alloc");
assert_eq!(s.samples_available(), 0);
drop(s);
}
#[test]
fn dred_state_reset_zeroes_counter() {
let mut s = DredState::new().unwrap();
s.samples_available = 480; // pretend a parse populated it
assert_eq!(s.samples_available(), 480);
s.reset();
assert_eq!(s.samples_available(), 0);
}
/// Phase 3a end-to-end: encode a DRED-enabled stream, parse state out
/// of packets, and reconstruct audio at a past offset. Validates the
/// full parse → reconstruct pipeline against a real libopus 1.5.2
/// encoder so we catch FFI-layer bugs early.
#[test]
fn dred_parse_and_reconstruct_roundtrip() {
use crate::opus_enc::OpusEncoder;
use wzp_proto::{AudioEncoder, QualityProfile};
// Encoder with DRED at Opus 24k / 200 ms duration (Phase 1 default
// for GOOD profile). The loss floor is 5% per Phase 1.
let mut enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
// Decode-side handles.
let mut dec = DecoderHandle::new().unwrap();
let mut dred_dec = DredDecoderHandle::new().unwrap();
let mut state = DredState::new().unwrap();
// Generate 60 frames (1.2 s) of a voice-like 300 Hz sine wave so
// the encoder's DRED emitter has real content to encode rather
// than compressing silence.
let frame_len = 960usize; // 20 ms @ 48 kHz
let make_frame = |offset: usize| -> Vec<i16> {
(0..frame_len)
.map(|i| {
let t = (offset + i) as f64 / 48_000.0;
(8000.0 * (2.0 * std::f64::consts::PI * 300.0 * t).sin()) as i16
})
.collect()
};
// Track the freshest packet that carried non-zero DRED state.
let mut best_samples_available = 0;
let mut best_packet: Option<Vec<u8>> = None;
for frame_idx in 0..60 {
let pcm = make_frame(frame_idx * frame_len);
let mut encoded = vec![0u8; 512];
let n = enc.encode(&pcm, &mut encoded).unwrap();
encoded.truncate(n);
// Run the packet through the normal decode path so dec's
// internal state mirrors the full stream — this is necessary
// for DRED reconstruction to produce meaningful output.
let mut decoded = vec![0i16; frame_len];
dec.decode(&encoded, &mut decoded).unwrap();
// Parse DRED state out of the same packet. Early packets may
// have samples_available == 0 while the DRED encoder warms up;
// later packets should carry the full window.
match dred_dec.parse_into(&mut state, &encoded) {
Ok(available) => {
if available > best_samples_available {
best_samples_available = available;
best_packet = Some(encoded.clone());
}
}
Err(e) => panic!("parse_into errored unexpectedly: {e:?}"),
}
}
// By the time we're 60 frames in, DRED should have emitted data.
assert!(
best_samples_available > 0,
"DRED emitted zero samples across 60 frames — the encoder isn't \
producing DRED bytes (check set_dred_duration and packet_loss floor)"
);
// Parse the best packet into a fresh state and reconstruct some
// audio from somewhere inside its DRED window. We use frame_len/2
// as the offset to pick a point squarely inside the reconstructable
// range rather than at an edge.
let packet = best_packet.expect("at least one packet had DRED state");
let mut fresh_state = DredState::new().unwrap();
let available = dred_dec.parse_into(&mut fresh_state, &packet).unwrap();
assert!(available > 0, "re-parse of known-good packet returned 0");
// Need a decoder that's in the right state to reconstruct — rewind
// by creating a fresh one and feeding it the same stream up to the
// point of the best packet. Simpler: just use a fresh decoder and
// accept that the reconstructed samples may not be phase-matched.
// The test here only asserts *non-silent energy*, not signal fidelity.
let mut recon_dec = DecoderHandle::new().unwrap();
// Warm up the decoder with one frame so its internal state is valid.
let warmup_pcm = vec![0i16; frame_len];
let warmup_encoded = {
let mut warmup_enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
let mut buf = vec![0u8; 512];
let n = warmup_enc.encode(&warmup_pcm, &mut buf).unwrap();
buf.truncate(n);
buf
};
let mut throwaway = vec![0i16; frame_len];
let _ = recon_dec.decode(&warmup_encoded, &mut throwaway);
// Reconstruct 20 ms from some position inside the DRED window.
let offset = (available / 2).max(480).min(available);
let mut recon_pcm = vec![0i16; frame_len];
let n = recon_dec
.reconstruct_from_dred(&fresh_state, offset, &mut recon_pcm)
.expect("reconstruct_from_dred failed");
assert_eq!(n, frame_len);
// Energy check: reconstructed audio should not be all zeros. A
// loose threshold — the DRED reconstruction won't be phase-matched
// to our sine wave because we fed a cold decoder only one warmup
// frame, but it should still produce non-silent speech-like output
// since the DRED state was parsed from real speech content.
let energy: u64 = recon_pcm.iter().map(|&s| (s as i32).unsigned_abs() as u64).sum();
assert!(
energy > 0,
"reconstructed audio has zero total energy — DRED reconstruction produced silence"
);
}
/// A second roundtrip variant: offset too large errors cleanly rather
/// than crashing the FFI.
#[test]
fn reconstruct_with_out_of_range_offset_errors() {
let mut dec = DecoderHandle::new().unwrap();
let state = DredState::new().unwrap();
// state has samples_available == 0 (fresh), so any positive offset
// should be out of range.
let mut out = vec![0i16; 960];
let err = dec.reconstruct_from_dred(&state, 480, &mut out);
assert!(err.is_err());
}
#[test]
fn reconstruct_with_zero_offset_errors() {
let mut dec = DecoderHandle::new().unwrap();
let state = DredState::new().unwrap();
let mut out = vec![0i16; 960];
let err = dec.reconstruct_from_dred(&state, 0, &mut out);
assert!(err.is_err());
}
#[test]
fn dred_parse_empty_packet_returns_zero() {
let mut dred_dec = DredDecoderHandle::new().unwrap();
let mut state = DredState::new().unwrap();
let result = dred_dec.parse_into(&mut state, &[]).unwrap();
assert_eq!(result, 0);
assert_eq!(state.samples_available(), 0);
}
}

21
crates/wzp-codec/src/lib.rs
View File

@@ -15,7 +15,6 @@ pub mod agc;
pub mod codec2_dec;
pub mod codec2_enc;
pub mod denoise;
pub mod dred_ffi;
pub mod opus_dec;
pub mod opus_enc;
pub mod resample;
@@ -28,26 +27,6 @@ pub use denoise::NoiseSupressor;
pub use silence::{ComfortNoise, SilenceDetector};
pub use wzp_proto::{AudioDecoder, AudioEncoder, CodecId, QualityProfile};
use std::sync::atomic::{AtomicBool, Ordering};
/// Global verbose-logging flag for DRED. Off by default — when enabled
/// (via the GUI debug toggle wired through Tauri), the encoder logs its
/// DRED config + libopus version, and the recv path logs every DRED
/// reconstruction, classical PLC fill, and parse heartbeat. Off in
/// "normal" mode keeps logcat clean.
static DRED_VERBOSE_LOGS: AtomicBool = AtomicBool::new(false);
/// Returns whether DRED verbose logging is currently enabled.
#[inline]
pub fn dred_verbose_logs() -> bool {
DRED_VERBOSE_LOGS.load(Ordering::Relaxed)
}
/// Enable/disable DRED verbose logging at runtime.
pub fn set_dred_verbose_logs(enabled: bool) {
DRED_VERBOSE_LOGS.store(enabled, Ordering::Relaxed);
}
/// Create an adaptive encoder starting at the given quality profile.
///
/// The returned encoder accepts 48 kHz mono PCM regardless of the active

68
crates/wzp-codec/src/opus_dec.rs
View File

@@ -1,32 +1,30 @@
//! Opus decoder built on top of the raw opusic-sys `DecoderHandle`.
//!
//! Phase 0 of the DRED integration: we went straight to a custom
//! `DecoderHandle` instead of `opusic_c::Decoder` because the latter's
//! inner pointer is `pub(crate)` and we need to reach it in Phase 3 for
//! `opus_decoder_dred_decode`. See `dred_ffi.rs` for the rationale and
//! `docs/PRD-dred-integration.md` for the full plan.
//! Opus decoder wrapping the `audiopus` crate.
use crate::dred_ffi::{DecoderHandle, DredState};
use audiopus::coder::Decoder;
use audiopus::{Channels, MutSignals, SampleRate};
use audiopus::packet::Packet;
use wzp_proto::{AudioDecoder, CodecError, CodecId, QualityProfile};
/// Opus decoder implementing [`AudioDecoder`].
/// Opus decoder implementing `AudioDecoder`.
///
/// Operates at 48 kHz mono output. 20 ms and 40 ms frames supported via
/// the active `QualityProfile`. Behavior is intentionally identical to
/// the pre-swap audiopus-based decoder at this phase — DRED reconstruction
/// lands in Phase 3.
/// Operates at 48 kHz mono output.
pub struct OpusDecoder {
inner: DecoderHandle,
inner: Decoder,
codec_id: CodecId,
frame_duration_ms: u8,
}
// SAFETY: Same reasoning as OpusEncoder — exclusive access via &mut self.
unsafe impl Sync for OpusDecoder {}
impl OpusDecoder {
/// Create a new Opus decoder for the given quality profile.
pub fn new(profile: QualityProfile) -> Result<Self, CodecError> {
let inner = DecoderHandle::new()?;
let decoder = Decoder::new(SampleRate::Hz48000, Channels::Mono)
.map_err(|e| CodecError::DecodeFailed(format!("opus decoder init: {e}")))?;
Ok(Self {
inner,
inner: decoder,
codec_id: profile.codec,
frame_duration_ms: profile.frame_duration_ms,
})
@@ -36,24 +34,6 @@ impl OpusDecoder {
pub fn frame_samples(&self) -> usize {
(48_000 * self.frame_duration_ms as usize) / 1000
}
/// Reconstruct a lost frame from a previously parsed `DredState`.
///
/// Phase 3b entry point: callers (CallDecoder / engine.rs) use this to
/// synthesize audio for gaps detected by the jitter buffer when DRED
/// side-channel state from a later-arriving packet covers the gap's
/// sample offset. `offset_samples` is measured backward from the anchor
/// packet that produced `state`. See `DecoderHandle::reconstruct_from_dred`
/// for the full semantics.
pub fn reconstruct_from_dred(
&mut self,
state: &DredState,
offset_samples: i32,
output: &mut [i16],
) -> Result<usize, CodecError> {
self.inner
.reconstruct_from_dred(state, offset_samples, output)
}
}
impl AudioDecoder for OpusDecoder {
@@ -65,7 +45,15 @@ impl AudioDecoder for OpusDecoder {
pcm.len()
)));
}
self.inner.decode(encoded, pcm)
let packet = Packet::try_from(encoded)
.map_err(|e| CodecError::DecodeFailed(format!("invalid packet: {e}")))?;
let signals = MutSignals::try_from(pcm)
.map_err(|e| CodecError::DecodeFailed(format!("output signals: {e}")))?;
let n = self
.inner
.decode(Some(packet), signals, false)
.map_err(|e| CodecError::DecodeFailed(format!("opus decode: {e}")))?;
Ok(n)
}
fn decode_lost(&mut self, pcm: &mut [i16]) -> Result<usize, CodecError> {
@@ -76,7 +64,13 @@ impl AudioDecoder for OpusDecoder {
pcm.len()
)));
}
self.inner.decode_lost(pcm)
let signals = MutSignals::try_from(pcm)
.map_err(|e| CodecError::DecodeFailed(format!("output signals: {e}")))?;
let n = self
.inner
.decode(None, signals, false)
.map_err(|e| CodecError::DecodeFailed(format!("opus PLC: {e}")))?;
Ok(n)
}
fn codec_id(&self) -> CodecId {
@@ -85,7 +79,7 @@ impl AudioDecoder for OpusDecoder {
fn set_profile(&mut self, profile: QualityProfile) -> Result<(), CodecError> {
match profile.codec {
c if c.is_opus() => {
CodecId::Opus24k | CodecId::Opus16k | CodecId::Opus6k => {
self.codec_id = profile.codec;
self.frame_duration_ms = profile.frame_duration_ms;
Ok(())

442
crates/wzp-codec/src/opus_enc.rs
View File

@@ -1,225 +1,58 @@
//! Opus encoder wrapping the `opusic-c` crate (libopus 1.5.2).
//!
//! Phase 1 of the DRED integration: encoder-side DRED is enabled on every
//! Opus profile with a tiered duration (studio 100 ms / normal 200 ms /
//! degraded 500 ms), and Opus inband FEC (LBRR) is disabled because DRED
//! is the stronger mechanism for the same failure mode. The legacy behavior
//! is preserved behind the `AUDIO_USE_LEGACY_FEC` environment variable as a
//! runtime escape hatch for rollout. See `docs/PRD-dred-integration.md`.
//!
//! # DRED duration policy
//!
//! Rationale from the PRD:
//! - Studio tiers (Opus 32k/48k/64k): 100 ms — loss is rare on high-quality
//! networks; short window keeps decoder CPU modest.
//! - Normal tiers (Opus 16k/24k): 200 ms — balanced baseline covering common
//! VoIP loss patterns (20–150 ms bursts from wifi roam, transient congestion).
//! - Degraded tier (Opus 6k): 1040 ms — users on 6k are by definition on a
//! bad link; the maximum libopus DRED window buys the best burst resilience
//! where it matters. The RDO-VAE naturally degrades quality at longer offsets.
//!
//! # Why the 15% packet loss floor
//!
//! libopus 1.5's DRED emitter is gated on `OPUS_SET_PACKET_LOSS_PERC` and
//! scales the emitted window proportionally to the assumed loss:
//!
//! ```text
//! loss_pct samples_available effective_ms
//! 5% 720 15
//! 10% 2640 55
//! 15% 4560 95
//! 20% 6480 135
//! 25%+ 8400 (capped) 175 (≈ 87% of the 200ms configured max)
//! ```
//!
//! Measured empirically against libopus 1.5.2 on Opus 24k / 200 ms DRED
//! duration during Phase 3b. At 5% loss the window is only 15 ms — too
//! small to even reconstruct a single 20 ms Opus frame. 15% gives 95 ms
//! (enough for single-frame recovery plus modest burst margin) while
//! keeping the bitrate overhead modest compared to 25%. Real measurements
//! from the quality adapter override upward when loss exceeds the floor.
//! Opus encoder wrapping the `audiopus` crate.
use std::sync::OnceLock;
use opusic_c::{Application, Bitrate, Channels, Encoder, InbandFec, SampleRate, Signal};
use tracing::{debug, info, warn};
use audiopus::coder::Encoder;
use audiopus::{Application, Bitrate, Channels, SampleRate, Signal};
use tracing::debug;
use wzp_proto::{AudioEncoder, CodecError, CodecId, QualityProfile};
/// Logged exactly once per process the first time an OpusEncoder is built.
/// Confirms that libopus 1.5.2 (the version with DRED) is actually linked
/// at runtime — invaluable when chasing "is the new codec loaded?"
/// regressions on Android, where the only debug surface is logcat.
static LIBOPUS_VERSION_LOGGED: OnceLock<()> = OnceLock::new();
/// Minimum `OPUS_SET_PACKET_LOSS_PERC` value used in DRED mode. libopus
/// scales the DRED emission window with the assumed loss percentage:
/// empirically, 5% gives a 15 ms window (useless), 10% gives 55 ms, 15%
/// gives 95 ms, and 25%+ saturates the configured max (~175 ms at 200 ms
/// duration). 15% is the minimum value that produces a DRED window larger
/// than a single 20 ms frame, making it the minimum floor that actually
/// gives DRED something useful to reconstruct. Real loss measurements from
/// the quality adapter override this upward.
const DRED_LOSS_FLOOR_PCT: u8 = 15;
/// Environment variable that reverts Phase 1 behavior to Phase 0 (inband FEC
/// on, DRED off, no loss floor). Read once per encoder construction.
const LEGACY_FEC_ENV: &str = "AUDIO_USE_LEGACY_FEC";
/// Returns the DRED duration in 10 ms frame units for a given Opus codec.
///
/// Unit: each frame is 10 ms, so the max value of 104 corresponds to 1040 ms
/// of reconstructable history. Returns 0 for non-Opus codecs (DRED is not
/// emitted by the libopus encoder in that case anyway, but we avoid a
/// pointless FFI call).
///
/// See the DRED duration policy in the module docs for per-tier rationale.
pub fn dred_duration_for(codec: CodecId) -> u8 {
match codec {
// Studio tiers — loss is rare, short window.
CodecId::Opus32k | CodecId::Opus48k | CodecId::Opus64k => 10,
// Normal tiers — balanced baseline.
CodecId::Opus16k | CodecId::Opus24k => 20,
// Degraded tier — maximum burst resilience. 104 × 10 ms = 1040 ms,
// the highest value libopus 1.5 supports. Users on 6k are on a bad
// link by definition; the RDO-VAE naturally degrades quality at longer
// offsets, so the extra window costs only ~1-2 kbps additional overhead
// while buying substantially better burst resilience (up from 500 ms).
CodecId::Opus6k => 104,
// Non-Opus (Codec2 / CN): DRED is N/A.
CodecId::Codec2_1200 | CodecId::Codec2_3200 | CodecId::ComfortNoise => 0,
}
}
/// Returns whether the legacy-FEC escape hatch is active.
///
/// Read from `AUDIO_USE_LEGACY_FEC`. Any non-empty value activates legacy
/// mode; unset or empty leaves DRED enabled.
fn read_legacy_fec_env() -> bool {
match std::env::var(LEGACY_FEC_ENV) {
Ok(v) => !v.is_empty() && v != "0" && v.to_ascii_lowercase() != "false",
Err(_) => false,
}
}
/// Opus encoder implementing `AudioEncoder`.
///
/// Operates at 48 kHz mono. Supports 20 ms and 40 ms frames via the active
/// `QualityProfile`.
/// Operates at 48 kHz mono. Supports frame sizes of 20 ms (960 samples)
/// and 40 ms (1920 samples).
pub struct OpusEncoder {
inner: Encoder,
codec_id: CodecId,
frame_duration_ms: u8,
/// When `true`, revert to the Phase 0 behavior: inband FEC Mode1, DRED
/// disabled, no loss floor. Captured at construction time and not
/// re-read mid-call.
legacy_fec_mode: bool,
}
// SAFETY: OpusEncoder is only used via `&mut self` methods. The inner
// opusic-c Encoder wraps a non-null pointer that is !Sync by default,
// but we never share it across threads without exclusive access.
// audiopus Encoder contains a raw pointer that is !Sync, but we never
// share it across threads without exclusive access.
unsafe impl Sync for OpusEncoder {}
impl OpusEncoder {
/// Create a new Opus encoder for the given quality profile.
pub fn new(profile: QualityProfile) -> Result<Self, CodecError> {
// opusic-c argument order: (Channels, SampleRate, Application)
// — different from audiopus's (SampleRate, Channels, Application).
let encoder = Encoder::new(Channels::Mono, SampleRate::Hz48000, Application::Voip)
.map_err(|e| CodecError::EncodeFailed(format!("opus encoder init: {e:?}")))?;
let legacy_fec_mode = read_legacy_fec_env();
if legacy_fec_mode {
warn!(
"AUDIO_USE_LEGACY_FEC active — reverting Opus encoder to Phase 0 \
behavior (inband FEC Mode1, no DRED)"
);
}
let encoder = Encoder::new(SampleRate::Hz48000, Channels::Mono, Application::Voip)
.map_err(|e| CodecError::EncodeFailed(format!("opus encoder init: {e}")))?;
let mut enc = Self {
inner: encoder,
codec_id: profile.codec,
frame_duration_ms: profile.frame_duration_ms,
legacy_fec_mode,
};
// Common setup — bitrate, DTX, signal hint, complexity. These are
// identical regardless of the protection mode below.
enc.apply_bitrate(profile.codec)?;
enc.set_inband_fec(true);
enc.set_dtx(true);
// Voice signal type hint for better compression
enc.inner
.set_signal(Signal::Voice)
.map_err(|e| CodecError::EncodeFailed(format!("set signal: {e:?}")))?;
.map_err(|e| CodecError::EncodeFailed(format!("set signal: {e}")))?;
// Default complexity 7 — good quality/CPU trade-off for VoIP
enc.inner
.set_complexity(7)
.map_err(|e| CodecError::EncodeFailed(format!("set complexity: {e:?}")))?;
// Protection mode: DRED (Phase 1 default) or legacy inband FEC.
enc.apply_protection_mode(profile.codec)?;
.map_err(|e| CodecError::EncodeFailed(format!("set complexity: {e}")))?;
Ok(enc)
}
/// Configure the protection mode for the active codec.
///
/// In DRED mode (default): disable inband FEC, set DRED duration for the
/// codec tier, clamp packet_loss to the 5% floor so DRED stays active.
///
/// In legacy mode: enable inband FEC Mode1 (Phase 0 behavior), leave
/// DRED and packet_loss at libopus defaults.
fn apply_protection_mode(&mut self, codec: CodecId) -> Result<(), CodecError> {
if self.legacy_fec_mode {
self.inner
.set_inband_fec(InbandFec::Mode1)
.map_err(|e| CodecError::EncodeFailed(format!("set inband FEC: {e:?}")))?;
// Leave DRED at 0 and packet_loss at default — matches Phase 0.
return Ok(());
}
// DRED path: disable the overlapping inband FEC, enable DRED with
// per-profile duration, floor packet_loss so DRED emits.
self.inner
.set_inband_fec(InbandFec::Off)
.map_err(|e| CodecError::EncodeFailed(format!("set inband FEC off: {e:?}")))?;
let dred_frames = dred_duration_for(codec);
self.inner
.set_dred_duration(dred_frames)
.map_err(|e| CodecError::EncodeFailed(format!("set DRED duration: {e:?}")))?;
self.inner
.set_packet_loss(DRED_LOSS_FLOOR_PCT)
.map_err(|e| CodecError::EncodeFailed(format!("set packet loss floor: {e:?}")))?;
// Both of these are gated behind the GUI debug toggle so logcat
// stays clean in normal mode. Flip "DRED verbose logs" in the
// settings panel to see the per-encoder config + libopus version.
if crate::dred_verbose_logs() {
info!(
codec = ?codec,
dred_frames,
dred_ms = dred_frames as u32 * 10,
loss_floor_pct = DRED_LOSS_FLOOR_PCT,
"opus encoder: DRED enabled"
);
// One-shot logging of the linked libopus version so we can
// confirm at a glance that opusic-c (libopus 1.5.2) is loaded.
// Pre-Phase-0 audiopus shipped libopus 1.3 which has no DRED;
// if this log says "libopus 1.3" something is very wrong.
LIBOPUS_VERSION_LOGGED.get_or_init(|| {
info!(libopus_version = %opusic_c::version(), "linked libopus version");
});
}
Ok(())
}
fn apply_bitrate(&mut self, codec: CodecId) -> Result<(), CodecError> {
let bps = codec.bitrate_bps();
let bps = codec.bitrate_bps() as i32;
self.inner
.set_bitrate(Bitrate::Value(bps))
.map_err(|e| CodecError::EncodeFailed(format!("set bitrate: {e:?}")))?;
.set_bitrate(Bitrate::BitsPerSecond(bps))
.map_err(|e| CodecError::EncodeFailed(format!("set bitrate: {e}")))?;
debug!(bitrate_bps = bps, "opus encoder bitrate set");
Ok(())
}
@@ -238,36 +71,10 @@ impl OpusEncoder {
/// Hint the encoder about expected packet loss percentage (0-100).
///
/// In DRED mode, the value is floored at `DRED_LOSS_FLOOR_PCT` so the
/// encoder never drops DRED emission even on a perfect network. Real
/// loss measurements from the quality adapter override upward.
///
/// In legacy mode, the value is passed through unchanged (min 0, max 100).
/// Higher values cause the encoder to use more redundancy to survive
/// packet loss, at the expense of slightly higher bitrate.
pub fn set_expected_loss(&mut self, loss_pct: u8) {
let clamped = if self.legacy_fec_mode {
loss_pct.min(100)
} else {
loss_pct.max(DRED_LOSS_FLOOR_PCT).min(100)
};
let _ = self.inner.set_packet_loss(clamped);
}
/// Set the DRED duration in 10 ms frame units (0 disables, max 104).
///
/// No-op in legacy mode. Normally driven automatically by the active
/// quality profile via `apply_protection_mode`; this setter exists for
/// tests and for the rare case where a caller needs to override the
/// per-profile default.
pub fn set_dred_duration(&mut self, frames: u8) {
if self.legacy_fec_mode {
return;
}
let _ = self.inner.set_dred_duration(frames.min(104));
}
/// Test/introspection accessor: whether legacy FEC mode is active.
pub fn is_legacy_fec_mode(&self) -> bool {
self.legacy_fec_mode
let _ = self.inner.set_packet_loss_perc(loss_pct.min(100));
}
}
@@ -280,14 +87,10 @@ impl AudioEncoder for OpusEncoder {
pcm.len()
)));
}
// opusic-c takes &[u16] for the sample input. Bit pattern is
// identical to i16 — the cast is zero-cost and the encoder
// interprets the bytes the same way as libopus internally.
let pcm_u16: &[u16] = bytemuck::cast_slice(pcm);
let n = self
.inner
.encode_to_slice(pcm_u16, out)
.map_err(|e| CodecError::EncodeFailed(format!("opus encode: {e:?}")))?;
.encode(pcm, out)
.map_err(|e| CodecError::EncodeFailed(format!("opus encode: {e}")))?;
Ok(n)
}
@@ -297,13 +100,10 @@ impl AudioEncoder for OpusEncoder {
fn set_profile(&mut self, profile: QualityProfile) -> Result<(), CodecError> {
match profile.codec {
c if c.is_opus() => {
CodecId::Opus24k | CodecId::Opus16k | CodecId::Opus6k => {
self.codec_id = profile.codec;
self.frame_duration_ms = profile.frame_duration_ms;
self.apply_bitrate(profile.codec)?;
// Refresh DRED duration for the new tier. apply_protection_mode
// is idempotent and handles the legacy-vs-DRED branch correctly.
self.apply_protection_mode(profile.codec)?;
Ok(())
}
other => Err(CodecError::UnsupportedTransition {
@@ -320,198 +120,10 @@ impl AudioEncoder for OpusEncoder {
}
fn set_inband_fec(&mut self, enabled: bool) {
// In DRED mode, ignore external requests to re-enable inband FEC —
// running both mechanisms wastes bitrate on overlapping protection
// and opusic-c's own docs recommend disabling inband FEC when DRED
// is on. Trait callers that genuinely want classical FEC should set
// `AUDIO_USE_LEGACY_FEC=1` and re-create the encoder.
if !self.legacy_fec_mode {
debug!(
enabled,
"set_inband_fec ignored: DRED mode is active (set AUDIO_USE_LEGACY_FEC to revert)"
);
return;
}
let mode = if enabled { InbandFec::Mode1 } else { InbandFec::Off };
let _ = self.inner.set_inband_fec(mode);
let _ = self.inner.set_inband_fec(enabled);
}
fn set_dtx(&mut self, enabled: bool) {
let _ = self.inner.set_dtx(enabled);
}
fn set_expected_loss(&mut self, loss_pct: u8) {
OpusEncoder::set_expected_loss(self, loss_pct);
}
fn set_dred_duration(&mut self, frames: u8) {
OpusEncoder::set_dred_duration(self, frames);
}
}
#[cfg(test)]
mod tests {
use super::*;
use wzp_proto::AudioDecoder;
/// Phase 0 acceptance gate: fail loudly if the linked libopus is not 1.5.x.
/// DRED (Phase 1+) only exists in libopus ≥ 1.5, so running against an
/// older version would silently regress the entire DRED integration.
#[test]
fn linked_libopus_is_1_5() {
let version = opusic_c::version();
assert!(
version.contains("1.5"),
"expected libopus 1.5.x, got: {version}"
);
}
#[test]
fn encoder_creates_at_good_profile() {
let enc = OpusEncoder::new(QualityProfile::GOOD).expect("opus encoder init");
assert_eq!(enc.codec_id, CodecId::Opus24k);
assert_eq!(enc.frame_samples(), 960); // 20 ms @ 48 kHz
}
#[test]
fn encoder_roundtrip_silence() {
let mut enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
let mut dec = crate::opus_dec::OpusDecoder::new(QualityProfile::GOOD).unwrap();
let pcm_in = vec![0i16; 960]; // 20 ms silence
let mut encoded = vec![0u8; 512];
let n = enc.encode(&pcm_in, &mut encoded).unwrap();
assert!(n > 0);
let mut pcm_out = vec![0i16; 960];
let samples = dec.decode(&encoded[..n], &mut pcm_out).unwrap();
assert_eq!(samples, 960);
}
// ─── Phase 1 — DRED duration policy ─────────────────────────────────────
#[test]
fn dred_duration_for_studio_tiers_is_100ms() {
assert_eq!(dred_duration_for(CodecId::Opus32k), 10);
assert_eq!(dred_duration_for(CodecId::Opus48k), 10);
assert_eq!(dred_duration_for(CodecId::Opus64k), 10);
}
#[test]
fn dred_duration_for_normal_tiers_is_200ms() {
assert_eq!(dred_duration_for(CodecId::Opus16k), 20);
assert_eq!(dred_duration_for(CodecId::Opus24k), 20);
}
#[test]
fn dred_duration_for_degraded_tier_is_1040ms() {
assert_eq!(dred_duration_for(CodecId::Opus6k), 104);
}
#[test]
fn dred_duration_for_codec2_is_zero() {
assert_eq!(dred_duration_for(CodecId::Codec2_3200), 0);
assert_eq!(dred_duration_for(CodecId::Codec2_1200), 0);
assert_eq!(dred_duration_for(CodecId::ComfortNoise), 0);
}
// ─── Phase 1 — Legacy escape hatch ──────────────────────────────────────
/// By default (env var unset), legacy mode is off.
///
/// This test does NOT manipulate the environment to avoid flakiness
/// when the full suite runs in parallel. It only asserts on a freshly
/// created encoder in the ambient environment.
#[test]
fn default_mode_is_dred_not_legacy() {
// SAFETY: only run if the ambient env hasn't set the var externally.
if std::env::var(LEGACY_FEC_ENV).is_ok() {
return; // don't assert — someone set the env for a reason.
}
let enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
assert!(!enc.is_legacy_fec_mode());
}
// ─── Phase 1 — Behavioral regression: roundtrip still works ─────────────
#[test]
fn dred_mode_roundtrip_voice_pattern() {
// Use a realistic voice-like input (sine wave at speech frequencies)
// so the encoder emits meaningful DRED data rather than trivially
// compressible silence.
let mut enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
let mut dec = crate::opus_dec::OpusDecoder::new(QualityProfile::GOOD).unwrap();
let mut total_encoded_bytes = 0usize;
// Run 50 frames (1 second) so DRED fills up and starts emitting.
for frame_idx in 0..50 {
let pcm_in: Vec<i16> = (0..960)
.map(|i| {
let t = (frame_idx * 960 + i) as f64 / 48_000.0;
(8000.0 * (2.0 * std::f64::consts::PI * 300.0 * t).sin()) as i16
})
.collect();
let mut encoded = vec![0u8; 512];
let n = enc.encode(&pcm_in, &mut encoded).unwrap();
assert!(n > 0);
total_encoded_bytes += n;
let mut pcm_out = vec![0i16; 960];
let samples = dec.decode(&encoded[..n], &mut pcm_out).unwrap();
assert_eq!(samples, 960);
}
// Effective bitrate after 1 second of encoding.
// Opus 24k base + ~1 kbps DRED ≈ 25 kbps ≈ 3125 bytes/sec.
// Allow generous headroom (2000 lower bound, 8000 upper bound) —
// this is a behavioral regression check, not a tight bitrate assertion.
// The exact value is printed with --nocapture for diagnostic use.
eprintln!(
"[phase1 bitrate probe] legacy_fec_mode={} total_encoded={} bytes/sec",
enc.is_legacy_fec_mode(),
total_encoded_bytes
);
assert!(
total_encoded_bytes > 2000,
"encoder output too small: {total_encoded_bytes} bytes/sec (DRED likely not emitting)"
);
assert!(
total_encoded_bytes < 8000,
"encoder output too large: {total_encoded_bytes} bytes/sec"
);
}
// ─── Phase 1 — set_profile updates DRED duration on tier switch ─────────
#[test]
fn profile_switch_refreshes_dred_duration() {
// Start on GOOD (Opus 24k, DRED 20 frames), switch to DEGRADED
// (Opus 6k, DRED 50 frames). The encoder should accept both profile
// changes without error. We can't directly observe the DRED duration
// inside libopus, but apply_protection_mode returns Ok for both.
let mut enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
assert_eq!(enc.codec_id, CodecId::Opus24k);
enc.set_profile(QualityProfile::DEGRADED).unwrap();
assert_eq!(enc.codec_id, CodecId::Opus6k);
enc.set_profile(QualityProfile::STUDIO_64K).unwrap();
assert_eq!(enc.codec_id, CodecId::Opus64k);
}
// ─── Phase 1 — Trait set_inband_fec is a no-op in DRED mode ─────────────
#[test]
fn set_inband_fec_noop_in_dred_mode() {
if std::env::var(LEGACY_FEC_ENV).is_ok() {
return;
}
let mut enc = OpusEncoder::new(QualityProfile::GOOD).unwrap();
// Should not error, should not re-enable inband FEC internally.
enc.set_inband_fec(true);
// We can't directly query libopus's inband FEC state through opusic-c,
// but the call must not panic and the encoder must still work.
let pcm_in = vec![0i16; 960];
let mut encoded = vec![0u8; 512];
let n = enc.encode(&pcm_in, &mut encoded).unwrap();
assert!(n > 0);
}
}

64
crates/wzp-crypto/src/handshake.rs
View File

@@ -18,14 +18,10 @@ use crate::session::ChaChaSession;
pub struct WarzoneKeyExchange {
/// Ed25519 signing key (identity).
signing_key: SigningKey,
/// X25519 static secret derived from identity seed. Reserved for future
/// use in static-key federation authentication (not used in current
/// ephemeral-only handshake protocol).
/// X25519 static secret (derived from seed, used for identity encryption).
#[allow(dead_code)]
x25519_static_secret: StaticSecret,
/// X25519 static public key derived from identity seed. Reserved for
/// future use in static-key federation authentication (not used in
/// current ephemeral-only handshake protocol).
/// X25519 static public key.
#[allow(dead_code)]
x25519_static_public: X25519PublicKey,
/// Ephemeral X25519 secret for the current call (set by generate_ephemeral).
@@ -114,18 +110,7 @@ impl KeyExchange for WarzoneKeyExchange {
hk.expand(b"warzone-session-key", &mut session_key)
.expect("HKDF expand for session key should not fail");
// Derive SAS (Short Authentication String) from shared secret only.
// The shared secret is identical on both sides (X25519 DH property).
// A MITM would produce a different shared secret → different SAS.
// We use a dedicated HKDF label so SAS is independent of the session key.
let mut sas_key = [0u8; 4];
hk.expand(b"warzone-sas-code", &mut sas_key)
.expect("HKDF expand for SAS should not fail");
let sas_code = u32::from_be_bytes(sas_key) % 10000;
let mut session = ChaChaSession::new(session_key);
session.set_sas(sas_code);
Ok(Box::new(session))
Ok(Box::new(ChaChaSession::new(session_key)))
}
}
@@ -226,47 +211,4 @@ mod tests {
assert_eq!(&decrypted, plaintext);
}
#[test]
fn sas_codes_match_between_peers() {
let mut alice = WarzoneKeyExchange::from_identity_seed(&[0xAA; 32]);
let mut bob = WarzoneKeyExchange::from_identity_seed(&[0xBB; 32]);
let alice_eph_pub = alice.generate_ephemeral();
let bob_eph_pub = bob.generate_ephemeral();
let alice_session = alice.derive_session(&bob_eph_pub).unwrap();
let bob_session = bob.derive_session(&alice_eph_pub).unwrap();
let alice_sas = alice_session.sas_code();
let bob_sas = bob_session.sas_code();
assert!(alice_sas.is_some(), "Alice should have SAS");
assert!(bob_sas.is_some(), "Bob should have SAS");
assert_eq!(alice_sas, bob_sas, "SAS codes must match between peers");
assert!(alice_sas.unwrap() < 10000, "SAS should be 4 digits");
}
#[test]
fn sas_differs_for_different_peers() {
let mut alice = WarzoneKeyExchange::from_identity_seed(&[0xAA; 32]);
let mut bob = WarzoneKeyExchange::from_identity_seed(&[0xBB; 32]);
let mut eve = WarzoneKeyExchange::from_identity_seed(&[0xEE; 32]);
let alice_eph = alice.generate_ephemeral();
let bob_eph = bob.generate_ephemeral();
let eve_eph = eve.generate_ephemeral();
let alice_bob_session = alice.derive_session(&bob_eph).unwrap();
// Eve does separate handshake with Bob (MITM scenario)
let eve_bob_session = eve.derive_session(&bob_eph).unwrap();
// SAS codes should differ — Eve's session has different shared secret
assert_ne!(
alice_bob_session.sas_code(),
eve_bob_session.sas_code(),
"MITM session should produce different SAS"
);
}
}

12
crates/wzp-crypto/src/session.rs
View File

@@ -26,8 +26,6 @@ pub struct ChaChaSession {
rekey_mgr: RekeyManager,
/// Pending ephemeral secret for rekey (stored until peer responds).
pending_rekey_secret: Option<StaticSecret>,
/// Short Authentication String (4-digit code for verbal verification).
sas_code: Option<u32>,
}
impl ChaChaSession {
@@ -48,15 +46,9 @@ impl ChaChaSession {
recv_seq: 0,
rekey_mgr: RekeyManager::new(shared_secret),
pending_rekey_secret: None,
sas_code: None,
}
}
/// Set the SAS code (called by key exchange after derivation).
pub fn set_sas(&mut self, code: u32) {
self.sas_code = Some(code);
}
/// Install a new key (after rekeying).
fn install_key(&mut self, new_key: [u8; 32]) {
use sha2::Digest;
@@ -144,10 +136,6 @@ impl CryptoSession for ChaChaSession {
Ok(())
}
fn sas_code(&self) -> Option<u32> {
self.sas_code
}
}
#[cfg(test)]

6
crates/wzp-crypto/tests/featherchat_compat.rs
View File

@@ -115,7 +115,6 @@ fn wzp_signal_serializes_into_fc_callsignal_payload() {
ephemeral_pub: [2u8; 32],
signature: vec![3u8; 64],
supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
alias: None,
};
// Encode as featherChat CallSignal payload
@@ -199,7 +198,6 @@ fn wzp_answer_round_trips_through_fc_callsignal() {
fn wzp_hangup_round_trips_through_fc_callsignal() {
let hangup = wzp_proto::SignalMessage::Hangup {
reason: wzp_proto::HangupReason::Normal,
call_id: None,
};
let payload = wzp_client::featherchat::encode_call_payload(&hangup, None, None);
@@ -275,14 +273,13 @@ fn auth_invalid_response_matches() {
#[test]
fn all_signal_types_map_correctly() {
use wzp_client::featherchat::signal_to_call_type;
use wzp_client::featherchat::{signal_to_call_type, CallSignalType};
let cases: Vec<(wzp_proto::SignalMessage, &str)> = vec![
(
wzp_proto::SignalMessage::CallOffer {
identity_pub: [0; 32], ephemeral_pub: [0; 32],
signature: vec![], supported_profiles: vec![],
alias: None,
},
"Offer",
),
@@ -303,7 +300,6 @@ fn all_signal_types_map_correctly() {
(
wzp_proto::SignalMessage::Hangup {
reason: wzp_proto::HangupReason::Normal,
call_id: None,
},
"Hangup",
),

24
crates/wzp-fec/src/decoder.rs
View File

@@ -1,7 +1,6 @@
//! RaptorQ FEC decoder — reassembles source blocks from received source and repair symbols.
use std::collections::HashMap;
use std::time::Instant;
use raptorq::{EncodingPacket, ObjectTransmissionInformation, PayloadId, SourceBlockDecoder};
use wzp_proto::error::FecError;
@@ -10,9 +9,6 @@ use wzp_proto::FecDecoder;
/// Length prefix size (u16 little-endian), must match encoder.
const LEN_PREFIX: usize = 2;
/// Decoded blocks older than this are eligible for reuse by a new sender.
const BLOCK_STALE_SECS: u64 = 2;
/// State for one in-flight block being decoded.
struct BlockState {
/// Number of source symbols expected.
@@ -25,8 +21,6 @@ struct BlockState {
decoded: bool,
/// Cached decoded result.
result: Option<Vec<Vec<u8>>>,
/// When this block was last decoded (for staleness check).
decoded_at: Option<Instant>,
}
/// RaptorQ-based FEC decoder that handles multiple concurrent blocks.
@@ -64,7 +58,6 @@ impl RaptorQFecDecoder {
symbol_size: self.symbol_size,
decoded: false,
result: None,
decoded_at: None,
})
}
}
@@ -81,20 +74,8 @@ impl FecDecoder for RaptorQFecDecoder {
let block = self.get_or_create_block(block_id);
if block.decoded {
// If the block was decoded recently, skip (normal duplicate).
// If it's stale (>2s), a new sender is reusing this block_id — reset it.
if let Some(at) = block.decoded_at {
if at.elapsed().as_secs() >= BLOCK_STALE_SECS {
block.decoded = false;
block.result = None;
block.decoded_at = None;
block.packets.clear();
} else {
return Ok(());
}
} else {
return Ok(());
}
// Already decoded, ignore additional symbols.
return Ok(());
}
// Data should already be at symbol_size (length-prefixed and padded by the encoder).
@@ -151,7 +132,6 @@ impl FecDecoder for RaptorQFecDecoder {
let block = self.blocks.get_mut(&block_id).unwrap();
block.decoded = true;
block.decoded_at = Some(Instant::now());
block.result = Some(frames.clone());
Ok(Some(frames))
}

29
crates/wzp-native/Cargo.toml
View File

@@ -1,29 +0,0 @@
[package]
name = "wzp-native"
version = "0.1.0"
edition = "2024"
description = "WarzonePhone native audio library — standalone Android cdylib that eventually owns all C++ (Oboe bridge) and exposes a pure-C FFI. Built with cargo-ndk, loaded at runtime by the Tauri desktop cdylib via libloading."
# Crate-type is DELIBERATELY only cdylib (no rlib, no staticlib). This crate
# is built with `cargo ndk -t arm64-v8a build --release -p wzp-native` as a
# standalone .so, which is the same path the legacy wzp-android crate uses
# successfully on the same phone / same NDK. Keeping the crate-type single
# avoids the rust-lang/rust#104707 symbol leak that bit us when Tauri's
# desktop crate had ["staticlib", "cdylib", "rlib"] and any C++ static
# archive pulled bionic's internal pthread_create into the final .so.
[lib]
name = "wzp_native"
crate-type = ["cdylib"]
[build-dependencies]
# cc is SAFE to use here because this crate is a single-cdylib: no
# staticlib in crate-type → no rust-lang/rust#104707 symbol leak. The
# legacy wzp-android crate uses the same setup and works.
cc = "1"
[dependencies]
# Phase 2: Oboe C++ audio bridge. Still no Rust deps — we do the whole
# audio pipeline via extern "C" into the bundled C++ and expose our own
# narrow extern "C" API for wzp-desktop to dlopen via libloading.
# Phase 3 can add wzp-proto/wzp-codec if we want to share codec logic
# instead of calling back into wzp-desktop via callbacks.

119
crates/wzp-native/build.rs
View File

@@ -1,119 +0,0 @@
//! wzp-native build.rs — Oboe C++ bridge compile on Android.
//!
//! Near-verbatim copy of crates/wzp-android/build.rs (which is known to
//! work). The crucial distinction: this crate is a single-cdylib (no
//! staticlib, no rlib in crate-type) so rust-lang/rust#104707 doesn't
//! apply — bionic's internal pthread_create / __init_tcb symbols stay
//! UND and resolve against libc.so at runtime, as they should.
//!
//! On non-Android hosts we compile `cpp/oboe_stub.cpp` (empty stubs) so
//! `cargo check --target <host>` still works for IDEs and CI.
use std::path::PathBuf;
fn main() {
let target = std::env::var("TARGET").unwrap_or_default();
if target.contains("android") {
// getauxval_fix: override compiler-rt's broken static getauxval
// stub that SIGSEGVs in shared libraries.
cc::Build::new()
.file("cpp/getauxval_fix.c")
.compile("wzp_native_getauxval_fix");
let oboe_dir = fetch_oboe();
match oboe_dir {
Some(oboe_path) => {
println!("cargo:warning=wzp-native: building with Oboe from {:?}", oboe_path);
let mut build = cc::Build::new();
build
.cpp(true)
.std("c++17")
// Shared libc++ — matches legacy wzp-android setup.
.cpp_link_stdlib(Some("c++_shared"))
.include("cpp")
.include(oboe_path.join("include"))
.include(oboe_path.join("src"))
.define("WZP_HAS_OBOE", None)
.file("cpp/oboe_bridge.cpp");
add_cpp_files_recursive(&mut build, &oboe_path.join("src"));
build.compile("wzp_native_oboe_bridge");
}
None => {
println!("cargo:warning=wzp-native: Oboe not found, building stub");
cc::Build::new()
.cpp(true)
.std("c++17")
.cpp_link_stdlib(Some("c++_shared"))
.file("cpp/oboe_stub.cpp")
.include("cpp")
.compile("wzp_native_oboe_bridge");
}
}
// Oboe needs log + OpenSLES backends at runtime.
println!("cargo:rustc-link-lib=log");
println!("cargo:rustc-link-lib=OpenSLES");
// Re-run if any cpp file changes
println!("cargo:rerun-if-changed=cpp/oboe_bridge.cpp");
println!("cargo:rerun-if-changed=cpp/oboe_bridge.h");
println!("cargo:rerun-if-changed=cpp/oboe_stub.cpp");
println!("cargo:rerun-if-changed=cpp/getauxval_fix.c");
} else {
// Non-Android hosts: compile the empty stub so lib.rs's extern
// declarations resolve when someone runs `cargo check` on macOS
// or Linux without an NDK.
cc::Build::new()
.cpp(true)
.std("c++17")
.file("cpp/oboe_stub.cpp")
.include("cpp")
.compile("wzp_native_oboe_bridge");
println!("cargo:rerun-if-changed=cpp/oboe_stub.cpp");
}
}
/// Recursively add all `.cpp` files from a directory to a cc::Build.
fn add_cpp_files_recursive(build: &mut cc::Build, dir: &std::path::Path) {
if !dir.is_dir() {
return;
}
for entry in std::fs::read_dir(dir).unwrap() {
let entry = entry.unwrap();
let path = entry.path();
if path.is_dir() {
add_cpp_files_recursive(build, &path);
} else if path.extension().map_or(false, |e| e == "cpp") {
build.file(&path);
}
}
}
/// Fetch or find Oboe headers + sources (v1.8.1). Same logic as the
/// legacy wzp-android crate's build.rs.
fn fetch_oboe() -> Option<PathBuf> {
let out_dir = PathBuf::from(std::env::var("OUT_DIR").unwrap());
let oboe_dir = out_dir.join("oboe");
if oboe_dir.join("include").join("oboe").join("Oboe.h").exists() {
return Some(oboe_dir);
}
let status = std::process::Command::new("git")
.args([
"clone",
"--depth=1",
"--branch=1.8.1",
"https://github.com/google/oboe.git",
oboe_dir.to_str().unwrap(),
])
.status();
match status {
Ok(s) if s.success() && oboe_dir.join("include").join("oboe").join("Oboe.h").exists() => {
Some(oboe_dir)
}
_ => None,
}
}

21
crates/wzp-native/cpp/getauxval_fix.c
View File

@@ -1,21 +0,0 @@
// Override the broken static getauxval from compiler-rt/CRT.
// The static version reads from __libc_auxv which is NULL in shared libs
// loaded via dlopen, causing SIGSEGV in init_have_lse_atomics at load time.
// This version calls the real bionic getauxval via dlsym.
#ifdef __ANDROID__
#include <dlfcn.h>
#include <stdint.h>
typedef unsigned long (*getauxval_fn)(unsigned long);
unsigned long getauxval(unsigned long type) {
static getauxval_fn real_getauxval = (getauxval_fn)0;
if (!real_getauxval) {
real_getauxval = (getauxval_fn)dlsym((void*)-1L /* RTLD_DEFAULT */, "getauxval");
if (!real_getauxval) {
return 0;
}
}
return real_getauxval(type);
}
#endif

477
crates/wzp-native/cpp/oboe_bridge.cpp
View File

@@ -1,477 +0,0 @@
// Full Oboe implementation for Android
// This file is compiled only when targeting Android
#include "oboe_bridge.h"
#ifdef __ANDROID__
#include <oboe/Oboe.h>
#include <android/log.h>
#include <cstring>
#include <atomic>
#include <chrono>
#include <thread>
#define LOG_TAG "wzp-oboe"
#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
#define LOGW(...) __android_log_print(ANDROID_LOG_WARN, LOG_TAG, __VA_ARGS__)
#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
// ---------------------------------------------------------------------------
// Ring buffer helpers (SPSC, lock-free)
// ---------------------------------------------------------------------------
static inline int32_t ring_available_read(const wzp_atomic_int* write_idx,
const wzp_atomic_int* read_idx,
int32_t capacity) {
int32_t w = std::atomic_load_explicit(write_idx, std::memory_order_acquire);
int32_t r = std::atomic_load_explicit(read_idx, std::memory_order_relaxed);
int32_t avail = w - r;
if (avail < 0) avail += capacity;
return avail;
}
static inline int32_t ring_available_write(const wzp_atomic_int* write_idx,
const wzp_atomic_int* read_idx,
int32_t capacity) {
return capacity - 1 - ring_available_read(write_idx, read_idx, capacity);
}
static inline void ring_write(int16_t* buf, int32_t capacity,
wzp_atomic_int* write_idx, const wzp_atomic_int* read_idx,
const int16_t* src, int32_t count) {
int32_t w = std::atomic_load_explicit(write_idx, std::memory_order_relaxed);
for (int32_t i = 0; i < count; i++) {
buf[w] = src[i];
w++;
if (w >= capacity) w = 0;
}
std::atomic_store_explicit(write_idx, w, std::memory_order_release);
}
static inline void ring_read(int16_t* buf, int32_t capacity,
const wzp_atomic_int* write_idx, wzp_atomic_int* read_idx,
int16_t* dst, int32_t count) {
int32_t r = std::atomic_load_explicit(read_idx, std::memory_order_relaxed);
for (int32_t i = 0; i < count; i++) {
dst[i] = buf[r];
r++;
if (r >= capacity) r = 0;
}
std::atomic_store_explicit(read_idx, r, std::memory_order_release);
}
// ---------------------------------------------------------------------------
// Global state
// ---------------------------------------------------------------------------
static std::shared_ptr<oboe::AudioStream> g_capture_stream;
static std::shared_ptr<oboe::AudioStream> g_playout_stream;
// Value copy — the WzpOboeRings the Rust side passes us lives on the caller's
// stack frame and goes away as soon as wzp_oboe_start returns. The raw
// int16/atomic pointers INSIDE the struct point into the Rust-owned, leaked-
// for-the-lifetime-of-the-process AudioBackend singleton, so copying the
// struct by value is safe and keeps the inner pointers valid indefinitely.
// g_rings_valid guards the audio-callback-side read; clearing it in stop()
// signals "no backend" to the callbacks which then return silence + Stop.
static WzpOboeRings g_rings{};
static std::atomic<bool> g_rings_valid{false};
static std::atomic<bool> g_running{false};
static std::atomic<float> g_capture_latency_ms{0.0f};
static std::atomic<float> g_playout_latency_ms{0.0f};
// ---------------------------------------------------------------------------
// Capture callback
// ---------------------------------------------------------------------------
class CaptureCallback : public oboe::AudioStreamDataCallback {
public:
uint64_t calls = 0;
uint64_t total_frames = 0;
uint64_t total_written = 0;
uint64_t ring_full_drops = 0;
oboe::DataCallbackResult onAudioReady(
oboe::AudioStream* stream,
void* audioData,
int32_t numFrames) override {
if (!g_running.load(std::memory_order_relaxed) ||
!g_rings_valid.load(std::memory_order_acquire)) {
return oboe::DataCallbackResult::Stop;
}
const int16_t* src = static_cast<const int16_t*>(audioData);
int32_t avail = ring_available_write(g_rings.capture_write_idx,
g_rings.capture_read_idx,
g_rings.capture_capacity);
int32_t to_write = (numFrames < avail) ? numFrames : avail;
if (to_write > 0) {
ring_write(g_rings.capture_buf, g_rings.capture_capacity,
g_rings.capture_write_idx, g_rings.capture_read_idx,
src, to_write);
}
total_frames += numFrames;
total_written += to_write;
if (to_write < numFrames) {
ring_full_drops += (numFrames - to_write);
}
// Sample-range probe on the FIRST callback to prove we get real audio
if (calls == 0 && numFrames > 0) {
int16_t lo = src[0], hi = src[0];
int32_t sumsq = 0;
for (int32_t i = 0; i < numFrames; i++) {
if (src[i] < lo) lo = src[i];
if (src[i] > hi) hi = src[i];
sumsq += (int32_t)src[i] * (int32_t)src[i];
}
int32_t rms = (int32_t) (numFrames > 0 ? (int32_t)__builtin_sqrt((double)sumsq / (double)numFrames) : 0);
LOGI("capture cb#0: numFrames=%d sample_range=[%d..%d] rms=%d to_write=%d",
numFrames, lo, hi, rms, to_write);
}
// Heartbeat every 50 callbacks (~1s at 20ms/burst)
calls++;
if ((calls % 50) == 0) {
LOGI("capture heartbeat: calls=%llu numFrames=%d ring_avail_write=%d to_write=%d full_drops=%llu total_written=%llu",
(unsigned long long)calls, numFrames, avail, to_write,
(unsigned long long)ring_full_drops, (unsigned long long)total_written);
}
// Update latency estimate
auto result = stream->calculateLatencyMillis();
if (result) {
g_capture_latency_ms.store(static_cast<float>(result.value()),
std::memory_order_relaxed);
}
return oboe::DataCallbackResult::Continue;
}
};
// ---------------------------------------------------------------------------
// Playout callback
// ---------------------------------------------------------------------------
class PlayoutCallback : public oboe::AudioStreamDataCallback {
public:
uint64_t calls = 0;
uint64_t total_frames = 0;
uint64_t total_played_real = 0;
uint64_t underrun_frames = 0;
uint64_t nonempty_calls = 0;
oboe::DataCallbackResult onAudioReady(
oboe::AudioStream* stream,
void* audioData,
int32_t numFrames) override {
if (!g_running.load(std::memory_order_relaxed) ||
!g_rings_valid.load(std::memory_order_acquire)) {
memset(audioData, 0, numFrames * sizeof(int16_t));
return oboe::DataCallbackResult::Stop;
}
int16_t* dst = static_cast<int16_t*>(audioData);
int32_t avail = ring_available_read(g_rings.playout_write_idx,
g_rings.playout_read_idx,
g_rings.playout_capacity);
int32_t to_read = (numFrames < avail) ? numFrames : avail;
if (to_read > 0) {
ring_read(g_rings.playout_buf, g_rings.playout_capacity,
g_rings.playout_write_idx, g_rings.playout_read_idx,
dst, to_read);
nonempty_calls++;
}
// Fill remainder with silence on underrun
if (to_read < numFrames) {
memset(dst + to_read, 0, (numFrames - to_read) * sizeof(int16_t));
underrun_frames += (numFrames - to_read);
}
total_frames += numFrames;
total_played_real += to_read;
// First callback: log requested config + prove we're being called
if (calls == 0) {
LOGI("playout cb#0: numFrames=%d ring_avail_read=%d to_read=%d",
numFrames, avail, to_read);
}
// On the first callback that actually has data, log the sample range
// so we can tell if the samples coming out of the ring look like real
// audio vs constant-zeroes vs garbage.
if (to_read > 0 && nonempty_calls == 1) {
int16_t lo = dst[0], hi = dst[0];
int32_t sumsq = 0;
for (int32_t i = 0; i < to_read; i++) {
if (dst[i] < lo) lo = dst[i];
if (dst[i] > hi) hi = dst[i];
sumsq += (int32_t)dst[i] * (int32_t)dst[i];
}
int32_t rms = (to_read > 0) ? (int32_t)__builtin_sqrt((double)sumsq / (double)to_read) : 0;
LOGI("playout FIRST nonempty read: to_read=%d sample_range=[%d..%d] rms=%d",
to_read, lo, hi, rms);
}
// Heartbeat every 50 callbacks (~1s at 20ms/burst)
calls++;
if ((calls % 50) == 0) {
int state = (int)stream->getState();
auto xrunRes = stream->getXRunCount();
int xruns = xrunRes ? xrunRes.value() : -1;
LOGI("playout heartbeat: calls=%llu nonempty=%llu numFrames=%d ring_avail_read=%d to_read=%d underrun_frames=%llu total_played_real=%llu state=%d xruns=%d",
(unsigned long long)calls, (unsigned long long)nonempty_calls,
numFrames, avail, to_read,
(unsigned long long)underrun_frames, (unsigned long long)total_played_real,
state, xruns);
}
// Update latency estimate
auto result = stream->calculateLatencyMillis();
if (result) {
g_playout_latency_ms.store(static_cast<float>(result.value()),
std::memory_order_relaxed);
}
return oboe::DataCallbackResult::Continue;
}
};
static CaptureCallback g_capture_cb;
static PlayoutCallback g_playout_cb;
// ---------------------------------------------------------------------------
// Public C API
// ---------------------------------------------------------------------------
int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
if (g_running.load(std::memory_order_relaxed)) {
LOGW("wzp_oboe_start: already running");
return -1;
}
// Deep-copy the rings struct into static storage BEFORE we publish it to
// the audio callbacks — `rings` points at the caller's stack frame and
// goes away as soon as this function returns.
g_rings = *rings;
g_rings_valid.store(true, std::memory_order_release);
// Build capture stream
oboe::AudioStreamBuilder captureBuilder;
captureBuilder.setDirection(oboe::Direction::Input)
->setPerformanceMode(oboe::PerformanceMode::LowLatency)
->setSharingMode(oboe::SharingMode::Shared)
->setFormat(oboe::AudioFormat::I16)
->setChannelCount(config->channel_count)
->setSampleRateConversionQuality(oboe::SampleRateConversionQuality::Best)
->setDataCallback(&g_capture_cb);
if (config->bt_active) {
// BT SCO mode: do NOT set sample rate or input preset.
// Requesting 48kHz against a BT SCO device fails with
// "getInputProfile could not find profile". Letting the system
// choose the native rate (8/16kHz) and relying on Oboe's
// resampler (SampleRateConversionQuality::Best) to bridge
// to our 48kHz ring buffer is the only path that works.
// InputPreset::VoiceCommunication can also prevent BT SCO
// routing on some devices — skip it for BT.
LOGI("capture: BT mode — no sample rate or input preset set");
} else {
captureBuilder.setSampleRate(config->sample_rate)
->setFramesPerDataCallback(config->frames_per_burst)
->setInputPreset(oboe::InputPreset::VoiceCommunication);
}
oboe::Result result = captureBuilder.openStream(g_capture_stream);
if (result != oboe::Result::OK) {
LOGE("Failed to open capture stream: %s", oboe::convertToText(result));
return -2;
}
LOGI("capture stream opened: actualSR=%d actualCh=%d actualFormat=%d actualFramesPerBurst=%d actualFramesPerDataCallback=%d bufferCapacityInFrames=%d sharing=%d perfMode=%d",
g_capture_stream->getSampleRate(),
g_capture_stream->getChannelCount(),
(int)g_capture_stream->getFormat(),
g_capture_stream->getFramesPerBurst(),
g_capture_stream->getFramesPerDataCallback(),
g_capture_stream->getBufferCapacityInFrames(),
(int)g_capture_stream->getSharingMode(),
(int)g_capture_stream->getPerformanceMode());
// Build playout stream.
//
// Regression triangulation between builds:
// 96be740 (Usage::Media, default API): playout callback DID drain
// the ring at steady 50Hz (playout heartbeat: calls=1100,
// total_played_real=1055040). Audio not audible because OS routing
// sent it to a silent output.
//
// 8c36fb5 (Usage::VoiceCommunication + setAudioApi(AAudio) +
// ContentType::Speech): playout callback fired cb#0 once then
// stopped draining the ring entirely. written_samples stuck at
// ring capacity (7679) across all subsequent heartbeats, so Oboe
// accepted zero samples after startup. Still inaudible.
//
// Hypothesis: forcing setAudioApi(AAudio) + VoiceCommunication on
// Pixel 6 / Android 15 opens a stream that succeeds at cb#0 but
// then detaches from the real audio driver. Reverting to the
// config that at least drove callbacks correctly, plus the
// Kotlin-side MODE_IN_COMMUNICATION + setSpeakerphoneOn(true)
// handled in MainActivity.kt to route audio to the loud speaker.
// Usage::VoiceCommunication is the correct Oboe usage for a VoIP app
// — it respects Android's in-call audio routing and lets
// AudioManager.setSpeakerphoneOn/setBluetoothScoOn actually switch
// between earpiece, loudspeaker, and Bluetooth headset. Combined with
// MODE_IN_COMMUNICATION set from MainActivity.kt and
// speakerphoneOn=false by default, this produces handset/earpiece as
// the default output.
//
// IMPORTANT: do NOT add setAudioApi(AAudio) here. Build 8c36fb5 proved
// forcing AAudio with Usage::VoiceCommunication makes the playout
// callback stop draining the ring after cb#0, even though the stream
// opens successfully. Letting Oboe pick the API (which will be AAudio
// on API ≥ 27 but via a different codepath) kept callbacks firing in
// every other build.
oboe::AudioStreamBuilder playoutBuilder;
playoutBuilder.setDirection(oboe::Direction::Output)
->setPerformanceMode(oboe::PerformanceMode::LowLatency)
->setSharingMode(oboe::SharingMode::Shared)
->setFormat(oboe::AudioFormat::I16)
->setChannelCount(config->channel_count)
->setSampleRateConversionQuality(oboe::SampleRateConversionQuality::Best)
->setDataCallback(&g_playout_cb);
if (config->bt_active) {
LOGI("playout: BT mode — no sample rate set, using Usage::Media");
// Usage::Media instead of VoiceCommunication for BT output
// to avoid conflicts with the communication device routing.
playoutBuilder.setUsage(oboe::Usage::Media);
} else {
playoutBuilder.setSampleRate(config->sample_rate)
->setFramesPerDataCallback(config->frames_per_burst)
->setUsage(oboe::Usage::VoiceCommunication);
}
result = playoutBuilder.openStream(g_playout_stream);
if (result != oboe::Result::OK) {
LOGE("Failed to open playout stream: %s", oboe::convertToText(result));
g_capture_stream->close();
g_capture_stream.reset();
return -3;
}
LOGI("playout stream opened: actualSR=%d actualCh=%d actualFormat=%d actualFramesPerBurst=%d actualFramesPerDataCallback=%d bufferCapacityInFrames=%d sharing=%d perfMode=%d",
g_playout_stream->getSampleRate(),
g_playout_stream->getChannelCount(),
(int)g_playout_stream->getFormat(),
g_playout_stream->getFramesPerBurst(),
g_playout_stream->getFramesPerDataCallback(),
g_playout_stream->getBufferCapacityInFrames(),
(int)g_playout_stream->getSharingMode(),
(int)g_playout_stream->getPerformanceMode());
g_running.store(true, std::memory_order_release);
// Start both streams
result = g_capture_stream->requestStart();
if (result != oboe::Result::OK) {
LOGE("Failed to start capture: %s", oboe::convertToText(result));
g_running.store(false, std::memory_order_release);
g_capture_stream->close();
g_playout_stream->close();
g_capture_stream.reset();
g_playout_stream.reset();
return -4;
}
result = g_playout_stream->requestStart();
if (result != oboe::Result::OK) {
LOGE("Failed to start playout: %s", oboe::convertToText(result));
g_running.store(false, std::memory_order_release);
g_capture_stream->requestStop();
g_capture_stream->close();
g_playout_stream->close();
g_capture_stream.reset();
g_playout_stream.reset();
return -5;
}
// Log initial stream states right after requestStart() returns.
// On well-behaved HALs both will already be Started; on others
// (Nothing A059) they may still be in Starting state.
LOGI("requestStart returned: capture_state=%d playout_state=%d",
(int)g_capture_stream->getState(),
(int)g_playout_stream->getState());
// Poll until both streams report Started state, up to 2s timeout.
// Some Android HALs (Nothing A059) delay transitioning from Starting
// to Started; proceeding before the transition completes causes the
// first capture/playout callbacks to be dropped silently.
{
auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(2000);
int poll_count = 0;
while (std::chrono::steady_clock::now() < deadline) {
auto cap_state = g_capture_stream->getState();
auto play_state = g_playout_stream->getState();
if (cap_state == oboe::StreamState::Started &&
play_state == oboe::StreamState::Started) {
LOGI("both streams Started after %d polls", poll_count);
break;
}
poll_count++;
std::this_thread::sleep_for(std::chrono::milliseconds(10));
}
// Log final state even on timeout (helps diagnose HAL quirks)
LOGI("stream states after poll: capture=%d playout=%d (polls=%d)",
(int)g_capture_stream->getState(),
(int)g_playout_stream->getState(),
poll_count);
}
LOGI("Oboe started: sr=%d burst=%d ch=%d",
config->sample_rate, config->frames_per_burst, config->channel_count);
return 0;
}
void wzp_oboe_stop(void) {
g_running.store(false, std::memory_order_release);
// Tell the audio callbacks to stop touching g_rings BEFORE we tear down
// the streams, so any in-flight callback returns Stop instead of reading
// stale pointers.
g_rings_valid.store(false, std::memory_order_release);
if (g_capture_stream) {
g_capture_stream->requestStop();
g_capture_stream->close();
g_capture_stream.reset();
}
if (g_playout_stream) {
g_playout_stream->requestStop();
g_playout_stream->close();
g_playout_stream.reset();
}
LOGI("Oboe stopped");
}
float wzp_oboe_capture_latency_ms(void) {
return g_capture_latency_ms.load(std::memory_order_relaxed);
}
float wzp_oboe_playout_latency_ms(void) {
return g_playout_latency_ms.load(std::memory_order_relaxed);
}
int wzp_oboe_is_running(void) {
return g_running.load(std::memory_order_relaxed) ? 1 : 0;
}
#else
// Non-Android fallback — should not be reached; oboe_stub.cpp is used instead.
// Provide empty implementations just in case.
int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
(void)config; (void)rings;
return -99;
}
void wzp_oboe_stop(void) {}
float wzp_oboe_capture_latency_ms(void) { return 0.0f; }
float wzp_oboe_playout_latency_ms(void) { return 0.0f; }
int wzp_oboe_is_running(void) { return 0; }
#endif // __ANDROID__

44
crates/wzp-native/cpp/oboe_bridge.h
View File

@@ -1,44 +0,0 @@
#ifndef WZP_OBOE_BRIDGE_H
#define WZP_OBOE_BRIDGE_H
#include <stdint.h>
#ifdef __cplusplus
#include <atomic>
typedef std::atomic<int32_t> wzp_atomic_int;
extern "C" {
#else
#include <stdatomic.h>
typedef atomic_int wzp_atomic_int;
#endif
typedef struct {
int32_t sample_rate;
int32_t frames_per_burst;
int32_t channel_count;
int32_t bt_active; /* nonzero = BT SCO mode: skip sample rate + input preset */
} WzpOboeConfig;
typedef struct {
int16_t* capture_buf;
int32_t capture_capacity;
wzp_atomic_int* capture_write_idx;
wzp_atomic_int* capture_read_idx;
int16_t* playout_buf;
int32_t playout_capacity;
wzp_atomic_int* playout_write_idx;
wzp_atomic_int* playout_read_idx;
} WzpOboeRings;
int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings);
void wzp_oboe_stop(void);
float wzp_oboe_capture_latency_ms(void);
float wzp_oboe_playout_latency_ms(void);
int wzp_oboe_is_running(void);
#ifdef __cplusplus
}
#endif
#endif // WZP_OBOE_BRIDGE_H

27
crates/wzp-native/cpp/oboe_stub.cpp
View File

@@ -1,27 +0,0 @@
// Stub implementation for non-Android host builds (testing, cargo check, etc.)
#include "oboe_bridge.h"
#include <stdio.h>
int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
(void)config;
(void)rings;
fprintf(stderr, "wzp_oboe_start: stub (not on Android)\n");
return 0;
}
void wzp_oboe_stop(void) {
fprintf(stderr, "wzp_oboe_stop: stub (not on Android)\n");
}
float wzp_oboe_capture_latency_ms(void) {
return 0.0f;
}
float wzp_oboe_playout_latency_ms(void) {
return 0.0f;
}
int wzp_oboe_is_running(void) {
return 0;
}

449
crates/wzp-native/src/lib.rs
View File

@@ -1,449 +0,0 @@
//! wzp-native — standalone Android cdylib for all the C++ audio code.
//!
//! Built with `cargo ndk`, NOT `cargo tauri android build`. Loaded at
//! runtime by the Tauri desktop cdylib (`wzp-desktop`) via libloading.
//! See `docs/incident-tauri-android-init-tcb.md` for why the split exists.
//!
//! Phase 2: real Oboe audio backend.
//!
//! Architecture: Oboe runs capture + playout streams on its own high-
//! priority AAudio callback threads inside the C++ bridge. Two SPSC ring
//! buffers (capture and playout) are shared between the C++ callbacks
//! and the Rust side via atomic indices — no locks on the hot path.
//! `wzp-desktop` drains the capture ring into its Opus encoder and fills
//! the playout ring with decoded PCM.
use std::sync::atomic::{AtomicI32, Ordering};
// ─── Phase 1 smoke-test exports (kept for sanity checks) ─────────────────
/// Returns 42. Used by wzp-desktop's setup() to verify dlopen + dlsym
/// work before any audio code runs.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_version() -> i32 {
42
}
/// Writes a NUL-terminated string into `out` (capped at `cap`) and
/// returns bytes written excluding the NUL.
///
/// # Safety
/// `out` must be a valid pointer to at least `cap` contiguous bytes of
/// writable memory. Passing a null pointer or zero capacity is safe
/// (returns 0), but a dangling non-null pointer is undefined behaviour.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn wzp_native_hello(out: *mut u8, cap: usize) -> usize {
const MSG: &[u8] = b"hello from wzp-native\0";
if out.is_null() || cap == 0 {
return 0;
}
let n = MSG.len().min(cap);
unsafe {
core::ptr::copy_nonoverlapping(MSG.as_ptr(), out, n);
*out.add(n - 1) = 0;
}
n - 1
}
// ─── C++ Oboe bridge FFI ─────────────────────────────────────────────────
#[repr(C)]
struct WzpOboeConfig {
sample_rate: i32,
frames_per_burst: i32,
channel_count: i32,
/// When nonzero, capture stream skips setSampleRate and setInputPreset
/// so the system can route to BT SCO at its native rate (8/16kHz).
/// Oboe's SampleRateConversionQuality::Best resamples to 48kHz.
bt_active: i32,
}
#[repr(C)]
struct WzpOboeRings {
capture_buf: *mut i16,
capture_capacity: i32,
capture_write_idx: *mut AtomicI32,
capture_read_idx: *mut AtomicI32,
playout_buf: *mut i16,
playout_capacity: i32,
playout_write_idx: *mut AtomicI32,
playout_read_idx: *mut AtomicI32,
}
// SAFETY: atomics synchronise producer/consumer; raw pointers are owned
// by the AudioBackend singleton below whose lifetime covers all calls.
unsafe impl Send for WzpOboeRings {}
unsafe impl Sync for WzpOboeRings {}
unsafe extern "C" {
fn wzp_oboe_start(config: *const WzpOboeConfig, rings: *const WzpOboeRings) -> i32;
fn wzp_oboe_stop();
fn wzp_oboe_capture_latency_ms() -> f32;
fn wzp_oboe_playout_latency_ms() -> f32;
fn wzp_oboe_is_running() -> i32;
}
// ─── SPSC ring buffer (shared with C++ via AtomicI32) ────────────────────
/// 20 ms @ 48 kHz mono = 960 samples.
const FRAME_SAMPLES: usize = 960;
/// ~160 ms headroom at 48 kHz.
const RING_CAPACITY: usize = 7680;
struct RingBuffer {
buf: Vec<i16>,
capacity: usize,
write_idx: AtomicI32,
read_idx: AtomicI32,
}
// SAFETY: SPSC with atomic read/write cursors; producer and consumer
// are always on different threads.
unsafe impl Send for RingBuffer {}
unsafe impl Sync for RingBuffer {}
impl RingBuffer {
fn new(capacity: usize) -> Self {
Self {
buf: vec![0i16; capacity],
capacity,
write_idx: AtomicI32::new(0),
read_idx: AtomicI32::new(0),
}
}
fn available_read(&self) -> usize {
let w = self.write_idx.load(Ordering::Acquire);
let r = self.read_idx.load(Ordering::Relaxed);
let avail = w - r;
if avail < 0 { (avail + self.capacity as i32) as usize } else { avail as usize }
}
fn available_write(&self) -> usize {
self.capacity - 1 - self.available_read()
}
fn write(&self, data: &[i16]) -> usize {
let count = data.len().min(self.available_write());
if count == 0 {
return 0;
}
let mut w = self.write_idx.load(Ordering::Relaxed) as usize;
let cap = self.capacity;
let buf_ptr = self.buf.as_ptr() as *mut i16;
for sample in &data[..count] {
unsafe { *buf_ptr.add(w) = *sample; }
w += 1;
if w >= cap { w = 0; }
}
self.write_idx.store(w as i32, Ordering::Release);
count
}
fn read(&self, out: &mut [i16]) -> usize {
let count = out.len().min(self.available_read());
if count == 0 {
return 0;
}
let mut r = self.read_idx.load(Ordering::Relaxed) as usize;
let cap = self.capacity;
let buf_ptr = self.buf.as_ptr();
for slot in &mut out[..count] {
unsafe { *slot = *buf_ptr.add(r); }
r += 1;
if r >= cap { r = 0; }
}
self.read_idx.store(r as i32, Ordering::Release);
count
}
fn buf_ptr(&self) -> *mut i16 {
self.buf.as_ptr() as *mut i16
}
fn write_idx_ptr(&self) -> *mut AtomicI32 {
&self.write_idx as *const AtomicI32 as *mut AtomicI32
}
fn read_idx_ptr(&self) -> *mut AtomicI32 {
&self.read_idx as *const AtomicI32 as *mut AtomicI32
}
}
// ─── AudioBackend singleton ──────────────────────────────────────────────
//
// There is one global AudioBackend instance because Oboe's C++ side
// holds its own singleton of the streams. The `Box::leak`'d statics own
// the ring buffers for the lifetime of the process — dropping them while
// Oboe is still running would cause use-after-free in the audio callback.
use std::sync::OnceLock;
struct AudioBackend {
capture: RingBuffer,
playout: RingBuffer,
started: std::sync::Mutex<bool>,
/// Per-write logging throttle counter for wzp_native_audio_write_playout.
playout_write_log_count: std::sync::atomic::AtomicU64,
/// Fix A (task #35): the playout ring's read_idx at the last
/// check. If audio_write_playout observes read_idx hasn't
/// advanced after N writes, the Oboe playout callback has
/// stopped firing → restart the streams.
playout_last_read_idx: std::sync::atomic::AtomicI32,
/// Number of writes since the last read_idx advance.
playout_stall_writes: std::sync::atomic::AtomicU32,
}
static BACKEND: OnceLock<&'static AudioBackend> = OnceLock::new();
fn backend() -> &'static AudioBackend {
BACKEND.get_or_init(|| {
Box::leak(Box::new(AudioBackend {
capture: RingBuffer::new(RING_CAPACITY),
playout: RingBuffer::new(RING_CAPACITY),
started: std::sync::Mutex::new(false),
playout_write_log_count: std::sync::atomic::AtomicU64::new(0),
playout_last_read_idx: std::sync::atomic::AtomicI32::new(0),
playout_stall_writes: std::sync::atomic::AtomicU32::new(0),
}))
})
}
// ─── C FFI for wzp-desktop ───────────────────────────────────────────────
/// Start the Oboe audio streams. Returns 0 on success, non-zero on error.
/// Idempotent — calling while already running is a no-op that returns 0.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_start() -> i32 {
audio_start_inner(false)
}
/// Start Oboe in Bluetooth SCO mode — skips sample rate and input preset
/// on capture so the system can route to the BT SCO device natively.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_start_bt() -> i32 {
audio_start_inner(true)
}
fn audio_start_inner(bt: bool) -> i32 {
let b = backend();
let mut started = match b.started.lock() {
Ok(g) => g,
Err(_) => return -1,
};
if *started {
return 0;
}
let config = WzpOboeConfig {
sample_rate: 48_000,
frames_per_burst: FRAME_SAMPLES as i32,
channel_count: 1,
bt_active: if bt { 1 } else { 0 },
};
let rings = WzpOboeRings {
capture_buf: b.capture.buf_ptr(),
capture_capacity: b.capture.capacity as i32,
capture_write_idx: b.capture.write_idx_ptr(),
capture_read_idx: b.capture.read_idx_ptr(),
playout_buf: b.playout.buf_ptr(),
playout_capacity: b.playout.capacity as i32,
playout_write_idx: b.playout.write_idx_ptr(),
playout_read_idx: b.playout.read_idx_ptr(),
};
let ret = unsafe { wzp_oboe_start(&config, &rings) };
if ret != 0 {
return ret;
}
*started = true;
0
}
/// Stop Oboe. Idempotent. Safe to call from any thread.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_stop() {
let b = backend();
if let Ok(mut started) = b.started.lock() {
if *started {
unsafe { wzp_oboe_stop() };
*started = false;
}
}
}
/// Number of capture samples available to read without blocking.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_capture_available() -> usize {
backend().capture.available_read()
}
/// Read captured PCM samples from the capture ring. Returns the number
/// of `i16` samples actually copied into `out` (may be less than
/// `out_len` if the ring is empty).
///
/// # Safety
/// `out` must be a valid pointer to `out_len` contiguous `i16` values.
/// The caller must ensure no other thread writes to the same buffer
/// concurrently. Passing a null pointer or zero length is safe (returns 0).
#[unsafe(no_mangle)]
pub unsafe extern "C" fn wzp_native_audio_read_capture(out: *mut i16, out_len: usize) -> usize {
if out.is_null() || out_len == 0 {
return 0;
}
let slice = unsafe { std::slice::from_raw_parts_mut(out, out_len) };
backend().capture.read(slice)
}
/// Write PCM samples into the playout ring. Returns the number of
/// samples actually enqueued (may be less than `in_len` if the ring
/// is nearly full — in practice the caller should pace to 20 ms
/// frames and spin briefly if the ring is full).
///
/// # Safety
/// `input` must be a valid pointer to `in_len` contiguous `i16` values
/// that remain valid for the duration of the call. Passing a null pointer
/// or zero length is safe (returns 0). The caller must not free or mutate
/// the buffer while this function is executing.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn wzp_native_audio_write_playout(input: *const i16, in_len: usize) -> usize {
if input.is_null() || in_len == 0 {
return 0;
}
let slice = unsafe { std::slice::from_raw_parts(input, in_len) };
let b = backend();
// Fix A (task #35): detect playout callback stall. If the
// playout ring's read_idx hasn't advanced in 50+ writes
// (~1 second at 50 writes/sec), the Oboe playout callback
// has stopped firing → restart the streams. This is the
// self-healing behavior that makes rejoin work: teardown +
// rebuild clears whatever HAL state locked up the callback.
let current_read_idx = b.playout.read_idx.load(std::sync::atomic::Ordering::Relaxed);
let last_read_idx = b.playout_last_read_idx.load(std::sync::atomic::Ordering::Relaxed);
if current_read_idx == last_read_idx {
let stall = b.playout_stall_writes.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
if stall >= 50 {
// Callback hasn't drained anything in ~1 second.
// Force a stream restart.
unsafe {
android_log("playout STALL detected (50 writes, read_idx unchanged) — restarting Oboe streams");
}
b.playout_stall_writes.store(0, std::sync::atomic::Ordering::Relaxed);
// Release the started lock, stop, re-start.
// This is the same logic as the Rust-side
// audio_stop() + audio_start() but done inline
// because we can't call the extern "C" fns
// recursively. Just call the C++ side directly.
{
if let Ok(mut started) = b.started.lock() {
if *started {
unsafe { wzp_oboe_stop() };
*started = false;
}
}
}
// Clear the rings so the restart doesn't read stale data
b.playout.write_idx.store(0, std::sync::atomic::Ordering::Relaxed);
b.playout.read_idx.store(0, std::sync::atomic::Ordering::Relaxed);
b.capture.write_idx.store(0, std::sync::atomic::Ordering::Relaxed);
b.capture.read_idx.store(0, std::sync::atomic::Ordering::Relaxed);
// Re-start (stall detector — always non-BT mode)
let config = WzpOboeConfig {
sample_rate: 48_000,
frames_per_burst: FRAME_SAMPLES as i32,
channel_count: 1,
bt_active: 0,
};
let rings = WzpOboeRings {
capture_buf: b.capture.buf_ptr(),
capture_capacity: b.capture.capacity as i32,
capture_write_idx: b.capture.write_idx_ptr(),
capture_read_idx: b.capture.read_idx_ptr(),
playout_buf: b.playout.buf_ptr(),
playout_capacity: b.playout.capacity as i32,
playout_write_idx: b.playout.write_idx_ptr(),
playout_read_idx: b.playout.read_idx_ptr(),
};
let ret = unsafe { wzp_oboe_start(&config, &rings) };
if ret == 0 {
if let Ok(mut started) = b.started.lock() {
*started = true;
}
unsafe { android_log("playout restart OK — Oboe streams rebuilt"); }
} else {
unsafe { android_log(&format!("playout restart FAILED: {ret}")); }
}
b.playout_last_read_idx.store(0, std::sync::atomic::Ordering::Relaxed);
return 0; // caller will retry on next frame
}
} else {
// read_idx advanced — callback is alive, reset counter
b.playout_stall_writes.store(0, std::sync::atomic::Ordering::Relaxed);
b.playout_last_read_idx.store(current_read_idx, std::sync::atomic::Ordering::Relaxed);
}
let before_w = b.playout.write_idx.load(std::sync::atomic::Ordering::Relaxed);
let before_r = b.playout.read_idx.load(std::sync::atomic::Ordering::Relaxed);
let written = b.playout.write(slice);
// First few writes: log ring state + sample range so we can compare what
// engine.rs hands us to what the C++ playout callback reads.
let first_writes = b.playout_write_log_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
if first_writes < 3 || first_writes % 50 == 0 {
let (mut lo, mut hi, mut sumsq) = (i16::MAX, i16::MIN, 0i64);
for &s in slice.iter() {
if s < lo { lo = s; }
if s > hi { hi = s; }
sumsq += (s as i64) * (s as i64);
}
let rms = (sumsq as f64 / slice.len() as f64).sqrt() as i32;
let avail_w_after = b.playout.available_write();
let avail_r_after = b.playout.available_read();
let msg = format!(
"playout WRITE #{first_writes}: in_len={} written={} range=[{lo}..{hi}] rms={rms} before_w={before_w} before_r={before_r} avail_read_after={avail_r_after} avail_write_after={avail_w_after}",
slice.len(), written
);
unsafe {
android_log(msg.as_str());
}
}
written
}
// Minimal android logcat shim so we can print from the cdylib without pulling
// in android_logger crate (which would add another dep that has to build with
// cargo-ndk). Uses libc's __android_log_print via extern linkage.
#[cfg(target_os = "android")]
unsafe extern "C" {
fn __android_log_write(prio: i32, tag: *const u8, text: *const u8) -> i32;
}
#[cfg(target_os = "android")]
unsafe fn android_log(msg: &str) {
// ANDROID_LOG_INFO = 4. Tag and text must be NUL-terminated.
let tag = b"wzp-native\0";
let mut buf = Vec::with_capacity(msg.len() + 1);
buf.extend_from_slice(msg.as_bytes());
buf.push(0);
unsafe { __android_log_write(4, tag.as_ptr(), buf.as_ptr()); }
}
#[cfg(not(target_os = "android"))]
#[allow(dead_code)]
unsafe fn android_log(_msg: &str) {}
/// Current capture latency reported by Oboe, in milliseconds. Returns
/// NaN / 0.0 if the stream isn't running.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_capture_latency_ms() -> f32 {
unsafe { wzp_oboe_capture_latency_ms() }
}
/// Current playout latency reported by Oboe, in milliseconds.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_playout_latency_ms() -> f32 {
unsafe { wzp_oboe_playout_latency_ms() }
}
/// Non-zero if both Oboe streams are currently running.
#[unsafe(no_mangle)]
pub extern "C" fn wzp_native_audio_is_running() -> i32 {
unsafe { wzp_oboe_is_running() }
}

48
crates/wzp-proto/src/codec_id.rs
View File

@@ -18,12 +18,6 @@ pub enum CodecId {
Codec2_1200 = 4,
/// Comfort noise descriptor (silence suppression)
ComfortNoise = 5,
/// Opus at 32kbps (studio low)
Opus32k = 6,
/// Opus at 48kbps (studio)
Opus48k = 7,
/// Opus at 64kbps (studio high)
Opus64k = 8,
}
impl CodecId {
@@ -33,9 +27,6 @@ impl CodecId {
Self::Opus24k => 24_000,
Self::Opus16k => 16_000,
Self::Opus6k => 6_000,
Self::Opus32k => 32_000,
Self::Opus48k => 48_000,
Self::Opus64k => 64_000,
Self::Codec2_3200 => 3_200,
Self::Codec2_1200 => 1_200,
Self::ComfortNoise => 0,
@@ -45,7 +36,8 @@ impl CodecId {
/// Preferred frame duration in milliseconds.
pub const fn frame_duration_ms(self) -> u8 {
match self {
Self::Opus24k | Self::Opus16k | Self::Opus32k | Self::Opus48k | Self::Opus64k => 20,
Self::Opus24k => 20,
Self::Opus16k => 20,
Self::Opus6k => 40,
Self::Codec2_3200 => 20,
Self::Codec2_1200 => 40,
@@ -56,8 +48,7 @@ impl CodecId {
/// Sample rate expected by this codec.
pub const fn sample_rate_hz(self) -> u32 {
match self {
Self::Opus24k | Self::Opus16k | Self::Opus6k
| Self::Opus32k | Self::Opus48k | Self::Opus64k => 48_000,
Self::Opus24k | Self::Opus16k | Self::Opus6k => 48_000,
Self::Codec2_3200 | Self::Codec2_1200 => 8_000,
Self::ComfortNoise => 48_000,
}
@@ -72,9 +63,6 @@ impl CodecId {
3 => Some(Self::Codec2_3200),
4 => Some(Self::Codec2_1200),
5 => Some(Self::ComfortNoise),
6 => Some(Self::Opus32k),
7 => Some(Self::Opus48k),
8 => Some(Self::Opus64k),
_ => None,
}
}
@@ -83,12 +71,6 @@ impl CodecId {
pub const fn to_wire(self) -> u8 {
self as u8
}
/// Returns true if this is an Opus variant.
pub const fn is_opus(self) -> bool {
matches!(self, Self::Opus6k | Self::Opus16k | Self::Opus24k
| Self::Opus32k | Self::Opus48k | Self::Opus64k)
}
}
/// Describes the complete quality configuration for a call session.
@@ -129,30 +111,6 @@ impl QualityProfile {
frames_per_block: 8,
};
/// Studio low: Opus 32kbps, minimal FEC.
pub const STUDIO_32K: Self = Self {
codec: CodecId::Opus32k,
fec_ratio: 0.1,
frame_duration_ms: 20,
frames_per_block: 5,
};
/// Studio: Opus 48kbps, minimal FEC.
pub const STUDIO_48K: Self = Self {
codec: CodecId::Opus48k,
fec_ratio: 0.1,
frame_duration_ms: 20,
frames_per_block: 5,
};
/// Studio high: Opus 64kbps, minimal FEC.
pub const STUDIO_64K: Self = Self {
codec: CodecId::Opus64k,
fec_ratio: 0.1,
frame_duration_ms: 20,
frames_per_block: 5,
};
/// Estimated total bandwidth in kbps including FEC overhead.
pub fn total_bitrate_kbps(&self) -> f32 {
let base = self.codec.bitrate_bps() as f32 / 1000.0;

316
crates/wzp-proto/src/dred_tuner.rs
View File

@@ -1,316 +0,0 @@
//! Continuous DRED tuning from real-time network metrics.
//!
//! Instead of locking DRED duration to 3 discrete quality tiers (100/200/500 ms),
//! `DredTuner` maps live path quality metrics to a continuous DRED duration and
//! expected-loss hint, updated every N packets. This makes DRED reactive within
//! ~200 ms instead of waiting for 3+ consecutive bad quality reports to trigger
//! a full tier transition.
//!
//! The tuner also implements pre-emptive jitter-spike detection ("sawtooth"
//! prediction): when jitter variance spikes >30% over a 200 ms window — typical
//! of Starlink satellite handovers — it temporarily boosts DRED to the maximum
//! allowed for the current codec before packets actually start dropping.
//!
//! See also: [`crate::quality`] for discrete tier classification that drives
//! codec switching. DredTuner operates within a tier, adjusting DRED
//! parameters continuously based on live network metrics.
use crate::CodecId;
/// Output of a single tuning cycle.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DredTuning {
/// DRED duration in 10 ms frame units (0–104). Passed directly to
/// `OpusEncoder::set_dred_duration()`.
pub dred_frames: u8,
/// Expected packet loss percentage (0–100). Passed to
/// `OpusEncoder::set_expected_loss()`. Floored at 15% by the encoder
/// itself, but we pass the real value so the encoder can override upward.
pub expected_loss_pct: u8,
}
/// Minimum DRED frames for any Opus codec (matches DRED_LOSS_FLOOR_PCT logic:
/// at 15% loss, libopus 1.5 emits ~95 ms of DRED, which needs at least 10
/// frames configured to be useful).
const MIN_DRED_FRAMES: u8 = 5;
/// Maximum DRED frames libopus supports (104 × 10 ms = 1040 ms).
const MAX_DRED_FRAMES: u8 = 104;
/// Jitter variance spike ratio that triggers pre-emptive DRED boost.
const JITTER_SPIKE_RATIO: f32 = 1.3;
/// How many tuning cycles a jitter-spike boost persists (at 25 packets/cycle
/// and 20 ms/packet, 10 cycles ≈ 5 seconds).
const SPIKE_BOOST_COOLDOWN_CYCLES: u32 = 10;
/// Maps codec tier to its baseline DRED frames (used when network is healthy).
fn baseline_dred_frames(codec: CodecId) -> u8 {
match codec {
CodecId::Opus32k | CodecId::Opus48k | CodecId::Opus64k => 10, // 100 ms
CodecId::Opus16k | CodecId::Opus24k => 20, // 200 ms
CodecId::Opus6k => 50, // 500 ms
_ => 0,
}
}
/// Maps codec tier to its maximum allowed DRED frames under spike/bad conditions.
fn max_dred_frames_for(codec: CodecId) -> u8 {
match codec {
// Studio: cap at 300 ms (don't waste bitrate on good links)
CodecId::Opus32k | CodecId::Opus48k | CodecId::Opus64k => 30,
// Normal: cap at 500 ms
CodecId::Opus16k | CodecId::Opus24k => 50,
// Degraded: allow full 1040 ms
CodecId::Opus6k => MAX_DRED_FRAMES,
_ => 0,
}
}
/// Continuous DRED tuner driven by network path metrics.
pub struct DredTuner {
/// Current codec (determines baseline and ceiling).
codec: CodecId,
/// Last computed tuning output.
last_tuning: DredTuning,
/// EWMA-smoothed jitter for spike detection (in ms).
jitter_ewma: f32,
/// Remaining cooldown cycles for a jitter-spike boost.
spike_cooldown: u32,
/// Whether the tuner has received at least one observation.
initialized: bool,
}
impl DredTuner {
/// Create a new tuner for the given codec.
pub fn new(codec: CodecId) -> Self {
let baseline = baseline_dred_frames(codec);
Self {
codec,
last_tuning: DredTuning {
dred_frames: baseline,
expected_loss_pct: 15, // match DRED_LOSS_FLOOR_PCT
},
jitter_ewma: 0.0,
spike_cooldown: 0,
initialized: false,
}
}
/// Update the active codec (e.g. on tier transition). Resets spike state.
pub fn set_codec(&mut self, codec: CodecId) {
self.codec = codec;
self.spike_cooldown = 0;
}
/// Feed network metrics and compute new DRED parameters.
///
/// Call this every tuning cycle (e.g. every 25 packets ≈ 500 ms at 20 ms
/// frame duration).
///
/// - `loss_pct`: observed packet loss (0.0–100.0)
/// - `rtt_ms`: smoothed round-trip time
/// - `jitter_ms`: current jitter estimate (RTT variance)
///
/// Returns `Some(tuning)` if the output changed, `None` if unchanged.
pub fn update(&mut self, loss_pct: f32, rtt_ms: u32, jitter_ms: u32) -> Option<DredTuning> {
if !self.codec.is_opus() {
return None;
}
let baseline = baseline_dred_frames(self.codec);
let ceiling = max_dred_frames_for(self.codec);
// --- Jitter spike detection ---
let jitter_f = jitter_ms as f32;
if !self.initialized {
self.jitter_ewma = jitter_f;
self.initialized = true;
} else {
// Fast-up (alpha=0.3), slow-down (alpha=0.05) asymmetric EWMA
let alpha = if jitter_f > self.jitter_ewma { 0.3 } else { 0.05 };
self.jitter_ewma = alpha * jitter_f + (1.0 - alpha) * self.jitter_ewma;
}
// Detect spike: instantaneous jitter > EWMA × 1.3
if self.jitter_ewma > 1.0 && jitter_f > self.jitter_ewma * JITTER_SPIKE_RATIO {
self.spike_cooldown = SPIKE_BOOST_COOLDOWN_CYCLES;
}
// Decrement cooldown
if self.spike_cooldown > 0 {
self.spike_cooldown -= 1;
}
// --- Compute DRED frames ---
let dred_frames = if self.spike_cooldown > 0 {
// During spike boost: jump to ceiling
ceiling
} else {
// Continuous mapping: scale linearly between baseline and ceiling
// based on loss percentage.
// 0% loss → baseline
// 40% loss → ceiling
let loss_clamped = loss_pct.clamp(0.0, 40.0);
let t = loss_clamped / 40.0;
let raw = baseline as f32 + t * (ceiling - baseline) as f32;
(raw as u8).clamp(MIN_DRED_FRAMES, ceiling)
};
// --- Compute expected loss hint ---
// Pass the real loss so the encoder can clamp at its own floor (15%).
// For RTT-driven boost: high RTT suggests impending loss, so add a
// phantom loss contribution to keep DRED emitting generously.
let rtt_loss_phantom = if rtt_ms > 200 {
((rtt_ms - 200) as f32 / 40.0).min(15.0)
} else {
0.0
};
let expected_loss = (loss_pct + rtt_loss_phantom).clamp(0.0, 100.0) as u8;
let tuning = DredTuning {
dred_frames,
expected_loss_pct: expected_loss,
};
if tuning != self.last_tuning {
self.last_tuning = tuning;
Some(tuning)
} else {
None
}
}
/// Get the last computed tuning without updating.
pub fn current(&self) -> DredTuning {
self.last_tuning
}
/// Whether a jitter-spike boost is currently active.
pub fn spike_boost_active(&self) -> bool {
self.spike_cooldown > 0
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn baseline_for_opus24k() {
let tuner = DredTuner::new(CodecId::Opus24k);
assert_eq!(tuner.current().dred_frames, 20); // 200 ms
}
#[test]
fn baseline_for_opus6k() {
let tuner = DredTuner::new(CodecId::Opus6k);
assert_eq!(tuner.current().dred_frames, 50); // 500 ms
}
#[test]
fn codec2_returns_none() {
let mut tuner = DredTuner::new(CodecId::Codec2_1200);
assert!(tuner.update(10.0, 100, 20).is_none());
}
#[test]
fn scales_with_loss() {
let mut tuner = DredTuner::new(CodecId::Opus24k);
// 0% loss → baseline (20 frames)
tuner.update(0.0, 50, 5);
assert_eq!(tuner.current().dred_frames, 20);
// 20% loss → midpoint between 20 and 50 = 35
tuner.update(20.0, 50, 5);
assert_eq!(tuner.current().dred_frames, 35);
// 40%+ loss → ceiling (50 frames)
tuner.update(40.0, 50, 5);
assert_eq!(tuner.current().dred_frames, 50);
}
#[test]
fn jitter_spike_triggers_boost() {
let mut tuner = DredTuner::new(CodecId::Opus24k);
// Establish baseline jitter
for _ in 0..20 {
tuner.update(0.0, 50, 10);
}
assert!(!tuner.spike_boost_active());
// Spike: jitter jumps to 50 ms (5x the EWMA of ~10)
tuner.update(0.0, 50, 50);
assert!(tuner.spike_boost_active());
// Should be at ceiling (50 frames = 500 ms for Opus24k)
assert_eq!(tuner.current().dred_frames, 50);
}
#[test]
fn spike_cooldown_decays() {
let mut tuner = DredTuner::new(CodecId::Opus24k);
// Establish baseline then spike
for _ in 0..20 {
tuner.update(0.0, 50, 10);
}
tuner.update(0.0, 50, 50);
assert!(tuner.spike_boost_active());
// Run through cooldown
for _ in 0..SPIKE_BOOST_COOLDOWN_CYCLES {
tuner.update(0.0, 50, 10);
}
assert!(!tuner.spike_boost_active());
// Should return to baseline
assert_eq!(tuner.current().dred_frames, 20);
}
#[test]
fn rtt_phantom_loss() {
let mut tuner = DredTuner::new(CodecId::Opus24k);
// High RTT (400ms) with 0% real loss
tuner.update(0.0, 400, 10);
// Phantom loss = (400-200)/40 = 5
assert_eq!(tuner.current().expected_loss_pct, 5);
}
#[test]
fn set_codec_resets_spike() {
let mut tuner = DredTuner::new(CodecId::Opus24k);
// Trigger spike
for _ in 0..20 {
tuner.update(0.0, 50, 10);
}
tuner.update(0.0, 50, 50);
assert!(tuner.spike_boost_active());
// Switch codec — spike should reset
tuner.set_codec(CodecId::Opus6k);
assert!(!tuner.spike_boost_active());
}
#[test]
fn opus6k_reaches_max_1040ms() {
let mut tuner = DredTuner::new(CodecId::Opus6k);
// High loss → should reach 104 frames (1040 ms)
tuner.update(40.0, 50, 5);
assert_eq!(tuner.current().dred_frames, MAX_DRED_FRAMES);
}
#[test]
fn returns_none_when_unchanged() {
let mut tuner = DredTuner::new(CodecId::Opus24k);
// First update always returns Some (initial → computed)
let first = tuner.update(0.0, 50, 5);
// Same inputs → None
let second = tuner.update(0.0, 50, 5);
assert!(first.is_some() || second.is_none());
}
}

9
crates/wzp-proto/src/error.rs
View File

@@ -53,15 +53,6 @@ pub enum TransportError {
Timeout { ms: u64 },
#[error("io error: {0}")]
Io(#[from] std::io::Error),
/// Parsed wire bytes successfully but the payload didn't
/// deserialize into a known `SignalMessage` variant. Usually
/// means the peer is running a newer build with a variant we
/// don't know yet. Callers should **log and continue** rather
/// than tearing down the connection, so that forward-compat
/// additions to `SignalMessage` don't silently kill old
/// clients/relays.
#[error("signal deserialize: {0}")]
Deserialize(String),
#[error("internal transport error: {0}")]
Internal(String),
}

34
crates/wzp-proto/src/jitter.rs
View File

@@ -273,21 +273,10 @@ impl JitterBuffer {
return;
}
// Check if packet is too old (already played out).
// A backward jump of >100 seq (~2s at 50fps) indicates a new sender in a
// federation room — reset instead of dropping.
// Check if packet is too old (already played out)
if self.stats.packets_played > 0 && seq_before(seq, self.next_playout_seq) {
let backward_distance = self.next_playout_seq.wrapping_sub(seq);
tracing::warn!(seq, next = self.next_playout_seq, backward_distance, "jitter: backward seq detected");
if backward_distance > 100 {
tracing::info!(seq, next = self.next_playout_seq, "jitter: RESET — new sender detected");
self.buffer.clear();
self.next_playout_seq = seq;
self.stats.packets_late = 0;
} else {
self.stats.packets_late += 1;
return;
}
self.stats.packets_late += 1;
return;
}
// If we haven't started playout yet, adjust next_playout_seq to earliest known
@@ -423,21 +412,10 @@ impl JitterBuffer {
return;
}
// Check if packet is too old (already played out).
// A backward jump of >100 seq (~2s at 50fps) indicates a new sender in a
// federation room — reset instead of dropping.
// Check if packet is too old (already played out)
if self.stats.packets_played > 0 && seq_before(seq, self.next_playout_seq) {
let backward_distance = self.next_playout_seq.wrapping_sub(seq);
tracing::warn!(seq, next = self.next_playout_seq, backward_distance, "jitter: backward seq detected");
if backward_distance > 100 {
tracing::info!(seq, next = self.next_playout_seq, "jitter: RESET — new sender detected");
self.buffer.clear();
self.next_playout_seq = seq;
self.stats.packets_late = 0;
} else {
self.stats.packets_late += 1;
return;
}
self.stats.packets_late += 1;
return;
}
// If we haven't started playout yet, adjust next_playout_seq to earliest known

7
crates/wzp-proto/src/lib.rs
View File

@@ -14,7 +14,6 @@
pub mod bandwidth;
pub mod codec_id;
pub mod dred_tuner;
pub mod error;
pub mod jitter;
pub mod packet;
@@ -26,12 +25,10 @@ pub mod traits;
pub use codec_id::{CodecId, QualityProfile};
pub use error::*;
pub use packet::{
CallAcceptMode, HangupReason, MediaHeader, MediaPacket, MiniFrameContext, MiniHeader,
PresenceUser, QualityReport, RoomParticipant, SignalMessage, TrunkEntry, TrunkFrame, FRAME_TYPE_FULL,
FRAME_TYPE_MINI,
HangupReason, MediaHeader, MediaPacket, MiniFrameContext, MiniHeader, QualityReport,
RoomParticipant, SignalMessage, TrunkEntry, TrunkFrame, FRAME_TYPE_FULL, FRAME_TYPE_MINI,
};
pub use bandwidth::{BandwidthEstimator, CongestionState};
pub use dred_tuner::{DredTuner, DredTuning};
pub use quality::{AdaptiveQualityController, NetworkContext, Tier};
pub use session::{Session, SessionEvent, SessionState};
pub use traits::*;

1133
crates/wzp-proto/src/packet.rs
View File

File diff suppressed because it is too large Load Diff

413
crates/wzp-proto/src/quality.rs
View File

@@ -1,5 +1,3 @@
//! See also: [`crate::dred_tuner`] for continuous DRED tuning within a tier.
use std::collections::VecDeque;
use std::time::{Duration, Instant};
@@ -8,31 +6,19 @@ use crate::traits::QualityController;
use crate::QualityProfile;
/// Network quality tier — drives codec and FEC selection.
///
/// 5-tier range from studio quality down to catastrophic:
/// Studio64k > Studio48k > Studio32k > Good > Degraded > Catastrophic
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Tier {
/// loss >= 15% OR RTT >= 200ms — Codec2 1.2k
Catastrophic = 0,
/// loss < 15% AND RTT < 200ms — Opus 6k
Degraded = 1,
/// loss < 5% AND RTT < 100ms — Opus 24k
Good = 2,
/// loss < 2% AND RTT < 80ms — Opus 32k
Studio32k = 3,
/// loss < 1% AND RTT < 50ms — Opus 48k
Studio48k = 4,
/// loss < 1% AND RTT < 30ms — Opus 64k
Studio64k = 5,
/// loss < 10%, RTT < 400ms
Good,
/// loss 10-40% OR RTT 400-600ms
Degraded,
/// loss > 40% OR RTT > 600ms
Catastrophic,
}
impl Tier {
pub fn profile(self) -> QualityProfile {
match self {
Self::Studio64k => QualityProfile::STUDIO_64K,
Self::Studio48k => QualityProfile::STUDIO_48K,
Self::Studio32k => QualityProfile::STUDIO_32K,
Self::Good => QualityProfile::GOOD,
Self::Degraded => QualityProfile::DEGRADED,
Self::Catastrophic => QualityProfile::CATASTROPHIC,
@@ -53,7 +39,7 @@ impl Tier {
NetworkContext::CellularLte
| NetworkContext::Cellular5g
| NetworkContext::Cellular3g => {
// Tighter thresholds for cellular — no studio tiers
// Tighter thresholds for cellular networks
if loss > 25.0 || rtt > 500 {
Self::Catastrophic
} else if loss > 8.0 || rtt > 300 {
@@ -63,18 +49,13 @@ impl Tier {
}
}
NetworkContext::WiFi | NetworkContext::Unknown => {
if loss >= 15.0 || rtt >= 200 {
// Original thresholds
if loss > 40.0 || rtt > 600 {
Self::Catastrophic
} else if loss >= 5.0 || rtt >= 100 {
} else if loss > 10.0 || rtt > 400 {
Self::Degraded
} else if loss >= 2.0 || rtt >= 80 {
Self::Good
} else if loss >= 1.0 || rtt >= 50 {
Self::Studio32k
} else if rtt >= 30 {
Self::Studio48k
} else {
Self::Studio64k
Self::Good
}
}
}
@@ -83,19 +64,11 @@ impl Tier {
/// Return the next lower (worse) tier, or None if already at the worst.
pub fn downgrade(self) -> Option<Tier> {
match self {
Self::Studio64k => Some(Self::Studio48k),
Self::Studio48k => Some(Self::Studio32k),
Self::Studio32k => Some(Self::Good),
Self::Good => Some(Self::Degraded),
Self::Degraded => Some(Self::Catastrophic),
Self::Catastrophic => None,
}
}
/// Whether this is a studio tier (above Good).
pub fn is_studio(self) -> bool {
matches!(self, Self::Studio64k | Self::Studio48k | Self::Studio32k)
}
}
/// Describes the network transport type for context-aware quality decisions.
@@ -135,48 +108,20 @@ pub struct AdaptiveQualityController {
fec_boost_until: Option<Instant>,
/// FEC boost amount to add during handoff recovery window.
fec_boost_amount: f32,
/// Probing state: when Some, we're actively testing a higher tier.
probe: Option<ProbeState>,
/// Time spent stable at the current tier (for probe trigger).
stable_since: Option<Instant>,
}
/// Threshold for downgrading (fast reaction to degradation).
const DOWNGRADE_THRESHOLD: u32 = 3;
/// Threshold for downgrading on cellular networks (even faster).
const CELLULAR_DOWNGRADE_THRESHOLD: u32 = 2;
/// Threshold for upgrading from Catastrophic/Degraded to Good.
const UPGRADE_THRESHOLD: u32 = 5;
/// Threshold for upgrading into studio tiers (very conservative).
const STUDIO_UPGRADE_THRESHOLD: u32 = 10;
/// Threshold for upgrading (slow, cautious improvement).
const UPGRADE_THRESHOLD: u32 = 10;
/// Maximum history window size.
const HISTORY_SIZE: usize = 20;
/// Default FEC boost amount during handoff recovery.
const DEFAULT_FEC_BOOST: f32 = 0.2;
/// Duration of FEC boost after a network handoff.
const FEC_BOOST_DURATION_SECS: u64 = 10;
/// Minimum time stable at current tier before probing upward (30 seconds).
const PROBE_STABLE_SECS: u64 = 30;
/// Duration of a probe window (5 seconds — ~25 quality reports at 1/s).
const PROBE_DURATION_SECS: u64 = 5;
/// Maximum bad reports during probe before aborting (1 out of ~5 = 20%).
const PROBE_MAX_BAD: u32 = 1;
/// Cooldown after a failed probe before trying again (60 seconds).
const PROBE_COOLDOWN_SECS: u64 = 60;
/// Active bandwidth probe state.
struct ProbeState {
/// The tier we're probing (one step above current).
target_tier: Tier,
/// Profile to apply during probe.
target_profile: QualityProfile,
/// When the probe started.
started: Instant,
/// Reports observed during probe.
probe_reports: u32,
/// Bad reports during probe (loss/RTT exceeded target tier thresholds).
bad_reports: u32,
}
impl AdaptiveQualityController {
pub fn new() -> Self {
@@ -190,8 +135,6 @@ impl AdaptiveQualityController {
network_context: NetworkContext::default(),
fec_boost_until: None,
fec_boost_amount: DEFAULT_FEC_BOOST,
probe: None,
stable_since: None,
}
}
@@ -231,10 +174,6 @@ impl AdaptiveQualityController {
self.forced = false;
}
// Cancel any active probe
self.probe = None;
self.stable_since = None;
// Activate FEC boost for any network change
self.fec_boost_until = Some(Instant::now() + Duration::from_secs(FEC_BOOST_DURATION_SECS));
}
@@ -255,8 +194,6 @@ impl AdaptiveQualityController {
pub fn reset_counters(&mut self) {
self.consecutive_up = 0;
self.consecutive_down = 0;
self.probe = None;
self.stable_since = None;
}
/// Get the effective downgrade threshold based on network context.
@@ -276,13 +213,16 @@ impl AdaptiveQualityController {
return None;
}
let is_worse = observed_tier < self.current_tier;
let is_worse = match (self.current_tier, observed_tier) {
(Tier::Good, Tier::Degraded | Tier::Catastrophic) => true,
(Tier::Degraded, Tier::Catastrophic) => true,
_ => false,
};
if is_worse {
self.consecutive_up = 0;
self.consecutive_down += 1;
if self.consecutive_down >= self.downgrade_threshold() {
// Jump directly to the observed tier (don't step one-at-a-time on downgrade)
self.current_tier = observed_tier;
self.current_profile = observed_tier.profile();
self.consecutive_down = 0;
@@ -292,115 +232,22 @@ impl AdaptiveQualityController {
// Better conditions
self.consecutive_down = 0;
self.consecutive_up += 1;
// Studio tiers require more consecutive good reports
let threshold = if self.current_tier >= Tier::Good {
STUDIO_UPGRADE_THRESHOLD
} else {
UPGRADE_THRESHOLD
};
if self.consecutive_up >= threshold {
if self.consecutive_up >= UPGRADE_THRESHOLD {
// Only upgrade one step at a time
if let Some(next_tier) = self.upgrade_one_step() {
self.current_tier = next_tier;
self.current_profile = next_tier.profile();
self.consecutive_up = 0;
return Some(self.current_profile);
}
}
}
None
}
/// Check whether to start, continue, or conclude a bandwidth probe.
///
/// Called from `observe()` when no hysteresis transition fired.
fn check_probe(&mut self, observed_tier: Tier) -> Option<QualityProfile> {
// Don't probe if forced, or if already at highest tier, or on cellular
if self.forced || self.current_tier == Tier::Studio64k {
return None;
}
if matches!(
self.network_context,
NetworkContext::CellularLte | NetworkContext::Cellular5g | NetworkContext::Cellular3g
) {
return None;
}
// If we have an active probe, evaluate it
if let Some(ref mut probe) = self.probe {
probe.probe_reports += 1;
// Check if the observed tier meets the probe target
if observed_tier < probe.target_tier {
probe.bad_reports += 1;
}
// Probe failed: too many bad reports
if probe.bad_reports > PROBE_MAX_BAD {
let _failed_probe = self.probe.take();
// Reset stable_since to trigger cooldown
self.stable_since =
Some(Instant::now() + Duration::from_secs(PROBE_COOLDOWN_SECS));
return None; // stay at current tier
}
// Probe succeeded: enough good reports within the window
if probe.started.elapsed() >= Duration::from_secs(PROBE_DURATION_SECS) {
let target = probe.target_tier;
let profile = probe.target_profile;
self.probe.take();
self.current_tier = target;
self.current_profile = profile;
let next_tier = match self.current_tier {
Tier::Catastrophic => Tier::Degraded,
Tier::Degraded => Tier::Good,
Tier::Good => return None,
};
self.current_tier = next_tier;
self.current_profile = next_tier.profile();
self.consecutive_up = 0;
self.stable_since = Some(Instant::now());
return Some(profile);
return Some(self.current_profile);
}
return None; // probe still running
}
// No active probe — check if we should start one
if observed_tier >= self.current_tier {
// Track stability
if self.stable_since.is_none() {
self.stable_since = Some(Instant::now());
}
if let Some(stable_since) = self.stable_since {
if stable_since.elapsed() >= Duration::from_secs(PROBE_STABLE_SECS) {
// Stable long enough — start probing
if let Some(next) = self.upgrade_one_step() {
self.probe = Some(ProbeState {
target_tier: next,
target_profile: next.profile(),
started: Instant::now(),
probe_reports: 0,
bad_reports: 0,
});
// Return the probe profile so the encoder switches
return Some(next.profile());
}
}
}
} else {
// Conditions degraded — reset stability timer
self.stable_since = None;
}
None
}
fn upgrade_one_step(&self) -> Option<Tier> {
match self.current_tier {
Tier::Catastrophic => Some(Tier::Degraded),
Tier::Degraded => Some(Tier::Good),
Tier::Good => Some(Tier::Studio32k),
Tier::Studio32k => Some(Tier::Studio48k),
Tier::Studio48k => Some(Tier::Studio64k),
Tier::Studio64k => None,
}
}
}
impl Default for AdaptiveQualityController {
@@ -422,17 +269,7 @@ impl QualityController for AdaptiveQualityController {
}
let observed = Tier::classify_with_context(report, self.network_context);
// First check for downgrades/upgrades via hysteresis
if let Some(profile) = self.try_transition(observed) {
// Cancel any active probe on tier change
self.probe.take();
self.stable_since = None;
return Some(profile);
}
// Then check probing
self.check_probe(observed)
self.try_transition(observed)
}
fn force_profile(&mut self, profile: QualityProfile) {
@@ -494,33 +331,25 @@ mod tests {
}
assert_eq!(ctrl.tier(), Tier::Catastrophic);
// 4 good reports — not enough (threshold is 5)
let good = make_report(0.5, 20); // studio-quality report
for _ in 0..4 {
// 9 good reports — not enough
let good = make_report(2.0, 100);
for _ in 0..9 {
assert!(ctrl.observe(&good).is_none());
}
assert_eq!(ctrl.tier(), Tier::Catastrophic);
// 5th good report triggers upgrade (one step: Catastrophic → Degraded)
// 10th good report triggers upgrade (one step: Catastrophic → Degraded)
let result = ctrl.observe(&good);
assert!(result.is_some());
assert_eq!(ctrl.tier(), Tier::Degraded);
// Another 5 to go from Degraded → Good
for _ in 0..4 {
assert!(ctrl.observe(&good).is_none());
}
let result = ctrl.observe(&good);
assert!(result.is_some());
assert_eq!(ctrl.tier(), Tier::Good);
// Studio upgrades need 10 consecutive — Good → Studio32k
// Need another 10 to go from Degraded → Good
for _ in 0..9 {
assert!(ctrl.observe(&good).is_none());
}
let result = ctrl.observe(&good);
assert!(result.is_some());
assert_eq!(ctrl.tier(), Tier::Studio32k);
assert_eq!(ctrl.tier(), Tier::Good);
}
#[test]
@@ -537,29 +366,11 @@ mod tests {
#[test]
fn tier_classification() {
// Studio tiers
assert_eq!(Tier::classify(&make_report(0.5, 20)), Tier::Studio64k);
assert_eq!(Tier::classify(&make_report(0.5, 40)), Tier::Studio48k);
assert_eq!(Tier::classify(&make_report(1.5, 60)), Tier::Studio32k);
// Good/Degraded/Catastrophic
assert_eq!(Tier::classify(&make_report(3.0, 90)), Tier::Good);
assert_eq!(Tier::classify(&make_report(6.0, 120)), Tier::Degraded);
assert_eq!(Tier::classify(&make_report(16.0, 120)), Tier::Catastrophic);
assert_eq!(Tier::classify(&make_report(5.0, 200)), Tier::Catastrophic);
}
#[test]
fn studio_tier_boundaries() {
// loss < 1% AND RTT < 30ms → Studio64k
assert_eq!(Tier::classify(&make_report(0.9, 28)), Tier::Studio64k);
// loss < 1% AND RTT 30-49ms → Studio48k
assert_eq!(Tier::classify(&make_report(0.9, 32)), Tier::Studio48k);
// loss < 2% AND RTT < 80ms → Studio32k (but loss >= 1%)
assert_eq!(Tier::classify(&make_report(1.5, 40)), Tier::Studio32k);
// loss >= 2% → Good (use 2.5 to survive u8 quantization)
assert_eq!(Tier::classify(&make_report(2.5, 40)), Tier::Good);
// RTT 80ms → Good
assert_eq!(Tier::classify(&make_report(0.5, 80)), Tier::Good);
assert_eq!(Tier::classify(&make_report(5.0, 200)), Tier::Good);
assert_eq!(Tier::classify(&make_report(15.0, 200)), Tier::Degraded);
assert_eq!(Tier::classify(&make_report(5.0, 500)), Tier::Degraded);
assert_eq!(Tier::classify(&make_report(50.0, 200)), Tier::Catastrophic);
assert_eq!(Tier::classify(&make_report(5.0, 700)), Tier::Catastrophic);
}
// ---------------------------------------------------------------
@@ -568,8 +379,8 @@ mod tests {
#[test]
fn cellular_tighter_thresholds() {
// 9% loss: Degraded on both WiFi (>=5%) and cellular (>=8%)
let report = make_report(9.0, 80);
// 12% loss: Good on WiFi, Degraded on cellular
let report = make_report(12.0, 200);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::WiFi),
Tier::Degraded
@@ -579,22 +390,22 @@ mod tests {
Tier::Degraded
);
// 6% loss, low RTT: Degraded on WiFi (>=5%), Good on cellular (<8%)
let report = make_report(6.0, 80);
// 9% loss: Good on WiFi, Degraded on cellular
let report = make_report(9.0, 200);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::WiFi),
Tier::Degraded
);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::CellularLte),
Tier::Good
);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::CellularLte),
Tier::Degraded
);
// 30% loss: Catastrophic on WiFi (>=15%), Catastrophic on cellular (>=25%)
let report = make_report(30.0, 80);
// 30% loss: Degraded on WiFi, Catastrophic on cellular
let report = make_report(30.0, 200);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::WiFi),
Tier::Catastrophic
Tier::Degraded
);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::Cellular3g),
@@ -604,30 +415,16 @@ mod tests {
#[test]
fn cellular_rtt_thresholds() {
// RTT 150ms: Degraded on WiFi (>=100ms), Good on cellular (<300ms and loss<8%)
let report = make_report(2.0, 148);
// RTT 350ms: Good on WiFi, Degraded on cellular
let report = make_report(2.0, 348); // rtt_4ms rounds so use 348
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::WiFi),
Tier::Good
);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::CellularLte),
Tier::Degraded
);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::CellularLte),
Tier::Good
);
}
#[test]
fn cellular_no_studio_tiers() {
// Even with perfect network, cellular stays at Good (no studio)
let report = make_report(0.0, 10);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::CellularLte),
Tier::Good
);
assert_eq!(
Tier::classify_with_context(&report, NetworkContext::WiFi),
Tier::Studio64k
);
}
#[test]
@@ -672,9 +469,6 @@ mod tests {
#[test]
fn tier_downgrade() {
assert_eq!(Tier::Studio64k.downgrade(), Some(Tier::Studio48k));
assert_eq!(Tier::Studio48k.downgrade(), Some(Tier::Studio32k));
assert_eq!(Tier::Studio32k.downgrade(), Some(Tier::Good));
assert_eq!(Tier::Good.downgrade(), Some(Tier::Degraded));
assert_eq!(Tier::Degraded.downgrade(), Some(Tier::Catastrophic));
assert_eq!(Tier::Catastrophic.downgrade(), None);
@@ -684,97 +478,4 @@ mod tests {
fn network_context_default() {
assert_eq!(NetworkContext::default(), NetworkContext::Unknown);
}
// ---------------------------------------------------------------
// Bandwidth probing tests
// ---------------------------------------------------------------
#[test]
fn probe_triggers_after_stable_period() {
let mut ctrl = AdaptiveQualityController::new();
let excellent = make_report(0.3, 20); // would classify as Studio64k
// Starts at Good. Fast-forward stability by setting stable_since directly.
ctrl.stable_since = Some(Instant::now() - Duration::from_secs(31));
// One excellent report should trigger a probe (Good → Studio32k)
let result = ctrl.observe(&excellent);
assert!(result.is_some(), "should start probe after 30s stable");
assert!(ctrl.probe.is_some(), "probe should be active");
assert_eq!(ctrl.probe.as_ref().unwrap().target_tier, Tier::Studio32k);
}
#[test]
fn probe_succeeds_after_window() {
let mut ctrl = AdaptiveQualityController::new();
ctrl.stable_since = Some(Instant::now() - Duration::from_secs(31));
let excellent = make_report(0.3, 20);
// Trigger probe start
let result = ctrl.observe(&excellent);
assert!(result.is_some());
// Simulate probe window elapsed by backdating started
ctrl.probe.as_mut().unwrap().started =
Instant::now() - Duration::from_secs(PROBE_DURATION_SECS);
// Next good report should finalize the probe
let result = ctrl.observe(&excellent);
assert!(result.is_some(), "probe should succeed");
assert_eq!(ctrl.current_tier, Tier::Studio32k);
assert!(ctrl.probe.is_none(), "probe should be cleared");
}
#[test]
fn probe_fails_on_bad_reports() {
let mut ctrl = AdaptiveQualityController::new();
// Put controller at Studio32k, pretend we've been stable
ctrl.current_tier = Tier::Studio32k;
ctrl.current_profile = Tier::Studio32k.profile();
ctrl.stable_since = Some(Instant::now() - Duration::from_secs(31));
// Start a probe to Studio48k
let excellent = make_report(0.3, 20);
let result = ctrl.observe(&excellent);
assert!(result.is_some()); // probe started
assert_eq!(ctrl.probe.as_ref().unwrap().target_tier, Tier::Studio48k);
// Feed bad reports (loss too high for Studio48k)
let degraded = make_report(3.0, 100);
ctrl.observe(&degraded); // first bad
ctrl.observe(&degraded); // second bad — exceeds PROBE_MAX_BAD (1)
// Probe should be cancelled
assert!(ctrl.probe.is_none(), "probe should be cancelled after bad reports");
// Should still be at Studio32k (not upgraded)
assert_eq!(ctrl.current_tier, Tier::Studio32k);
}
#[test]
fn no_probe_on_cellular() {
let mut ctrl = AdaptiveQualityController::new();
ctrl.signal_network_change(NetworkContext::CellularLte);
ctrl.current_tier = Tier::Good;
ctrl.current_profile = Tier::Good.profile();
ctrl.stable_since = Some(Instant::now() - Duration::from_secs(60));
let good = make_report(0.5, 40);
let result = ctrl.observe(&good);
// Should NOT probe on cellular
assert!(ctrl.probe.is_none(), "should not probe on cellular");
assert!(result.is_none() || ctrl.current_tier == Tier::Good);
}
#[test]
fn no_probe_at_highest_tier() {
let mut ctrl = AdaptiveQualityController::new();
ctrl.current_tier = Tier::Studio64k;
ctrl.current_profile = Tier::Studio64k.profile();
ctrl.stable_since = Some(Instant::now() - Duration::from_secs(60));
let excellent = make_report(0.1, 10);
let result = ctrl.observe(&excellent);
assert!(result.is_none(), "should not probe when already at Studio64k");
}
}

15
crates/wzp-proto/src/traits.rs
View File

@@ -28,13 +28,6 @@ pub trait AudioEncoder: Send + Sync {
/// Enable/disable DTX (discontinuous transmission). No-op for Codec2.
fn set_dtx(&mut self, _enabled: bool) {}
/// Hint the encoder about expected packet loss (0–100). In DRED mode the
/// encoder floors this at 15% internally. No-op for Codec2.
fn set_expected_loss(&mut self, _loss_pct: u8) {}
/// Set DRED duration in 10 ms frame units (0–104). No-op for Codec2.
fn set_dred_duration(&mut self, _frames: u8) {}
}
/// Decodes compressed frames back to PCM audio.
@@ -139,14 +132,6 @@ pub trait CryptoSession: Send + Sync {
fn overhead(&self) -> usize {
16 // ChaCha20-Poly1305 tag
}
/// Short Authentication String (SAS) — 4-digit code for verbal verification.
/// Both peers derive the same code from the shared secret + identity keys.
/// If a MITM relay is intercepting, the codes will differ.
/// Returns None if SAS was not computed (e.g., relay-side sessions).
fn sas_code(&self) -> Option<u32> {
None
}
}
/// Key exchange using the Warzone identity model.

4
crates/wzp-relay/Cargo.toml
View File

@@ -20,7 +20,6 @@ bytes = { workspace = true }
serde = { workspace = true }
toml = "0.8"
anyhow = "1"
clap = { version = "4", features = ["derive"] }
reqwest = { version = "0.12", features = ["json"] }
serde_json = "1"
rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
@@ -29,10 +28,7 @@ prometheus = "0.13"
axum = { version = "0.7", default-features = false, features = ["tokio", "http1", "ws"] }
tower-http = { version = "0.6", features = ["fs"] }
futures-util = "0.3"
dashmap = "6"
dirs = "6"
sha2 = { workspace = true }
chrono = "0.4"
[[bin]]
name = "wzp-relay"

18
crates/wzp-relay/build.rs
View File

@@ -1,18 +0,0 @@
use std::process::Command;
fn main() {
// Get git hash at build time
let output = Command::new("git")
.args(["rev-parse", "--short", "HEAD"])
.output();
let hash = match output {
Ok(o) if o.status.success() => {
String::from_utf8_lossy(&o.stdout).trim().to_string()
}
_ => "unknown".to_string(),
};
println!("cargo:rustc-env=WZP_BUILD_HASH={hash}");
println!("cargo:rerun-if-changed=.git/HEAD");
}

422
crates/wzp-relay/src/call_registry.rs
View File

@@ -1,422 +0,0 @@
//! Direct call state tracking.
//!
//! Manages the lifecycle of 1:1 direct calls placed via the `_signal` channel.
//! Each call goes through: Pending → Ringing → Active → Ended.
use std::collections::HashMap;
use std::time::{Duration, Instant};
/// State of a direct call.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DirectCallState {
/// Offer sent to callee, waiting for response.
Pending,
/// Callee acknowledged, ringing.
Ringing,
/// Call accepted, media room active.
Active,
/// Call ended (hangup, reject, timeout, or error).
Ended,
}
/// A tracked direct call between two users.
pub struct DirectCall {
pub call_id: String,
pub caller_fingerprint: String,
pub callee_fingerprint: String,
pub state: DirectCallState,
pub accept_mode: Option<wzp_proto::CallAcceptMode>,
/// Private room name (set when accepted).
pub room_name: Option<String>,
pub created_at: Instant,
pub answered_at: Option<Instant>,
pub ended_at: Option<Instant>,
/// Phase 3 (hole-punching): caller's server-reflexive address
/// as carried in the `DirectCallOffer`. The relay stashes it
/// here when the offer arrives so it can later inject it as
/// `peer_direct_addr` into the callee's `CallSetup`.
pub caller_reflexive_addr: Option<String>,
/// Phase 3 (hole-punching): callee's server-reflexive address
/// as carried in the `DirectCallAnswer`. Only populated for
/// `AcceptTrusted` answers — privacy-mode answers leave this
/// `None`. Fed into the caller's `CallSetup.peer_direct_addr`.
pub callee_reflexive_addr: Option<String>,
/// Phase 4 (cross-relay): federation TLS fingerprint of the
/// PEER RELAY that forwarded the offer/answer for this call.
/// `None` for local calls — caller and callee both
/// registered on this relay. `Some(fp)` when one side of
/// the call is on a remote relay reached through the
/// federation link identified by `fp`. The
/// `DirectCallAnswer` handling uses this to route the reply
/// back through the SAME link instead of broadcasting again.
pub peer_relay_fp: Option<String>,
/// Phase 5.5 (ICE host candidates): caller's LAN-local
/// interface addresses from the `DirectCallOffer`. Cross-
/// wired into the callee's `CallSetup.peer_local_addrs` so
/// the callee can direct-dial the caller over the same LAN
/// without going through the WAN reflex addr (NAT
/// hairpinning often doesn't work for same-LAN peers).
pub caller_local_addrs: Vec<String>,
/// Phase 5.5 (ICE host candidates): callee's LAN-local
/// interface addresses from the `DirectCallAnswer`. Cross-
/// wired into the caller's `CallSetup.peer_local_addrs`.
pub callee_local_addrs: Vec<String>,
/// Phase 8 (Tailscale-inspired): caller's port-mapped
/// external address from NAT-PMP/PCP/UPnP. Cross-wired
/// into callee's `CallSetup.peer_mapped_addr`.
pub caller_mapped_addr: Option<String>,
/// Phase 8: callee's port-mapped external address.
/// Cross-wired into caller's `CallSetup.peer_mapped_addr`.
pub callee_mapped_addr: Option<String>,
}
/// Registry of active direct calls.
pub struct CallRegistry {
calls: HashMap<String, DirectCall>,
}
impl CallRegistry {
pub fn new() -> Self {
Self {
calls: HashMap::new(),
}
}
/// Create a new pending call. Returns the call_id.
pub fn create_call(&mut self, call_id: String, caller_fp: String, callee_fp: String) -> &DirectCall {
let call = DirectCall {
call_id: call_id.clone(),
caller_fingerprint: caller_fp,
callee_fingerprint: callee_fp,
state: DirectCallState::Pending,
accept_mode: None,
room_name: None,
created_at: Instant::now(),
answered_at: None,
ended_at: None,
caller_reflexive_addr: None,
callee_reflexive_addr: None,
peer_relay_fp: None,
caller_local_addrs: Vec::new(),
callee_local_addrs: Vec::new(),
caller_mapped_addr: None,
callee_mapped_addr: None,
};
self.calls.insert(call_id.clone(), call);
self.calls.get(&call_id).unwrap()
}
/// Phase 5.5: stash the caller's LAN host candidates from
/// the `DirectCallOffer`. Empty Vec is a valid value meaning
/// "caller has no LAN candidates" (e.g. old client).
pub fn set_caller_local_addrs(&mut self, call_id: &str, addrs: Vec<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.caller_local_addrs = addrs;
}
}
/// Phase 5.5: stash the callee's LAN host candidates from
/// the `DirectCallAnswer`.
pub fn set_callee_local_addrs(&mut self, call_id: &str, addrs: Vec<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.callee_local_addrs = addrs;
}
}
/// Phase 4: stash the federation TLS fingerprint of the peer
/// relay that originated (or will receive) the cross-relay
/// forward for this call. Safe to call with `None` to clear
/// a previously-set value.
pub fn set_peer_relay_fp(&mut self, call_id: &str, fp: Option<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.peer_relay_fp = fp;
}
}
/// Phase 3: stash the caller's server-reflexive address read
/// off a `DirectCallOffer`. Safe to call on any call state;
/// a no-op if the call doesn't exist.
pub fn set_caller_reflexive_addr(&mut self, call_id: &str, addr: Option<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.caller_reflexive_addr = addr;
}
}
/// Phase 3: stash the callee's server-reflexive address read
/// off a `DirectCallAnswer`. Safe to call on any call state;
/// a no-op if the call doesn't exist.
pub fn set_callee_reflexive_addr(&mut self, call_id: &str, addr: Option<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.callee_reflexive_addr = addr;
}
}
/// Phase 8: stash the caller's port-mapped address from
/// the `DirectCallOffer`.
pub fn set_caller_mapped_addr(&mut self, call_id: &str, addr: Option<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.caller_mapped_addr = addr;
}
}
/// Phase 8: stash the callee's port-mapped address from
/// the `DirectCallAnswer`.
pub fn set_callee_mapped_addr(&mut self, call_id: &str, addr: Option<String>) {
if let Some(call) = self.calls.get_mut(call_id) {
call.callee_mapped_addr = addr;
}
}
/// Get a call by ID.
pub fn get(&self, call_id: &str) -> Option<&DirectCall> {
self.calls.get(call_id)
}
/// Get a mutable call by ID.
pub fn get_mut(&mut self, call_id: &str) -> Option<&mut DirectCall> {
self.calls.get_mut(call_id)
}
/// Transition to Ringing state.
pub fn set_ringing(&mut self, call_id: &str) -> bool {
if let Some(call) = self.calls.get_mut(call_id) {
if call.state == DirectCallState::Pending {
call.state = DirectCallState::Ringing;
return true;
}
}
false
}
/// Transition to Active state.
pub fn set_active(&mut self, call_id: &str, mode: wzp_proto::CallAcceptMode, room: String) -> bool {
if let Some(call) = self.calls.get_mut(call_id) {
if call.state == DirectCallState::Pending || call.state == DirectCallState::Ringing {
call.state = DirectCallState::Active;
call.accept_mode = Some(mode);
call.room_name = Some(room);
call.answered_at = Some(Instant::now());
return true;
}
}
false
}
/// End a call.
pub fn end_call(&mut self, call_id: &str) -> Option<DirectCall> {
if let Some(call) = self.calls.get_mut(call_id) {
call.state = DirectCallState::Ended;
call.ended_at = Some(Instant::now());
}
self.calls.remove(call_id)
}
/// Find active/pending calls involving a fingerprint.
pub fn calls_for_fingerprint(&self, fp: &str) -> Vec<&DirectCall> {
self.calls.values()
.filter(|c| {
c.state != DirectCallState::Ended
&& (c.caller_fingerprint == fp || c.callee_fingerprint == fp)
})
.collect()
}
/// Find the peer's fingerprint in a call.
pub fn peer_fingerprint(&self, call_id: &str, my_fp: &str) -> Option<&str> {
self.calls.get(call_id).map(|c| {
if c.caller_fingerprint == my_fp {
c.callee_fingerprint.as_str()
} else {
c.caller_fingerprint.as_str()
}
})
}
/// Remove calls that have been pending longer than the timeout.
/// Returns call IDs of expired calls.
pub fn expire_stale(&mut self, timeout: Duration) -> Vec<DirectCall> {
let now = Instant::now();
let expired: Vec<String> = self.calls.iter()
.filter(|(_, c)| {
c.state == DirectCallState::Pending
&& now.duration_since(c.created_at) > timeout
})
.map(|(id, _)| id.clone())
.collect();
expired.into_iter()
.filter_map(|id| self.calls.remove(&id))
.collect()
}
/// Number of active (non-ended) calls.
pub fn active_count(&self) -> usize {
self.calls.values()
.filter(|c| c.state != DirectCallState::Ended)
.count()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn call_lifecycle() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
assert_eq!(reg.get("c1").unwrap().state, DirectCallState::Pending);
assert!(reg.set_ringing("c1"));
assert_eq!(reg.get("c1").unwrap().state, DirectCallState::Ringing);
assert!(reg.set_active("c1", wzp_proto::CallAcceptMode::AcceptGeneric, "_call:c1".into()));
assert_eq!(reg.get("c1").unwrap().state, DirectCallState::Active);
assert_eq!(reg.get("c1").unwrap().room_name.as_deref(), Some("_call:c1"));
let ended = reg.end_call("c1").unwrap();
assert_eq!(ended.state, DirectCallState::Ended);
assert_eq!(reg.active_count(), 0);
}
#[test]
fn expire_stale_calls() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
// Not expired yet
let expired = reg.expire_stale(Duration::from_secs(30));
assert!(expired.is_empty());
// Force expiry with 0 timeout
let expired = reg.expire_stale(Duration::from_secs(0));
assert_eq!(expired.len(), 1);
assert_eq!(expired[0].call_id, "c1");
}
#[test]
fn peer_lookup() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
assert_eq!(reg.peer_fingerprint("c1", "alice"), Some("bob"));
assert_eq!(reg.peer_fingerprint("c1", "bob"), Some("alice"));
}
#[test]
fn call_registry_stores_reflexive_addrs() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
// Default: both addrs are None.
let c = reg.get("c1").unwrap();
assert!(c.caller_reflexive_addr.is_none());
assert!(c.callee_reflexive_addr.is_none());
// Caller advertises its reflex addr via DirectCallOffer.
reg.set_caller_reflexive_addr("c1", Some("192.0.2.1:4433".into()));
assert_eq!(
reg.get("c1").unwrap().caller_reflexive_addr.as_deref(),
Some("192.0.2.1:4433")
);
// Callee responds with AcceptTrusted + its own reflex addr.
reg.set_callee_reflexive_addr("c1", Some("198.51.100.9:4433".into()));
assert_eq!(
reg.get("c1").unwrap().callee_reflexive_addr.as_deref(),
Some("198.51.100.9:4433")
);
// Both addrs are independently readable — the relay uses
// them to cross-wire peer_direct_addr in CallSetup.
let c = reg.get("c1").unwrap();
assert_eq!(
c.caller_reflexive_addr.as_deref(),
Some("192.0.2.1:4433")
);
assert_eq!(
c.callee_reflexive_addr.as_deref(),
Some("198.51.100.9:4433")
);
// Setter on an unknown call is a no-op, not a panic.
reg.set_caller_reflexive_addr("does-not-exist", Some("x".into()));
}
#[test]
fn call_registry_stores_peer_relay_fp() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
// Default: no peer relay.
assert!(reg.get("c1").unwrap().peer_relay_fp.is_none());
// Cross-relay call: origin relay's fp is stashed.
reg.set_peer_relay_fp("c1", Some("relay-a-tls-fp".into()));
assert_eq!(
reg.get("c1").unwrap().peer_relay_fp.as_deref(),
Some("relay-a-tls-fp")
);
// Clearing with None is a valid no-op and empties the field.
reg.set_peer_relay_fp("c1", None);
assert!(reg.get("c1").unwrap().peer_relay_fp.is_none());
// Unknown call is a no-op, not a panic.
reg.set_peer_relay_fp("does-not-exist", Some("x".into()));
}
#[test]
fn call_registry_stores_mapped_addrs() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
// Default: both mapped addrs are None.
let c = reg.get("c1").unwrap();
assert!(c.caller_mapped_addr.is_none());
assert!(c.callee_mapped_addr.is_none());
// Caller advertises its port-mapped addr via DirectCallOffer.
reg.set_caller_mapped_addr("c1", Some("203.0.113.5:12345".into()));
assert_eq!(
reg.get("c1").unwrap().caller_mapped_addr.as_deref(),
Some("203.0.113.5:12345")
);
// Callee responds with its mapped addr.
reg.set_callee_mapped_addr("c1", Some("198.51.100.9:54321".into()));
assert_eq!(
reg.get("c1").unwrap().callee_mapped_addr.as_deref(),
Some("198.51.100.9:54321")
);
// Both addrs readable — relay uses them to cross-wire
// peer_mapped_addr in CallSetup.
let c = reg.get("c1").unwrap();
assert_eq!(c.caller_mapped_addr.as_deref(), Some("203.0.113.5:12345"));
assert_eq!(c.callee_mapped_addr.as_deref(), Some("198.51.100.9:54321"));
// Setter on unknown call is a no-op.
reg.set_caller_mapped_addr("nope", Some("x".into()));
}
#[test]
fn call_registry_clearing_mapped_addr_works() {
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
reg.set_caller_mapped_addr("c1", Some("1.2.3.4:5".into()));
reg.set_caller_mapped_addr("c1", None);
assert!(reg.get("c1").unwrap().caller_mapped_addr.is_none());
}
#[test]
fn call_registry_clearing_reflex_addr_works() {
// Passing None to the setter must clear a previously-set value
// so callers that downgrade to privacy mode mid-flow don't
// leak a stale addr into CallSetup.
let mut reg = CallRegistry::new();
reg.create_call("c1".into(), "alice".into(), "bob".into());
reg.set_caller_reflexive_addr("c1", Some("192.0.2.1:4433".into()));
reg.set_caller_reflexive_addr("c1", None);
assert!(reg.get("c1").unwrap().caller_reflexive_addr.is_none());
}
}

153
crates/wzp-relay/src/config.rs
View File

@@ -3,41 +3,8 @@
use serde::{Deserialize, Serialize};
use std::net::SocketAddr;
/// A federated peer relay.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct PeerConfig {
/// Address of the peer relay (e.g., "193.180.213.68:4433").
pub url: String,
/// Expected TLS certificate fingerprint (hex, with colons).
pub fingerprint: String,
/// Optional human-readable label.
#[serde(default)]
pub label: Option<String>,
}
/// A trusted relay — accepts inbound federation without needing the peer's address.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct TrustedConfig {
/// Expected TLS certificate fingerprint (hex, with colons).
pub fingerprint: String,
/// Optional human-readable label.
#[serde(default)]
pub label: Option<String>,
}
/// A room declared global — bridged across all federated peers.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct GlobalRoomConfig {
/// Room name to bridge (e.g., "android").
pub name: String,
}
/// Configuration for the relay daemon.
///
/// All fields have defaults, so a minimal TOML file only needs the
/// fields you want to override (e.g., just `[[peers]]`).
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(default)]
pub struct RelayConfig {
/// Address to listen on for incoming connections (client-facing).
pub listen_addr: SocketAddr,
@@ -77,30 +44,6 @@ pub struct RelayConfig {
pub ws_port: Option<u16>,
/// Directory to serve static files from (HTML/JS/WASM for web clients).
pub static_dir: Option<String>,
/// Federation peer relays.
#[serde(default)]
pub peers: Vec<PeerConfig>,
/// Global rooms bridged across federation.
#[serde(default)]
pub global_rooms: Vec<GlobalRoomConfig>,
/// Trusted relay fingerprints — accept inbound federation from these relays.
/// Unlike [[peers]], no url is needed — the peer connects to us.
#[serde(default)]
pub trusted: Vec<TrustedConfig>,
/// Phase 8: geographic region identifier (e.g., "us-east", "eu-west").
/// Sent to clients in `RegisterPresenceAck.relay_region` so they can
/// build a relay map for automatic selection.
pub region: Option<String>,
/// Phase 8: externally-advertised address for this relay. Used to
/// populate `available_relays` in `RegisterPresenceAck`. If not set,
/// `listen_addr` is used.
pub advertised_addr: Option<SocketAddr>,
/// Debug tap: log packet headers for matching rooms ("*" = all rooms).
/// Activated via --debug-tap <room> or debug_tap = "room" in TOML.
pub debug_tap: Option<String>,
/// JSONL event log path for protocol analysis (--event-log).
#[serde(skip)]
pub event_log: Option<String>,
}
impl Default for RelayConfig {
@@ -119,102 +62,6 @@ impl Default for RelayConfig {
trunking_enabled: false,
ws_port: None,
static_dir: None,
peers: Vec::new(),
global_rooms: Vec::new(),
trusted: Vec::new(),
region: None,
advertised_addr: None,
debug_tap: None,
event_log: None,
}
}
}
/// Load relay configuration from a TOML file.
pub fn load_config(path: &str) -> Result<RelayConfig, anyhow::Error> {
let content = std::fs::read_to_string(path)?;
let config: RelayConfig = toml::from_str(&content)?;
Ok(config)
}
/// Info about this relay instance, used to generate personalized example configs.
pub struct RelayInfo {
pub listen_addr: String,
pub tls_fingerprint: String,
pub public_ip: Option<String>,
}
/// Load config from path, or create a personalized example config if it doesn't exist.
pub fn load_or_create_config(path: &str, info: Option<&RelayInfo>) -> Result<RelayConfig, anyhow::Error> {
let p = std::path::Path::new(path);
if p.exists() {
return load_config(path);
}
// Create parent directory if needed
if let Some(parent) = p.parent() {
std::fs::create_dir_all(parent)?;
}
// Generate personalized example config
let example = generate_example_config(info);
std::fs::write(p, &example)?;
eprintln!("Created example config at {path} — edit it and restart.");
let config: RelayConfig = toml::from_str(&example)?;
Ok(config)
}
/// Generate an example TOML config, personalized with this relay's info if available.
fn generate_example_config(info: Option<&RelayInfo>) -> String {
let listen = info.map(|i| i.listen_addr.as_str()).unwrap_or("0.0.0.0:4433");
let peer_example = if let Some(i) = info {
let ip = i.public_ip.as_deref().unwrap_or("this-relay-ip");
format!(
r#"# Other relays can peer with this relay using:
# [[peers]]
# url = "{ip}:{port}"
# fingerprint = "{fp}"
# label = "This Relay""#,
port = listen.rsplit(':').next().unwrap_or("4433"),
fp = i.tls_fingerprint,
)
} else {
"# To peer with another relay, add its url + fingerprint:".to_string()
};
format!(
r#"# WarzonePhone Relay Configuration
# See docs/ADMINISTRATION.md for full reference.
# Listen address for client connections
listen_addr = "{listen}"
# Maximum concurrent sessions
# max_sessions = 100
# Prometheus metrics endpoint (uncomment to enable)
# metrics_port = 9090
# featherChat auth endpoint (uncomment to enable)
# auth_url = "https://chat.example.com/v1/auth/validate"
{peer_example}
# Federation: peer relays we connect to (outbound)
# [[peers]]
# url = "other-relay.example.com:4433"
# fingerprint = "aa:bb:cc:dd:..."
# label = "Relay B"
# Federation: relays we trust inbound connections from
# [[trusted]]
# fingerprint = "ee:ff:00:11:..."
# label = "Relay X"
# Global rooms bridged across all federated peers
# [[global_rooms]]
# name = "general"
# Debug: log packet headers for a room ("*" for all)
# debug_tap = "*"
"#
)
}

200
crates/wzp-relay/src/event_log.rs
View File

@@ -1,200 +0,0 @@
//! JSONL event log for protocol analysis.
//!
//! When `--event-log <path>` is set, every media packet emits a structured
//! event at each decision point (recv, forward, drop, deliver).
//! Use `wzp-analyzer` to correlate events across multiple relays.
use std::path::PathBuf;
use serde::Serialize;
use tokio::sync::mpsc;
use tracing::{error, info};
/// A single protocol event for JSONL output.
#[derive(Debug, Serialize)]
pub struct Event {
/// ISO 8601 timestamp with microseconds.
pub ts: String,
/// Event type.
pub event: &'static str,
/// Room name.
#[serde(skip_serializing_if = "Option::is_none")]
pub room: Option<String>,
/// Source address or peer label.
#[serde(skip_serializing_if = "Option::is_none")]
pub src: Option<String>,
/// Packet sequence number.
#[serde(skip_serializing_if = "Option::is_none")]
pub seq: Option<u16>,
/// Codec identifier.
#[serde(skip_serializing_if = "Option::is_none")]
pub codec: Option<String>,
/// FEC block ID.
#[serde(skip_serializing_if = "Option::is_none")]
pub fec_block: Option<u8>,
/// FEC symbol index.
#[serde(skip_serializing_if = "Option::is_none")]
pub fec_sym: Option<u8>,
/// Is FEC repair packet.
#[serde(skip_serializing_if = "Option::is_none")]
pub repair: Option<bool>,
/// Payload length in bytes.
#[serde(skip_serializing_if = "Option::is_none")]
pub len: Option<usize>,
/// Number of recipients.
#[serde(skip_serializing_if = "Option::is_none")]
pub to_count: Option<usize>,
/// Peer label (for federation events).
#[serde(skip_serializing_if = "Option::is_none")]
pub peer: Option<String>,
/// Drop/error reason.
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
/// Presence action (active/inactive).
#[serde(skip_serializing_if = "Option::is_none")]
pub action: Option<String>,
/// Participant count (presence events).
#[serde(skip_serializing_if = "Option::is_none")]
pub participants: Option<usize>,
}
impl Event {
fn now() -> String {
chrono::Utc::now().format("%Y-%m-%dT%H:%M:%S%.6fZ").to_string()
}
/// Create a minimal event with just type and timestamp.
pub fn new(event: &'static str) -> Self {
Self {
ts: Self::now(),
event,
room: None,
src: None,
seq: None,
codec: None,
fec_block: None,
fec_sym: None,
repair: None,
len: None,
to_count: None,
peer: None,
reason: None,
action: None,
participants: None,
}
}
/// Set room.
pub fn room(mut self, room: &str) -> Self { self.room = Some(room.to_string()); self }
/// Set source.
pub fn src(mut self, src: &str) -> Self { self.src = Some(src.to_string()); self }
/// Set packet header fields from a MediaPacket.
pub fn packet(mut self, pkt: &wzp_proto::MediaPacket) -> Self {
self.seq = Some(pkt.header.seq);
self.codec = Some(format!("{:?}", pkt.header.codec_id));
self.fec_block = Some(pkt.header.fec_block);
self.fec_sym = Some(pkt.header.fec_symbol);
self.repair = Some(pkt.header.is_repair);
self.len = Some(pkt.payload.len());
self
}
/// Set seq only (when full packet not available).
pub fn seq(mut self, seq: u16) -> Self { self.seq = Some(seq); self }
/// Set payload length.
pub fn len(mut self, len: usize) -> Self { self.len = Some(len); self }
/// Set recipient count.
pub fn to_count(mut self, n: usize) -> Self { self.to_count = Some(n); self }
/// Set peer label.
pub fn peer(mut self, peer: &str) -> Self { self.peer = Some(peer.to_string()); self }
/// Set drop reason.
pub fn reason(mut self, reason: &str) -> Self { self.reason = Some(reason.to_string()); self }
/// Set presence action.
pub fn action(mut self, action: &str) -> Self { self.action = Some(action.to_string()); self }
/// Set participant count.
pub fn participants(mut self, n: usize) -> Self { self.participants = Some(n); self }
}
/// Handle for emitting events. Cheap to clone.
#[derive(Clone)]
pub struct EventLog {
tx: mpsc::UnboundedSender<Event>,
}
impl EventLog {
/// Emit an event (non-blocking, drops if channel is full).
pub fn emit(&self, event: Event) {
let _ = self.tx.send(event);
}
}
/// No-op event log for when `--event-log` is not set.
/// All methods are no-ops that compile to nothing.
#[derive(Clone)]
pub struct NoopEventLog;
/// Unified event log handle — either real or no-op.
#[derive(Clone)]
pub enum EventLogger {
Active(EventLog),
Noop,
}
impl EventLogger {
pub fn emit(&self, event: Event) {
if let EventLogger::Active(log) = self {
log.emit(event);
}
}
pub fn is_active(&self) -> bool {
matches!(self, EventLogger::Active(_))
}
}
/// Start the event log writer. Returns an `EventLogger` handle.
pub fn start_event_log(path: Option<PathBuf>) -> EventLogger {
match path {
Some(path) => {
let (tx, rx) = mpsc::unbounded_channel();
tokio::spawn(writer_task(path, rx));
info!("event log enabled");
EventLogger::Active(EventLog { tx })
}
None => EventLogger::Noop,
}
}
/// Background task that writes events to a JSONL file.
async fn writer_task(path: PathBuf, mut rx: mpsc::UnboundedReceiver<Event>) {
use tokio::io::AsyncWriteExt;
let file = match tokio::fs::File::create(&path).await {
Ok(f) => f,
Err(e) => {
error!("failed to create event log {}: {e}", path.display());
return;
}
};
let mut writer = tokio::io::BufWriter::new(file);
let mut count: u64 = 0;
while let Some(event) = rx.recv().await {
match serde_json::to_string(&event) {
Ok(json) => {
if writer.write_all(json.as_bytes()).await.is_err() { break; }
if writer.write_all(b"\n").await.is_err() { break; }
count += 1;
// Flush every 100 events
if count % 100 == 0 {
let _ = writer.flush().await;
}
}
Err(e) => {
error!("event log serialize error: {e}");
}
}
}
let _ = writer.flush().await;
info!(events = count, "event log closed");
}

1145
crates/wzp-relay/src/federation.rs
View File

File diff suppressed because it is too large Load Diff

39
crates/wzp-relay/src/handshake.rs
View File

@@ -78,30 +78,31 @@ pub async fn accept_handshake(
};
transport.send_signal(&answer).await?;
// Derive caller fingerprint: SHA-256(Ed25519 pub)[:16], formatted as xxxx:xxxx:...
// Must match the format used in signal registration and presence.
let caller_fp = {
use sha2::{Sha256, Digest};
let hash = Sha256::digest(&caller_identity_pub);
let fp = wzp_crypto::Fingerprint([
hash[0], hash[1], hash[2], hash[3], hash[4], hash[5], hash[6], hash[7],
hash[8], hash[9], hash[10], hash[11], hash[12], hash[13], hash[14], hash[15],
]);
fp.to_string()
};
// Derive caller fingerprint from their identity public key (first 8 bytes as hex)
let caller_fp = caller_identity_pub[..8]
.iter()
.map(|b| format!("{b:02x}"))
.collect::<String>();
Ok((session, chosen_profile, caller_fp, caller_alias))
}
/// Select the best quality profile from those the caller supports.
///
/// The `_supported` list is currently ignored — we hardcode GOOD (24k) until
/// studio tiers (32k/48k/64k) have been validated across federation (large
/// packets may exceed path MTU and fragment in unpleasant ways). Once that's
/// tested, the body should pick the highest supported profile ≤ the relay's
/// configured ceiling.
fn choose_profile(_supported: &[QualityProfile]) -> QualityProfile {
QualityProfile::GOOD
fn choose_profile(supported: &[QualityProfile]) -> QualityProfile {
// Prefer higher-quality profiles. Use GOOD as default if supported list is empty.
if supported.is_empty() {
return QualityProfile::GOOD;
}
// Pick the profile with the highest bitrate.
supported
.iter()
.max_by(|a, b| {
a.total_bitrate_kbps()
.partial_cmp(&b.total_bitrate_kbps())
.unwrap_or(std::cmp::Ordering::Equal)
})
.copied()
.unwrap_or(QualityProfile::GOOD)
}
#[cfg(test)]

4
crates/wzp-relay/src/lib.rs
View File

@@ -8,11 +8,7 @@
//! quality transitions.
pub mod auth;
pub mod call_registry;
pub mod config;
pub mod event_log;
pub mod federation;
pub mod signal_hub;
pub mod handshake;
pub mod metrics;
pub mod pipeline;

1502
crates/wzp-relay/src/main.rs
View File

File diff suppressed because it is too large Load Diff

154
crates/wzp-relay/src/metrics.rs
View File

@@ -16,22 +16,12 @@ pub struct RelayMetrics {
pub bytes_forwarded: IntCounter,
pub auth_attempts: IntCounterVec,
pub handshake_duration: Histogram,
// Federation metrics
pub federation_peer_status: IntGaugeVec,
pub federation_peer_rtt_ms: GaugeVec,
pub federation_packets_forwarded: IntCounterVec,
pub federation_packets_deduped: IntCounter,
pub federation_packets_rate_limited: IntCounter,
pub federation_active_rooms: IntGauge,
// Per-session metrics
pub session_buffer_depth: IntGaugeVec,
pub session_loss_pct: GaugeVec,
pub session_rtt_ms: GaugeVec,
pub session_underruns: IntCounterVec,
pub session_overruns: IntCounterVec,
// Phase 4: loss-recovery breakdown per session.
pub session_dred_reconstructions: IntCounterVec,
pub session_classical_plc: IntCounterVec,
registry: Registry,
}
@@ -70,28 +60,6 @@ impl RelayMetrics {
)
.expect("metric");
let federation_peer_status = IntGaugeVec::new(
Opts::new("wzp_federation_peer_status", "Peer connection status (0=disconnected, 1=connected)"),
&["peer"],
).expect("metric");
let federation_peer_rtt_ms = GaugeVec::new(
Opts::new("wzp_federation_peer_rtt_ms", "QUIC RTT to federated peer in milliseconds"),
&["peer"],
).expect("metric");
let federation_packets_forwarded = IntCounterVec::new(
Opts::new("wzp_federation_packets_forwarded_total", "Packets forwarded to/from federated peers"),
&["peer", "direction"],
).expect("metric");
let federation_packets_deduped = IntCounter::with_opts(
Opts::new("wzp_federation_packets_deduped_total", "Duplicate federation packets dropped"),
).expect("metric");
let federation_packets_rate_limited = IntCounter::with_opts(
Opts::new("wzp_federation_packets_rate_limited_total", "Federation packets dropped by rate limiter"),
).expect("metric");
let federation_active_rooms = IntGauge::with_opts(
Opts::new("wzp_federation_active_rooms", "Number of federated rooms currently active"),
).expect("metric");
let session_buffer_depth = IntGaugeVec::new(
Opts::new(
"wzp_relay_session_jitter_buffer_depth",
@@ -133,42 +101,17 @@ impl RelayMetrics {
)
.expect("metric");
let session_dred_reconstructions = IntCounterVec::new(
Opts::new(
"wzp_relay_session_dred_reconstructions_total",
"Frames reconstructed via DRED (Deep REDundancy) per session",
),
&["session_id"],
)
.expect("metric");
let session_classical_plc = IntCounterVec::new(
Opts::new(
"wzp_relay_session_classical_plc_total",
"Frames filled via classical Opus/Codec2 PLC per session",
),
&["session_id"],
)
.expect("metric");
registry.register(Box::new(active_sessions.clone())).expect("register");
registry.register(Box::new(active_rooms.clone())).expect("register");
registry.register(Box::new(packets_forwarded.clone())).expect("register");
registry.register(Box::new(bytes_forwarded.clone())).expect("register");
registry.register(Box::new(auth_attempts.clone())).expect("register");
registry.register(Box::new(handshake_duration.clone())).expect("register");
registry.register(Box::new(federation_peer_status.clone())).expect("register");
registry.register(Box::new(federation_peer_rtt_ms.clone())).expect("register");
registry.register(Box::new(federation_packets_forwarded.clone())).expect("register");
registry.register(Box::new(federation_packets_deduped.clone())).expect("register");
registry.register(Box::new(federation_packets_rate_limited.clone())).expect("register");
registry.register(Box::new(federation_active_rooms.clone())).expect("register");
registry.register(Box::new(session_buffer_depth.clone())).expect("register");
registry.register(Box::new(session_loss_pct.clone())).expect("register");
registry.register(Box::new(session_rtt_ms.clone())).expect("register");
registry.register(Box::new(session_underruns.clone())).expect("register");
registry.register(Box::new(session_overruns.clone())).expect("register");
registry.register(Box::new(session_dred_reconstructions.clone())).expect("register");
registry.register(Box::new(session_classical_plc.clone())).expect("register");
Self {
active_sessions,
@@ -177,19 +120,11 @@ impl RelayMetrics {
bytes_forwarded,
auth_attempts,
handshake_duration,
federation_peer_status,
federation_peer_rtt_ms,
federation_packets_forwarded,
federation_packets_deduped,
federation_packets_rate_limited,
federation_active_rooms,
session_buffer_depth,
session_loss_pct,
session_rtt_ms,
session_underruns,
session_overruns,
session_dred_reconstructions,
session_classical_plc,
registry,
}
}
@@ -241,39 +176,6 @@ impl RelayMetrics {
}
}
/// Phase 4: update per-session loss-recovery counters from a client's
/// `LossRecoveryUpdate` signal message. The client sends monotonic
/// totals (frames reconstructed since call start); we compute the
/// delta against the current Prometheus counter and increment by it.
/// IntCounterVec only increases, so a client restart that resets the
/// counter to 0 simply produces no delta until the new totals exceed
/// the Prometheus state.
pub fn update_session_loss_recovery(
&self,
session_id: &str,
dred_reconstructions: u64,
classical_plc: u64,
) {
let cur_dred = self
.session_dred_reconstructions
.with_label_values(&[session_id])
.get();
if dred_reconstructions > cur_dred {
self.session_dred_reconstructions
.with_label_values(&[session_id])
.inc_by(dred_reconstructions - cur_dred);
}
let cur_plc = self
.session_classical_plc
.with_label_values(&[session_id])
.get();
if classical_plc > cur_plc {
self.session_classical_plc
.with_label_values(&[session_id])
.inc_by(classical_plc - cur_plc);
}
}
/// Remove all per-session label values for a disconnected session.
pub fn remove_session_metrics(&self, session_id: &str) {
let _ = self.session_buffer_depth.remove_label_values(&[session_id]);
@@ -281,10 +183,6 @@ impl RelayMetrics {
let _ = self.session_rtt_ms.remove_label_values(&[session_id]);
let _ = self.session_underruns.remove_label_values(&[session_id]);
let _ = self.session_overruns.remove_label_values(&[session_id]);
let _ = self
.session_dred_reconstructions
.remove_label_values(&[session_id]);
let _ = self.session_classical_plc.remove_label_values(&[session_id]);
}
/// Get a reference to the underlying Prometheus registry.
@@ -479,13 +377,10 @@ mod tests {
};
m.update_session_quality("sess-cleanup", &report);
m.update_session_buffer("sess-cleanup", 42, 3, 1);
m.update_session_loss_recovery("sess-cleanup", 17, 4);
// Verify they appear
let output = m.metrics_handler();
assert!(output.contains("sess-cleanup"));
assert!(output.contains("wzp_relay_session_dred_reconstructions_total"));
assert!(output.contains("wzp_relay_session_classical_plc_total"));
// Remove and verify they are gone
m.remove_session_metrics("sess-cleanup");
@@ -493,55 +388,6 @@ mod tests {
assert!(!output.contains("sess-cleanup"));
}
/// Phase 4: LossRecoveryUpdate → per-session counters, monotonic delta
/// application.
#[test]
fn session_loss_recovery_monotonic_delta() {
let m = RelayMetrics::new();
let sess = "sess-dred";
// First update: 10 DRED, 2 PLC
m.update_session_loss_recovery(sess, 10, 2);
let dred1 = m
.session_dred_reconstructions
.with_label_values(&[sess])
.get();
let plc1 = m.session_classical_plc.with_label_values(&[sess]).get();
assert_eq!(dred1, 10);
assert_eq!(plc1, 2);
// Second update: 25 DRED, 5 PLC — counter advances by (15, 3)
m.update_session_loss_recovery(sess, 25, 5);
let dred2 = m
.session_dred_reconstructions
.with_label_values(&[sess])
.get();
let plc2 = m.session_classical_plc.with_label_values(&[sess]).get();
assert_eq!(dred2, 25);
assert_eq!(plc2, 5);
// Third update with LOWER values (e.g., client reset) — counters
// hold steady, no decrement.
m.update_session_loss_recovery(sess, 5, 1);
let dred3 = m
.session_dred_reconstructions
.with_label_values(&[sess])
.get();
let plc3 = m.session_classical_plc.with_label_values(&[sess]).get();
assert_eq!(dred3, 25, "counter must not decrease");
assert_eq!(plc3, 5, "counter must not decrease");
// Fourth update: client caught up and exceeded the old max.
m.update_session_loss_recovery(sess, 30, 8);
let dred4 = m
.session_dred_reconstructions
.with_label_values(&[sess])
.get();
let plc4 = m.session_classical_plc.with_label_values(&[sess]).get();
assert_eq!(dred4, 30);
assert_eq!(plc4, 8);
}
#[test]
fn metrics_increment() {
let m = RelayMetrics::new();

809
crates/wzp-relay/src/room.rs
View File

File diff suppressed because it is too large Load Diff

125
crates/wzp-relay/src/signal_hub.rs
View File

@@ -1,125 +0,0 @@
//! Persistent signaling connection manager.
//!
//! Tracks clients connected via `_signal` SNI. Routes call signals
//! (DirectCallOffer, DirectCallAnswer, Hangup) between registered users.
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Instant;
use tracing::info;
use wzp_proto::{MediaTransport, SignalMessage};
use wzp_transport::QuinnTransport;
/// A client connected via `_signal` for direct calling.
pub struct SignalClient {
pub fingerprint: String,
pub alias: Option<String>,
pub transport: Arc<QuinnTransport>,
pub connected_at: Instant,
}
/// Manages persistent signaling connections.
pub struct SignalHub {
clients: HashMap<String, SignalClient>,
}
impl SignalHub {
pub fn new() -> Self {
Self {
clients: HashMap::new(),
}
}
/// Register a new signaling client.
pub fn register(&mut self, fp: String, transport: Arc<QuinnTransport>, alias: Option<String>) {
info!(fingerprint = %fp, alias = ?alias, "signal client registered");
self.clients.insert(fp.clone(), SignalClient {
fingerprint: fp,
alias,
transport,
connected_at: Instant::now(),
});
}
/// Unregister a signaling client. Returns the client if found.
pub fn unregister(&mut self, fp: &str) -> Option<SignalClient> {
let client = self.clients.remove(fp);
if client.is_some() {
info!(fingerprint = %fp, "signal client unregistered");
}
client
}
/// Look up a client by fingerprint.
pub fn get(&self, fp: &str) -> Option<&SignalClient> {
self.clients.get(fp)
}
/// Check if a fingerprint is online.
pub fn is_online(&self, fp: &str) -> bool {
self.clients.contains_key(fp)
}
/// Send a signal message to a client by fingerprint.
pub async fn send_to(&self, fp: &str, msg: &SignalMessage) -> Result<(), String> {
match self.clients.get(fp) {
Some(client) => {
client.transport.send_signal(msg).await
.map_err(|e| format!("send to {fp}: {e}"))
}
None => Err(format!("{fp} not online")),
}
}
/// Number of connected signaling clients.
pub fn online_count(&self) -> usize {
self.clients.len()
}
/// List all online fingerprints.
pub fn online_fingerprints(&self) -> Vec<&str> {
self.clients.keys().map(|s| s.as_str()).collect()
}
/// Get alias for a fingerprint.
pub fn alias(&self, fp: &str) -> Option<&str> {
self.clients.get(fp).and_then(|c| c.alias.as_deref())
}
/// Build a PresenceList message with all online users.
pub fn presence_list(&self) -> SignalMessage {
let users: Vec<wzp_proto::PresenceUser> = self
.clients
.values()
.map(|c| wzp_proto::PresenceUser {
fingerprint: c.fingerprint.clone(),
alias: c.alias.clone(),
})
.collect();
SignalMessage::PresenceList { users }
}
/// Broadcast a message to ALL connected signal clients.
pub async fn broadcast(&self, msg: &SignalMessage) {
for client in self.clients.values() {
let _ = client.transport.send_signal(msg).await;
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn register_unregister() {
let hub = SignalHub::new();
assert_eq!(hub.online_count(), 0);
assert!(!hub.is_online("alice"));
// Can't easily construct QuinnTransport in a unit test,
// so we just test the HashMap logic conceptually.
// Integration tests cover the full flow.
}
}

19
crates/wzp-relay/src/ws.rs
View File

@@ -31,7 +31,7 @@ use crate::session_mgr::SessionManager;
/// Shared state for WebSocket handlers.
#[derive(Clone)]
pub struct WsState {
pub room_mgr: Arc<RoomManager>,
pub room_mgr: Arc<Mutex<RoomManager>>,
pub session_mgr: Arc<Mutex<SessionManager>>,
pub auth_url: Option<String>,
pub metrics: Arc<RelayMetrics>,
@@ -143,9 +143,10 @@ async fn handle_ws_connection(socket: WebSocket, room: String, state: WsState) {
// 4. Join room with WS sender
let addr: SocketAddr = ([0, 0, 0, 0], 0).into();
let participant_id = {
match state.room_mgr.join_ws(&room, addr, tx, fingerprint.as_deref()) {
let mut mgr = state.room_mgr.lock().await;
match mgr.join_ws(&room, addr, tx, fingerprint.as_deref()) {
Ok(id) => {
state.metrics.active_rooms.set(state.room_mgr.list().len() as i64);
state.metrics.active_rooms.set(mgr.list().len() as i64);
id
}
Err(e) => {
@@ -183,7 +184,10 @@ async fn handle_ws_connection(socket: WebSocket, room: String, state: WsState) {
loop {
match ws_rx.next().await {
Some(Ok(Message::Binary(data))) => {
let others = state.room_mgr.others(&room, participant_id);
let others = {
let mgr = state.room_mgr.lock().await;
mgr.others(&room, participant_id)
};
for other in &others {
let _ = other.send_raw(&data).await;
}
@@ -210,8 +214,11 @@ async fn handle_ws_connection(socket: WebSocket, room: String, state: WsState) {
reg.unregister_local(fp);
}
state.room_mgr.leave(&room, participant_id);
state.metrics.active_rooms.set(state.room_mgr.list().len() as i64);
{
let mut mgr = state.room_mgr.lock().await;
mgr.leave(&room, participant_id);
state.metrics.active_rooms.set(mgr.list().len() as i64);
}
let session_id_str: String = session_id.iter().map(|b| format!("{b:02x}")).collect();
state.metrics.remove_session_metrics(&session_id_str);

321
crates/wzp-relay/tests/cross_relay_direct_call.rs
View File

@@ -1,321 +0,0 @@
//! Phase 4 integration test for cross-relay direct calling
//! (PRD: .taskmaster/docs/prd_phase4_cross_relay_p2p.txt).
//!
//! Drives the call-registry cross-wiring + a simulated federation
//! forward without spinning up actual relay binaries. The real
//! main-loop and dispatcher code are exercised end-to-end in
//! `reflect.rs` / `hole_punching.rs` already; this file focuses on
//! the *new* invariants Phase 4 adds:
//!
//! 1. When Relay A forwards a DirectCallOffer, its local registry
//! stashes caller_reflexive_addr and leaves peer_relay_fp
//! unset (broadcast, answer-side will identify itself).
//! 2. When Relay B's cross-relay dispatcher receives the forward,
//! its local registry stores the call with
//! peer_relay_fp = Some(relay_a_tls_fp).
//! 3. When Relay B processes the local callee's answer, it sees
//! peer_relay_fp.is_some() and MUST NOT deliver the answer via
//! local signal_hub — instead it routes through federation.
//! 4. When Relay A receives the forwarded answer via its
//! cross-relay dispatcher, it stashes callee_reflexive_addr
//! and emits a CallSetup to its local caller with
//! peer_direct_addr = callee_addr.
//! 5. Final state: Alice's CallSetup carries Bob's reflex addr,
//! Bob's CallSetup carries Alice's reflex addr — cross-wired
//! through two relays + a federation link.
use wzp_proto::{CallAcceptMode, SignalMessage};
use wzp_relay::call_registry::CallRegistry;
// ────────────────────────────────────────────────────────────────
// Simulated dispatch helpers — these reproduce the exact logic
// in main.rs without the tokio + federation boilerplate.
// ────────────────────────────────────────────────────────────────
const RELAY_A_TLS_FP: &str = "relay-A-tls-fingerprint";
const RELAY_B_TLS_FP: &str = "relay-B-tls-fingerprint";
const ALICE_ADDR: &str = "192.0.2.1:4433";
const BOB_ADDR: &str = "198.51.100.9:4433";
const RELAY_A_ADDR: &str = "203.0.113.5:4433";
const RELAY_B_ADDR: &str = "203.0.113.10:4433";
/// Helper that Alice's place_call sends.
fn alice_offer(call_id: &str) -> SignalMessage {
SignalMessage::DirectCallOffer {
caller_fingerprint: "alice".into(),
caller_alias: None,
target_fingerprint: "bob".into(),
call_id: call_id.into(),
identity_pub: [0; 32],
ephemeral_pub: [0; 32],
signature: vec![],
supported_profiles: vec![],
caller_reflexive_addr: Some(ALICE_ADDR.into()),
caller_local_addrs: Vec::new(),
caller_mapped_addr: None,
caller_build_version: None,
}
}
/// Relay A receives Alice's offer. Target Bob is not local.
/// Relay A wraps + broadcasts over federation, stashes the call
/// locally with peer_relay_fp = None (broadcast — answer-side
/// identifies itself).
fn relay_a_handle_offer(reg_a: &mut CallRegistry, offer: &SignalMessage) -> SignalMessage {
match offer {
SignalMessage::DirectCallOffer {
caller_fingerprint,
target_fingerprint,
call_id,
caller_reflexive_addr,
..
} => {
reg_a.create_call(
call_id.clone(),
caller_fingerprint.clone(),
target_fingerprint.clone(),
);
reg_a.set_caller_reflexive_addr(call_id, caller_reflexive_addr.clone());
// peer_relay_fp stays None — we don't know which peer
// will respond yet.
}
_ => panic!("not an offer"),
}
// Build the federation envelope the main loop would
// broadcast.
SignalMessage::FederatedSignalForward {
inner: Box::new(offer.clone()),
origin_relay_fp: RELAY_A_TLS_FP.into(),
}
}
/// Relay B receives a FederatedSignalForward(DirectCallOffer).
/// This is the cross-relay dispatcher task code in main.rs —
/// reproduced here for the test.
fn relay_b_handle_forwarded_offer(reg_b: &mut CallRegistry, forward: &SignalMessage) {
let (inner, origin_relay_fp) = match forward {
SignalMessage::FederatedSignalForward { inner, origin_relay_fp } => {
(inner.as_ref().clone(), origin_relay_fp.clone())
}
_ => panic!("not a forward"),
};
// Loop-prevention: drop self-sourced.
assert_ne!(origin_relay_fp, RELAY_B_TLS_FP);
let SignalMessage::DirectCallOffer {
caller_fingerprint,
target_fingerprint,
call_id,
caller_reflexive_addr,
..
} = inner
else {
panic!("inner was not DirectCallOffer");
};
// Simulated: target is local to B (Bob is registered here).
reg_b.create_call(
call_id.clone(),
caller_fingerprint,
target_fingerprint,
);
reg_b.set_caller_reflexive_addr(&call_id, caller_reflexive_addr);
reg_b.set_peer_relay_fp(&call_id, Some(origin_relay_fp));
}
/// Bob's answer — AcceptTrusted with his reflex addr.
fn bob_answer(call_id: &str) -> SignalMessage {
SignalMessage::DirectCallAnswer {
call_id: call_id.into(),
accept_mode: CallAcceptMode::AcceptTrusted,
identity_pub: None,
ephemeral_pub: None,
signature: None,
chosen_profile: None,
callee_reflexive_addr: Some(BOB_ADDR.into()),
callee_local_addrs: Vec::new(),
callee_mapped_addr: None,
callee_build_version: None,
}
}
/// Relay B handles the LOCAL callee's answer. If peer_relay_fp
/// is Some, wrap the answer in a FederatedSignalForward + emit the
/// local CallSetup to Bob. Returns the (forward_envelope,
/// bob_call_setup) pair.
fn relay_b_handle_local_answer(
reg_b: &mut CallRegistry,
answer: &SignalMessage,
) -> (SignalMessage, SignalMessage) {
let (call_id, mode, callee_addr) = match answer {
SignalMessage::DirectCallAnswer {
call_id,
accept_mode,
callee_reflexive_addr,
..
} => (call_id.clone(), *accept_mode, callee_reflexive_addr.clone()),
_ => panic!(),
};
// Stash callee addr + activate.
reg_b.set_active(&call_id, mode, format!("call-{call_id}"));
reg_b.set_callee_reflexive_addr(&call_id, callee_addr);
let call = reg_b.get(&call_id).unwrap();
let caller_addr = call.caller_reflexive_addr.clone();
let callee_addr = call.callee_reflexive_addr.clone();
assert!(
call.peer_relay_fp.is_some(),
"Relay B must know this call is cross-relay"
);
// Forward the answer back over federation.
let forward = SignalMessage::FederatedSignalForward {
inner: Box::new(answer.clone()),
origin_relay_fp: RELAY_B_TLS_FP.into(),
};
// Local CallSetup for Bob — peer_direct_addr = Alice's addr.
let setup_for_bob = SignalMessage::CallSetup {
call_id: call_id.clone(),
room: format!("call-{call_id}"),
relay_addr: RELAY_B_ADDR.into(),
peer_direct_addr: caller_addr,
peer_local_addrs: Vec::new(),
peer_mapped_addr: None,
};
let _ = callee_addr;
(forward, setup_for_bob)
}
/// Relay A's cross-relay dispatcher receives the forwarded answer.
/// It stashes the callee addr, forwards the raw answer to local
/// Alice, and emits a CallSetup with peer_direct_addr = Bob's addr.
fn relay_a_handle_forwarded_answer(
reg_a: &mut CallRegistry,
forward: &SignalMessage,
) -> SignalMessage {
let (inner, origin_relay_fp) = match forward {
SignalMessage::FederatedSignalForward { inner, origin_relay_fp } => {
(inner.as_ref().clone(), origin_relay_fp.clone())
}
_ => panic!("not a forward"),
};
assert_ne!(origin_relay_fp, RELAY_A_TLS_FP);
let SignalMessage::DirectCallAnswer {
call_id,
accept_mode,
callee_reflexive_addr,
..
} = inner
else {
panic!("inner was not DirectCallAnswer");
};
assert_eq!(accept_mode, CallAcceptMode::AcceptTrusted);
reg_a.set_active(&call_id, accept_mode, format!("call-{call_id}"));
reg_a.set_callee_reflexive_addr(&call_id, callee_reflexive_addr.clone());
// Alice's CallSetup — peer_direct_addr = Bob's addr.
SignalMessage::CallSetup {
call_id: call_id.clone(),
room: format!("call-{call_id}"),
relay_addr: RELAY_A_ADDR.into(),
peer_direct_addr: callee_reflexive_addr,
peer_local_addrs: Vec::new(),
peer_mapped_addr: None,
}
}
// ────────────────────────────────────────────────────────────────
// Tests
// ────────────────────────────────────────────────────────────────
#[test]
fn cross_relay_offer_forwards_and_stashes_peer_relay_fp() {
let mut reg_a = CallRegistry::new();
let mut reg_b = CallRegistry::new();
let offer = alice_offer("c-xrelay-1");
let forward = relay_a_handle_offer(&mut reg_a, &offer);
// Relay A's local view: call exists, caller addr stashed,
// peer_relay_fp still None (broadcast — answer identifies the
// peer).
let call_a = reg_a.get("c-xrelay-1").unwrap();
assert_eq!(call_a.caller_fingerprint, "alice");
assert_eq!(call_a.callee_fingerprint, "bob");
assert_eq!(call_a.caller_reflexive_addr.as_deref(), Some(ALICE_ADDR));
assert!(call_a.peer_relay_fp.is_none());
// Relay B dispatches the forward: creates the call locally
// and stashes peer_relay_fp = Relay A.
relay_b_handle_forwarded_offer(&mut reg_b, &forward);
let call_b = reg_b.get("c-xrelay-1").unwrap();
assert_eq!(call_b.caller_fingerprint, "alice");
assert_eq!(call_b.callee_fingerprint, "bob");
assert_eq!(call_b.caller_reflexive_addr.as_deref(), Some(ALICE_ADDR));
assert_eq!(call_b.peer_relay_fp.as_deref(), Some(RELAY_A_TLS_FP));
}
#[test]
fn cross_relay_answer_crosswires_peer_direct_addrs() {
let mut reg_a = CallRegistry::new();
let mut reg_b = CallRegistry::new();
// Full round trip: offer → forward → dispatch → answer →
// forward back → dispatch → both CallSetups.
let offer = alice_offer("c-xrelay-2");
let offer_forward = relay_a_handle_offer(&mut reg_a, &offer);
relay_b_handle_forwarded_offer(&mut reg_b, &offer_forward);
// Bob answers on Relay B.
let answer = bob_answer("c-xrelay-2");
let (answer_forward, setup_for_bob) =
relay_b_handle_local_answer(&mut reg_b, &answer);
// Bob's CallSetup carries Alice's addr.
match setup_for_bob {
SignalMessage::CallSetup { peer_direct_addr, relay_addr, .. } => {
assert_eq!(peer_direct_addr.as_deref(), Some(ALICE_ADDR));
assert_eq!(relay_addr, RELAY_B_ADDR);
}
_ => panic!("wrong variant"),
}
// Alice's dispatcher receives the forwarded answer and builds
// her CallSetup.
let setup_for_alice = relay_a_handle_forwarded_answer(&mut reg_a, &answer_forward);
match setup_for_alice {
SignalMessage::CallSetup { peer_direct_addr, relay_addr, .. } => {
assert_eq!(peer_direct_addr.as_deref(), Some(BOB_ADDR));
assert_eq!(relay_addr, RELAY_A_ADDR);
}
_ => panic!("wrong variant"),
}
// Both registries agree on caller + callee reflex addrs after
// the full round-trip.
for reg in [&reg_a, &reg_b] {
let c = reg.get("c-xrelay-2").unwrap();
assert_eq!(c.caller_reflexive_addr.as_deref(), Some(ALICE_ADDR));
assert_eq!(c.callee_reflexive_addr.as_deref(), Some(BOB_ADDR));
}
}
#[test]
fn cross_relay_loop_prevention_drops_self_sourced_forward() {
// A FederatedSignalForward that circles back to the origin
// relay should be dropped before it hits the call registry.
let forward = SignalMessage::FederatedSignalForward {
inner: Box::new(alice_offer("c-loop")),
origin_relay_fp: RELAY_B_TLS_FP.into(),
};
// The dispatcher in main.rs calls this explicit check before
// doing any work. Reproduce it inline.
let origin = match &forward {
SignalMessage::FederatedSignalForward { origin_relay_fp, .. } => origin_relay_fp.clone(),
_ => unreachable!(),
};
// Relay B sees origin == its own fp → drop.
assert_eq!(origin, RELAY_B_TLS_FP, "loop-prevention triggers on self-fp");
}

662
crates/wzp-relay/tests/federation.rs
View File

@@ -1,662 +0,0 @@
//! Tests for `wzp_relay::federation`.
//!
//! Covers:
//! - room_hash determinism and uniqueness
//! - is_global_room (static config + call-* implicit global)
//! - resolve_global_room
//! - global_room_hash
//! - forward_to_peers with zero peers (no-op)
//! - forward_to_peers with live QUIC peer links
//! - broadcast_signal to live QUIC peers
//! - send_signal_to_peer targeted routing
//! - find_peer_by_fingerprint / find_peer_by_addr / check_inbound_trust
//! - set_cross_relay_tx + local_tls_fp accessors
use std::collections::HashSet;
use std::net::{Ipv4Addr, SocketAddr};
use std::sync::Arc;
use std::time::Duration;
use bytes::Bytes;
use wzp_proto::{MediaTransport, SignalMessage};
use wzp_relay::config::{PeerConfig, TrustedConfig};
use wzp_relay::event_log::EventLogger;
use wzp_relay::federation::{room_hash, FederationManager};
use wzp_relay::metrics::RelayMetrics;
use wzp_relay::room::RoomManager;
use wzp_transport::{client_config, create_endpoint, server_config, QuinnTransport};
// ───────────────────────────── helpers ──────────────────────────────
/// Create a FederationManager for unit tests (no live peers).
fn create_test_fm(global_rooms: HashSet<String>) -> Arc<FederationManager> {
create_test_fm_full(vec![], vec![], global_rooms)
}
/// Create a FederationManager with full config (peers + trusted + global rooms).
fn create_test_fm_full(
peers: Vec<PeerConfig>,
trusted: Vec<TrustedConfig>,
global_rooms: HashSet<String>,
) -> Arc<FederationManager> {
let _ = rustls::crypto::ring::default_provider().install_default();
let (sc, _cert) = server_config();
let ep = create_endpoint((Ipv4Addr::LOCALHOST, 0).into(), Some(sc))
.expect("test endpoint");
let room_mgr = Arc::new(RoomManager::new());
let metrics = Arc::new(RelayMetrics::new());
let event_log = EventLogger::Noop;
Arc::new(FederationManager::new(
peers,
trusted,
global_rooms,
room_mgr,
ep,
"test-relay-fp-abc123".into(),
metrics,
event_log,
))
}
/// Build an in-process QUIC client/server pair on loopback.
/// Returns (client_transport, server_transport, endpoints).
/// The endpoints must be kept alive for the test duration.
async fn connected_pair() -> (
Arc<QuinnTransport>,
Arc<QuinnTransport>,
(quinn::Endpoint, quinn::Endpoint),
) {
let _ = rustls::crypto::ring::default_provider().install_default();
let (sc, _cert_der) = server_config();
let server_addr: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let server_ep = create_endpoint(server_addr, Some(sc)).expect("server endpoint");
let server_listen = server_ep.local_addr().expect("server local addr");
let client_bind: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let client_ep = create_endpoint(client_bind, None).expect("client endpoint");
let server_ep_clone = server_ep.clone();
let accept_fut = tokio::spawn(async move {
let conn = wzp_transport::accept(&server_ep_clone)
.await
.expect("accept");
Arc::new(QuinnTransport::new(conn))
});
let client_conn =
wzp_transport::connect(&client_ep, server_listen, "localhost", client_config())
.await
.expect("connect");
let client_transport = Arc::new(QuinnTransport::new(client_conn));
let server_transport = accept_fut.await.expect("join accept task");
(client_transport, server_transport, (server_ep, client_ep))
}
// ───────────────────── 1. room_hash determinism ─────────────────────
#[test]
fn room_hash_deterministic() {
let h1 = room_hash("podcast");
let h2 = room_hash("podcast");
assert_eq!(h1, h2);
}
#[test]
fn room_hash_different_rooms() {
let h1 = room_hash("room-a");
let h2 = room_hash("room-b");
assert_ne!(h1, h2);
}
#[test]
fn room_hash_is_8_bytes() {
let h = room_hash("some-room");
assert_eq!(h.len(), 8);
}
#[test]
fn room_hash_empty_string() {
// Should not panic on empty input
let h = room_hash("");
assert_eq!(h.len(), 8);
// And should differ from a non-empty room
assert_ne!(h, room_hash("nonempty"));
}
#[test]
fn room_hash_case_sensitive() {
// "Podcast" and "podcast" are different rooms
let h1 = room_hash("Podcast");
let h2 = room_hash("podcast");
assert_ne!(h1, h2);
}
// ───────────────── 2. is_global_room / resolve_global_room ──────────
#[tokio::test]
async fn is_global_room_static_config() {
let global: HashSet<String> = ["podcast", "lobby"].iter().map(|s| s.to_string()).collect();
let fm = create_test_fm(global);
assert!(fm.is_global_room("podcast"));
assert!(fm.is_global_room("lobby"));
assert!(!fm.is_global_room("private-room"));
assert!(!fm.is_global_room(""));
}
#[tokio::test]
async fn is_global_room_call_prefix_implicit() {
// Phase 4.1: call-* rooms are implicitly global
let fm = create_test_fm(HashSet::new());
assert!(fm.is_global_room("call-abc123"));
assert!(fm.is_global_room("call-"));
assert!(fm.is_global_room("call-some-uuid-here"));
// But not just "call" without the dash
assert!(!fm.is_global_room("call"));
assert!(!fm.is_global_room("callback"));
}
#[tokio::test]
async fn resolve_global_room_static() {
let global: HashSet<String> = ["podcast"].iter().map(|s| s.to_string()).collect();
let fm = create_test_fm(global);
assert_eq!(fm.resolve_global_room("podcast"), Some("podcast".into()));
assert_eq!(fm.resolve_global_room("unknown"), None);
}
#[tokio::test]
async fn resolve_global_room_call_prefix() {
let fm = create_test_fm(HashSet::new());
let resolved = fm.resolve_global_room("call-test-123");
assert_eq!(resolved, Some("call-test-123".into()));
}
#[tokio::test]
async fn global_room_hash_uses_canonical_name() {
let global: HashSet<String> = ["podcast"].iter().map(|s| s.to_string()).collect();
let fm = create_test_fm(global);
// For a known global room, global_room_hash should match room_hash of the canonical name
let expected = room_hash("podcast");
assert_eq!(fm.global_room_hash("podcast"), expected);
}
#[tokio::test]
async fn global_room_hash_unknown_room_falls_through() {
let fm = create_test_fm(HashSet::new());
// Unknown room: just hashes whatever was passed
let expected = room_hash("random-room");
assert_eq!(fm.global_room_hash("random-room"), expected);
}
#[tokio::test]
async fn global_room_hash_call_prefix() {
let fm = create_test_fm(HashSet::new());
// call-* resolves to itself
let expected = room_hash("call-xyz");
assert_eq!(fm.global_room_hash("call-xyz"), expected);
}
// ───────────────── 3. forward_to_peers with zero peers ──────────────
#[tokio::test]
async fn forward_to_peers_empty_returns_immediately() {
let fm = create_test_fm(HashSet::new());
let hash = room_hash("room");
let data = Bytes::from_static(b"test-media-payload");
// Should not panic or hang
let result = tokio::time::timeout(
Duration::from_secs(2),
fm.forward_to_peers("room", &hash, &data),
)
.await;
assert!(result.is_ok(), "forward_to_peers should return immediately with no peers");
}
// ─────────── 4. forward_to_peers with live QUIC peer links ──────────
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn forward_to_peers_delivers_tagged_datagram() {
// We create a FederationManager and manually wire a connected QUIC
// pair to simulate a peer link. The fm holds the server-side
// transport; we read from the client side to verify delivery.
let fm = create_test_fm(HashSet::new());
let (client_transport, server_transport, _endpoints) = connected_pair().await;
// Manually insert a PeerLink by using handle_inbound's internal
// pattern: we call the private peer_links mutex directly. Since
// PeerLink is private, we instead use handle_inbound which calls
// run_federation_link. But that requires a full signal loop.
//
// Alternative approach: spawn a mock "federation relay" server,
// have the FM connect to it via connect_to_peer, and read back
// from the server side. But connect_to_peer also starts the full
// link loop.
//
// Simplest: create a second FM that acts as the peer, and use
// the broadcast_signal / forward_to_peers pattern after the link
// is established via handle_inbound.
//
// Actually the simplest approach for testing forward_to_peers is
// to accept that PeerLink is private, so we instead test through
// the full federation link lifecycle. We'll spawn a mini relay
// that does the FederationHello handshake and then reads datagrams.
// Approach: spawn the server side to do the hello exchange, then
// the fm handle_inbound will register the link, then we can call
// forward_to_peers and read from the server side... But
// handle_inbound blocks in run_federation_link.
//
// Final approach: we test the wire format directly. The client
// side is "us" (the relay) — we send a tagged datagram manually,
// and verify the peer side receives it with the correct format.
// This tests the same logic as forward_to_peers without needing
// peer_links access.
let room = "test-room";
let rh = room_hash(room);
let media = b"opus-frame-data-here";
// Build the tagged datagram the same way forward_to_peers does
let mut tagged = Vec::with_capacity(8 + media.len());
tagged.extend_from_slice(&rh);
tagged.extend_from_slice(media);
// Send from the server side (as if we are the relay forwarding)
server_transport
.send_raw_datagram(&tagged)
.expect("send datagram");
// Read from client side (as if we are the peer relay receiving)
let received = tokio::time::timeout(
Duration::from_secs(2),
client_transport.connection().read_datagram(),
)
.await
.expect("should receive within timeout")
.expect("read_datagram ok");
// Verify: first 8 bytes are the room hash, remainder is media
assert!(received.len() >= 8, "datagram too short");
let mut recv_hash = [0u8; 8];
recv_hash.copy_from_slice(&received[..8]);
assert_eq!(recv_hash, rh, "room hash mismatch");
assert_eq!(&received[8..], media, "media payload mismatch");
drop(client_transport);
drop(server_transport);
}
// ─────────── 5. broadcast_signal to live QUIC peers ─────────────────
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn broadcast_signal_sends_to_all_peers() {
// We need the peer links to be registered inside the FM.
// The simplest approach: spawn a mock peer relay that accepts
// federation connections, does the FederationHello handshake,
// and then reads signals.
let _ = rustls::crypto::ring::default_provider().install_default();
// Create a mock "peer relay" server endpoint
let (sc, _cert) = server_config();
let peer_addr: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let peer_ep = create_endpoint(peer_addr, Some(sc)).expect("peer endpoint");
let peer_listen = peer_ep.local_addr().expect("peer local addr");
// The FM that will connect outbound
let peer_cfg = PeerConfig {
url: peer_listen.to_string(),
fingerprint: "aa:bb:cc:dd".into(),
label: Some("mock-peer".into()),
};
let global: HashSet<String> = ["podcast"].iter().map(|s| s.to_string()).collect();
let fm = create_test_fm_full(vec![peer_cfg], vec![], global);
// Spawn the FM's run (which will try to connect to our mock peer)
let fm_clone = fm.clone();
let _fm_task = tokio::spawn(async move {
fm_clone.run().await;
});
// Accept the connection on the mock peer side
let peer_ep_clone = peer_ep.clone();
let peer_transport = tokio::time::timeout(Duration::from_secs(5), async {
let conn = wzp_transport::accept(&peer_ep_clone).await.expect("accept");
Arc::new(QuinnTransport::new(conn))
})
.await
.expect("FM should connect to mock peer within 5s");
// The FM sends FederationHello as the first signal. Read it.
let hello = tokio::time::timeout(
Duration::from_secs(2),
peer_transport.recv_signal(),
)
.await
.expect("hello timeout")
.expect("recv ok")
.expect("some message");
match hello {
SignalMessage::FederationHello { tls_fingerprint } => {
assert_eq!(tls_fingerprint, "test-relay-fp-abc123");
}
other => panic!("expected FederationHello, got: {:?}", std::mem::discriminant(&other)),
}
// Now the FM's run_federation_link registered the peer in peer_links
// and will announce active global rooms. We may receive
// GlobalRoomActive signals next (for any rooms the FM has active).
// For this test, no local participants, so no GlobalRoomActive.
// Give the link time to fully set up
tokio::time::sleep(Duration::from_millis(100)).await;
// Now call broadcast_signal on the FM
let test_msg = SignalMessage::FederatedSignalForward {
inner: Box::new(SignalMessage::Reflect),
origin_relay_fp: "other-relay-fp".into(),
};
let count = fm.broadcast_signal(&test_msg).await;
assert_eq!(count, 1, "should have broadcast to exactly 1 peer");
// Read the signal on the peer side
let received = tokio::time::timeout(
Duration::from_secs(2),
peer_transport.recv_signal(),
)
.await
.expect("broadcast signal timeout")
.expect("recv ok")
.expect("some message");
match received {
SignalMessage::FederatedSignalForward { origin_relay_fp, .. } => {
assert_eq!(origin_relay_fp, "other-relay-fp");
}
other => panic!("expected FederatedSignalForward, got: {:?}", std::mem::discriminant(&other)),
}
drop(peer_transport);
}
// ──────────── 6. send_signal_to_peer targeted routing ───────────────
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn send_signal_to_peer_unknown_fp_returns_error() {
let fm = create_test_fm(HashSet::new());
let msg = SignalMessage::Reflect;
let result = fm.send_signal_to_peer("nonexistent-fp", &msg).await;
assert!(result.is_err());
assert!(result.unwrap_err().contains("no active federation link"));
}
// ──────────── 7. find_peer_by_fingerprint / addr / trust ────────────
#[tokio::test]
async fn find_peer_by_fingerprint_matches() {
let peer = PeerConfig {
url: "10.0.0.1:4433".into(),
fingerprint: "AA:BB:CC:DD".into(),
label: Some("relay-eu".into()),
};
let fm = create_test_fm_full(vec![peer], vec![], HashSet::new());
// Normalized match (colons removed, lowercased)
let found = fm.find_peer_by_fingerprint("aabbccdd");
assert!(found.is_some());
assert_eq!(found.unwrap().label.as_deref(), Some("relay-eu"));
// With colons
let found2 = fm.find_peer_by_fingerprint("AA:BB:CC:DD");
assert!(found2.is_some());
// Non-matching
assert!(fm.find_peer_by_fingerprint("11:22:33:44").is_none());
}
#[tokio::test]
async fn find_peer_by_addr_matches_ip() {
let peer = PeerConfig {
url: "10.0.0.1:4433".into(),
fingerprint: "aabb".into(),
label: None,
};
let fm = create_test_fm_full(vec![peer], vec![], HashSet::new());
// Same IP, different port still matches (find_peer_by_addr matches by IP)
let addr: SocketAddr = "10.0.0.1:9999".parse().unwrap();
let found = fm.find_peer_by_addr(addr);
assert!(found.is_some());
// Different IP
let addr2: SocketAddr = "10.0.0.2:4433".parse().unwrap();
assert!(fm.find_peer_by_addr(addr2).is_none());
}
#[tokio::test]
async fn find_trusted_by_fingerprint() {
let trusted = TrustedConfig {
fingerprint: "AA:BB:CC:DD:EE".into(),
label: Some("trusted-relay".into()),
};
let fm = create_test_fm_full(vec![], vec![trusted], HashSet::new());
let found = fm.find_trusted_by_fingerprint("aabbccddee");
assert!(found.is_some());
assert_eq!(found.unwrap().label.as_deref(), Some("trusted-relay"));
assert!(fm.find_trusted_by_fingerprint("ffffffff").is_none());
}
#[tokio::test]
async fn check_inbound_trust_prefers_peer_by_addr() {
let peer = PeerConfig {
url: "10.0.0.1:4433".into(),
fingerprint: "aabb".into(),
label: Some("peer-relay".into()),
};
let trusted = TrustedConfig {
fingerprint: "ccdd".into(),
label: Some("trusted-relay".into()),
};
let fm = create_test_fm_full(vec![peer], vec![trusted], HashSet::new());
// Matches by addr (peer takes priority)
let addr: SocketAddr = "10.0.0.1:5555".parse().unwrap();
let label = fm.check_inbound_trust(addr, "ccdd");
assert_eq!(label, Some("peer-relay".into()));
}
#[tokio::test]
async fn check_inbound_trust_falls_back_to_trusted_fp() {
let trusted = TrustedConfig {
fingerprint: "CC:DD".into(),
label: Some("trusted-relay".into()),
};
let fm = create_test_fm_full(vec![], vec![trusted], HashSet::new());
// No peer matches, but trusted fingerprint matches
let addr: SocketAddr = "10.99.99.99:1234".parse().unwrap();
let label = fm.check_inbound_trust(addr, "ccdd");
assert_eq!(label, Some("trusted-relay".into()));
}
#[tokio::test]
async fn check_inbound_trust_returns_none_for_unknown() {
let fm = create_test_fm(HashSet::new());
let addr: SocketAddr = "10.0.0.1:4433".parse().unwrap();
assert!(fm.check_inbound_trust(addr, "unknown-fp").is_none());
}
// ──────────── 8. set_cross_relay_tx + local_tls_fp ──────────────────
#[tokio::test]
async fn local_tls_fp_returns_configured_value() {
let fm = create_test_fm(HashSet::new());
assert_eq!(fm.local_tls_fp(), "test-relay-fp-abc123");
}
#[tokio::test]
async fn set_cross_relay_tx_wires_channel() {
let fm = create_test_fm(HashSet::new());
let (tx, mut rx) = tokio::sync::mpsc::channel(16);
fm.set_cross_relay_tx(tx).await;
// The channel is now wired — we can't easily test it without
// going through handle_signal, but we can at least verify it
// doesn't panic and the fm accepted the sender.
// (The channel itself works — we test the Sender.)
let msg = SignalMessage::Reflect;
let _ = rx.try_recv(); // should be empty
drop(rx);
}
// ──────────── 9. broadcast_signal with zero peers ───────────────────
#[tokio::test]
async fn broadcast_signal_zero_peers_returns_zero() {
let fm = create_test_fm(HashSet::new());
let msg = SignalMessage::Reflect;
let count = fm.broadcast_signal(&msg).await;
assert_eq!(count, 0);
}
// ──────────── 10. get_remote_participants with no links ─────────────
#[tokio::test]
async fn get_remote_participants_empty_with_no_links() {
let fm = create_test_fm(HashSet::new());
let participants = fm.get_remote_participants("podcast").await;
assert!(participants.is_empty());
}
// ─────── 11. Federation media egress with live QUIC connection ──────
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn federation_media_egress_forwards_to_peer() {
// This test verifies the full media path:
// local media -> federation egress channel -> forward_to_peers -> peer reads datagram
//
// We set up a real QUIC federation link via fm.run() connecting to
// a mock peer, then push media through the room manager's federation
// egress channel.
let _ = rustls::crypto::ring::default_provider().install_default();
// Mock peer relay
let (sc, _cert) = server_config();
let peer_addr: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let peer_ep = create_endpoint(peer_addr, Some(sc)).expect("peer endpoint");
let peer_listen = peer_ep.local_addr().expect("peer local addr");
let peer_cfg = PeerConfig {
url: peer_listen.to_string(),
fingerprint: "ee:ff:00:11".into(),
label: Some("egress-peer".into()),
};
let global: HashSet<String> = ["podcast"].iter().map(|s| s.to_string()).collect();
let fm = create_test_fm_full(vec![peer_cfg], vec![], global);
// Start the FM (connects to mock peer)
let fm_clone = fm.clone();
let _fm_task = tokio::spawn(async move { fm_clone.run().await });
// Accept the connection
let peer_ep_clone = peer_ep.clone();
let peer_transport = tokio::time::timeout(Duration::from_secs(5), async {
let conn = wzp_transport::accept(&peer_ep_clone).await.expect("accept");
Arc::new(QuinnTransport::new(conn))
})
.await
.expect("FM should connect within 5s");
// Read the FederationHello
let _hello = tokio::time::timeout(
Duration::from_secs(2),
peer_transport.recv_signal(),
)
.await
.expect("hello timeout")
.expect("recv ok")
.expect("some message");
// Wait for link setup
tokio::time::sleep(Duration::from_millis(100)).await;
// Now send media via forward_to_peers
let room = "podcast";
let rh = room_hash(room);
let media_payload = Bytes::from_static(b"test-opus-frame-1234567890");
fm.forward_to_peers(room, &rh, &media_payload).await;
// Read the datagram on the peer side
let received = tokio::time::timeout(
Duration::from_secs(2),
peer_transport.connection().read_datagram(),
)
.await
.expect("should receive media within timeout")
.expect("read_datagram ok");
// Verify tagged format: [8-byte room_hash][media_payload]
assert!(received.len() >= 8);
let mut recv_hash = [0u8; 8];
recv_hash.copy_from_slice(&received[..8]);
assert_eq!(recv_hash, rh, "room hash must match");
assert_eq!(
&received[8..],
&media_payload[..],
"media payload must match"
);
drop(peer_transport);
}
// ───── 12. Multiple global rooms: each hashes independently ─────────
#[tokio::test]
async fn multiple_global_rooms_independent_hashes() {
let global: HashSet<String> = ["podcast", "lobby", "arena"]
.iter()
.map(|s| s.to_string())
.collect();
let fm = create_test_fm(global);
let hashes: Vec<[u8; 8]> = ["podcast", "lobby", "arena"]
.iter()
.map(|r| fm.global_room_hash(r))
.collect();
// All different
assert_ne!(hashes[0], hashes[1]);
assert_ne!(hashes[1], hashes[2]);
assert_ne!(hashes[0], hashes[2]);
}
// ───── 13. is_global_room edge cases ────────────────────────────────
#[tokio::test]
async fn is_global_room_exact_match_required_for_static() {
let global: HashSet<String> = ["podcast"].iter().map(|s| s.to_string()).collect();
let fm = create_test_fm(global);
// Substring/prefix should NOT match
assert!(!fm.is_global_room("podcast-extra"));
assert!(!fm.is_global_room("pod"));
assert!(!fm.is_global_room("podcastt"));
}

13
crates/wzp-relay/tests/handshake_integration.rs
View File

@@ -63,11 +63,11 @@ async fn handshake_succeeds() {
accept_handshake(server_t.as_ref(), &callee_seed).await
});
let caller_session = perform_handshake(client_transport.as_ref(), &caller_seed, None)
let caller_session = perform_handshake(client_transport.as_ref(), &caller_seed)
.await
.expect("perform_handshake should succeed");
let (callee_session, chosen_profile, _caller_fp, _caller_alias) = callee_handle
let (callee_session, chosen_profile) = callee_handle
.await
.expect("join callee task")
.expect("accept_handshake should succeed");
@@ -124,11 +124,11 @@ async fn handshake_verifies_identity() {
accept_handshake(server_t.as_ref(), &callee_seed).await
});
let caller_session = perform_handshake(client_transport.as_ref(), &caller_seed, None)
let caller_session = perform_handshake(client_transport.as_ref(), &caller_seed)
.await
.expect("handshake must succeed even with different identities");
let (callee_session, _profile, _caller_fp, _caller_alias) = callee_handle
let (callee_session, _profile) = callee_handle
.await
.expect("join")
.expect("accept_handshake must succeed");
@@ -183,7 +183,7 @@ async fn auth_then_handshake() {
};
// 2. Run the cryptographic handshake
let (session, profile, _caller_fp, _caller_alias) = accept_handshake(server_t.as_ref(), &callee_seed)
let (session, profile) = accept_handshake(server_t.as_ref(), &callee_seed)
.await
.expect("accept_handshake after auth");
@@ -199,7 +199,7 @@ async fn auth_then_handshake() {
.await
.expect("send AuthToken");
let caller_session = perform_handshake(client_transport.as_ref(), &caller_seed, None)
let caller_session = perform_handshake(client_transport.as_ref(), &caller_seed)
.await
.expect("perform_handshake after auth");
@@ -270,7 +270,6 @@ async fn handshake_rejects_bad_signature() {
ephemeral_pub,
signature,
supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
alias: None,
};
client_transport

298
crates/wzp-relay/tests/hole_punching.rs
View File

@@ -1,298 +0,0 @@
//! Phase 3 integration tests for hole-punching advertising
//! (PRD: .taskmaster/docs/prd_hole_punching.txt).
//!
//! These verify the end-to-end protocol cross-wiring:
//! caller (places offer with caller_reflexive_addr=A)
//! → relay (stashes A in registry)
//! → callee (reads A off the forwarded offer)
//! callee (sends AcceptTrusted answer with callee_reflexive_addr=B)
//! → relay (stashes B, emits CallSetup to both parties)
//! → caller receives CallSetup.peer_direct_addr = B
//! → callee receives CallSetup.peer_direct_addr = A
//!
//! The actual QUIC hole-punch race is a Phase 3.5 follow-up.
//! These tests only cover the signal-plane plumbing — that the
//! addrs make it from each peer's offer/answer through the relay
//! cross-wiring back out in CallSetup with the peer's addr.
//!
//! We drive the call registry + a minimal routing function
//! directly instead of spinning up a full relay process — easier
//! to reason about, no real network, and what we actually want to
//! test is the cross-wiring logic, not the whole signal stack.
use wzp_proto::{CallAcceptMode, SignalMessage};
use wzp_relay::call_registry::CallRegistry;
/// Helper: simulate the relay's handling of a DirectCallOffer. In
/// `wzp-relay/src/main.rs` this is the match arm that creates the
/// call in the registry and stashes the caller's reflex addr.
fn handle_offer(reg: &mut CallRegistry, offer: &SignalMessage) -> String {
match offer {
SignalMessage::DirectCallOffer {
caller_fingerprint,
target_fingerprint,
call_id,
caller_reflexive_addr,
..
} => {
reg.create_call(
call_id.clone(),
caller_fingerprint.clone(),
target_fingerprint.clone(),
);
reg.set_caller_reflexive_addr(call_id, caller_reflexive_addr.clone());
call_id.clone()
}
_ => panic!("not an offer"),
}
}
/// Helper: simulate the relay's handling of a DirectCallAnswer +
/// the subsequent CallSetup emission. Returns the two CallSetup
/// messages the relay would push: (for_caller, for_callee).
fn handle_answer_and_build_setups(
reg: &mut CallRegistry,
answer: &SignalMessage,
) -> (SignalMessage, SignalMessage) {
let (call_id, mode, callee_addr) = match answer {
SignalMessage::DirectCallAnswer {
call_id,
accept_mode,
callee_reflexive_addr,
..
} => (call_id.clone(), *accept_mode, callee_reflexive_addr.clone()),
_ => panic!("not an answer"),
};
reg.set_callee_reflexive_addr(&call_id, callee_addr);
let room = format!("call-{call_id}");
reg.set_active(&call_id, mode, room.clone());
let (caller_addr, callee_addr) = {
let c = reg.get(&call_id).unwrap();
(
c.caller_reflexive_addr.clone(),
c.callee_reflexive_addr.clone(),
)
};
let setup_for_caller = SignalMessage::CallSetup {
call_id: call_id.clone(),
room: room.clone(),
relay_addr: "203.0.113.5:4433".into(),
peer_direct_addr: callee_addr,
peer_local_addrs: Vec::new(),
peer_mapped_addr: None,
};
let setup_for_callee = SignalMessage::CallSetup {
call_id,
room,
relay_addr: "203.0.113.5:4433".into(),
peer_direct_addr: caller_addr,
peer_local_addrs: Vec::new(),
peer_mapped_addr: None,
};
(setup_for_caller, setup_for_callee)
}
fn mk_offer(call_id: &str, caller_reflexive_addr: Option<&str>) -> SignalMessage {
SignalMessage::DirectCallOffer {
caller_fingerprint: "alice".into(),
caller_alias: None,
target_fingerprint: "bob".into(),
call_id: call_id.into(),
identity_pub: [0; 32],
ephemeral_pub: [0; 32],
signature: vec![],
supported_profiles: vec![],
caller_reflexive_addr: caller_reflexive_addr.map(String::from),
caller_local_addrs: Vec::new(),
caller_mapped_addr: None,
caller_build_version: None,
}
}
fn mk_answer(
call_id: &str,
mode: CallAcceptMode,
callee_reflexive_addr: Option<&str>,
) -> SignalMessage {
SignalMessage::DirectCallAnswer {
call_id: call_id.into(),
accept_mode: mode,
identity_pub: None,
ephemeral_pub: None,
signature: None,
chosen_profile: None,
callee_reflexive_addr: callee_reflexive_addr.map(String::from),
callee_local_addrs: Vec::new(),
callee_mapped_addr: None,
callee_build_version: None,
}
}
// -----------------------------------------------------------------------
// Test 1: both peers advertise — CallSetup cross-wires correctly
// -----------------------------------------------------------------------
#[test]
fn both_peers_advertise_reflex_addrs_cross_wire_in_setup() {
let mut reg = CallRegistry::new();
let caller_addr = "192.0.2.1:4433";
let callee_addr = "198.51.100.9:4433";
let offer = mk_offer("c1", Some(caller_addr));
let call_id = handle_offer(&mut reg, &offer);
assert_eq!(call_id, "c1");
assert_eq!(
reg.get("c1").unwrap().caller_reflexive_addr.as_deref(),
Some(caller_addr)
);
let answer = mk_answer("c1", CallAcceptMode::AcceptTrusted, Some(callee_addr));
let (setup_caller, setup_callee) =
handle_answer_and_build_setups(&mut reg, &answer);
// The CALLER's setup should carry the CALLEE's addr as peer_direct_addr.
match setup_caller {
SignalMessage::CallSetup { peer_direct_addr, .. } => {
assert_eq!(
peer_direct_addr.as_deref(),
Some(callee_addr),
"caller's CallSetup must contain callee's addr"
);
}
_ => panic!("wrong variant"),
}
// The CALLEE's setup should carry the CALLER's addr.
match setup_callee {
SignalMessage::CallSetup { peer_direct_addr, .. } => {
assert_eq!(
peer_direct_addr.as_deref(),
Some(caller_addr),
"callee's CallSetup must contain caller's addr"
);
}
_ => panic!("wrong variant"),
}
}
// -----------------------------------------------------------------------
// Test 2: callee uses AcceptGeneric (privacy) — no addr leaks
// -----------------------------------------------------------------------
#[test]
fn privacy_mode_answer_omits_callee_addr_from_setup() {
let mut reg = CallRegistry::new();
let caller_addr = "192.0.2.1:4433";
handle_offer(&mut reg, &mk_offer("c2", Some(caller_addr)));
// AcceptGeneric explicitly passes None for callee_reflexive_addr —
// the whole point is to hide the callee's IP from the caller.
let answer = mk_answer("c2", CallAcceptMode::AcceptGeneric, None);
let (setup_caller, setup_callee) =
handle_answer_and_build_setups(&mut reg, &answer);
// CALLER should see peer_direct_addr = None (privacy preserved).
match setup_caller {
SignalMessage::CallSetup { peer_direct_addr, .. } => {
assert!(
peer_direct_addr.is_none(),
"privacy mode must not leak callee addr to caller"
);
}
_ => panic!("wrong variant"),
}
// CALLEE still gets the caller's addr — only the callee opted for
// privacy, the caller already volunteered its addr in the offer.
match setup_callee {
SignalMessage::CallSetup { peer_direct_addr, .. } => {
assert_eq!(
peer_direct_addr.as_deref(),
Some(caller_addr),
"callee's CallSetup should still carry caller's volunteered addr"
);
}
_ => panic!("wrong variant"),
}
}
// -----------------------------------------------------------------------
// Test 3: old caller (no addr) + new callee — relay path only
// -----------------------------------------------------------------------
#[test]
fn pre_phase3_caller_leaves_both_setups_relay_only() {
let mut reg = CallRegistry::new();
// Pre-Phase-3 client doesn't know about caller_reflexive_addr
// so the field is None.
handle_offer(&mut reg, &mk_offer("c3", None));
// New callee advertises its addr — doesn't matter because
// without caller_reflexive_addr the caller has nothing to
// attempt a direct handshake to, so the cross-wiring should
// still leave the caller's CallSetup without peer_direct_addr.
let answer = mk_answer(
"c3",
CallAcceptMode::AcceptTrusted,
Some("198.51.100.9:4433"),
);
let (setup_caller, setup_callee) =
handle_answer_and_build_setups(&mut reg, &answer);
match setup_caller {
SignalMessage::CallSetup { peer_direct_addr, .. } => {
// Phase 3 relay behavior: we always inject whatever
// addrs are in the registry, regardless of who
// advertised. The caller here gets the callee's addr
// because the callee did advertise.
assert_eq!(peer_direct_addr.as_deref(), Some("198.51.100.9:4433"));
}
_ => panic!("wrong variant"),
}
// The callee's setup has no caller addr (pre-Phase-3 offer).
match setup_callee {
SignalMessage::CallSetup { peer_direct_addr, .. } => {
assert!(
peer_direct_addr.is_none(),
"callee should see no caller addr when offer was pre-Phase-3"
);
}
_ => panic!("wrong variant"),
}
}
// -----------------------------------------------------------------------
// Test 4: neither side advertises — both CallSetups fall back cleanly
// -----------------------------------------------------------------------
#[test]
fn neither_peer_advertises_both_setups_are_relay_only() {
let mut reg = CallRegistry::new();
handle_offer(&mut reg, &mk_offer("c4", None));
let answer = mk_answer("c4", CallAcceptMode::AcceptTrusted, None);
let (setup_caller, setup_callee) =
handle_answer_and_build_setups(&mut reg, &answer);
for (label, setup) in [("caller", setup_caller), ("callee", setup_callee)] {
match setup {
SignalMessage::CallSetup { peer_direct_addr, relay_addr, .. } => {
assert!(
peer_direct_addr.is_none(),
"{label}'s CallSetup must have no peer_direct_addr"
);
// Relay addr is always filled — that's the fallback
// path and the existing behavior.
assert!(!relay_addr.is_empty(), "{label} relay_addr must be set");
}
_ => panic!("wrong variant"),
}
}
}

231
crates/wzp-relay/tests/multi_reflect.rs
View File

@@ -1,231 +0,0 @@
//! Phase 2 integration tests for multi-relay NAT reflection
//! (PRD: .taskmaster/docs/prd_multi_relay_reflect.txt).
//!
//! These spin up one or two mock relays that implement the full
//! pre-reflect dance — RegisterPresence → RegisterPresenceAck →
//! Reflect → ReflectResponse — which is what the transient
//! probe helper in `wzp_client::reflect::probe_reflect_addr` does
//! against a real relay.
//!
//! Test matrix:
//! 1. `probe_reflect_addr_happy_path`
//! — single mock relay, assert the probe helper returns the
//! observed addr as 127.0.0.1:<client ephemeral port>
//! 2. `detect_nat_type_two_loopback_relays_is_cone`
//! — two mock relays, one client; loopback single-host means
//! every probe sees the same (127.0.0.1, same_port) so the
//! classifier returns `Cone` + a consensus addr
//! 3. `detect_nat_type_dead_relay_is_unknown`
//! — one alive relay + one dead address; aggregator returns
//! `Unknown` with a non-empty `error` field on the failed
//! probe
use std::net::{Ipv4Addr, SocketAddr};
use std::sync::Arc;
use std::time::Duration;
use wzp_client::reflect::{detect_nat_type, probe_reflect_addr, NatType};
use wzp_proto::{MediaTransport, SignalMessage};
use wzp_transport::{create_endpoint, server_config, QuinnTransport};
/// Minimal mock relay that loops accepting connections, handles
/// RegisterPresence + Reflect, and responds correctly. Mirrors the
/// two match arms from `wzp-relay/src/main.rs` that matter here.
///
/// Each accepted connection gets its own inner task so multiple
/// simultaneous probes work.
async fn spawn_mock_relay() -> (SocketAddr, tokio::task::JoinHandle<()>) {
let _ = rustls::crypto::ring::default_provider().install_default();
let (sc, _cert_der) = server_config();
let bind: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let endpoint = create_endpoint(bind, Some(sc)).expect("server endpoint");
let listen_addr = endpoint.local_addr().expect("local_addr");
let handle = tokio::spawn(async move {
loop {
// Accept the next incoming connection. `wzp_transport::accept`
// returns the established `quinn::Connection`.
let conn = match wzp_transport::accept(&endpoint).await {
Ok(c) => c,
Err(_) => break, // endpoint closed
};
let observed_addr = conn.remote_address();
let transport = Arc::new(QuinnTransport::new(conn));
// Per-connection handler. Keep servicing messages until
// the peer closes so one probe connection can do
// RegisterPresence → Ack → Reflect → Response without
// racing other incoming connections.
let t = transport;
tokio::spawn(async move {
loop {
match t.recv_signal().await {
Ok(Some(SignalMessage::RegisterPresence { .. })) => {
let _ = t
.send_signal(&SignalMessage::RegisterPresenceAck {
success: true,
error: None,
relay_build: None,
relay_region: None,
available_relays: Vec::new(),
})
.await;
}
Ok(Some(SignalMessage::Reflect)) => {
let _ = t
.send_signal(&SignalMessage::ReflectResponse {
observed_addr: observed_addr.to_string(),
})
.await;
}
Ok(Some(_other)) => { /* ignore */ }
Ok(None) => break,
Err(_) => break,
}
}
});
}
});
(listen_addr, handle)
}
// -----------------------------------------------------------------------
// Test 1: probe_reflect_addr against a single mock relay
// -----------------------------------------------------------------------
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn probe_reflect_addr_happy_path() {
let (relay_addr, _relay_handle) = spawn_mock_relay().await;
let (observed, latency_ms) = tokio::time::timeout(
Duration::from_secs(3),
probe_reflect_addr(relay_addr, 2000, None),
)
.await
.expect("probe must complete within 3s")
.expect("probe must succeed");
assert_eq!(
observed.ip().to_string(),
"127.0.0.1",
"loopback test should see 127.0.0.1"
);
assert_ne!(observed.port(), 0, "observed port must be non-zero");
// Latency on same host is dominated by the handshake — generously
// allow up to 2s (the timeout) rather than picking a tight number
// that would be flaky on busy CI runners.
assert!(latency_ms < 2000, "latency {latency_ms}ms too high");
}
// -----------------------------------------------------------------------
// Test 2: two loopback relays → probes succeed, classification is Unknown
// -----------------------------------------------------------------------
//
// With the private-IP filter added in the NAT classifier, loopback
// reflex addrs (127.0.0.1) are dropped before classification —
// they can't possibly indicate public-internet NAT state. So the
// test now asserts:
// - both probes succeed end-to-end (wire plumbing works)
// - both return 127.0.0.1 (same-host is visible)
// - the aggregated verdict is Unknown (no public probes)
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn detect_nat_type_two_loopback_relays_probes_work_but_classify_unknown() {
let (addr_a, _h_a) = spawn_mock_relay().await;
let (addr_b, _h_b) = spawn_mock_relay().await;
let detection = detect_nat_type(
vec![
("RelayA".into(), addr_a),
("RelayB".into(), addr_b),
],
2000,
None,
)
.await;
assert_eq!(detection.probes.len(), 2);
for p in &detection.probes {
assert!(
p.observed_addr.is_some(),
"probe {:?} failed: {:?}",
p.relay_name,
p.error
);
}
let observed_ips: Vec<String> = detection
.probes
.iter()
.map(|p| {
p.observed_addr
.as_ref()
.and_then(|s| s.parse::<SocketAddr>().ok())
.map(|a| a.ip().to_string())
.unwrap_or_default()
})
.collect();
assert_eq!(observed_ips[0], "127.0.0.1");
assert_eq!(observed_ips[1], "127.0.0.1");
// Classification: loopback probes are filtered out of the
// public-NAT classifier, so with 0 public probes the result
// is Unknown.
assert_eq!(
detection.nat_type,
NatType::Unknown,
"loopback-only probes must not contribute to public NAT classification"
);
assert!(detection.consensus_addr.is_none());
}
// -----------------------------------------------------------------------
// Test 3: one alive relay + one dead address → Unknown
// -----------------------------------------------------------------------
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn detect_nat_type_dead_relay_is_unknown() {
let (alive_addr, _alive_handle) = spawn_mock_relay().await;
// Dead relay: a port that nothing is listening on. OS will drop
// the packets, the probe should time out within the 600ms budget
// we give it. Pick a port unlikely to be in use — port 1 on
// loopback works on every OS I care about and fails fast.
let dead_addr: SocketAddr = "127.0.0.1:1".parse().unwrap();
let detection = detect_nat_type(
vec![
("Alive".into(), alive_addr),
("Dead".into(), dead_addr),
],
600, // tight timeout so the dead probe fails fast
None,
)
.await;
assert_eq!(detection.probes.len(), 2);
// Find the alive and dead probes by name (order of JoinSet
// completions is not guaranteed).
let alive = detection.probes.iter().find(|p| p.relay_name == "Alive").unwrap();
let dead = detection.probes.iter().find(|p| p.relay_name == "Dead").unwrap();
assert!(
alive.observed_addr.is_some(),
"alive probe must succeed: {:?}",
alive.error
);
assert!(
dead.observed_addr.is_none(),
"dead probe must fail, got addr {:?}",
dead.observed_addr
);
assert!(
dead.error.is_some(),
"dead probe must surface an error string"
);
// With only 1 successful probe, the classifier returns Unknown.
assert_eq!(detection.nat_type, NatType::Unknown);
assert!(detection.consensus_addr.is_none());
}

318
crates/wzp-relay/tests/reflect.rs
View File

@@ -1,318 +0,0 @@
//! Integration tests for the "STUN for QUIC" reflect protocol
//! (PRD: .taskmaster/docs/prd_reflect_over_quic.txt, Phase 1).
//!
//! We don't spin up the full relay binary — instead we exercise the
//! same wire-level request/response dance with a mock relay loop
//! that implements exactly the match arm added to
//! `wzp-relay/src/main.rs`. This isolates the protocol test from the
//! rest of the relay state (rooms, federation, call registry, ...).
//!
//! Three test cases:
//! 1. `reflect_happy_path` — client sends `Reflect`, mock relay
//! replies with `ReflectResponse { observed_addr }`, client
//! parses it back to a `SocketAddr` and confirms the IP is
//! `127.0.0.1` and the port matches its own bound port.
//! 2. `reflect_two_clients_distinct_ports` — two simultaneous
//! client connections on different ephemeral ports get back
//! different reflected ports, proving the relay uses
//! per-connection `remote_address` rather than a global.
//! 3. `reflect_old_relay_times_out` — mock relay that *doesn't*
//! handle `Reflect`; client side times out in the expected
//! window and does not hang.
//!
//! The third test uses a `tokio::time::timeout` wrapper directly
//! (the client-side `request_reflect` helper lives in
//! `desktop/src-tauri/src/lib.rs` which isn't a library we can
//! depend on from here, so we reproduce the timeout semantics
//! inline).
use std::net::{Ipv4Addr, SocketAddr};
use std::sync::Arc;
use std::time::Duration;
use wzp_proto::{MediaTransport, SignalMessage};
use wzp_transport::{client_config, create_endpoint, server_config, QuinnTransport};
/// Spawn a minimal mock relay that loops over `recv_signal`,
/// matches on `Reflect`, and responds with `ReflectResponse` using
/// the remote_address observed for this connection. Mirrors the
/// match arm in `crates/wzp-relay/src/main.rs`.
async fn spawn_mock_relay_with_reflect(
server_transport: Arc<QuinnTransport>,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
// Observed remote address at the time the connection was
// accepted. Stable for the life of the connection under quinn's
// normal operation. This is exactly what the real relay does.
let observed = server_transport.connection().remote_address();
loop {
match server_transport.recv_signal().await {
Ok(Some(SignalMessage::Reflect)) => {
let resp = SignalMessage::ReflectResponse {
observed_addr: observed.to_string(),
};
// If the send fails the client has gone; just exit.
if server_transport.send_signal(&resp).await.is_err() {
break;
}
}
Ok(Some(_other)) => {
// Ignore anything else — not relevant to this test.
}
Ok(None) => break,
Err(_e) => break,
}
}
})
}
/// Spawn a mock relay that intentionally DOES NOT handle Reflect.
/// Models a pre-Phase-1 relay — it keeps reading signal messages and
/// logs them to stderr, but never produces a `ReflectResponse`.
async fn spawn_mock_relay_without_reflect(
server_transport: Arc<QuinnTransport>,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
loop {
match server_transport.recv_signal().await {
Ok(Some(_msg)) => {
// Deliberately do nothing. Old relay.
}
Ok(None) => break,
Err(_) => break,
}
}
})
}
/// Build an in-process QUIC client/server pair on loopback and
/// return (client_transport, server_transport, endpoints). The
/// endpoints tuple must be kept alive for the test duration.
///
/// `client_port_hint` of 0 means "let OS pick". Pass an explicit
/// port to pin the client's source port (useful for the
/// distinct-ports test).
async fn connected_pair_with_port(
_client_port_hint: u16,
) -> (Arc<QuinnTransport>, Arc<QuinnTransport>, (quinn::Endpoint, quinn::Endpoint)) {
let _ = rustls::crypto::ring::default_provider().install_default();
let (sc, _cert_der) = server_config();
let server_addr: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let server_ep = create_endpoint(server_addr, Some(sc)).expect("server endpoint");
let server_listen = server_ep.local_addr().expect("server local addr");
// Always bind the client to an ephemeral port — we'll read back
// the actual assigned port via `local_addr()` in the assertions.
let client_bind: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let client_ep = create_endpoint(client_bind, None).expect("client endpoint");
let server_ep_clone = server_ep.clone();
let accept_fut = tokio::spawn(async move {
let conn = wzp_transport::accept(&server_ep_clone).await.expect("accept");
Arc::new(QuinnTransport::new(conn))
});
let client_conn =
wzp_transport::connect(&client_ep, server_listen, "localhost", client_config())
.await
.expect("connect");
let client_transport = Arc::new(QuinnTransport::new(client_conn));
let server_transport = accept_fut.await.expect("join accept task");
(client_transport, server_transport, (server_ep, client_ep))
}
// -----------------------------------------------------------------------
// Test 1: happy path — client learns its own port via Reflect
// -----------------------------------------------------------------------
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn reflect_happy_path() {
let (client_transport, server_transport, (_server_ep, client_ep)) =
connected_pair_with_port(0).await;
// Grab the client's actual bound port so we can cross-check
// against the reflected response.
let client_port = client_ep
.local_addr()
.expect("client local addr")
.port();
assert_ne!(client_port, 0, "client must have a real bound port");
// Start the mock relay's reflect handler.
let _relay_handle = spawn_mock_relay_with_reflect(Arc::clone(&server_transport)).await;
// Client sends Reflect and awaits the response. The real
// request_reflect helper in desktop/src-tauri/src/lib.rs uses a
// oneshot channel driven off the spawned recv loop; here we just
// do it inline because there's no spawned loop yet in this test
// — this isolates the wire protocol from the client-side state
// machine.
client_transport
.send_signal(&SignalMessage::Reflect)
.await
.expect("send Reflect");
let resp = tokio::time::timeout(Duration::from_secs(2), client_transport.recv_signal())
.await
.expect("reflect response should arrive within 2s")
.expect("recv_signal ok")
.expect("some message");
let observed_addr = match resp {
SignalMessage::ReflectResponse { observed_addr } => observed_addr,
other => panic!("expected ReflectResponse, got {:?}", std::mem::discriminant(&other)),
};
let parsed: SocketAddr = observed_addr
.parse()
.expect("ReflectResponse.observed_addr must parse as SocketAddr");
// The relay should see the client on 127.0.0.1 (loopback in the
// test harness) and on the client's bound ephemeral port.
assert_eq!(parsed.ip().to_string(), "127.0.0.1");
assert_eq!(
parsed.port(),
client_port,
"reflected port must match the client's local_addr port"
);
drop(client_transport);
drop(server_transport);
}
// -----------------------------------------------------------------------
// Test 2: two clients get DIFFERENT reflected ports
// -----------------------------------------------------------------------
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn reflect_two_clients_distinct_ports() {
let _ = rustls::crypto::ring::default_provider().install_default();
// Shared server: one endpoint, two incoming accepts.
let (sc, _cert_der) = server_config();
let server_addr: SocketAddr = (Ipv4Addr::LOCALHOST, 0).into();
let server_ep = create_endpoint(server_addr, Some(sc)).expect("server endpoint");
let server_listen = server_ep.local_addr().expect("server local addr");
// Accept two clients in parallel.
let server_ep_a = server_ep.clone();
let accept_a = tokio::spawn(async move {
let conn = wzp_transport::accept(&server_ep_a).await.expect("accept A");
Arc::new(QuinnTransport::new(conn))
});
let server_ep_b = server_ep.clone();
let accept_b = tokio::spawn(async move {
let conn = wzp_transport::accept(&server_ep_b).await.expect("accept B");
Arc::new(QuinnTransport::new(conn))
});
// Client A
let client_ep_a = create_endpoint((Ipv4Addr::LOCALHOST, 0).into(), None).expect("ep A");
let conn_a =
wzp_transport::connect(&client_ep_a, server_listen, "localhost", client_config())
.await
.expect("connect A");
let client_a = Arc::new(QuinnTransport::new(conn_a));
let port_a = client_ep_a.local_addr().unwrap().port();
// Client B
let client_ep_b = create_endpoint((Ipv4Addr::LOCALHOST, 0).into(), None).expect("ep B");
let conn_b =
wzp_transport::connect(&client_ep_b, server_listen, "localhost", client_config())
.await
.expect("connect B");
let client_b = Arc::new(QuinnTransport::new(conn_b));
let port_b = client_ep_b.local_addr().unwrap().port();
assert_ne!(
port_a, port_b,
"preconditions: OS must assign two clients different ephemeral ports"
);
let server_a = accept_a.await.expect("join A");
let server_b = accept_b.await.expect("join B");
// Spawn a reflect handler for each server-side transport.
let _relay_a = spawn_mock_relay_with_reflect(Arc::clone(&server_a)).await;
let _relay_b = spawn_mock_relay_with_reflect(Arc::clone(&server_b)).await;
// Each client requests reflect concurrently.
let reflect_for = |t: Arc<QuinnTransport>| async move {
t.send_signal(&SignalMessage::Reflect).await.expect("send");
let resp = tokio::time::timeout(Duration::from_secs(2), t.recv_signal())
.await
.expect("timeout")
.expect("ok")
.expect("some");
match resp {
SignalMessage::ReflectResponse { observed_addr } => observed_addr,
_ => panic!("wrong variant"),
}
};
let (addr_a, addr_b) = tokio::join!(reflect_for(client_a.clone()), reflect_for(client_b.clone()));
let parsed_a: SocketAddr = addr_a.parse().unwrap();
let parsed_b: SocketAddr = addr_b.parse().unwrap();
assert_eq!(parsed_a.port(), port_a, "client A's reflected port");
assert_eq!(parsed_b.port(), port_b, "client B's reflected port");
assert_ne!(
parsed_a.port(),
parsed_b.port(),
"each client must see its own port, not a shared one"
);
drop(client_a);
drop(client_b);
drop(server_a);
drop(server_b);
}
// -----------------------------------------------------------------------
// Test 3: old relay never answers — client times out cleanly
// -----------------------------------------------------------------------
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn reflect_old_relay_times_out() {
let (client_transport, server_transport, _endpoints) =
connected_pair_with_port(0).await;
// Mock relay that ignores Reflect — simulates a pre-Phase-1 build.
let _relay_handle =
spawn_mock_relay_without_reflect(Arc::clone(&server_transport)).await;
client_transport
.send_signal(&SignalMessage::Reflect)
.await
.expect("send Reflect");
// 1100ms ceiling matches the 1s timeout baked into
// get_reflected_address plus a tiny bit of slack. If this
// regression ever fires it probably means recv_signal blocked
// longer than expected and the Tauri command would hang the UI.
let start = std::time::Instant::now();
let result =
tokio::time::timeout(Duration::from_millis(1100), client_transport.recv_signal()).await;
let elapsed = start.elapsed();
assert!(
result.is_err(),
"recv_signal must time out when the relay ignores Reflect"
);
assert!(
elapsed >= Duration::from_millis(1000),
"timeout fired too early ({:?})",
elapsed
);
assert!(
elapsed < Duration::from_millis(1200),
"timeout fired too late ({:?}), client would feel unresponsive",
elapsed
);
drop(client_transport);
drop(server_transport);
}

4
crates/wzp-transport/Cargo.toml
View File

@@ -15,11 +15,7 @@ tracing = { workspace = true }
async-trait = { workspace = true }
serde_json = "1"
rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
socket2 = { workspace = true }
rcgen = "0.13"
ed25519-dalek = { workspace = true }
hkdf = { workspace = true }
sha2 = { workspace = true }
[dev-dependencies]
tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }

87
crates/wzp-transport/src/config.rs
View File

@@ -6,74 +6,20 @@ use std::time::Duration;
use quinn::crypto::rustls::QuicClientConfig;
use quinn::crypto::rustls::QuicServerConfig;
/// Create a server configuration with a self-signed certificate (random keypair).
/// Create a server configuration with a self-signed certificate (for testing).
///
/// The certificate changes on every call. Use `server_config_from_seed` for
/// a deterministic certificate that survives relay restarts.
/// Tunes QUIC transport parameters for lossy VoIP:
/// - 30s idle timeout
/// - 5s keep-alive interval
/// - DATAGRAM extension enabled
/// - Conservative flow control for bandwidth-constrained links
pub fn server_config() -> (quinn::ServerConfig, Vec<u8>) {
let cert_key = rcgen::generate_simple_self_signed(vec!["localhost".to_string()])
.expect("failed to generate self-signed cert");
let cert_der = rustls::pki_types::CertificateDer::from(cert_key.cert);
let key_der =
rustls::pki_types::PrivateKeyDer::try_from(cert_key.key_pair.serialize_der()).unwrap();
build_server_config(cert_der, key_der)
}
/// Create a server configuration with a deterministic self-signed certificate
/// derived from a 32-byte seed. Same seed = same cert = same TLS fingerprint.
pub fn server_config_from_seed(seed: &[u8; 32]) -> (quinn::ServerConfig, Vec<u8>) {
use ed25519_dalek::pkcs8::EncodePrivateKey;
use ed25519_dalek::SigningKey;
use hkdf::Hkdf;
use sha2::Sha256;
// Derive Ed25519 key bytes from seed via HKDF
let hk = Hkdf::<Sha256>::new(None, seed);
let mut ed_bytes = [0u8; 32];
hk.expand(b"wzp-tls-ed25519", &mut ed_bytes)
.expect("HKDF expand failed");
// Create Ed25519 signing key and export as PKCS8 DER
let signing_key = SigningKey::from_bytes(&ed_bytes);
let pkcs8_doc = signing_key.to_pkcs8_der()
.expect("failed to encode Ed25519 key as PKCS8");
let key_der_for_rcgen = rustls::pki_types::PrivateKeyDer::try_from(pkcs8_doc.as_bytes().to_vec())
.expect("failed to wrap PKCS8 DER");
// Create rcgen KeyPair from DER
let key_pair = rcgen::KeyPair::from_der_and_sign_algo(
&key_der_for_rcgen,
&rcgen::PKCS_ED25519,
)
.expect("failed to create KeyPair from seed-derived Ed25519 key");
// Build self-signed cert with this deterministic keypair
let params = rcgen::CertificateParams::new(vec!["localhost".to_string()])
.expect("failed to create CertificateParams");
let cert = params.self_signed(&key_pair).expect("failed to self-sign cert");
let cert_der = rustls::pki_types::CertificateDer::from(cert.der().to_vec());
let key_der = rustls::pki_types::PrivateKeyDer::try_from(key_pair.serialize_der())
.expect("failed to serialize key DER");
build_server_config(cert_der, key_der)
}
/// Compute a hex-formatted SHA-256 fingerprint of a DER-encoded certificate.
///
/// Format: `xx:xx:xx:xx:...` (32 bytes = 64 hex chars with colons).
pub fn tls_fingerprint(cert_der: &[u8]) -> String {
use sha2::{Sha256, Digest};
let hash = Sha256::digest(cert_der);
hash.iter()
.map(|b| format!("{b:02x}"))
.collect::<Vec<_>>()
.join(":")
}
fn build_server_config(
cert_der: rustls::pki_types::CertificateDer<'static>,
key_der: rustls::pki_types::PrivateKeyDer<'static>,
) -> (quinn::ServerConfig, Vec<u8>) {
let mut server_crypto = rustls::ServerConfig::builder()
.with_no_client_auth()
.with_single_cert(vec![cert_der.clone()], key_der)
@@ -123,6 +69,7 @@ fn transport_config() -> quinn::TransportConfig {
config.keep_alive_interval(Some(Duration::from_secs(5)));
// Enable DATAGRAM extension for unreliable media packets.
// Allow datagrams up to 1200 bytes (conservative for lossy links).
config.datagram_receive_buffer_size(Some(65536));
// Conservative flow control for bandwidth-constrained links
@@ -133,26 +80,6 @@ fn transport_config() -> quinn::TransportConfig {
// Aggressive initial RTT estimate for high-latency links
config.initial_rtt(Duration::from_millis(300));
// PMTUD (Path MTU Discovery) — quinn 0.11 enables this by default but
// with conservative bounds (initial 1200, upper 1452). We keep the safe
// initial_mtu of 1200 so the first packets always get through, but raise
// upper_bound so the binary search can discover larger MTUs on paths that
// support them. Typical results:
// - Ethernet/fiber: discovers ~1452 (Ethernet MTU minus IP/UDP/QUIC)
// - WireGuard/VPN: discovers ~1380-1420
// - Starlink: discovers ~1400-1452
// - Cellular: stays at 1200-1300
// Black hole detection automatically falls back to 1200 if probes fail.
// This matters for future video frames which can be 1-50 KB and benefit
// from fewer application-layer fragments per frame.
let mut mtu_config = quinn::MtuDiscoveryConfig::default();
mtu_config
.upper_bound(1452)
.interval(Duration::from_secs(300)) // re-probe every 5 min
.black_hole_cooldown(Duration::from_secs(30)); // retry faster on lossy links
config.mtu_discovery_config(Some(mtu_config));
config.initial_mtu(1200); // safe starting point
config
}

65
crates/wzp-transport/src/connection.rs
View File

@@ -39,71 +39,6 @@ pub async fn connect(
Ok(connection)
}
/// Create an IPv6-only QUIC endpoint with `IPV6_V6ONLY=1`.
///
/// Tries `[::]:preferred_port` first (same port as the IPv4 signal
/// endpoint — allowed on Linux/Android when the AFs differ and
/// V6ONLY is set). Falls back to `[::]:0` (OS-assigned) if the
/// preferred port is already taken.
///
/// Must be called from within a tokio runtime (quinn needs the
/// async runtime handle for its I/O driver).
pub fn create_ipv6_endpoint(
preferred_port: u16,
server_config: Option<quinn::ServerConfig>,
) -> Result<quinn::Endpoint, TransportError> {
use socket2::{Domain, Protocol, Socket, Type};
use std::net::{Ipv6Addr, SocketAddrV6};
let sock = Socket::new(Domain::IPV6, Type::DGRAM, Some(Protocol::UDP))
.map_err(|e| TransportError::Internal(format!("ipv6 socket: {e}")))?;
// Critical: IPv6-only so this socket never intercepts IPv4.
// On Android some kernels default to V6ONLY=1 anyway, but we
// set it explicitly for cross-platform consistency.
sock.set_only_v6(true)
.map_err(|e| TransportError::Internal(format!("set_only_v6: {e}")))?;
sock.set_reuse_address(true)
.map_err(|e| TransportError::Internal(format!("set_reuse_address: {e}")))?;
// Try the preferred port (same as IPv4 signal endpoint), fall
// back to ephemeral if the OS rejects it.
let bind_addr = SocketAddrV6::new(Ipv6Addr::UNSPECIFIED, preferred_port, 0, 0);
if let Err(e) = sock.bind(&bind_addr.into()) {
if preferred_port != 0 {
tracing::debug!(
preferred_port,
error = %e,
"ipv6 bind to preferred port failed, falling back to ephemeral"
);
let fallback = SocketAddrV6::new(Ipv6Addr::UNSPECIFIED, 0, 0, 0);
sock.bind(&fallback.into())
.map_err(|e| TransportError::Internal(format!("ipv6 bind fallback: {e}")))?;
} else {
return Err(TransportError::Internal(format!("ipv6 bind: {e}")));
}
}
sock.set_nonblocking(true)
.map_err(|e| TransportError::Internal(format!("set_nonblocking: {e}")))?;
let udp_socket: std::net::UdpSocket = sock.into();
let runtime = quinn::default_runtime()
.ok_or_else(|| TransportError::Internal("no async runtime for ipv6 endpoint".into()))?;
let endpoint = quinn::Endpoint::new(
quinn::EndpointConfig::default(),
server_config,
udp_socket,
runtime,
)
.map_err(|e| TransportError::Internal(format!("ipv6 endpoint: {e}")))?;
Ok(endpoint)
}
/// Accept the next incoming connection on an endpoint.
pub async fn accept(endpoint: &quinn::Endpoint) -> Result<quinn::Connection, TransportError> {
let incoming = endpoint

11
crates/wzp-transport/src/lib.rs
View File

@@ -22,13 +22,8 @@ pub mod path_monitor;
pub mod quic;
pub mod reliable;
pub use config::{client_config, server_config, server_config_from_seed, tls_fingerprint};
pub use connection::{accept, connect, create_endpoint, create_ipv6_endpoint};
pub use config::{client_config, server_config};
pub use connection::{accept, connect, create_endpoint};
pub use path_monitor::PathMonitor;
pub use quic::{QuinnPathSnapshot, QuinnTransport};
pub use quic::QuinnTransport;
pub use wzp_proto::{MediaTransport, PathQuality, TransportError};
// Re-export the quinn Endpoint type so downstream crates (wzp-desktop) can
// thread a shared endpoint between signaling and media connections without
// needing to depend on quinn directly.
pub use quinn::Endpoint;

29
crates/wzp-transport/src/path_monitor.rs
View File

@@ -2,17 +2,11 @@
//!
//! Tracks packet loss (via sequence number gaps), RTT, jitter, and bandwidth.
use std::collections::VecDeque;
use wzp_proto::PathQuality;
/// EWMA smoothing factor.
const ALPHA: f64 = 0.1;
/// Maximum number of RTT samples in the jitter variance sliding window.
/// At ~50 packets/sec (20 ms frame), 10 samples ≈ 200 ms.
const JITTER_VARIANCE_WINDOW_SIZE: usize = 10;
/// Monitors network path quality metrics.
pub struct PathMonitor {
/// EWMA-smoothed loss percentage (0.0 - 100.0).
@@ -37,8 +31,6 @@ pub struct PathMonitor {
last_rtt_ms: Option<f64>,
/// Whether we have any observations yet.
initialized: bool,
/// Sliding window of recent RTT samples for variance calculation.
rtt_window: VecDeque<f64>,
}
impl PathMonitor {
@@ -59,7 +51,6 @@ impl PathMonitor {
total_received: 0,
last_rtt_ms: None,
initialized: false,
rtt_window: VecDeque::with_capacity(JITTER_VARIANCE_WINDOW_SIZE),
}
}
@@ -131,12 +122,6 @@ impl PathMonitor {
} else {
self.rtt_ewma = ALPHA * rtt + (1.0 - ALPHA) * self.rtt_ewma;
}
// Maintain sliding window for variance calculation
if self.rtt_window.len() >= JITTER_VARIANCE_WINDOW_SIZE {
self.rtt_window.pop_front();
}
self.rtt_window.push_back(rtt);
}
/// Get the current estimated path quality.
@@ -170,20 +155,6 @@ impl PathMonitor {
0
}
/// Compute the jitter (RTT standard deviation) over the sliding window.
///
/// Returns the standard deviation in milliseconds, or 0.0 if insufficient
/// samples. Used by `DredTuner` for spike detection.
pub fn jitter_variance_ms(&self) -> f64 {
let n = self.rtt_window.len();
if n < 2 {
return 0.0;
}
let mean = self.rtt_window.iter().sum::<f64>() / n as f64;
let var = self.rtt_window.iter().map(|r| (r - mean).powi(2)).sum::<f64>() / n as f64;
var.sqrt()
}
/// Detect whether a network handoff likely occurred.
///
/// Returns `true` if the most recent RTT jitter measurement exceeds 3x

68
crates/wzp-transport/src/quic.rs
View File

@@ -13,29 +13,6 @@ use crate::datagram;
use crate::path_monitor::PathMonitor;
use crate::reliable;
/// Snapshot of quinn's QUIC-level path statistics.
///
/// Provides more accurate loss/RTT data than `PathMonitor`'s sequence-gap
/// heuristic because quinn sees ACK frames and congestion signals directly.
#[derive(Clone, Copy, Debug)]
pub struct QuinnPathSnapshot {
/// Smoothed RTT in milliseconds (from quinn's congestion controller).
pub rtt_ms: u32,
/// Cumulative loss percentage (lost_packets / sent_packets × 100).
pub loss_pct: f32,
/// Total congestion events observed by the QUIC stack.
pub congestion_events: u64,
/// Current congestion window in bytes.
pub cwnd: u64,
/// Total packets sent on this path.
pub sent_packets: u64,
/// Total packets lost on this path.
pub lost_packets: u64,
/// Current PMTUD-discovered maximum datagram payload size (bytes).
/// Starts at `initial_mtu` (1200) and grows as PMTUD probes succeed.
pub current_mtu: usize,
}
/// QUIC-based transport implementing the `MediaTransport` trait.
pub struct QuinnTransport {
connection: quinn::Connection,
@@ -56,18 +33,6 @@ impl QuinnTransport {
&self.connection
}
/// Remote address of the peer on this connection.
pub fn remote_address(&self) -> std::net::SocketAddr {
self.connection.remote_address()
}
/// Send raw bytes as a QUIC datagram (no MediaPacket framing).
pub fn send_raw_datagram(&self, data: &[u8]) -> Result<(), TransportError> {
self.connection
.send_datagram(bytes::Bytes::copy_from_slice(data))
.map_err(|e| TransportError::Internal(format!("datagram: {e}")))
}
/// Close the QUIC connection immediately (synchronous, no async needed).
/// The relay will detect the close and remove this participant from the room.
pub fn close_now(&self) {
@@ -89,31 +54,6 @@ impl QuinnTransport {
datagram::max_datagram_payload(&self.connection)
}
/// Snapshot of QUIC-level path stats from quinn, useful for DRED tuning.
///
/// Returns `(rtt_ms, loss_pct, congestion_events)` derived from quinn's
/// internal congestion controller — more accurate than our own sequence-gap
/// heuristic in `PathMonitor` because quinn sees ACK frames directly.
pub fn quinn_path_stats(&self) -> QuinnPathSnapshot {
let stats = self.connection.stats();
let rtt_ms = stats.path.rtt.as_millis() as u32;
let loss_pct = if stats.path.sent_packets > 0 {
(stats.path.lost_packets as f32 / stats.path.sent_packets as f32) * 100.0
} else {
0.0
};
let current_mtu = self.connection.max_datagram_size().unwrap_or(1200);
QuinnPathSnapshot {
rtt_ms,
loss_pct,
congestion_events: stats.path.congestion_events,
cwnd: stats.path.cwnd,
sent_packets: stats.path.sent_packets,
lost_packets: stats.path.lost_packets,
current_mtu,
}
}
/// Send an encoded [`TrunkFrame`] as a single QUIC datagram.
pub fn send_trunk(&self, frame: &TrunkFrame) -> Result<(), TransportError> {
let data = frame.encode();
@@ -196,7 +136,7 @@ impl MediaTransport for QuinnTransport {
}
};
match datagram::deserialize_media(data.clone()) {
match datagram::deserialize_media(data) {
Some(packet) => {
// Record receive observation
{
@@ -209,10 +149,8 @@ impl MediaTransport for QuinnTransport {
Ok(Some(packet))
}
None => {
tracing::warn!(len = data.len(), "skipping malformed media datagram, continuing");
// Don't return Ok(None) — that signals connection closed.
// Recurse to read the next datagram instead.
Box::pin(self.recv_media()).await
tracing::warn!("received malformed media datagram");
Ok(None)
}
}
}

11
crates/wzp-transport/src/reliable.rs
View File

@@ -53,13 +53,6 @@ pub async fn recv_signal(recv: &mut quinn::RecvStream) -> Result<SignalMessage,
.await
.map_err(|e| TransportError::Internal(format!("stream read payload error: {e}")))?;
serde_json::from_slice(&payload).map_err(|e| {
// Distinguish serde failures from transport failures so the
// caller (relay main loop, client recv loop) can continue on
// unknown-variant / parse errors instead of tearing down the
// whole signal connection. Forward-compat: adding a new
// `SignalMessage` variant in one side must not break the
// other side's signal connection.
TransportError::Deserialize(format!("{e}"))
})
serde_json::from_slice(&payload)
.map_err(|e| TransportError::Internal(format!("signal deserialize error: {e}")))
}

115
debug/INCIDENT-2026-04-06-art-gc-sigbus.md
View File

@@ -1,115 +0,0 @@
# Incident Report: SIGBUS in ART GC During Audio Thread JNI Calls
**Date:** 2026-04-06
**Severity:** High — app crash (SIGBUS) mid-call
**Status:** Root-caused, fix proposed
**Affects:** Android 16 (API 36) devices with concurrent mark-compact GC
## Summary
The app crashes with SIGBUS (signal 7, BUS_ADRERR) during an active call. The crash occurs in ART's garbage collector or JIT compiler, NOT in our Rust native code or AudioRing buffer. Both `wzp-capture` and `wzp-playout` Kotlin threads are affected.
## Crash Details
### Crash 1: wzp-capture (18:42, after 476s of call)
```
Fatal signal 7 (SIGBUS), code 2 (BUS_ADRERR), fault addr 0x720009be38
tid 19697 (wzp-capture), pid 17885 (com.wzp.phone)
```
**Backtrace:**
```
#00 art::StackVisitor::WalkStack
#01 art::Thread::VisitRoots
#02 art::gc::collector::MarkCompact::ThreadFlipVisitor::Run
#03 art::Thread::EnsureFlipFunctionStarted
#04 CheckJNI::ReleasePrimitiveArrayElements ← JNI boundary
#05 android_media_AudioRecord_readInArray ← AudioRecord.read()
#09 com.wzp.audio.AudioPipeline.runCapture
```
**Root cause:** ART's concurrent mark-compact GC (`MarkCompact::ThreadFlipVisitor`) is flipping thread roots while the capture thread is in the middle of a JNI call (`AudioRecord.read()`). The GC's `EnsureFlipFunctionStarted` triggers a stack walk that hits an invalid address.
### Crash 2: wzp-playout (19:17, mid-call)
```
Fatal signal 7 (SIGBUS), code 2 (BUS_ADRERR), fault addr 0x225eb98
tid 32574 (wzp-playout), pid 32479 (com.wzp.phone)
```
**Backtrace:**
```
#00 com.wzp.audio.AudioPipeline.runPlayout ← JIT-compiled code
#01 art_quick_osr_stub ← On-Stack Replacement
#02 art::jit::Jit::MaybeDoOnStackReplacement
#03-#04 art::interpreter::ExecuteSwitchImplCpp
```
**Root cause:** ART's JIT compiler performed On-Stack Replacement (OSR) on the hot playout loop. The OSR stub references a code address (`0x225eb98`) that is no longer valid — likely because the GC moved the compiled code in memory during concurrent compaction.
## Why This Happens
Android 16 introduced a new **concurrent mark-compact GC** (CMC) that moves objects in memory while other threads are running. This is safe for normal Java code because ART uses read barriers. But our audio threads have specific properties that stress this:
1. **`Thread.MAX_PRIORITY`** — audio threads run at the highest priority, starving the GC thread of CPU time. The GC may not complete its thread-flip before the audio thread resumes.
2. **Tight JNI loops** — `runCapture()` and `runPlayout()` loop every 20ms calling `AudioRecord.read()` / `AudioTrack.write()` via JNI. Each JNI transition is a GC safepoint, but the thread spends most of its time in native code where the GC can't flip it.
3. **Long-running JIT-compiled code** — the hot loop gets JIT-compiled and may undergo OSR. If the GC compacts memory while OSR is in progress, the stub can reference stale addresses.
4. **Daemon threads that never exit** — our threads are parked with `Thread.sleep(Long.MAX_VALUE)` after the call ends (to avoid the libcrypto TLS destructor crash). These zombie threads accumulate GC root scan work.
## Evidence This Is Not Our Bug
| Component | Evidence |
|-----------|---------|
| **AudioRing** | Not in any backtrace. All crash frames are in `libart.so` (ART runtime) |
| **Rust native code** | `libwzp_android.so` not in any crash frame |
| **JNI bridge** | Crash happens during `ReleasePrimitiveArrayElements` (ART internal), not during our JNI calls |
| **Timing** | Crashes after 476s and mid-call — not during init or teardown |
## Proposed Fix
### Option A: Disable concurrent GC compaction for audio threads (recommended)
Use `dalvik.vm.gctype` or per-thread GC pinning to prevent the mark-compact collector from moving objects referenced by audio threads.
**Not directly controllable from app code.** But we can reduce GC pressure:
### Option B: Reduce JNI transitions in audio threads
Instead of calling `engine.writeAudio(pcm)` / `engine.readAudio(pcm)` via JNI on every 20ms frame, batch multiple frames or use `DirectByteBuffer` to share memory without JNI array copies.
**Implementation:**
- Allocate a `DirectByteBuffer` in Kotlin, share the pointer with Rust via JNI
- Audio threads write/read directly to the buffer (no JNI call per frame)
- Rust reads/writes from the same memory region
- Reduces JNI transitions from 100/sec to 0/sec per audio direction
### Option C: Use Android's Oboe (AAudio) natively from Rust
Skip the Kotlin AudioRecord/AudioTrack entirely. Use Oboe (which we already have as a dependency in `wzp-android/Cargo.toml`) to create native audio streams directly from Rust. The audio callbacks run in native code with no JNI, no GC interaction, no ART.
This is how the project was originally designed (see `audio_android.rs` with Oboe references) before switching to Kotlin AudioRecord for simplicity.
**Pros:** Eliminates the entire JNI audio path. No GC interaction. Lower latency.
**Cons:** Requires rewriting `AudioPipeline.kt` into Rust. Oboe setup is more complex.
### Option D: Pin audio thread objects to prevent GC movement
Use JNI `GetPrimitiveArrayCritical` instead of `GetShortArrayRegion` to pin the array in memory during the operation. This prevents the GC from moving the array while we're using it.
**Implementation:** Change `nativeWriteAudio` / `nativeReadAudio` JNI functions to use critical sections.
### Recommendation
**Short term: Option B** (DirectByteBuffer) — reduces JNI transitions without major refactoring.
**Long term: Option C** (Oboe from Rust) — eliminates the problem entirely. This is the architecturally correct solution and matches the original design intent.
## Data Files
- Logcat from Nothing A059 (Android 16, API 36)
- Two crashes in the same session: 18:42 (capture, after 476s) and 19:17 (playout)
- Both SIGBUS/BUS_ADRERR, both in ART internal frames

175
debug/INCIDENT-2026-04-06-capture-thread-use-after-free.md
View File

@@ -1,175 +0,0 @@
# Incident Report: Native Crash in Capture Thread — Use-After-Free on Engine Handle
**Date:** 2026-04-06
**Severity:** Critical — app crash (SIGSEGV) on call hangup
**Status:** Root-caused, fix pending
**Affects:** Android client only
## Summary
The app crashes with a native SIGSEGV during or shortly after call hangup. The crash occurs in JIT-compiled code inside `AudioPipeline.runCapture()`. The root cause is a use-after-free: the capture thread calls `engine.writeAudio()` via JNI after the engine's native handle has been freed by `teardown()` on the ViewModel thread.
## Crash Stacktrace
```
04-06 13:05:42.707 F DEBUG: #09 pc 000000000250696c /memfd:jit-cache (deleted) (com.wzp.audio.AudioPipeline.runCapture+3228)
04-06 13:05:42.707 F DEBUG: #14 pc 0000000000005270 <anonymous:730900d000> (com.wzp.audio.AudioPipeline.start$lambda$0+0)
04-06 13:05:42.708 F DEBUG: #19 pc 00000000000044cc <anonymous:730900d000> (com.wzp.audio.AudioPipeline.$r8$lambda$0rYcivupwvyN4SgBXhsroKmTlo8+0)
04-06 13:05:42.708 F DEBUG: #24 pc 00000000000042e4 <anonymous:730900d000> (com.wzp.audio.AudioPipeline$$ExternalSyntheticLambda0.run+0)
```
This is a tombstone (signal crash), not a Java exception. The `F DEBUG` tag indicates a native crash handler (debuggerd) captured the signal.
## Root Cause
### The Race Condition
Two threads operate on the engine concurrently without synchronization:
**Thread 1: `wzp-capture` (AudioRecord thread, MAX_PRIORITY)**
```kotlin
// AudioPipeline.runCapture() — runs in a tight loop
while (running) {
val read = recorder.read(pcm, 0, FRAME_SAMPLES)
if (read > 0) {
engine.writeAudio(pcm) // <-- JNI call to native engine
}
}
```
**Thread 2: ViewModel/UI thread (normal priority)**
```kotlin
// CallViewModel.teardown()
stopAudio() // sets AudioPipeline.running = false
engine?.stopCall() // tells Rust to stop
engine?.destroy() // frees native memory, sets nativeHandle = 0L
engine = null
```
### The Kotlin Guard is Insufficient
`WzpEngine.writeAudio()` has a guard:
```kotlin
fun writeAudio(pcm: ShortArray): Int {
if (nativeHandle == 0L) return 0 // check
return nativeWriteAudio(nativeHandle, pcm) // use
}
```
This is a **TOCTOU (time-of-check/time-of-use) race**:
1. Capture thread checks `nativeHandle != 0L` → true
2. ViewModel thread calls `destroy()`, which calls `nativeDestroy(handle)` then sets `nativeHandle = 0L`
3. Capture thread calls `nativeWriteAudio(handle, pcm)` with the now-freed handle
4. The JNI function dereferences `handle` as a pointer → **SIGSEGV**
The same race exists for `readAudio()` on the `wzp-playout` thread.
### Why `stopAudio()` Doesn't Prevent This
`AudioPipeline.stop()` sets `running = false` but does **NOT join or wait** for the threads:
```kotlin
fun stop() {
running = false
// Don't join — threads are parked as daemons to avoid native TLS crash
captureThread = null
playoutThread = null
}
```
The threads are intentionally not joined because of a separate bug: exiting a JNI-calling thread triggers a `SIGSEGV in OPENSSL_free` due to libcrypto TLS destructors on Android. The threads instead "park" with `Thread.sleep(Long.MAX_VALUE)` after the loop exits.
But the problem is the **window between `running = false` and the thread actually checking it**. The capture thread may be blocked in `recorder.read()` (which blocks for 20ms per frame) or in the middle of `engine.writeAudio()` when `destroy()` is called.
### Timeline of the Crash
```
T=0ms ViewModel: stopAudio() → sets running=false
T=0ms ViewModel: stopStatsPolling()
T=0ms ViewModel: engine.stopCall() — Rust stops internal tasks
T=1ms ViewModel: engine.destroy() — frees native memory
↑ nativeHandle = 0L
T=0-20ms Capture thread: still in recorder.read() or writeAudio()
→ if in writeAudio(), the nativeHandle check passed BEFORE destroy()
→ JNI dereferences freed pointer → SIGSEGV
```
## Affected Code
### Files with the race
| File | Line(s) | Issue |
|------|---------|-------|
| `android/.../WzpEngine.kt` | 107-108, 116-117 | TOCTOU on `nativeHandle` in `writeAudio()` / `readAudio()` |
| `android/.../CallViewModel.kt` | 257-262 | `stopAudio()` + `destroy()` without waiting for audio threads to quiesce |
| `android/.../AudioPipeline.kt` | 80-82 | `stop()` doesn't synchronize with running threads |
### Files with the thread parking workaround
| File | Line(s) | Context |
|------|---------|---------|
| `android/.../AudioPipeline.kt` | 57-58, 69-70 | Threads parked after loop exit to avoid libcrypto TLS crash |
| `android/.../AudioPipeline.kt` | 96-101 | `parkThread()` — `Thread.sleep(Long.MAX_VALUE)` |
## Constraints for the Fix
1. **Cannot join audio threads** — joining triggers a separate SIGSEGV in `OPENSSL_free` when the thread's TLS destructors fire (documented in `AudioPipeline.kt` comments). The parking workaround must be preserved.
2. **Must guarantee no JNI calls after `destroy()`** — the native handle is a raw pointer; any dereference after free is undefined behavior.
3. **Must not add blocking waits on the UI thread** — `teardown()` runs on the ViewModel thread which must remain responsive.
4. **The `@Volatile running` flag is necessary but not sufficient** — it prevents new loop iterations but doesn't help with in-flight JNI calls.
5. **Both `writeAudio` and `readAudio` have the same race** — the fix must cover both the capture and playout paths.
## Reproduction
The crash is timing-dependent. It's most likely to occur when:
- The capture thread is in the middle of a `writeAudio()` JNI call when `destroy()` is called
- More likely on slower devices or under CPU pressure (GC, thermal throttling)
- Can happen on every hangup, but only crashes ~10-30% of the time due to the timing window
## Analysis of Possible Fix Approaches
### Approach A: Add a synchronization gate in the JNI bridge
Use a `ReentrantReadWriteLock` or `AtomicBoolean` in `WzpEngine.kt`:
- Audio threads acquire a read lock / check the flag before JNI calls
- `destroy()` acquires a write lock / sets the flag and waits for in-flight calls to drain
**Pro:** Clean, solves the race directly.
**Con:** Adding a lock to the audio hot path (every 20ms). `ReentrantReadWriteLock` is not lock-free. However, the read-lock path is uncontended 99.99% of the time (write-lock only during destroy), so contention is negligible.
### Approach B: Defer `destroy()` until audio threads have stopped
Instead of calling `destroy()` in `teardown()`, set a flag and have the audio threads call `destroy()` after they exit the loop (before parking).
**Pro:** No locks on hot path.
**Con:** Complex lifecycle — which thread calls destroy? What if both threads race to destroy? Need a `CountDownLatch` or similar.
### Approach C: Make the JNI handle atomically invalidated
Use `AtomicLong` for `nativeHandle` and use `compareAndExchange` in `destroy()` + `getAndCheck` pattern in audio calls.
**Pro:** Lock-free.
**Con:** Still has a TOCTOU window — the thread can load the handle, then it gets CAS'd to 0, then the thread uses the stale handle. Doesn't fully solve the race without combining with a reference count or epoch.
### Approach D: Introduce a destroy latch
Add a `CountDownLatch(1)` that audio threads wait on before parking. `teardown()` sets `running=false`, then `await`s the latch (with timeout), then calls `destroy()`. Each audio thread counts down the latch after exiting the loop.
Actually this needs a `CountDownLatch(2)` — one for each thread (capture + playout).
**Pro:** Guarantees no in-flight JNI calls at destroy time. No locks on hot path.
**Con:** `teardown()` blocks for up to one frame duration (~20ms) waiting for threads to exit their loops. Acceptable for a hangup path.
### Recommendation
**Approach D (destroy latch)** is the cleanest. The 20ms worst-case wait is imperceptible on the hangup path, and it provides a hard guarantee that no JNI calls are in flight when `destroy()` runs. Combined with the existing `running` volatile flag, the audio threads exit their loops within one frame and count down the latch.
If the latch times out (e.g., AudioRecord.read() is stuck), `destroy()` proceeds anyway — the `panic::catch_unwind` in the JNI bridge will catch the invalid access as a panic rather than a SIGSEGV (though this is best-effort; a true SIGSEGV from freed memory is not catchable).
## Data Files
The crash was captured from the Nothing A059 device at 13:05:42 on 2026-04-06. The tombstone is in the device's `/data/tombstones/` directory. The logcat output shows the crash frames.

221
desktop/index.html
View File

@@ -2,80 +2,53 @@
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, viewport-fit=cover"
/>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>WarzonePhone</title>
<link rel="stylesheet" href="/src/style.css" />
</head>
<body>
<div id="app">
<!-- ═══════════════════════════════════════════════════════
LOBBY — default view, auto-connects signal on launch
═══════════════════════════════════════════════════════ -->
<div id="lobby-screen">
<header class="lobby-header">
<div class="lobby-title-row">
<h1>WarzonePhone</h1>
<button id="settings-btn" class="icon-btn" title="Settings">&#9881;</button>
</div>
<div class="lobby-status-row">
<span id="lobby-dot" class="dot"></span>
<span id="lobby-relay-label" class="lobby-relay">Connecting...</span>
<span id="lobby-room-label" class="lobby-room">general</span>
</div>
<div class="lobby-identity">
<span id="lobby-identicon"></span>
<span id="lobby-fp" class="fp-display"></span>
</div>
</header>
<!-- User list -->
<div class="lobby-users-section">
<div class="lobby-users-header">
<span>Online</span>
<span id="lobby-user-count" class="badge">0</span>
</div>
<div id="lobby-user-list" class="lobby-user-list">
<div class="lobby-empty">No one else is here yet</div>
<!-- Connect screen -->
<div id="connect-screen">
<h1>WarzonePhone</h1>
<p class="subtitle">Encrypted Voice</p>
<div class="form">
<label>Relay
<button id="relay-selected" class="relay-selected" type="button">
<span id="relay-dot" class="dot"></span>
<span id="relay-label">Select relay...</span>
<span class="arrow">&#9881;</span>
</button>
</label>
<label>Room
<input id="room" type="text" value="android" />
</label>
<label>Alias
<input id="alias" type="text" placeholder="your name" />
</label>
<div class="form-row">
<label class="checkbox">
<input id="os-aec" type="checkbox" checked />
OS Echo Cancel
</label>
<button id="settings-btn-home" class="icon-btn" title="Settings (Cmd+,)">&#9881;</button>
</div>
<button id="connect-btn" class="primary">Connect</button>
<p id="connect-error" class="error"></p>
</div>
<!-- Voice join FAB -->
<div class="lobby-fab-row">
<button id="join-voice-btn" class="fab" title="Join Voice Chat">
<span class="fab-icon">&#x1F3A7;</span>
<span class="fab-label">Join Voice</span>
</button>
</div>
<!-- Incoming call banner -->
<div id="incoming-call-banner" class="incoming-banner hidden">
<div class="incoming-info">
<span id="incoming-identicon" class="incoming-identicon"></span>
<div>
<div id="incoming-caller-name" class="incoming-name">Unknown</div>
<div class="incoming-subtitle">Incoming call...</div>
</div>
</div>
<div class="incoming-actions">
<button id="accept-call-btn" class="btn-accept">Accept</button>
<button id="reject-call-btn" class="btn-reject">Reject</button>
</div>
<div class="identity-info">
<span id="my-identicon"></span>
<span id="my-fingerprint" class="fp-display"></span>
</div>
<div class="recent-rooms" id="recent-rooms"></div>
</div>
<!-- ═══════════════════════════════════════════════════════
IN-CALL — voice active (room or direct)
═══════════════════════════════════════════════════════ -->
<!-- In-call screen -->
<div id="call-screen" class="hidden">
<div class="call-header">
<div class="call-header-row">
<button id="back-to-lobby-btn" class="icon-btn small" title="Back to lobby">&#x2190;</button>
<div id="room-name" class="room-name"></div>
<button id="settings-btn-call" class="icon-btn small" title="Settings">&#9881;</button>
<button id="settings-btn-call" class="icon-btn small" title="Settings (Cmd+,)">&#9881;</button>
</div>
<div class="call-meta">
<span id="call-status" class="status-dot"></span>
@@ -85,14 +58,6 @@
<div class="level-meter">
<div id="level-bar" class="level-bar-fill"></div>
</div>
<!-- Direct-call phone layout -->
<div id="direct-call-view" class="direct-call-view hidden">
<div id="dc-identicon" class="dc-identicon"></div>
<div id="dc-name" class="dc-name">Unknown</div>
<div id="dc-fp" class="dc-fp"></div>
<div id="dc-badge" class="dc-badge">Connecting...</div>
</div>
<!-- Room participants -->
<div id="participants" class="participants"></div>
<div class="controls">
<button id="mic-btn" class="control-btn" title="Toggle Mic (m)">
@@ -108,29 +73,7 @@
<div id="stats" class="stats"></div>
</div>
<!-- ═══════════════════════════════════════════════════════
USER CONTEXT MENU (tap on user in lobby)
═══════════════════════════════════════════════════════ -->
<div id="user-context-menu" class="context-menu hidden">
<div class="context-header">
<span id="ctx-identicon" class="ctx-identicon"></span>
<div>
<div id="ctx-name" class="ctx-name">User</div>
<div id="ctx-fp" class="ctx-fp"></div>
</div>
</div>
<button id="ctx-call-btn" class="context-action">
<span>&#x1F4DE;</span> Direct Call
</button>
<button id="ctx-message-btn" class="context-action" disabled>
<span>&#x1F4AC;</span> Message (coming soon)
</button>
<button id="ctx-close-btn" class="context-action dim">Close</button>
</div>
<!-- ═══════════════════════════════════════════════════════
SETTINGS PANEL (overlay)
═══════════════════════════════════════════════════════ -->
<!-- Settings panel -->
<div id="settings-panel" class="hidden">
<div class="settings-card">
<div class="settings-header">
@@ -148,84 +91,50 @@
</div>
<div class="settings-section">
<h3>Audio</h3>
<div class="quality-control">
<div class="quality-header">
<span class="setting-label">QUALITY</span>
<span id="s-quality-label" class="quality-value">Auto</span>
</div>
<input id="s-quality" type="range" min="0" max="6" step="1" value="6" />
<div class="quality-labels">
<span>Codec2 1.2k</span>
<span>Auto</span>
</div>
</div>
<label class="checkbox">
<input id="s-os-aec" type="checkbox" checked />
OS Echo Cancellation
<input id="s-os-aec" type="checkbox" />
OS Echo Cancellation (macOS VoiceProcessingIO)
</label>
<label class="checkbox">
<input id="s-agc" type="checkbox" checked />
Automatic Gain Control
</label>
</div>
<div class="settings-section">
<h3>Relays</h3>
<div id="s-relay-list"></div>
<div class="relay-add">
<input id="s-relay-name" type="text" placeholder="Name" style="flex:1" />
<input id="s-relay-addr" type="text" placeholder="host:port" style="flex:2" />
<button id="s-relay-add" class="secondary-btn small">Add</button>
</div>
</div>
<div class="settings-section">
<h3>Identity</h3>
<div>
<span class="setting-label">FINGERPRINT</span>
<div id="s-fingerprint" class="fp-display" style="margin-top:4px"></div>
<div class="setting-row">
<span class="setting-label">Fingerprint</span>
<span id="s-fingerprint" class="fp-display-large"></span>
</div>
<div style="margin-top:8px">
<span class="setting-label">IDENTITY FILE</span>
<div style="font-size:12px;opacity:0.6;margin-top:2px">~/.wzp/identity</div>
<div class="setting-row">
<span class="setting-label">Identity file</span>
<span class="fp-display">~/.wzp/identity</span>
</div>
</div>
<div class="settings-section">
<h3>Network</h3>
<div>
<span class="setting-label">PUBLIC ADDRESS</span>
<span id="s-public-addr" style="color:var(--green);font-size:13px;margin-left:8px"></span>
<button id="s-reflect-btn" class="secondary-btn small" style="margin-left:8px">Detect</button>
</div>
<div style="margin-top:8px">
<button id="s-nat-detect-btn" class="secondary-btn" style="width:100%">Detect NAT</button>
<div id="s-nat-result" style="font-size:11px;margin-top:4px;opacity:0.7;white-space:pre-wrap"></div>
</div>
<h3>Recent Rooms</h3>
<div id="s-recent-rooms" class="recent-rooms-list"></div>
<button id="s-clear-recent" class="secondary-btn">Clear History</button>
</div>
<div class="settings-section">
<h3>Debug</h3>
<label class="checkbox">
<input id="s-dred-debug" type="checkbox" />
DRED debug logs (verbose, dev only)
</label>
<label class="checkbox">
<input id="s-call-debug" type="checkbox" />
Call flow debug logs (trace every step of a call)
</label>
<label class="checkbox">
<input id="s-direct-only" type="checkbox" />
Direct-only mode (no relay fallback)
</label>
<label class="checkbox">
<input id="s-birthday-attack" type="checkbox" />
Birthday attack (extra ports for hard NAT — adds ~3s)
</label>
<button id="settings-save" class="primary">Save</button>
</div>
</div>
<!-- Manage Relays dialog -->
<div id="relay-dialog" class="hidden">
<div class="settings-card relay-dialog-card">
<div class="settings-header">
<h2>Manage Relays</h2>
<button id="relay-dialog-close" class="icon-btn">&times;</button>
</div>
<div class="settings-section" id="s-call-debug-section" style="display:none">
<h3>Call Debug Log</h3>
<div id="s-call-debug-log" style="max-height:220px;overflow-y:auto;background:#0a0a0a;color:#e0e0e0;font-family:ui-monospace,Menlo,Monaco,'Courier New',monospace;font-size:10px;padding:6px;border-radius:4px;line-height:1.4;white-space:pre-wrap"></div>
<div style="display:flex;gap:6px;margin-top:6px">
<button id="s-call-debug-copy" class="secondary-btn" style="flex:1">Copy log</button>
<button id="s-call-debug-share" class="secondary-btn" style="flex:1">Share</button>
<button id="s-call-debug-clear" class="secondary-btn" style="flex:1">Clear log</button>
<div id="relay-dialog-list" class="relay-dialog-list"></div>
<div class="relay-add-row">
<div class="relay-add-inputs">
<input id="relay-add-name" type="text" placeholder="Name" />
<input id="relay-add-addr" type="text" placeholder="host:port" />
</div>
<small id="s-call-debug-copy-status" style="display:block;margin-top:4px;color:var(--text-dim);font-size:10px"></small>
<button id="relay-add-btn" class="primary">Add Relay</button>
</div>
<button id="settings-save" class="primary" style="margin-top:12px">Save</button>
</div>
</div>
</div>

80
desktop/src-tauri/Cargo.toml
View File

@@ -5,38 +5,12 @@ edition = "2024"
description = "WarzonePhone Desktop — encrypted VoIP client"
default-run = "wzp-desktop"
# Library target — required for Tauri mobile (Android/iOS link the app as a cdylib)
# and also used by the desktop binary below.
#
# `staticlib` was DROPPED from crate-type because rust-lang/rust#104707
# documents that having staticlib alongside cdylib leaks non-exported
# symbols from staticlibs into the cdylib. Bionic's private `__init_tcb`
# / `pthread_create` symbols end up bound LOCALLY inside our .so instead
# of resolved dynamically against libc.so at dlopen time — which crashes
# at launch as soon as tao tries to std::thread::spawn() from the JNI
# onCreate callback. The legacy wzp-android crate uses ["cdylib", "rlib"]
# and runs fine on the same phone with the same NDK + Rust toolchain.
#
# iOS Tauri builds that actually need staticlib can re-add it behind a
# target cfg if we ever ship on iOS.
[lib]
name = "wzp_desktop_lib"
crate-type = ["cdylib", "rlib"]
[[bin]]
name = "wzp-desktop"
path = "src/main.rs"
[build-dependencies]
tauri-build = { version = "2", features = [] }
# cc is no longer needed — all C++ moved to crates/wzp-native (built with
# cargo-ndk and loaded via libloading at runtime). wzp-desktop's .so on
# Android is now pure Rust.
[dependencies]
tauri = { version = "2", features = [] }
tauri-plugin-shell = "2"
tauri-plugin-notification = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
@@ -45,64 +19,18 @@ tracing-subscriber = "0.3"
anyhow = "1"
rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
# WarzonePhone crates — protocol layer is platform-independent
# WarzonePhone crates
wzp-proto = { path = "../../crates/wzp-proto" }
wzp-codec = { path = "../../crates/wzp-codec" }
wzp-fec = { path = "../../crates/wzp-fec" }
wzp-crypto = { path = "../../crates/wzp-crypto" }
wzp-transport = { path = "../../crates/wzp-transport" }
# wzp-client pulls in CPAL on every desktop target and, additionally on
# macOS, VoiceProcessingIO (coreaudio-rs behind the "vpio" feature). The
# vpio feature MUST NOT be enabled on Windows / Linux because coreaudio-rs
# is Apple-framework-only and will fail to build. Task #24 will add a
# matching Windows Voice Capture DSP path behind its own feature; until
# then, Windows desktops use plain CPAL with AEC disabled.
# macOS: CPAL + VoiceProcessingIO (hardware AEC via Core Audio).
[target.'cfg(target_os = "macos")'.dependencies]
wzp-client = { path = "../../crates/wzp-client", features = ["audio", "vpio"] }
# Windows: CPAL for playback + direct WASAPI for capture with OS-level
# AEC (AudioCategory_Communications). The wzp-client `windows-aec`
# feature swaps the default CPAL AudioCapture for a WASAPI one that
# opens the mic under AudioCategory_Communications, turning on Windows's
# communications audio processing chain (AEC, NS, AGC). The reference
# signal for AEC is the system render mix, so echo from our CPAL
# playback is cancelled automatically without extra plumbing.
[target.'cfg(target_os = "windows")'.dependencies]
wzp-client = { path = "../../crates/wzp-client", features = ["audio", "windows-aec"] }
# Linux: CPAL playback+capture baseline. AEC is enabled via the top-level
# `linux-aec` feature in wzp-desktop, which forwards to wzp-client/linux-aec.
# Keeping it opt-in at the wzp-desktop level (rather than forcing it always
# on here) lets `cargo tauri build` produce two variants from the same
# source tree — a noAEC baseline and an AEC build — by toggling the feature
# at build time: `cargo tauri build -- --features wzp-desktop/linux-aec`.
[target.'cfg(target_os = "linux")'.dependencies]
wzp-client = { path = "../../crates/wzp-client", features = ["audio"] }
# Android: no CPAL, no vpio — audio goes through the standalone wzp-native
# cdylib that we dlopen via libloading at runtime. See the wzp_native
# module in src/.
[target.'cfg(target_os = "android")'.dependencies]
wzp-client = { path = "../../crates/wzp-client", default-features = false }
# libloading: runtime dlopen of libwzp_native.so — the standalone cdylib
# crate that owns all C++ (Oboe bridge). Keeps wzp-desktop's .so free of
# any C/C++ static archives that would otherwise leak bionic's internal
# pthread_create into our cdylib and trigger the __init_tcb crash.
libloading = "0.8"
# jni + ndk-context: called from android_audio.rs to invoke
# AudioManager.setSpeakerphoneOn on the JVM side at runtime, so the
# Oboe playout stream (opened with Usage::VoiceCommunication) can route
# between earpiece and loud speaker without restarting.
jni = "0.21"
ndk-context = "0.1"
# Platform-specific
[target.'cfg(target_os = "macos")'.dependencies]
coreaudio-rs = "0.11"
[features]
default = ["custom-protocol"]
custom-protocol = ["tauri/custom-protocol"]
# linux-aec: forwards to wzp-client/linux-aec so `cargo tauri build -- --features
# wzp-desktop/linux-aec` enables the WebRTC AEC3 backend on Linux. No-op on
# other targets because wzp-client/linux-aec is itself cfg(target_os = "linux").
linux-aec = ["wzp-client/linux-aec"]

21
desktop/src-tauri/Info.plist
View File

@@ -1,21 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!--
Custom Info.plist keys merged into the bundled WarzonePhone.app by
tauri-bundler. The base Info.plist (CFBundleIdentifier, version,
etc.) is generated from tauri.conf.json — only put *additional*
keys here.
NSMicrophoneUsageDescription is required by macOS TCC for any
app that opens an audio input unit. Without this string the OS
silently denies CoreAudio capture (input callbacks return zeros)
and the app never appears in System Settings → Privacy &
Security → Microphone. This was the root cause of the desktop
mic regression where phones could not hear the desktop client.
-->
<key>NSMicrophoneUsageDescription</key>
<string>WarzonePhone needs microphone access to transmit your voice during calls.</string>
</dict>
</plist>

23
desktop/src-tauri/build.rs
View File

@@ -1,26 +1,3 @@
use std::process::Command;
fn main() {
// Capture short git hash so the running app can prove which build it is.
// Falls back to "unknown" if git isn't available (e.g. when building from
// a tarball without a .git dir).
let git_hash = Command::new("git")
.args(["rev-parse", "--short", "HEAD"])
.output()
.ok()
.filter(|o| o.status.success())
.and_then(|o| String::from_utf8(o.stdout).ok())
.map(|s| s.trim().to_string())
.unwrap_or_else(|| "unknown".into());
println!("cargo:rustc-env=WZP_GIT_HASH={git_hash}");
println!("cargo:rerun-if-changed=../../.git/HEAD");
println!("cargo:rerun-if-changed=../../.git/refs/heads");
// No cc::Build of ANY kind on Android — all C++ lives in the standalone
// `wzp-native` crate which is built separately with cargo-ndk and loaded
// via libloading at runtime. See docs/incident-tauri-android-init-tcb.md
// for why this split exists.
tauri_build::build()
}

30
desktop/src-tauri/capabilities/default.json
View File

@@ -1,30 +0,0 @@
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"description": "Default capability — grants core APIs (events, path, window, app, clipboard) to the main window on every platform we ship to.",
"windows": ["main"],
"platforms": [
"linux",
"macOS",
"windows",
"android",
"iOS"
],
"permissions": [
"core:default",
"core:event:default",
"core:event:allow-listen",
"core:event:allow-unlisten",
"core:event:allow-emit",
"core:event:allow-emit-to",
"core:path:default",
"core:window:default",
"core:app:default",
"core:webview:default",
"shell:default",
"notification:default",
"notification:allow-notify",
"notification:allow-request-permission",
"notification:allow-is-permission-granted"
]
}

40
desktop/src-tauri/gen/android/app/src/main/AndroidManifest.xml
View File

@@ -1,40 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-feature android:name="android.hardware.microphone" android:required="true" />
<!-- AndroidTV support -->
<uses-feature android:name="android.software.leanback" android:required="false" />
<application
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:theme="@style/Theme.wzp_desktop"
android:usesCleartextTraffic="${usesCleartextTraffic}">
<activity
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
android:launchMode="singleTask"
android:label="@string/main_activity_title"
android:name=".MainActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
<!-- AndroidTV support -->
<category android:name="android.intent.category.LEANBACK_LAUNCHER" />
</intent-filter>
</activity>
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_paths" />
</provider>
</application>
</manifest>

Some files were not shown because too many files have changed in this diff Show More