@dvai-bridge/android 4.0.0

package/android/src/test/java/co/deepvoiceai/bridge/DVAIBridgeAPIShapeTest.kt

@@ -0,0 +1,86 @@
+package co.deepvoiceai.bridge
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import kotlin.reflect.full.functions
+import kotlin.reflect.full.memberProperties
+
+/**
+ * Reflection-based smoke checks on the public DVAIBridge surface. These
+ * don't actually invoke the bridge — they just assert the 8 expected
+ * public methods + properties exist with the right shape.
+ *
+ * The point: prevent accidental rename / removal of public API across
+ * cross-platform parity refactors. Compare against
+ * `packages/dvai-bridge-ios/ios/Sources/DVAIBridge/DVAIBridge.swift`.
+ */
+class DVAIBridgeAPIShapeTest {
+    @Test
+    fun `singleton is the DVAIBridge object`() {
+        val instance = DVAIBridge
+        assertNotNull(instance)
+    }
+
+    @Test
+    fun `public methods include start stop status init downloadModel listeners`() {
+        val fnNames = DVAIBridge::class.functions.map { it.name }.toSet()
+        for (expected in listOf(
+            "init",
+            "start",
+            "stop",
+            "status",
+            "downloadModel",
+            "addProgressListener",
+            "removeProgressListener",
+        )) {
+            assertTrue("missing method: $expected (had: $fnNames)", expected in fnNames)
+        }
+    }
+
+    @Test
+    fun `public properties include progressFlow and reactive`() {
+        val propNames = DVAIBridge::class.memberProperties.map { it.name }.toSet()
+        for (expected in listOf("progressFlow", "reactive")) {
+            assertTrue("missing property: $expected (had: $propNames)", expected in propNames)
+        }
+    }
+
+    @Test
+    fun `BackendKind has the expected 4 cases`() {
+        // Cross-platform parity: same 4 cases as the iOS Android-relevant
+        // subset (iOS adds Foundation / CoreML / MLX which don't exist on
+        // Android; Android's MediaPipe / LiteRT don't exist on iOS).
+        assertEquals(4, BackendKind.values().size)
+    }
+
+    @Test
+    fun `StartOptions defaults match iOS DVAIBridgeConfig defaults`() {
+        val opts = StartOptions()
+        assertEquals(BackendKind.Auto, opts.backend)
+        assertEquals(2048, opts.contextSize)
+        assertEquals(4, opts.threads)
+        assertEquals(38883, opts.httpBasePort)
+        assertEquals(16, opts.httpMaxPortAttempts)
+        assertEquals(99, opts.gpuLayers)
+        assertEquals(512, opts.maxNewTokens)
+    }
+
+    @Test
+    fun `DVAIBridgeError sealed class has expected cases`() {
+        // Sanity-check error case names — consumer try-catch blocks should
+        // be able to pattern-match on each of these.
+        val expected = setOf(
+            "AlreadyStarted",
+            "ConfigurationInvalid",
+            "ModelLoadFailed",
+            "BackendUnavailable",
+            "BackendError",
+            "ChecksumMismatch",
+            "DownloadFailed",
+        )
+        val actual = DVAIBridgeError::class.sealedSubclasses.map { it.simpleName }.toSet()
+        assertEquals(expected, actual)
+    }
+}

package/android/src/test/java/co/deepvoiceai/bridge/OffloadProxyDecisionTest.kt

