@dvai-bridge/android-shared-core 4.0.0

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/CorsConfig.kt

@@ -0,0 +1,37 @@
+package co.deepvoiceai.bridge.shared.core
+
+/** CORS configuration for the dispatch layer. */
+sealed class CorsConfig {
+    object Wildcard : CorsConfig()
+    data class Exact(val origin: String) : CorsConfig()
+    data class Allowlist(val origins: List<String>) : CorsConfig()
+
+    /**
+     * Resolve the `Access-Control-Allow-Origin` header value for an incoming
+     * request. Returns null when the request origin isn't allowed (callers
+     * skip emitting the header in that case).
+     */
+    fun headerValue(reqOrigin: String?): String? = when (this) {
+        is Wildcard -> "*"
+        is Exact -> origin
+        is Allowlist -> if (reqOrigin != null && origins.contains(reqOrigin)) reqOrigin else null
+    }
+
+    companion object {
+        /**
+         * Map the JS-bridge `corsOrigin` opt onto a [CorsConfig]:
+         *   - `"*"`           -> [Wildcard]
+         *   - `"https://..."`  -> [Exact]
+         *   - `["https://...", ...]` -> [Allowlist]
+         *   - anything else   -> [Wildcard] (fail-open default)
+         *
+         * Same conventions as the iOS DVAISharedCore `parseCors` helper
+         * — keep them in lockstep when changing.
+         */
+        fun fromOpt(raw: Any?): CorsConfig = when (raw) {
+            is String -> if (raw == "*") Wildcard else Exact(raw)
+            is List<*> -> Allowlist(raw.filterIsInstance<String>())
+            else -> Wildcard
+        }
+    }
+}

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/DvaiHandlers.kt

@@ -0,0 +1,20 @@
+package co.deepvoiceai.bridge.shared.core
+
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * The handler-set contract every backend implements. The 4 methods map
+ * 1:1 to the OpenAI-compatible HTTP routes installed by
+ * [Routing.installDispatchRoutes][installDispatchRoutes]:
+ *
+ *   POST /v1/chat/completions  -> [handleChatCompletion]
+ *   POST /v1/completions       -> [handleCompletion]
+ *   POST /v1/embeddings        -> [handleEmbeddings]
+ *   GET  /v1/models            -> [handleModels]
+ */
+interface DvaiHandlers {
+    suspend fun handleChatCompletion(body: JsonObject, ctx: HandlerContext): HandlerResponse
+    suspend fun handleCompletion(body: JsonObject, ctx: HandlerContext): HandlerResponse
+    suspend fun handleEmbeddings(body: JsonObject, ctx: HandlerContext): HandlerResponse
+    suspend fun handleModels(ctx: HandlerContext): HandlerResponse
+}

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/HandlerContext.kt

@@ -0,0 +1,10 @@
+package co.deepvoiceai.bridge.shared.core
+
+/**
+ * Per-request context passed to every [DvaiHandlers] method.
+ *
+ * Both fields are surfaced in the OpenAI-compatible JSON responses (e.g.
+ * the `model` field of `/v1/chat/completions` results) so the consumer
+ * sees a stable name regardless of which backend handled the request.
+ */
+data class HandlerContext(val modelId: String, val backendName: String)

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/HandlerDispatch.kt

