@mentra/glasses-media 3.2.0-dev.225

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkObserver.kt

@@ -0,0 +1,160 @@
+package com.mentra.glassesmedia.network
+
+import com.mentra.glassesmedia.trace.SoftApTrace
+import org.webrtc.NetworkChangeDetector
+
+/**
+ * Owns libwebrtc's network state for as long as a scoped SoftAP is joined, and gives it back after.
+ *
+ * `getActiveNetworkList` is only a snapshot. libwebrtc's process-wide monitor also keeps every
+ * network it has ever been told about through [onNetworkConnect]. AutoDetect is constructed with
+ * this observer and reports cellular (and leftover home Wi-Fi) throughout the ACS join that happens
+ * *before* ingest starts, and those handles stay in the native list. Gathering unions the snapshot
+ * with that history, which is how a correct inventory still produced a lone cellular candidate.
+ *
+ * ## Ownership, not filtering
+ *
+ * The monitor is process-wide and the libwebrtc AAR is deliberately shared with LiveKit, so this
+ * cannot simply mute callbacks and walk away. The contract is explicit:
+ *
+ *  - **While SoftAP is joined** this observer owns the monitor. Stock connect/disconnect callbacks
+ *    are suppressed (but *recorded*), every handle outside the SoftAP inventory is disconnected,
+ *    and exactly that inventory is connected.
+ *  - **When the hotspot goes away** ownership is handed back by [restore]: the synthetic entry is
+ *    disconnected and every stock network whose callback was suppressed is replayed, so a WHEP or
+ *    LiveKit connection started afterwards sees real networks. Resuming pass-through alone is not
+ *    enough — the networks it never heard about would stay missing until the OS happened to
+ *    re-announce them.
+ *
+ * Restoration is driven from both directions, because either may come first: [publish] runs on
+ * every inventory read, and each stock callback checks too, since after teardown the OS may be the
+ * only thing still talking to us.
+ */
+internal class ScopedNetworkObserver(
+    private val downstream: NetworkChangeDetector.Observer,
+    private val scoped: () -> ScopedNetworkChangeDetector.ScopedInterface?,
+) : NetworkChangeDetector.Observer() {
+
+    private val lock = Any()
+
+    /**
+     * Stock networks by handle, kept whole rather than as bare handles: replaying a suppressed
+     * network on teardown requires the [NetworkChangeDetector.NetworkInformation] verbatim.
+     */
+    private val stock = linkedMapOf<Long, NetworkChangeDetector.NetworkInformation>()
+
+    private val published = mutableSetOf<Long>()
+    private var lastSignature: String? = null
+
+    /** True while this observer has taken over the monitor and still owes a [restore]. */
+    private var owning = false
+
+    /**
+     * Make native state match [inventory] whenever SoftAP is up. A no-op when the snapshot has not
+     * changed, so [ScopedNetworkChangeDetector.getActiveNetworkList] can call this on every read.
+     */
+    fun publish(inventory: List<NetworkChangeDetector.NetworkInformation>) {
+        if (scoped() == null) {
+            restore()
+            return
+        }
+        val signature =
+            inventory.joinToString("|") { info ->
+                val ips =
+                    info.ipAddresses.joinToString("/") { address ->
+                        ScopedNetworkChangeDetector.formatIpv4(address.address)
+                    }
+                "${info.handle}:${info.name}:$ips"
+            }
+        synchronized(lock) {
+            if (signature == lastSignature) return
+            lastSignature = signature
+            owning = true
+
+            val keep = inventory.map { it.handle }.toSet()
+            // Stock handles announced *before* the join are the ones that poison gathering, so
+            // they are disconnected here even though their callbacks were never forwarded.
+            val dropped = (stock.keys + published).filterNot { it in keep }
+            dropped.forEach { handle -> downstream.onNetworkDisconnect(handle) }
+            published.clear()
+            inventory.forEach { info ->
+                published.add(info.handle)
+                downstream.onNetworkConnect(info)
+            }
+            SoftApTrace.stage(
+                "webrtc_network_reconciled",
+                "published" to inventory.size,
+                "dropped" to dropped.size,
+            )
+        }
+    }
+
+    /**
+     * Hand the monitor back: drop the synthetic entry, replay every suppressed stock network.
+     *
+     * Idempotent, and safe to call when this observer never took ownership.
+     */
+    fun restore() {
+        synchronized(lock) {
+            if (!owning) return
+            owning = false
+            lastSignature = null
+
+            val synthetic = published.toList()
+            published.clear()
+            synthetic.forEach { handle -> downstream.onNetworkDisconnect(handle) }
+            // Replay rather than wait: these networks exist, and the monitor was told they did not.
+            stock.values.forEach { info -> downstream.onNetworkConnect(info) }
+            SoftApTrace.stage(
+                "webrtc_network_restored",
+                "syntheticDropped" to synthetic.size,
+                "stockReplayed" to stock.size,
+            )
+        }
+    }
+
+    override fun onConnectionTypeChanged(connectionType: NetworkChangeDetector.ConnectionType) {
+        if (scoped() != null) {
+            downstream.onConnectionTypeChanged(NetworkChangeDetector.ConnectionType.CONNECTION_WIFI)
+            return
+        }
+        restore()
+        downstream.onConnectionTypeChanged(connectionType)
+    }
+
+    override fun onNetworkConnect(networkInfo: NetworkChangeDetector.NetworkInformation) {
+        if (scoped() != null) {
+            synchronized(lock) { stock[networkInfo.handle] = networkInfo }
+            SoftApTrace.stage(
+                "webrtc_stock_connect_suppressed",
+                "name" to networkInfo.name,
+                "handle" to networkInfo.handle,
+            )
+            return
+        }
+        // Restore before recording, so this network is forwarded once below rather than also
+        // arriving in the replay.
+        restore()
+        synchronized(lock) { stock[networkInfo.handle] = networkInfo }
+        downstream.onNetworkConnect(networkInfo)
+    }
+
+    override fun onNetworkDisconnect(networkHandle: Long) {
+        if (scoped() != null) {
+            synchronized(lock) { stock.remove(networkHandle) }
+            return
+        }
+        restore()
+        synchronized(lock) { stock.remove(networkHandle) }
+        downstream.onNetworkDisconnect(networkHandle)
+    }
+
+    override fun onNetworkPreference(
+        types: List<NetworkChangeDetector.ConnectionType>,
+        preference: Int,
+    ) {
+        if (scoped() != null) return
+        restore()
+        downstream.onNetworkPreference(types, preference)
+    }
+}

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkReadiness.kt

