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

feat: wire QUIC transport, JNI bridge, connect UI + add docs

Browse Source 
- Replace raw FFI with proper `jni` crate for string marshalling
- Wire QUIC transport in engine: connect to relay, crypto handshake
  (CallOffer/CallAnswer, X25519+Ed25519), send/recv MediaPackets
- Feed received packets into jitter buffer (was previously ignored)
- Add connect screen UI with CALL button (idle state) and in-call
  controls (mute, speaker, hang up, live stats)
- Hardcode relay 172.16.81.125:4433, room "android"
- Add comprehensive docs in docs/android/:
  architecture.md (8 mermaid diagrams), build-guide.md,
  debugging.md, maintenance.md, roadmap.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude
2026-04-05 04:43:49 +00:00
parent 780309fede
commit 8d5f6fe044
16 changed files with 1496 additions and 398 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,88 +1,26 @@
//! JNI bridge for Android — thin layer between Kotlin and the WzpEngine.
//!
//! Each function converts JNI types to Rust types, delegates to WzpEngine,
//! and converts results back. No audio processing happens here.
//!
//! # Safety
//!
//! All functions in this module are called from the JVM via JNI. They use raw
//! pointers for the JNI environment and object references. The `jni` crate is
//! not yet a dependency, so we use raw FFI types and placeholder string extraction.
//! When the `jni` crate is added, the `extract_jstring` helper should be replaced
//! with proper `JNIEnv::get_string()` calls.
use std::os::raw::{c_long, c_void};
use std::panic;
use jni::objects::{JClass, JObject, JString};
use jni::sys::{jboolean, jint, jlong, jstring};
use jni::JNIEnv;
use tracing::{error, info};
use wzp_proto::QualityProfile;
use crate::engine::{CallStartConfig, WzpEngine};
/// Opaque engine handle passed to/from Kotlin as a `jlong`.
///
/// Boxed on the heap; the raw pointer is stored on the Kotlin side.
/// Only `nativeDestroy` frees it.
struct EngineHandle {
engine: WzpEngine,
}
// ---------------------------------------------------------------------------
// JNI type aliases (mirrors the C JNI ABI without pulling in the `jni` crate)
// ---------------------------------------------------------------------------
/// JNI boolean — `u8` where 0 = false, non-zero = true.
type JBoolean = u8;
/// JNI int — `i32`.
type JInt = i32;
/// JNI long — `i64` / `c_long` on 64-bit.
type JLong = c_long;
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/// Recover the `EngineHandle` from a raw handle value **without** taking ownership.
///
/// # Safety
/// `handle` must be a value previously returned by `nativeInit` and not yet
/// passed to `nativeDestroy`.
unsafe fn handle_ref(handle: JLong) -> &'static mut EngineHandle {
/// Recover the `EngineHandle` from a raw handle value.
unsafe fn handle_ref(handle: jlong) -> &'static mut EngineHandle {
unsafe { &mut *(handle as *mut EngineHandle) }
}
/// Placeholder: extract a `String` from a JNI `jstring`.
///
/// When the `jni` crate is added this should be replaced with:
/// ```ignore
/// let env = JNIEnv::from_raw(env_ptr).unwrap();
/// env.get_string(jstring).unwrap().into()
/// ```
///
/// # Safety
/// `_env` and `_jstring` are raw JNI pointers.
#[allow(unused)]
unsafe fn extract_jstring(_env: *mut c_void, _jstring: *mut c_void) -> String {
// TODO(jni): implement real string extraction once the `jni` crate is added.
// For now return a default so the rest of the bridge compiles and can be tested
// with hardcoded values from the Kotlin side.
String::new()
}
/// Allocate a JNI `jstring` from a Rust `&str`.
///
/// # Safety
/// `_env` is a raw JNI pointer.
#[allow(unused)]
unsafe fn new_jstring(_env: *mut c_void, _s: &str) -> *mut c_void {
// TODO(jni): implement via JNIEnv::new_string when jni crate is added.
std::ptr::null_mut()
}
/// Map a Kotlin `profile` int to a `QualityProfile`.
fn profile_from_int(value: JInt) -> QualityProfile {
fn profile_from_int(value: jint) -> QualityProfile {
match value {
1 => QualityProfile::DEGRADED,
2 => QualityProfile::CATASTROPHIC,
@@ -90,79 +28,42 @@ fn profile_from_int(value: JInt) -> QualityProfile {
}
}
// ---------------------------------------------------------------------------
// JNI exports
// ---------------------------------------------------------------------------
// Function names follow JNI convention: Java_<package>_<Class>_<method>
// with underscores in the package replaced by `_1` in actual JNI but here we
// use the simplified form that matches javah output for the package `com.wzp.engine`.
/// Create a new `WzpEngine`, returning an opaque handle as `jlong`.
///
/// Kotlin signature: `private external fun nativeInit(): Long`
///
/// # Safety
/// Called from JNI.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeInit(
_env: *mut c_void,
_class: *mut c_void,
) -> JLong {
_env: JNIEnv,
_class: JClass,
) -> jlong {
let result = panic::catch_unwind(|| {
// Note: tracing on Android requires android_logger or similar.
// fmt() subscriber writes to stdout which doesn't exist on Android.
// Skip tracing init here — add android_logger later.
let handle = Box::new(EngineHandle {
engine: WzpEngine::new(),
});
info!("WzpEngine created via JNI");
Box::into_raw(handle) as JLong
Box::into_raw(handle) as jlong
});
match result {
Ok(h) => h,
Err(_) => {
error!("panic in nativeInit");
0 // null handle — Kotlin side checks for 0
}
Err(_) => 0,
}
}
/// Start a call.
///
/// Kotlin signature:
/// ```kotlin
/// private external fun nativeStartCall(
/// handle: Long, relay: String, room: String, seed: String, token: String
/// ): Int
/// ```
///
/// Returns 0 on success, -1 on error.
///
/// # Safety
/// Called from JNI. `handle` must be a live engine handle.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartCall(
env: *mut c_void,
_class: *mut c_void,
handle: JLong,
relay_addr_ptr: *mut c_void,
room_ptr: *mut c_void,
seed_hex_ptr: *mut c_void,
token_ptr: *mut c_void,
) -> JInt {
mut env: JNIEnv,
_class: JClass,
handle: jlong,
relay_addr_j: JString,
room_j: JString,
seed_hex_j: JString,
token_j: JString,
) -> 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();
let room: String = env.get_string(&room_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 h = unsafe { handle_ref(handle) };
// Extract strings from JNI. When the `jni` crate is available these
// will use real JNI string conversion. For now, placeholders.
let relay_addr = unsafe { extract_jstring(env, relay_addr_ptr) };
let _room = unsafe { extract_jstring(env, room_ptr) };
let seed_hex = unsafe { extract_jstring(env, seed_hex_ptr) };
let token = unsafe { extract_jstring(env, token_ptr) };
// Parse the hex-encoded 32-byte identity seed.
// Parse hex seed
let mut identity_seed = [0u8; 32];
if seed_hex.len() == 64 {
for i in 0..32 {
@@ -170,20 +71,22 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartCall(
identity_seed[i] = byte;
}
}
} else {
// Generate random seed if not provided
use rand::RngCore;
rand::thread_rng().fill_bytes(&mut identity_seed);
}
let config = CallStartConfig {
profile: QualityProfile::GOOD,
relay_addr,
auth_token: token.into_bytes(),
room,
auth_token: if token.is_empty() { Vec::new() } else { token.into_bytes() },
identity_seed,
};
match h.engine.start_call(config) {
Ok(()) => {
info!("call started via JNI");
0
}
Ok(()) => 0,
Err(e) => {
error!("start_call failed: {e}");
-1
@@ -193,152 +96,92 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartCall(
match result {
Ok(code) => code,
Err(_) => {
error!("panic in nativeStartCall");
-1
}
Err(_) => -1,
}
}
/// Stop the active call.
///
/// Kotlin signature: `private external fun nativeStopCall(handle: Long)`
///
/// # Safety
/// Called from JNI.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStopCall(
_env: *mut c_void,
_class: *mut c_void,
handle: JLong,
_env: JNIEnv,
_class: JClass,
handle: jlong,
) {
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
h.engine.stop_call();
info!("call stopped via JNI");
}));
}
/// Set microphone mute state.
///
/// Kotlin signature: `private external fun nativeSetMute(handle: Long, muted: Boolean)`
///
/// # Safety
/// Called from JNI.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeSetMute(
_env: *mut c_void,
_class: *mut c_void,
handle: JLong,
muted: JBoolean,
_env: JNIEnv,
_class: JClass,
handle: jlong,
muted: jboolean,
) {
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let muted = muted != 0;
h.engine.set_mute(muted);
info!(muted, "mute set via JNI");
h.engine.set_mute(muted != 0);
}));
}
/// Set speaker (loudspeaker) mode.
///
/// Kotlin signature: `private external fun nativeSetSpeaker(handle: Long, speaker: Boolean)`
///
/// # Safety
/// Called from JNI.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeSetSpeaker(
_env: *mut c_void,
_class: *mut c_void,
handle: JLong,
speaker: JBoolean,
_env: JNIEnv,
_class: JClass,
handle: jlong,
speaker: jboolean,
) {
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let speaker = speaker != 0;
h.engine.set_speaker(speaker);
info!(speaker, "speaker set via JNI");
h.engine.set_speaker(speaker != 0);
}));
}
/// Get call statistics as a JSON string.
///
/// Kotlin signature: `private external fun nativeGetStats(handle: Long): String`
///
/// Returns a JSON-serialized `CallStats` struct, or `"{}"` on error.
///
/// # Safety
/// Called from JNI.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeGetStats(
env: *mut c_void,
_class: *mut c_void,
handle: JLong,
) -> *mut c_void {
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeGetStats<'a>(
mut env: JNIEnv<'a>,
_class: JClass,
handle: jlong,
) -> jstring {
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let stats = h.engine.get_stats();
match serde_json::to_string(&stats) {
Ok(json) => unsafe { new_jstring(env, &json) },
Err(e) => {
error!("failed to serialize stats: {e}");
unsafe { new_jstring(env, "{}") }
}
}
serde_json::to_string(&stats).unwrap_or_else(|_| "{}".to_string())
}));
match result {
Ok(ptr) => ptr,
Err(_) => {
error!("panic in nativeGetStats");
unsafe { new_jstring(env, "{}") }
}
}
let json = match result {
Ok(s) => s,
Err(_) => "{}".to_string(),
};
env.new_string(&json)
.map(|s| s.into_raw())
.unwrap_or(JObject::null().into_raw())
}
/// Force a specific quality profile, overriding adaptive logic.
///
/// Kotlin signature: `private external fun nativeForceProfile(handle: Long, profile: Int)`
///
/// Profile values: 0 = GOOD, 1 = DEGRADED, 2 = CATASTROPHIC.
///
/// # Safety
/// Called from JNI.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeForceProfile(
_env: *mut c_void,
_class: *mut c_void,
handle: JLong,
profile: JInt,
_env: JNIEnv,
_class: JClass,
handle: jlong,
profile: jint,
) {
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let h = unsafe { handle_ref(handle) };
let qp = profile_from_int(profile);
h.engine.force_profile(qp);
info!(?qp, "profile forced via JNI");
}));
}
/// Destroy the engine and free all associated memory.
///
/// After this call the handle is invalid and must not be reused.
///
/// Kotlin signature: `private external fun nativeDestroy(handle: Long)`
///
/// # Safety
/// Called from JNI. `handle` must be a live engine handle. After this call
/// the handle is dangling.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeDestroy(
_env: *mut c_void,
_class: *mut c_void,
handle: JLong,
_env: JNIEnv,
_class: JClass,
handle: jlong,
) {
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
// Retake ownership of the Box and drop it, which calls WzpEngine::drop()
// and in turn stop_call().
let h = unsafe { Box::from_raw(handle as *mut EngineHandle) };
drop(h);
info!("engine destroyed via JNI");
}));
}