@mentra/glasses-media 3.2.0-dev.261 → 3.2.0-dev.262

package/android/src/main/java/com/mentra/glassesmedia/GlassesMediaRelayModule.kt

@@ -38,7 +38,9 @@ class GlassesMediaRelayModule : Module() {
           val context = requireNotNull(appContext.reactContext).applicationContext
           activeId = id
           val hold = InternetHold(context).also { internet = it }
-          check(hold.awaitValidatedCellular().validated) { "Turn on phone mobile data to stream through the glasses hotspot" }
+          check(hold.awaitValidatedCellular().validated) {
+            "Turn on phone mobile data to stream through the glasses hotspot"
+          }
           val scoped = ScopedSoftApNetwork(context).also { network = it }
           if (!scoped.isWifiEnabled()) {
             Handler(Looper.getMainLooper()).post {

package/android/src/main/java/com/mentra/glassesmedia/source/GlassesMediaSource.kt

@@ -1,5 +1,7 @@
 package com.mentra.glassesmedia.source
 
+import com.mentra.glassesmedia.trace.SoftApTrace
+
 enum class SourceKind {
   /** Subscribe to a Cloudflare WHEP endpoint. The phone is the offerer. */
   WHEP,
@@ -83,6 +85,18 @@ interface GlassesMediaSource {
   fun setPcmDeliveryEnabled(enabled: Boolean)
   fun setTargetSize(size: TargetSize?) {}
   fun setStateListener(listener: SourceStateListener?) {}
+
+  /**
+   * Drop a retiring SoftAP listener now, skipping its tombstone. No-op for every other kind.
+   *
+   * After [restart], this is the previous listener generation — not the one that just bound.
+   */
+  fun forceCloseIngest() {}
+
+  /**
+   * Has the retiring SoftAP listener released its port? `true` when there is nothing to wait for.
+   */
+  fun awaitIngestClosed(timeoutMs: Long): Boolean = true
 }
 
 /**
@@ -106,8 +120,11 @@ class GlassesMediaController(
    * [stop] drops the source, but a WHIP listener answers `410` for a few seconds after that and
    * still holds its port. Losing the reference here is what made the port's release unobservable
    * from above, so the next call bound into it.
+   *
+   * After [rebindIngest], this is the current source: [GlassesMediaSource.restart] parks the
+   * previous listener on that object, so [forceCloseIngest] / [awaitIngestClosed] stay unambiguous.
    */
-  private var retiringIngest: LocalWhipIngestSource? = null
+  private var retiringIngest: GlassesMediaSource? = null
 
   val state: SourceState
     get() = source?.state ?: SourceState.IDLE
@@ -128,6 +145,48 @@ class GlassesMediaController(
     source?.restart(config)
   }
 
+  /**
+   * Destroy the current SoftAP listener generation and bind a new one.
+   *
+   * [GlassesMediaSource.restart] is [LocalWhipIngestSource.start]: it parks the old listener as
+   * retiring and binds a new OS-chosen port. This then force-closes that parked generation —
+   * no tombstone wait — and refuses a null or unchanged URL so a stale listener cannot be reused.
+   *
+   * Does not call [LocalWhipIngestSource.close], which would dispose the shared
+   * PeerConnectionFactory.
+   */
+  fun rebindIngest(config: SourceConfig, timeoutMs: Long): String {
+    if (!MediaDiagnostics.SOFTAP_RECOVERY_ENABLED) {
+      SoftApTrace.failure("ingest_rebind_disabled")
+      throw IllegalStateException("SoftAP ingest rebind is disabled")
+    }
+    val current = source ?: throw IllegalStateException("No media source to rebind")
+    val oldUrl = ingestUrl
+    current.restart(config)
+    val newUrl = ingestUrl
+    if (newUrl.isNullOrBlank() || newUrl == oldUrl) {
+      SoftApTrace.failure("ingest_rebind_stale", "oldUrl" to oldUrl, "newUrl" to newUrl)
+      throw IllegalStateException(
+        "SoftAP ingest rebind did not mint a new listener (old=$oldUrl new=$newUrl)",
+      )
+    }
+    // After restart the current source's retiring handle is the previous listener.
+    retiringIngest = current
+    forceCloseIngest()
+    val closed = awaitIngestClosed(timeoutMs)
+    SoftApTrace.stage(
+      "ingest_rebind",
+      "oldUrl" to oldUrl,
+      "newUrl" to newUrl,
+      "closed" to closed,
+    )
+    if (!closed) {
+      SoftApTrace.failure("ingest_rebind_close_failed", "oldUrl" to oldUrl, "newUrl" to newUrl)
+      throw IllegalStateException("SoftAP ingest rebind did not release the old listener")
+    }
+    return newUrl
+  }
+
   fun forceRestart() {
     source?.forceRestart()
   }

package/android/src/main/java/com/mentra/glassesmedia/source/LocalWhipIngestSource.kt

@@ -183,7 +183,7 @@ class LocalWhipIngestSource(
    * Trivially true when nothing was ever bound, so a teardown after a join that failed before the
    * listener existed does not spend the whole bound discovering there is nothing to wait for.
    */
-  fun awaitIngestClosed(timeoutMs: Long): Boolean = (retiring ?: server)?.awaitClosed(timeoutMs) ?: true
+  override fun awaitIngestClosed(timeoutMs: Long): Boolean = (retiring ?: server)?.awaitClosed(timeoutMs) ?: true
 
   /**
    * Drop the listener now, tombstone or not.
@@ -192,7 +192,7 @@ class LocalWhipIngestSource(
    * gets a connection reset instead of `410`, which is a worse answer — but it is a better outcome
    * than a next call that cannot bind its port.
    */
-  fun forceCloseIngest() {
+  override fun forceCloseIngest() {
     // Keep the handle: forceSoftapCleanup re-asks awaitIngestClosed to confirm the port is really
     // free. Nulling here would make that check read `null -> true` and mask a closeNow that threw,
     // so the next Start binds a port this listener still holds. closeNow/awaitClosed are idempotent,

package/android/src/main/java/com/mentra/glassesmedia/source/VideoSourceArm.kt

@@ -102,6 +102,16 @@ object MediaDiagnostics {
    * timestamps is what makes the Teams jitter buffer hold.
    */
   const val acsAudioTimestamps = true
+
+  /**
+   * SoftAP ingest rebind kill switch. Ships on.
+   *
+   * When false, [GlassesMediaController.rebindIngest] refuses rather than destroying the live
+   * listener. Flip locally to freeze recovery without a rebuild.
+   */
+  @JvmField
+  @Volatile
+  var SOFTAP_RECOVERY_ENABLED = true
 }
 
 data class SyntheticConfig(

package/ios/CoreKit/Sources/GlassesMediaCore/GlassesMediaSource.swift

@@ -1,5 +1,11 @@
 import Foundation
 
+/// Investigation arms shared with the Android [MediaDiagnostics] object.
+public enum MediaDiagnostics {
+    /// SoftAP ingest rebind kill switch. Ships on. Flip off to refuse destroying the live listener.
+    public static var softapRecoveryEnabled = true
+}
+
 public enum SourceKind: String, Sendable {
     case whep
     case direct
@@ -33,6 +39,8 @@ public protocol GlassesMediaSource: AnyObject {
     func restart(config: SourceConfig)
     func stop()
     func setPcmDeliveryEnabled(_ enabled: Bool)
+    func forceCloseIngest()
+    func awaitIngestClosed(timeoutMs: Int) -> Bool
 }
 
 public final class GlassesMediaController {
@@ -74,6 +82,12 @@ public extension GlassesMediaSource {
     }
 
     func forceRestart() {}
+
+    func forceCloseIngest() {}
+
+    func awaitIngestClosed(timeoutMs _: Int) -> Bool {
+        true
+    }
 }
 
 public extension SourceConfig {

package/ios/LocalWhipIngestSource.swift

@@ -26,6 +26,8 @@ public final class LocalWhipIngestSource: NSObject, DecodedGlassesMediaSource {
     private var factory: RTCPeerConnectionFactory?
     private var peer: RTCPeerConnection?
     private var server: WhipIngestServer?
+    /// Parked by [rebindIngest] so the old generation still holds its port until force-close.
+    private var retiring: WhipIngestServer?
     private var video: RTCVideoTrack?
     private var audio: [RTCAudioTrack] = []
     private var renderer: LocalMediaRenderer?
@@ -56,16 +58,94 @@ public final class LocalWhipIngestSource: NSObject, DecodedGlassesMediaSource {
         queue.async { self.transition(.failed, "local_restart_requires_republish") }
     }
 
+    /// Destroy the current listener generation and bind a new one. Fail closed: a null or
+    /// unchanged URL is refused, and the parked listener is force-closed rather than reused.
+    public func rebindIngest(config: SourceConfig, timeoutMs: Int, completion: @escaping (Result<String, Error>) -> Void) {
+        queue.async {
+            guard MediaDiagnostics.softapRecoveryEnabled else {
+                completion(.failure(LocalMediaError("SoftAP ingest rebind is disabled")))
+                return
+            }
+            guard !self.stopping else {
+                completion(.failure(LocalMediaError("SoftAP ingest rebind is not possible while stopping")))
+                return
+            }
+            let oldUrl = self.url
+            if let server = self.server {
+                self.retiring = server
+                self.server = nil
+            }
+            self.url = nil
+            self.closePeer()
+            self.startListener(config: config) { result in
+                switch result {
+                case let .failure(error):
+                    completion(.failure(error))
+                case let .success(newUrl):
+                    if newUrl.isEmpty || newUrl == oldUrl {
+                        completion(.failure(LocalMediaError(
+                            "SoftAP ingest rebind did not mint a new listener (old=\(oldUrl ?? "none") new=\(newUrl))"
+                        )))
+                        return
+                    }
+                    self.forceCloseIngestLocked()
+                    let closed = self.awaitIngestClosedLocked(timeoutMs: timeoutMs)
+                    NSLog("SOFTAP_TRACE stage=ingest_rebind oldUrl=\(oldUrl ?? "none") newUrl=\(newUrl) closed=\(closed)")
+                    if !closed {
+                        completion(.failure(LocalMediaError("SoftAP ingest rebind did not release the old listener")))
+                        return
+                    }
+                    completion(.success(newUrl))
+                }
+            }
+        }
+    }
+
+    public func forceCloseIngest() {
+        if DispatchQueue.getSpecific(key: queueKey) == true {
+            forceCloseIngestLocked()
+        } else {
+            queue.sync { self.forceCloseIngestLocked() }
+        }
+    }
+
+    public func awaitIngestClosed(timeoutMs: Int) -> Bool {
+        if DispatchQueue.getSpecific(key: queueKey) == true {
+            return awaitIngestClosedLocked(timeoutMs: timeoutMs)
+        }
+        return queue.sync { self.awaitIngestClosedLocked(timeoutMs: timeoutMs) }
+    }
+
+    private func forceCloseIngestLocked() {
+        retiring?.stop {}
+    }
+
+    private func awaitIngestClosedLocked(timeoutMs: Int) -> Bool {
+        guard let retiring else { return true }
+        let done = DispatchSemaphore(value: 0)
+        retiring.stop { done.signal() }
+        return done.wait(timeout: .now() + .milliseconds(max(timeoutMs, 0))) == .success
+    }
+
     /// Resolves only after the HTTP listener is bound. The owner can then tell the glasses to publish.
     public func prepare(config: SourceConfig, completion: @escaping (Result<String, Error>) -> Void) {
         queue.async {
-            guard self.server == nil, !self.stopping, let address = config.bindAddress, LocalMediaPolicy.isPrivate(address) else {
+            guard self.server == nil, !self.stopping else {
                 completion(.failure(LocalMediaError("A free receiver and the phone's hotspot address are required"))); return
             }
-            self.address = address
-            self.generation += 1
-            let gen = self.generation
-            self.transition(.connecting, "listening")
+            self.startListener(config: config, completion: completion)
+        }
+    }
+
+    private func startListener(config: SourceConfig, completion: @escaping (Result<String, Error>) -> Void) {
+        guard let address = config.bindAddress, LocalMediaPolicy.isPrivate(address) else {
+            completion(.failure(LocalMediaError("A free receiver and the phone's hotspot address are required"))); return
+        }
+        self.address = address
+        generation += 1
+        let gen = generation
+        transition(.connecting, "listening")
+        if factory == nil {
             RTCInitializeSSL()
             let factory = GlassesPeerFactory.make(audioDevice: ReceiveOnlyAudioDevice())
             let options = RTCPeerConnectionFactoryOptions()
@@ -75,31 +155,31 @@ public final class LocalWhipIngestSource: NSObject, DecodedGlassesMediaSource {
             options.ignoreEthernetNetworkAdapter = true
             factory.setOptions(options)
             self.factory = factory
-            let server = WhipIngestServer(
-                negotiate: { [weak self] offer, reply in
-                    guard let self else { reply(.failure(LocalMediaError("Receiver released"))); return }
-                    self.queue.async { self.negotiate(offer, completion: reply) }
-                },
-                terminate: { [weak self] in
-                    self?.queue.async {
-                        guard let self else { return }
-                        self.closePeer()
-                        if self.currentState != .idle { self.transition(.failed, "publisher_terminated") }
-                    }
-                },
-                publisherFailed: { [weak self] in self?.state == .failed }
-            )
-            self.server = server
-            server.start(address: address) { [weak self] result in
-                guard let self else { completion(.failure(LocalMediaError("Receiver released"))); return }
-                self.queue.async {
-                    guard gen == self.generation, !self.stopping else { completion(.failure(LocalMediaError("Receiver cancelled"))); return }
-                    switch result {
-                    case let .success(url): self.url = url
-                    case let .failure(error): self.transition(.failed, error.localizedDescription)
-                    }
-                    completion(result)
+        }
+        let server = WhipIngestServer(
+            negotiate: { [weak self] offer, reply in
+                guard let self else { reply(.failure(LocalMediaError("Receiver released"))); return }
+                self.queue.async { self.negotiate(offer, completion: reply) }
+            },
+            terminate: { [weak self] in
+                self?.queue.async {
+                    guard let self else { return }
+                    self.closePeer()
+                    if self.currentState != .idle { self.transition(.failed, "publisher_terminated") }
                 }
+            },
+            publisherFailed: { [weak self] in self?.state == .failed }
+        )
+        self.server = server
+        server.start(address: address) { [weak self] result in
+            guard let self else { completion(.failure(LocalMediaError("Receiver released"))); return }
+            self.queue.async {
+                guard gen == self.generation, !self.stopping else { completion(.failure(LocalMediaError("Receiver cancelled"))); return }
+                switch result {
+                case let .success(url): self.url = url
+                case let .failure(error): self.transition(.failed, error.localizedDescription)
+                }
+                completion(result)
             }
         }
     }
@@ -121,6 +201,10 @@ public final class LocalWhipIngestSource: NSObject, DecodedGlassesMediaSource {
             self.url = nil
             self.closePeer()
             self.transition(.idle, "stop")
+            if let retiring = self.retiring {
+                self.retiring = nil
+                retiring.stop {}
+            }
             let server = self.server
             self.server = nil
             let finish = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/glasses-media",
-  "version": "3.2.0-dev.261",
+  "version": "3.2.0-dev.262",
   "description": "Shared native glasses media receivers and local network transport",
   "license": "MIT",
   "author": "Mentra Community",