@mentra/acs-meeting 3.2.0-dev.221 → 3.2.0-dev.222

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

@@ -0,0 +1,103 @@
+package com.mentra.acsmeeting.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/acsmeeting/network/ScopedNetworkRequestSpec.kt

@@ -0,0 +1,53 @@
+package com.mentra.acsmeeting.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/acsmeeting/network/ScopedNetworkState.kt

@@ -0,0 +1,127 @@
+package com.mentra.acsmeeting.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
+    }
+}