@@ -0,0 +1,144 @@
+package co.deepvoiceai.bridge
+
+import co.deepvoiceai.bridge.shared.core.discovery.Peer
+import co.deepvoiceai.bridge.shared.core.discovery.PeerSource
+import co.deepvoiceai.bridge.shared.core.offload.OffloadConfig
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * v3.2 — pre-routing decision logic.
+ *
+ * Mirrors `packages/dvai-bridge-core/src/__tests__/offload-decide.test.ts`
+ * for the canonical TS [decide] function. This test exercises the
+ * Kotlin port living inside [OffloadProxy] (private; exposed as
+ * `internal` for testing).
+ *
+ * Doesn't bind a server — only constructs an OffloadProxy and calls
+ * the route-decision function with synthetic peers. No HTTP, no
+ * Ktor lifecycle, fast.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class OffloadProxyDecisionTest {
+
+    private fun makeProxy(
+        backendBaseUrl: String? = "http://127.0.0.1:38983",
+        offloadEnabled: Boolean = true,
+        minLocalCapability: Double = 10.0,
+    ) = OffloadProxy(
+        backendBaseUrl = backendBaseUrl,
+        offloadConfig = OffloadConfig(
+            enabled = offloadEnabled,
+            minLocalCapability = minLocalCapability,
+        ),
+        pairingPolicy = null,
+        discovery = null,
+        appId = "test.app",
+        selfDeviceId = "test-self-device",
+    )
+
+    private fun peer(
+        deviceId: String,
+        modelScore: Map<String, Double>,
+        loadedModels: List<String> = emptyList(),
+    ) = Peer(
+        deviceId = deviceId,
+        deviceName = "$deviceId-name",
+        dvaiVersion = "3.2.0",
+        baseUrl = "http://10.0.0.1:38883",
+        loadedModels = loadedModels,
+        capability = modelScore,
+        via = PeerSource.MDNS,
+    )
+
+    /* ------------------------------------------------------------------ */
+    /* pickBestPeer                                                       */
+    /* ------------------------------------------------------------------ */
+
+    @Test
+    fun `pickBestPeer returns null when no peers`() {
+        val proxy = makeProxy()
+        assertNull(proxy.pickBestPeer(emptyList(), "model-a"))
+    }
+
+    @Test
+    fun `pickBestPeer prefers higher score`() {
+        val proxy = makeProxy()
+        val a = peer("a", mapOf("model-a" to 5.0))
+        val b = peer("b", mapOf("model-a" to 30.0))
+        val c = peer("c", mapOf("model-a" to 12.0))
+        val best = proxy.pickBestPeer(listOf(a, b, c), "model-a")
+        assertEquals("b", best?.peer?.deviceId)
+    }
+
+    @Test
+    fun `pickBestPeer prefers peer with model already loaded`() {
+        val proxy = makeProxy()
+        val notLoaded = peer("a", mapOf("model-a" to 30.0))
+        val loaded = peer("b", mapOf("model-a" to 20.0), loadedModels = listOf("model-a"))
+        val best = proxy.pickBestPeer(listOf(notLoaded, loaded), "model-a")
+        assertEquals("b", best?.peer?.deviceId)
+        assertTrue(best!!.hasModel)
+    }
+
+    @Test
+    fun `pickBestPeer skips peers with zero score for the model`() {
+        val proxy = makeProxy()
+        val none = peer("a", mapOf("other" to 100.0))
+        val zero = peer("b", mapOf("model-a" to 0.0))
+        assertNull(proxy.pickBestPeer(listOf(none, zero), "model-a"))
+    }
+
+    /* ------------------------------------------------------------------ */
+    /* decideRoute                                                        */
+    /* ------------------------------------------------------------------ */
+
+    private val emptyHeaders = emptyMap<String, String>()
+    private fun headers(vararg pairs: Pair<String, String>) = pairs.toMap()
+
+    @Test
+    fun `decideRoute non-chat-completion path goes Local`() {
+        val proxy = makeProxy()
+        val decision = proxy.decideRoute("/v1/embeddings", ByteArray(0), emptyHeaders)
+        assertTrue(
+            "expected Local, got $decision",
+            decision is OffloadProxy.RouteDecision.Local,
+        )
+    }
+
+    @Test
+    fun `decideRoute non-chat-completion with no backend gives NoCapableDevice`() {
+        val proxy = makeProxy(backendBaseUrl = null)
+        val decision = proxy.decideRoute("/v1/embeddings", ByteArray(0), emptyHeaders)
+        assertTrue(decision is OffloadProxy.RouteDecision.NoCapableDevice)
+    }
+
+    @Test
+    fun `decideRoute chat-completion + offload disabled goes Local`() {
+        val proxy = makeProxy(offloadEnabled = false)
+        val decision = proxy.decideRoute(
+            "/v1/chat/completions",
+            """{"model":"m","stream":false}""".toByteArray(),
+            emptyHeaders,
+        )
+        assertTrue(decision is OffloadProxy.RouteDecision.Local)
+    }
+
+    @Test
+    fun `decideRoute X-DVAI-Offload never forces local even with peer available`() {
+        val proxy = makeProxy()
+        val decision = proxy.decideRoute(
+            "/v1/chat/completions",
+            """{"model":"m"}""".toByteArray(),
+            headers("x-dvai-offload" to "never"),
+        )
+        assertTrue(decision is OffloadProxy.RouteDecision.Local)
+    }
+}