@@ -0,0 +1,103 @@
+package com.mentra.glassesmedia.network
+
+/**
+ * Decides when a joined scoped network is actually ready for ICE to gather on.
+ *
+ * `onAvailable` is not that moment. Android's own guidance is to wait for `onLinkPropertiesChanged`
+ * and `onCapabilitiesChanged` rather than reading properties synchronously inside `onAvailable`, and
+ * on device the consequence was concrete: the hotspot address can land in the kernel's interface
+ * table *after* `onAvailable` returns, and libwebrtc gathers from that table. Starting ingest on
+ * `onAvailable` therefore raced the address into existence, and losing that race is indistinguishable
+ * from the wiring bugs it was mistaken for.
+ *
+ * Readiness needs agreement from three places, so all three are recorded separately and the missing
+ * one is named. The kernel table is the odd one out: it has no callback, so the shell polls it and
+ * feeds the answer in through [onInterfaceTable].
+ *
+ * Pure and mutable-but-self-contained, so the awkward orderings are unit testable without a device.
+ */
+class ScopedNetworkReadiness {
+
+    /** What each source has reported so far. Null means "not yet", not "absent". */
+    data class Observations(
+        val available: Boolean = false,
+        val capabilities: Boolean = false,
+        val linkInterface: String? = null,
+        val linkAddress: String? = null,
+        val tableOwner: String? = null,
+    )
+
+    sealed interface Verdict {
+        /**
+         * [owner] is the interface the kernel says holds [address]. It can differ from
+         * [interfaceName], which is what `LinkProperties` claimed — a disagreement worth logging,
+         * not worth blocking on, since ICE only ever uses the address.
+         */
+        data class Ready(
+            val address: String,
+            val interfaceName: String?,
+            val owner: String,
+        ) : Verdict
+
+        /** [missing] names the one source still to report, for the timeout message. */
+        data class Waiting(val missing: String) : Verdict
+    }
+
+    @Volatile
+    var observations = Observations()
+        private set
+
+    private val lock = Any()
+
+    fun onAvailable() = update { it.copy(available = true) }
+
+    fun onCapabilities() = update { it.copy(capabilities = true) }
+
+    /**
+     * Taken verbatim: `LinkProperties` carries the network's whole current state, so a later
+     * callback without an address means the address is gone, not that the old one still holds.
+     */
+    fun onLinkProperties(interfaceName: String?, address: String?) =
+        update { it.copy(linkInterface = interfaceName, linkAddress = address) }
+
+    /** Seed from the synchronous read in `onAvailable`; never clears what a callback reported. */
+    fun seedLinkProperties(interfaceName: String?, address: String?) =
+        update {
+            if (address == null) it else it.copy(linkInterface = interfaceName, linkAddress = address)
+        }
+
+    fun onInterfaceTable(owner: String?) = update { it.copy(tableOwner = owner) }
+
+    fun reset() = update { Observations() }
+
+    fun verdict(): Verdict = verdictOf(observations)
+
+    /** True once everything with a callback has reported, so only the table poll is left. */
+    fun callbacksSatisfied(): Boolean = callbacksSatisfiedBy(observations)
+
+    private inline fun update(transform: (Observations) -> Observations) {
+        synchronized(lock) { observations = transform(observations) }
+    }
+
+    companion object {
+        fun callbacksSatisfiedBy(observations: Observations): Boolean =
+            observations.available && observations.capabilities && observations.linkAddress != null
+
+        /** Ordered so the named blocker is the earliest unmet one, which is the useful one. */
+        fun verdictOf(observations: Observations): Verdict =
+            when {
+                !observations.available -> Verdict.Waiting("onAvailable")
+                !observations.capabilities -> Verdict.Waiting("onCapabilitiesChanged")
+                observations.linkAddress == null ->
+                    Verdict.Waiting("an IPv4 address from onLinkPropertiesChanged")
+                observations.tableOwner == null ->
+                    Verdict.Waiting("the kernel interface table to carry ${observations.linkAddress}")
+                else ->
+                    Verdict.Ready(
+                        observations.linkAddress,
+                        observations.linkInterface,
+                        observations.tableOwner,
+                    )
+            }
+    }
+}

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkRequestSpec.kt