@@ -0,0 +1,98 @@
+package co.deepvoiceai.bridge.shared.core
+
+import io.ktor.http.*
+import io.ktor.server.application.*
+import io.ktor.server.request.*
+import io.ktor.server.response.*
+import io.ktor.server.routing.*
+import kotlinx.serialization.json.*
+
+/** Add CORS + PNA headers to a response. */
+fun applyCors(call: ApplicationCall, config: CorsConfig) {
+    call.response.headers.append("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
+    call.response.headers.append("Access-Control-Allow-Headers", "Content-Type, Authorization")
+    call.response.headers.append("Access-Control-Allow-Private-Network", "true")
+    config.headerValue(call.request.header("Origin"))?.let {
+        call.response.headers.append("Access-Control-Allow-Origin", it)
+    }
+}
+
+/** Install the standard 4-route OpenAI API + OPTIONS preflight + 404 catch-all. */
+fun Routing.installDispatchRoutes(handlers: DvaiHandlers, ctx: HandlerContext, config: CorsConfig) {
+    options("{...}") {
+        applyCors(call, config)
+        call.respond(HttpStatusCode.NoContent)
+    }
+    post("/v1/chat/completions") {
+        applyCors(call, config)
+        val body = parseBody(call.receiveText())
+        respondWithHandlerResponse(call, handlers.handleChatCompletion(body, ctx), config)
+    }
+    post("/v1/completions") {
+        applyCors(call, config)
+        val body = parseBody(call.receiveText())
+        respondWithHandlerResponse(call, handlers.handleCompletion(body, ctx), config)
+    }
+    post("/v1/embeddings") {
+        applyCors(call, config)
+        val body = parseBody(call.receiveText())
+        respondWithHandlerResponse(call, handlers.handleEmbeddings(body, ctx), config)
+    }
+    get("/v1/models") {
+        applyCors(call, config)
+        respondWithHandlerResponse(call, handlers.handleModels(ctx), config)
+    }
+    // Catch-all -> 404 with CORS
+    route("{...}") {
+        handle {
+            applyCors(call, config)
+            call.respondText(
+                buildJsonObject { put("error", "not found") }.toString(),
+                ContentType.Application.Json,
+                HttpStatusCode.NotFound,
+            )
+        }
+    }
+}
+
+private fun parseBody(raw: String): JsonObject {
+    if (raw.isBlank()) return JsonObject(emptyMap())
+    return try {
+        Json.parseToJsonElement(raw) as? JsonObject ?: JsonObject(emptyMap())
+    } catch (e: Exception) {
+        JsonObject(emptyMap())
+    }
+}
+
+private suspend fun respondWithHandlerResponse(
+    call: ApplicationCall,
+    response: HandlerResponse,
+    @Suppress("UNUSED_PARAMETER") config: CorsConfig,
+) {
+    when (response) {
+        is HandlerResponse.Json -> {
+            call.respondText(
+                response.body.toString(),
+                ContentType.Application.Json,
+                HttpStatusCode.fromValue(response.status),
+            )
+        }
+        is HandlerResponse.Sse -> {
+            // SSE: collect into single buffer for Phase 1 (true streaming deferred).
+            val buf = StringBuilder()
+            response.flow.collect { chunk -> buf.append(chunk) }
+            call.respondText(
+                buf.toString(),
+                ContentType.parse("text/event-stream"),
+                HttpStatusCode.OK,
+            )
+        }
+        is HandlerResponse.Error -> {
+            call.respondText(
+                buildJsonObject { put("error", response.message) }.toString(),
+                ContentType.Application.Json,
+                HttpStatusCode.fromValue(response.status),
+            )
+        }
+    }
+}

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/HandlerResponse.kt

@@ -0,0 +1,11 @@
+package co.deepvoiceai.bridge.shared.core
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.serialization.json.JsonElement
+
+/** What a [DvaiHandlers] method returns. */
+sealed class HandlerResponse {
+    data class Json(val status: Int, val body: JsonElement) : HandlerResponse()
+    data class Sse(val flow: Flow<String>) : HandlerResponse()
+    data class Error(val status: Int, val message: String) : HandlerResponse()
+}

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/HttpServer.kt

@@ -0,0 +1,126 @@
+package co.deepvoiceai.bridge.shared.core
+
+import io.ktor.server.application.*
+import io.ktor.server.cio.CIO
+import io.ktor.server.engine.ApplicationEngine
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.routing.*
+import kotlinx.coroutines.delay
+
+/**
+ * Wraps Ktor's CIO embedded server with port-fallback bind logic.
+ *
+ * Ktor 2.3.7's `embeddedServer(CIO, ...) { ... }` returns a
+ * `BaseApplicationEngine` which is a subtype of [ApplicationEngine].
+ * We hold the engine through that interface — `start(wait)` and
+ * `stop(...)` are defined on it.
+ */
+class HttpServer {
+    @Volatile private var engine: ApplicationEngine? = null
+    @Volatile var boundPort: Int? = null
+        private set
+
+    /**
+     * Try to bind to `basePort`, falling back to `basePort+1`, ..., up to
+     * `maxAttempts` ports. Returns the port that bound successfully.
+     * Throws [IllegalStateException] if all ports in the range are unavailable.
+     */
+    suspend fun tryBind(basePort: Int, maxAttempts: Int, host: String): Int {
+        val lastPort = basePort + maxAttempts - 1
+        for (i in 0 until maxAttempts) {
+            val port = basePort + i
+            val candidate: ApplicationEngine = embeddedServer(CIO, port = port, host = host) {
+                // routes installed later via configure() in Task 29
+            }
+            try {
+                candidate.start(wait = false)
+                // CIO's start(wait = false) returns before the listening
+                // socket is fully established. Probe the port to confirm
+                // we actually grabbed it (vs. getting a silent failure).
+                delay(100)
+                if (!isListening(host, port)) {
+                    runCatching { candidate.stop(0L, 100L) }
+                    continue
+                }
+                this.engine = candidate
+                this.boundPort = port
+                return port
+            } catch (_: Exception) {
+                // BindException, IOException, or wrapped variant — try next port.
+                runCatching { candidate.stop(0L, 100L) }
+                continue
+            }
+        }
+        throw IllegalStateException(
+            "[DVAI] Could not bind HTTP transport to any port in range " +
+                "$basePort..$lastPort (all in use). " +
+                "Another local AI server may already be running.",
+        )
+    }
+
+    /**
+     * Bind with port-fallback AND install the dispatch routes for the given
+     * handler set. Returns the port that bound successfully. Throws
+     * [IllegalStateException] if all ports in the range are unavailable.
+     */
+    suspend fun startWithRoutes(
+        basePort: Int,
+        maxAttempts: Int,
+        host: String,
+        handlers: DvaiHandlers,
+        ctx: HandlerContext,
+        corsConfig: CorsConfig,
+    ): Int {
+        val lastPort = basePort + maxAttempts - 1
+        for (i in 0 until maxAttempts) {
+            val port = basePort + i
+            val candidate: ApplicationEngine = embeddedServer(CIO, port = port, host = host) {
+                routing { installDispatchRoutes(handlers, ctx, corsConfig) }
+            }
+            try {
+                candidate.start(wait = false)
+                delay(100)
+                if (!isListening(host, port)) {
+                    runCatching { candidate.stop(0L, 100L) }
+                    continue
+                }
+                this.engine = candidate
+                this.boundPort = port
+                return port
+            } catch (_: Exception) {
+                runCatching { candidate.stop(0L, 100L) }
+                continue
+            }
+        }
+        throw IllegalStateException(
+            "[DVAI] Could not bind HTTP transport to any port in range " +
+                "$basePort..$lastPort (all in use). " +
+                "Another local AI server may already be running.",
+        )
+    }
+
+    /** Stops the server. Idempotent — safe to call multiple times. */
+    suspend fun stop() {
+        val s = engine ?: return
+        engine = null
+        boundPort = null
+        try {
+            s.stop(gracePeriodMillis = 100, timeoutMillis = 1000)
+        } catch (_: Exception) {
+            // best-effort
+        }
+    }
+
+    fun isRunning(): Boolean = engine != null
+
+    private fun isListening(host: String, port: Int): Boolean {
+        return try {
+            java.net.Socket().use { sock ->
+                sock.connect(java.net.InetSocketAddress(host, port), 200)
+                true
+            }
+        } catch (_: Exception) {
+            false
+        }
+    }
+}

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/capability/CapabilityCache.kt

@@ -0,0 +1,78 @@
+package co.deepvoiceai.bridge.shared.core.capability
+
+import android.content.Context
+import java.io.File
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.builtins.MapSerializer
+import kotlinx.serialization.builtins.serializer
+import kotlinx.serialization.json.Json
+
+/**
+ * Persistent capability-score cache backed by a single JSON file under
+ * `applicationContext.cacheDir/dvai-bridge/capability.json`. Mirrors
+ * the `CapabilityCache` interface from `@dvai-bridge/core`.
+ *
+ * Thread-safety: all read/write is synchronized via the instance lock
+ * since the file is shared by the whole process. Cross-process
+ * concurrency isn't a concern — only one DVAIBridge runs per app.
+ */
+class CapabilityCache(context: Context) {
+    private val cacheRoot: File =
+        File(context.applicationContext.cacheDir, "dvai-bridge").also {
+            if (!it.exists()) it.mkdirs()
+        }
+    private val file: File = File(cacheRoot, "capability.json")
+    private val json = Json { ignoreUnknownKeys = true; prettyPrint = true }
+    private val lock = Any()
+
+    @Serializable
+    private data class Persisted(
+        val scores: Map<String, CapabilityScore> = emptyMap(),
+    )
+
+    private fun load(): MutableMap<String, CapabilityScore> = synchronized(lock) {
+        if (!file.exists()) return mutableMapOf()
+        return try {
+            val raw = file.readText(Charsets.UTF_8)
+            val parsed = json.decodeFromString(Persisted.serializer(), raw)
+            parsed.scores.toMutableMap()
+        } catch (_: Throwable) {
+            // Corrupt cache — start fresh. Next save() overwrites.
+            mutableMapOf()
+        }
+    }
+
+    private fun save(scores: Map<String, CapabilityScore>) = synchronized(lock) {
+        try {
+            file.writeText(
+                json.encodeToString(Persisted.serializer(), Persisted(scores)),
+                Charsets.UTF_8,
+            )
+        } catch (_: Throwable) {
+            // Best-effort. Next save() retries.
+        }
+    }
+
+    private fun keyOf(k: CapabilityCacheKey): String = "${k.libraryVersion}::${k.modelId}"
+
+    fun get(key: CapabilityCacheKey): CapabilityScore? = load()[keyOf(key)]
+
+    fun set(score: CapabilityScore) {
+        synchronized(lock) {
+            val map = load()
+            map[keyOf(CapabilityCacheKey(score.modelId, score.libraryVersion))] = score
+            save(map)
+        }
+    }
+
+    fun list(): List<CapabilityScore> = load().values.toList()
+
+    fun clear() {
+        synchronized(lock) {
+            if (file.exists()) file.delete()
+        }
+    }
+
+    /** Path on disk — exposed for diagnostics + tests. */
+    fun cachePath(): String = file.absolutePath
+}

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/capability/CapabilityScore.kt

@@ -0,0 +1,41 @@
+package co.deepvoiceai.bridge.shared.core.capability
+
+import kotlinx.serialization.Serializable
+
+/**
+ * Phase 3 — capability score (Kotlin mirror of `CapabilityScore` in
+ * `@dvai-bridge/core/src/capability/types.ts`).
+ *
+ * A "capability score" is an estimate of decode tok/s for a given
+ * (model, device) pair on this device. Used by the offload decider
+ * to pick local vs. peer execution per request.
+ */
+@Serializable
+data class CapabilityScore(
+    /** Model identifier this score applies to. */
+    val modelId: String,
+    /** Stable per-install device identifier. */
+    val deviceId: String,
+    /** Library SemVer at the time the score was measured. */
+    val libraryVersion: String,
+    /** Estimated decode rate, tokens-per-second. */
+    val tokPerSec: Double,
+    /** Source of the estimate. */
+    val source: ScoreSource,
+    /** Unix milliseconds the score was measured / computed. */
+    val measuredAt: Long,
+)
+
+@Serializable
+enum class ScoreSource {
+    @kotlinx.serialization.SerialName("probe")
+    PROBE,
+    @kotlinx.serialization.SerialName("heuristic")
+    HEURISTIC,
+}
+
+/** Composite key for [CapabilityCache] — mirrors the TS `CapabilityCacheKey`. */
+data class CapabilityCacheKey(
+    val modelId: String,
+    val libraryVersion: String,
+)

package/android/src/main/java/co/deepvoiceai/bridge/shared/core/capability/DeviceID.kt

@@ -0,0 +1,95 @@
+package co.deepvoiceai.bridge.shared.core.capability
+
+import android.content.Context
+import java.io.File
+import java.security.SecureRandom
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+
+/**
+ * Stable per-install device identifier (Kotlin mirror of
+ * `@dvai-bridge/core/src/capability/deviceId.ts`).
+ *
+ * - Generated once on first call, then persisted under
+ *   `applicationContext.cacheDir/dvai-bridge/device.json`.
+ * - Used to identify THIS device in mDNS TXT records, rendezvous
+ *   pairing payloads, and as the key for the capability cache.
+ *
+ * NOT a privacy hazard: the ID is per-install and per-cache-storage,
+ * never tied to user identity. Reinstalling the app or wiping app
+ * storage produces a fresh ID — that's the right behaviour.
+ */
+object DeviceID {
+    private const val FILENAME = "device.json"
+    private const val CACHE_DIR_NAME = "dvai-bridge"
+
+    @Serializable
+    private data class DeviceFile(val deviceId: String)
+
+    private val json = Json { ignoreUnknownKeys = true; prettyPrint = true }
+
+    /**
+     * Read the persistent device ID, generating + persisting one if
+     * none exists. Safe to call from any thread; the file write
+     * is atomic-enough for the per-install lifetime guarantee
+     * (single-writer, never concurrent across processes).
+     */
+    @Synchronized
+    fun get(context: Context): String {
+        val dir = File(context.applicationContext.cacheDir, CACHE_DIR_NAME)
+        if (!dir.exists()) dir.mkdirs()
+        val file = File(dir, FILENAME)
+        if (file.exists()) {
+            try {
+                val txt = file.readText(Charsets.UTF_8)
+                val parsed = json.decodeFromString(DeviceFile.serializer(), txt)
+                if (parsed.deviceId.isNotEmpty()) return parsed.deviceId
+            } catch (_: Throwable) {
+                // Fall through and regenerate on parse error.
+            }
+        }
+        val fresh = generate()
+        try {
+            file.writeText(json.encodeToString(DeviceFile.serializer(), DeviceFile(fresh)), Charsets.UTF_8)
+        } catch (_: Throwable) {
+            // If we can't persist, the caller still gets a valid ID for
+            // this process; the next call will try again.
+        }
+        return fresh
+    }
+
+    /**
+     * Reset the persisted device ID. Returns the new ID. Mainly for
+     * tests + the "forget all paired peers" UI.
+     */
+    @Synchronized
+    fun reset(context: Context): String {
+        val dir = File(context.applicationContext.cacheDir, CACHE_DIR_NAME)
+        if (!dir.exists()) dir.mkdirs()
+        val file = File(dir, FILENAME)
+        val fresh = generate()
+        file.writeText(json.encodeToString(DeviceFile.serializer(), DeviceFile(fresh)), Charsets.UTF_8)
+        return fresh
+    }
+
+    /** Generate a 22-char URL-safe random ID. Equivalent to the TS impl. */
+    fun generate(): String {
+        val bytes = ByteArray(16)
+        SecureRandom().nextBytes(bytes)
+        return base64UrlEncode(bytes)
+    }
+
+    private fun base64UrlEncode(bytes: ByteArray): String {
+        val sb = StringBuilder()
+        val b64 = java.util.Base64.getEncoder().encodeToString(bytes)
+        for (c in b64) {
+            when (c) {
+                '+' -> sb.append('-')
+                '/' -> sb.append('_')
+                '=' -> Unit // strip padding
+                else -> sb.append(c)
+            }
+        }
+        return sb.toString()
+    }
+}