package/android/src/test/java/co/deepvoiceai/bridge/OffloadProxyForwardingTest.kt

@@ -0,0 +1,327 @@
+package co.deepvoiceai.bridge
+
+import co.deepvoiceai.bridge.shared.core.discovery.Peer
+import co.deepvoiceai.bridge.shared.core.discovery.PeerSource
+import co.deepvoiceai.bridge.shared.core.offload.OffloadConfig
+import co.deepvoiceai.bridge.shared.core.pairing.Pairing
+import co.deepvoiceai.bridge.shared.core.pairing.PairingPolicy
+import co.deepvoiceai.bridge.shared.core.pairing.PairingSource
+import co.deepvoiceai.bridge.shared.core.pairing.PairingStore
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.mockwebserver.MockResponse
+import okhttp3.mockwebserver.MockWebServer
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+import java.util.concurrent.TimeUnit
+
+/**
+ * v3.2 — full-loop integration test for [OffloadProxy].
+ *
+ * Spins up two [MockWebServer] instances inside the JVM:
+ *
+ *   - `backend` — stands in for the native backend's loopback HTTP
+ *     server. Always replies with a JSON body containing
+ *     `{"served_by":"backend"}` so tests can assert "did the proxy
+ *     forward to here".
+ *
+ *   - `peer`    — stands in for a remote peer that the proxy might
+ *     forward to. Replies with `{"served_by":"peer"}`.
+ *
+ * The OffloadProxy is constructed with the peerProvider lambda
+ * pointing at a fixed `Peer` whose baseUrl is `peer`'s URL. Tests
+ * make a real OkHttp request to the proxy's bound port and then
+ * inspect:
+ *
+ *   - which MockWebServer received a request (`takeRequest()` blocks
+ *     for up to 1s)
+ *   - the response body so we can tell which path executed
+ *   - the request headers received by the peer (HMAC signature
+ *     headers should be present on offload-routed requests)
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class OffloadProxyForwardingTest {
+
+    private lateinit var backend: MockWebServer
+    private lateinit var peer: MockWebServer
+    private val client = OkHttpClient.Builder()
+        .callTimeout(5, TimeUnit.SECONDS)
+        .build()
+
+    // Base64-url-encoded 256-bit pairing key (matches the v3.2.1 wire
+    // format — `OffloadProxy.signCanonical` decodes the key as
+    // base64-url before HMAC-keying, mirroring the TS Hub's
+    // `verifyHmac`). The test asserts header shape, not signature
+    // value, so the exact bytes don't matter — only that the string
+    // is decodable.
+    private val pairingKey = "vGzn8h_FNHkqL5Q1tN-rTu3pYWB7K0vGzn8h_FNHkqI"
+    private val peerDeviceId = "peer-device-id"
+
+    @Before
+    fun setup() {
+        backend = MockWebServer().apply { start() }
+        peer = MockWebServer().apply { start() }
+    }
+
+    @After
+    fun teardown() {
+        backend.shutdown()
+        peer.shutdown()
+    }
+
+    private fun makeProxy(
+        backendBaseUrlOverride: String? = backend.url("/").toString().trimEnd('/'),
+        offloadEnabled: Boolean = true,
+        peers: List<Peer> = emptyList(),
+        pairingPolicy: PairingPolicy? = null,
+        minLocalCapability: Double = 10.0,
+    ): OffloadProxy = OffloadProxy(
+        backendBaseUrl = backendBaseUrlOverride,
+        offloadConfig = OffloadConfig(
+            enabled = offloadEnabled,
+            minLocalCapability = minLocalCapability,
+        ),
+        pairingPolicy = pairingPolicy,
+        peerProvider = { peers },
+        appId = "co.test.app",
+        selfDeviceId = "self-device-id",
+    )
+
+    private fun fakePeer(
+        scoreForModel: Double = 30.0,
+        modelId: String = "test-model",
+    ) = Peer(
+        deviceId = peerDeviceId,
+        deviceName = "test-peer",
+        dvaiVersion = "3.2.0",
+        baseUrl = peer.url("/").toString().trimEnd('/'),
+        loadedModels = listOf(modelId),
+        capability = mapOf(modelId to scoreForModel),
+        via = PeerSource.MDNS,
+    )
+
+    /* ------------------------------------------------------------------ */
+    /* Local-only path                                                    */
+    /* ------------------------------------------------------------------ */
+
+    @Test
+    fun `chat-completion forwards to backend when no peers + offload disabled`() {
+        backend.enqueue(
+            MockResponse()
+                .setResponseCode(200)
+                .setHeader("Content-Type", "application/json")
+                .setBody("""{"served_by":"backend"}"""),
+        )
+
+        val proxy = makeProxy(offloadEnabled = false)
+        val proxyPort = proxy.start(basePort = freePort(), maxAttempts = 8)
+        try {
+            val resp = postJson("http://127.0.0.1:$proxyPort/v1/chat/completions", """{"model":"m"}""")
+            assertEquals(200, resp.code)
+            assertTrue(resp.body!!.contains(""""served_by":"backend""""))
+        } finally {
+            proxy.stop()
+        }
+
+        val recorded = backend.takeRequest(1, TimeUnit.SECONDS)
+        assertNotNull("backend should have received exactly one request", recorded)
+        assertEquals("/v1/chat/completions", recorded!!.path)
+
+        // No request should hit the peer.
+        assertNull(peer.takeRequest(100, TimeUnit.MILLISECONDS))
+    }
+
+    /* ------------------------------------------------------------------ */
+    /* Offload path — `prefer` (default) routes to peer when score high   */
+    /* ------------------------------------------------------------------ */
+
+    @Test
+    fun `chat-completion forwards to peer when offload prefer + peer score above threshold`() {
+        peer.enqueue(
+            MockResponse()
+                .setResponseCode(200)
+                .setHeader("Content-Type", "application/json")
+                .setBody("""{"served_by":"peer"}"""),
+        )
+
+        val proxy = makeProxy(
+            peers = listOf(fakePeer(scoreForModel = 50.0)),
+            pairingPolicy = pairingPolicyWithKey(),
+            minLocalCapability = 10.0,
+        )
+        val proxyPort = proxy.start(basePort = freePort(), maxAttempts = 8)
+        try {
+            val resp = postJson(
+                "http://127.0.0.1:$proxyPort/v1/chat/completions",
+                """{"model":"test-model"}""",
+            )
+            assertEquals(200, resp.code)
+            assertTrue(resp.body!!.contains(""""served_by":"peer""""))
+        } finally {
+            proxy.stop()
+        }
+
+        // Peer received it; backend did not.
+        val peerReq = peer.takeRequest(1, TimeUnit.SECONDS)
+        assertNotNull("peer should have received the offloaded request", peerReq)
+        assertEquals("/v1/chat/completions", peerReq!!.path)
+
+        // Identity headers must be present on peer-bound forwards.
+        assertEquals("self-device-id", peerReq.getHeader("X-DVAI-Peer-Device-Id"))
+        assertEquals("co.test.app", peerReq.getHeader("X-DVAI-App-Id"))
+        assertNotNull(peerReq.getHeader("X-DVAI-Nonce"))
+        assertNotNull(peerReq.getHeader("X-DVAI-Signature"))
+        assertEquals("1", peerReq.getHeader("X-DVAI-Forwarded"))
+
+        assertNull(backend.takeRequest(100, TimeUnit.MILLISECONDS))
+    }
+
+    /* ------------------------------------------------------------------ */
+    /* `never` header forces local even with peers                        */
+    /* ------------------------------------------------------------------ */
+
+    @Test
+    fun `X-DVAI-Offload never forces local even with strong peer`() {
+        backend.enqueue(
+            MockResponse()
+                .setResponseCode(200)
+                .setHeader("Content-Type", "application/json")
+                .setBody("""{"served_by":"backend"}"""),
+        )
+
+        val proxy = makeProxy(
+            peers = listOf(fakePeer(scoreForModel = 100.0)),
+            pairingPolicy = pairingPolicyWithKey(),
+        )
+        val proxyPort = proxy.start(basePort = freePort(), maxAttempts = 8)
+        try {
+            val resp = postJson(
+                "http://127.0.0.1:$proxyPort/v1/chat/completions",
+                """{"model":"test-model"}""",
+                extraHeaders = mapOf("X-DVAI-Offload" to "never"),
+            )
+            assertEquals(200, resp.code)
+            assertTrue(resp.body!!.contains(""""served_by":"backend""""))
+        } finally {
+            proxy.stop()
+        }
+
+        assertNotNull(backend.takeRequest(1, TimeUnit.SECONDS))
+        assertNull(peer.takeRequest(100, TimeUnit.MILLISECONDS))
+    }
+
+    /* ------------------------------------------------------------------ */
+    /* `require` header without peers → 503                               */
+    /* ------------------------------------------------------------------ */
+
+    @Test
+    fun `X-DVAI-Offload require with no peers returns no_capable_device`() {
+        val proxy = makeProxy(peers = emptyList())
+        val proxyPort = proxy.start(basePort = freePort(), maxAttempts = 8)
+        try {
+            val resp = postJson(
+                "http://127.0.0.1:$proxyPort/v1/chat/completions",
+                """{"model":"test-model"}""",
+                extraHeaders = mapOf("X-DVAI-Offload" to "require"),
+            )
+            assertEquals(503, resp.code)
+            assertTrue(resp.body!!.contains("no_capable_device"))
+        } finally {
+            proxy.stop()
+        }
+
+        assertNull(backend.takeRequest(100, TimeUnit.MILLISECONDS))
+        assertNull(peer.takeRequest(100, TimeUnit.MILLISECONDS))
+    }
+
+    /* ------------------------------------------------------------------ */
+    /* Offload-only mode (no backend) + no peers → 503                    */
+    /* ------------------------------------------------------------------ */
+
+    @Test
+    fun `offload-only mode with no peers returns no_local_backend`() {
+        val proxy = makeProxy(
+            backendBaseUrlOverride = null,
+            peers = emptyList(),
+        )
+        val proxyPort = proxy.start(basePort = freePort(), maxAttempts = 8)
+        try {
+            val resp = postJson(
+                "http://127.0.0.1:$proxyPort/v1/chat/completions",
+                """{"model":"test-model"}""",
+            )
+            assertEquals(503, resp.code)
+            // either no_local_backend (no offload) or no_capable_device (offload but no peers)
+            assertTrue(
+                "expected 503 with structured error, got: ${resp.body}",
+                resp.body!!.contains("no_local_backend") || resp.body.contains("no_capable_device"),
+            )
+        } finally {
+            proxy.stop()
+        }
+    }
+
+    /* ------------------------------------------------------------------ */
+    /* Helpers                                                            */
+    /* ------------------------------------------------------------------ */
+
+    private data class HttpResponseSnapshot(val code: Int, val body: String?)
+
+    /** Ask the OS for a free port, then close the socket so the proxy
+     *  can bind it on the next syscall. There's a tiny race window
+     *  but it's acceptable for unit tests. */
+    private fun freePort(): Int {
+        val socket = java.net.ServerSocket(0)
+        val port = socket.localPort
+        socket.close()
+        return port
+    }
+
+    private fun postJson(
+        url: String,
+        body: String,
+        extraHeaders: Map<String, String> = emptyMap(),
+    ): HttpResponseSnapshot {
+        val req = Request.Builder()
+            .url(url)
+            .post(body.toRequestBody("application/json".toMediaType()))
+            .apply { for ((k, v) in extraHeaders) header(k, v) }
+            .build()
+        return client.newCall(req).execute().use {
+            HttpResponseSnapshot(it.code, it.body?.string())
+        }
+    }
+
+    private fun pairingPolicyWithKey(): PairingPolicy {
+        // PairingStore writes to context.cacheDir/dvai-bridge — Robolectric
+        // provides a real cache dir. Pre-seed a pairing for our fake peer
+        // so the proxy's HMAC sign step finds a key.
+        val ctx = RuntimeEnvironment.getApplication()
+        val store = PairingStore(ctx)
+        store.clear()
+        store.set(
+            Pairing(
+                peerDeviceId = peerDeviceId,
+                peerDeviceName = "test-peer",
+                pairingKey = pairingKey,
+                pairedAt = System.currentTimeMillis(),
+                lastUsedAt = System.currentTimeMillis(),
+                via = PairingSource.LAN_HANDSHAKE,
+            ),
+        )
+        return PairingPolicy(store)
+    }
+
+}

package/android/src/test/java/co/deepvoiceai/bridge/ProgressBroadcasterTest.kt

@@ -0,0 +1,56 @@
+package co.deepvoiceai.bridge
+
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.take
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ProgressBroadcasterTest {
+    @Test
+    fun `flow and listener both receive emitted events`() = runTest {
+        val b = ProgressBroadcaster()
+        val captured = mutableListOf<ProgressEvent>()
+        b.addListener { captured.add(it) }
+
+        // Emit before any flow subscriber — the SharedFlow's replay buffer
+        // should make the most-recent event visible to a late subscriber.
+        b.emit(ProgressEvent.Started("phase-1"))
+
+        val replayed = b.flow.first()
+        assertTrue("late subscriber should see replay", replayed is ProgressEvent.Started)
+
+        b.emit(ProgressEvent.Progress("phase-1", percent = 0.5f, message = "halfway"))
+        b.emit(ProgressEvent.Completed("phase-1"))
+
+        // Listener saw all 3 events synchronously on the emit thread.
+        assertEquals(3, captured.size)
+        assertTrue(captured[0] is ProgressEvent.Started)
+        assertTrue(captured[1] is ProgressEvent.Progress)
+        assertTrue(captured[2] is ProgressEvent.Completed)
+    }
+
+    @Test
+    fun `removed listener stops receiving events`() {
+        val b = ProgressBroadcaster()
+        val captured = mutableListOf<ProgressEvent>()
+        val listener = ProgressListener { captured.add(it) }
+        b.addListener(listener)
+        b.emit(ProgressEvent.Started("p"))
+        b.removeListener(listener)
+        b.emit(ProgressEvent.Completed("p"))
+        assertEquals(1, captured.size)
+    }
+
+    @Test
+    fun `listener exception does not block other listeners`() {
+        val b = ProgressBroadcaster()
+        val good = mutableListOf<ProgressEvent>()
+        b.addListener { throw RuntimeException("misbehaving listener") }
+        b.addListener { good.add(it) }
+        b.emit(ProgressEvent.Started("p"))
+        assertEquals(1, good.size)
+    }
+}