@@ -0,0 +1,53 @@
+package com.mentra.glassesmedia.network
+
+import android.net.NetworkCapabilities
+
+/**
+ * Declarative description of the SoftAP network request.
+ *
+ * `NetworkRequest.Builder` cannot be constructed in a plain JVM test, so the shape of the request
+ * lives here as data and [ScopedSoftApNetwork] translates it into the real builder. That makes the
+ * one property this architecture depends on — that the request does **not** ask for
+ * `NET_CAPABILITY_INTERNET` — assertable without a device.
+ *
+ * Dropping the internet capability is what keeps the phone dual-homed: Android will not promote the
+ * glasses hotspot to the default network, so ACS traffic stays on cellular while media crosses the
+ * local link. The other half of that guarantee is the MTK firmware patch that stops the AP
+ * advertising a default route.
+ */
+data class ScopedNetworkRequestSpec(
+    val ssid: String,
+    val passphrase: String,
+    val transportTypes: Set<Int>,
+    val removedCapabilities: Set<Int>,
+    val timeoutMs: Int,
+) {
+    /** True when the request cannot be satisfied by, or promoted to, an internet-bearing network. */
+    val avoidsInternetCapability: Boolean
+        get() = removedCapabilities.contains(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+
+    val hasPassphrase: Boolean
+        get() = passphrase.isNotEmpty()
+
+    companion object {
+        /**
+         * Android caps `requestNetwork` timeouts well above this; 30 s matches the value the
+         * Bluetooth SDK already uses for the same hotspot and is long enough for a cold AP start.
+         */
+        const val DEFAULT_TIMEOUT_MS = 30_000
+
+        /** The canonical SoftAP request. Every caller should go through this. */
+        fun forSoftAp(
+            ssid: String,
+            passphrase: String,
+            timeoutMs: Int = DEFAULT_TIMEOUT_MS,
+        ): ScopedNetworkRequestSpec =
+            ScopedNetworkRequestSpec(
+                ssid = ssid,
+                passphrase = passphrase,
+                transportTypes = setOf(NetworkCapabilities.TRANSPORT_WIFI),
+                removedCapabilities = setOf(NetworkCapabilities.NET_CAPABILITY_INTERNET),
+                timeoutMs = timeoutMs,
+            )
+    }
+}

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkState.kt

@@ -0,0 +1,127 @@
+package com.mentra.glassesmedia.network
+
+/**
+ * Pure lifecycle state machine for a scoped SoftAP network join.
+ *
+ * Split from the Android shell so the awkward parts — duplicate callbacks, callbacks arriving after
+ * a cancel, a timeout racing a late `onAvailable` — are unit testable without a device. The shell
+ * ([ScopedSoftApNetwork]) owns `ConnectivityManager` and forwards raw callbacks in here.
+ *
+ * `ConnectivityManager` gives no ordering or at-most-once guarantee: `onAvailable` can fire more
+ * than once, `onCapabilitiesChanged` fires repeatedly, and callbacks from a request that was already
+ * unregistered can still land. Every transition below is therefore idempotent and generation-guarded.
+ */
+class ScopedNetworkState {
+
+    enum class Phase {
+        /** No request outstanding. */
+        IDLE,
+
+        /** `requestNetwork` issued, waiting for a usable network. */
+        REQUESTING,
+
+        /** Network joined and usable. */
+        AVAILABLE,
+
+        /** Terminal for this generation: released, lost, timed out, or failed. */
+        LOST,
+    }
+
+    /** Why a join ended without producing a usable network. */
+    enum class Failure {
+        NONE,
+        TIMEOUT,
+        UNAVAILABLE,
+        LOST,
+        PERMISSION_DENIED,
+        REQUEST_FAILED,
+    }
+
+    var phase: Phase = Phase.IDLE
+        private set
+
+    var failure: Failure = Failure.NONE
+        private set
+
+    /** Incremented on every new request so late callbacks from an old one can be rejected. */
+    var generation: Int = 0
+        private set
+
+    val isActive: Boolean
+        get() = phase == Phase.REQUESTING || phase == Phase.AVAILABLE
+
+    /**
+     * Begin a new join. Any in-flight generation is abandoned, so its callbacks become stale.
+     *
+     * @return the generation for this request; pass it back to every callback
+     */
+    fun startRequest(): Int {
+        generation += 1
+        phase = Phase.REQUESTING
+        failure = Failure.NONE
+        return generation
+    }
+
+    /** True when a callback belongs to the current, still-active generation. */
+    fun accepts(callbackGeneration: Int): Boolean = callbackGeneration == generation && isActive
+
+    /**
+     * A usable network arrived.
+     *
+     * @return true if this transitioned the machine; false when stale or already available
+     */
+    fun onAvailable(callbackGeneration: Int): Boolean {
+        if (!accepts(callbackGeneration)) return false
+        if (phase == Phase.AVAILABLE) return false // duplicate onAvailable
+        phase = Phase.AVAILABLE
+        return true
+    }
+
+    /** The request timed out before a usable network arrived. Ignored once available. */
+    fun onTimeout(callbackGeneration: Int): Boolean {
+        if (callbackGeneration != generation) return false
+        if (phase != Phase.REQUESTING) return false
+        phase = Phase.LOST
+        failure = Failure.TIMEOUT
+        return true
+    }
+
+    /** The framework reported the network cannot be provided. */
+    fun onUnavailable(callbackGeneration: Int): Boolean {
+        if (!accepts(callbackGeneration)) return false
+        phase = Phase.LOST
+        failure = Failure.UNAVAILABLE
+        return true
+    }
+
+    /** The joined network went away. This is the one the call path must react to. */
+    fun onLost(callbackGeneration: Int): Boolean {
+        if (!accepts(callbackGeneration)) return false
+        phase = Phase.LOST
+        failure = Failure.LOST
+        return true
+    }
+
+    /** `requestNetwork` threw, or the local-network permission was denied. */
+    fun onRequestFailed(callbackGeneration: Int, permissionDenied: Boolean): Boolean {
+        if (callbackGeneration != generation) return false
+        if (!isActive) return false
+        phase = Phase.LOST
+        failure = if (permissionDenied) Failure.PERMISSION_DENIED else Failure.REQUEST_FAILED
+        return true
+    }
+
+    /** Caller-initiated teardown. Not a failure. */
+    fun release(): Boolean {
+        if (!isActive) return false
+        phase = Phase.LOST
+        failure = Failure.NONE
+        return true
+    }
+
+    /** Return to IDLE so the same instance can be reused for the next call. */
+    fun reset() {
+        phase = Phase.IDLE
+        failure = Failure.NONE
+    }
+}