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

package/android/src/main/java/com/mentra/acsmeeting/source/WhipIngestProtocol.kt

@@ -0,0 +1,207 @@
+package com.mentra.acsmeeting.source
+
+/**
+ * The WHIP endpoint's request handling, as a pure function.
+ *
+ * Everything here is decided from the request plus [IngestState]; sockets, peers and SDP generation
+ * live in [WhipIngestServer]. That split exists because the interesting failures are protocol
+ * failures — a second POST while a session is live, a DELETE against a stale id, a POST that
+ * arrives after teardown — and those are painful to provoke through a socket and trivial to state
+ * as a table.
+ *
+ * The glasses are the offerer and keep the WHIP client they already use against Cloudflare. Only
+ * the endpoint moves onto the phone. So this implements the endpoint half of WHIP, and only the
+ * parts one publisher on a private link needs: no trickle `PATCH`, no ICE restart, no auth.
+ */
+object WhipIngestProtocol {
+
+  /** Base resource the glasses POST an offer to. */
+  const val BASE_PATH = "/whip"
+
+  /**
+   * Largest offer we will buffer. Real offers are 2-6 KB; the cap is generous but finite so a
+   * confused or hostile client on the hotspot cannot make the phone allocate without bound.
+   */
+  const val MAX_BODY_BYTES = 256 * 1024L
+
+  const val SDP_CONTENT_TYPE = "application/sdp"
+
+  /** A parsed request. [body] is only populated once the length check has passed. */
+  data class Request(
+    val method: String,
+    val target: String,
+    val contentType: String? = null,
+    val contentLength: Long? = null,
+    val body: String = "",
+  )
+
+  /**
+   * @param activeSessionId the one publisher currently negotiated or negotiating, if any
+   * @param stopped set by [WhipIngestServer.stop]. The listener stays up briefly afterwards so a
+   *   late POST gets a real `410 Gone` instead of a connection reset it cannot distinguish from a
+   *   network glitch.
+   */
+  data class State(val activeSessionId: String? = null, val stopped: Boolean = false)
+
+  /** Where to point the `Location` header. WHIP clients DELETE against exactly this URL. */
+  data class Endpoint(val host: String, val port: Int) {
+    fun sessionUrl(sessionId: String) = "http://$host:$port$BASE_PATH/$sessionId"
+  }
+
+  data class Response(
+    val status: Int,
+    val reason: String,
+    val headers: Map<String, String> = emptyMap(),
+    val body: String = "",
+  )
+
+  sealed interface Action {
+    /**
+     * A valid offer for a free endpoint. The shell must answer it and reply `201` with the answer
+     * and an absolute `Location`; [respondNegotiated] and [respondNegotiationFailed] build those.
+     */
+    data class Negotiate(val sessionId: String, val offer: String) : Action
+
+    /** A DELETE matching the live session. The shell tears down, then replies with [terminated]. */
+    data class Terminate(val sessionId: String) : Action
+
+    /** Nothing to do but write this. */
+    data class Reply(val response: Response) : Action
+  }
+
+  /**
+   * @param newSessionId id to assign if this request opens a session. Passed in rather than minted
+   *   here so the decision stays deterministic under test.
+   */
+  fun decide(request: Request, state: State, newSessionId: String): Action {
+    // Tombstone first. A POST arriving after stop() is well-formed and would otherwise be granted
+    // a session on an endpoint whose peer and scoped network are already gone.
+    if (state.stopped) {
+      return Action.Reply(Response(410, "Gone", body = "endpoint stopped"))
+    }
+
+    val target = request.target.substringBefore('?')
+    val sessionId = sessionIdOf(target)
+
+    return when {
+      target == BASE_PATH || target == "$BASE_PATH/" -> decideOnBase(request, state, newSessionId)
+      sessionId != null -> decideOnSession(request, state, sessionId)
+      else -> Action.Reply(Response(404, "Not Found", body = "no such resource"))
+    }
+  }
+
+  private fun decideOnBase(request: Request, state: State, newSessionId: String): Action {
+    if (!request.method.equals("POST", ignoreCase = true)) {
+      return Action.Reply(
+        Response(405, "Method Not Allowed", mapOf("Allow" to "POST"), "POST an SDP offer"),
+      )
+    }
+    // Length before type: we refuse to read the body at all, so we cannot have parsed its type.
+    val length = request.contentLength
+    if (length != null && length > MAX_BODY_BYTES) {
+      return Action.Reply(
+        Response(413, "Content Too Large", body = "offer exceeds $MAX_BODY_BYTES bytes"),
+      )
+    }
+    if (!isSdp(request.contentType)) {
+      return Action.Reply(
+        Response(415, "Unsupported Media Type", body = "expected $SDP_CONTENT_TYPE"),
+      )
+    }
+    if (request.body.isBlank()) {
+      return Action.Reply(Response(400, "Bad Request", body = "empty offer"))
+    }
+    // One publisher. A second POST means the glasses re-published without deleting — usually a
+    // retry after a reply they never saw. 409 keeps the live session rather than replacing a
+    // working peer with a speculative one; the orchestrator's teardown is what frees the slot.
+    state.activeSessionId?.let {
+      return Action.Reply(
+        Response(409, "Conflict", mapOf("Location" to it), "session $it already publishing"),
+      )
+    }
+    return Action.Negotiate(newSessionId, request.body)
+  }
+
+  private fun decideOnSession(request: Request, state: State, sessionId: String): Action {
+    if (!request.method.equals("DELETE", ignoreCase = true)) {
+      return Action.Reply(
+        Response(405, "Method Not Allowed", mapOf("Allow" to "DELETE"), "DELETE to terminate"),
+      )
+    }
+    if (sessionId != state.activeSessionId) {
+      return Action.Reply(Response(404, "Not Found", body = "session $sessionId is not active"))
+    }
+    return Action.Terminate(sessionId)
+  }
+
+  /** `201` with the answer. WHIP requires the endpoint to gather fully before answering. */
+  fun respondNegotiated(endpoint: Endpoint, sessionId: String, answerSdp: String) = Response(
+    status = 201,
+    reason = "Created",
+    headers = mapOf(
+      "Location" to endpoint.sessionUrl(sessionId),
+      "Content-Type" to SDP_CONTENT_TYPE,
+    ),
+    body = answerSdp,
+  )
+
+  /**
+   * The offer was acceptable but we could not answer it — no answer in time, no host candidate on
+   * the hotspot subnet, peer creation failed. `500` and not `4xx`: the publisher did nothing wrong,
+   * and a retry may well succeed.
+   */
+  fun respondNegotiationFailed(reason: String) =
+    Response(500, "Internal Server Error", body = reason)
+
+  /** WHIP terminations return no content. */
+  fun terminated() = Response(204, "No Content")
+
+  private fun isSdp(contentType: String?): Boolean {
+    val value = contentType?.substringBefore(';')?.trim() ?: return false
+    return value.equals(SDP_CONTENT_TYPE, ignoreCase = true)
+  }
+
+  /** `/whip/<id>` -> `<id>`, for a single non-empty path segment. Anything else is not a session. */
+  private fun sessionIdOf(target: String): String? {
+    if (!target.startsWith("$BASE_PATH/")) return null
+    val remainder = target.removePrefix("$BASE_PATH/")
+    if (remainder.isEmpty() || remainder.contains('/')) return null
+    return remainder
+  }
+
+  /**
+   * Renders a response to the wire. `Content-Length` is always present and the connection always
+   * closes: the glasses' WHIP client makes one request per connection, and a missing length turns
+   * a clean `410` into a hang while the client waits for a body that never ends.
+   */
+  fun render(response: Response): String {
+    val bodyBytes = response.body.toByteArray(Charsets.UTF_8)
+    val head = StringBuilder("HTTP/1.1 ${response.status} ${response.reason}\r\n")
+    for ((name, value) in response.headers) {
+      head.append("$name: $value\r\n")
+    }
+    if (!response.headers.keys.any { it.equals("Content-Type", ignoreCase = true) } &&
+      bodyBytes.isNotEmpty()
+    ) {
+      head.append("Content-Type: text/plain; charset=utf-8\r\n")
+    }
+    head.append("Content-Length: ${bodyBytes.size}\r\n")
+    head.append("Connection: close\r\n\r\n")
+    head.append(response.body)
+    return head.toString()
+  }
+
+  /** Parses `POST /whip HTTP/1.1`. Null when the line is not a plausible request line. */
+  fun parseRequestLine(line: String): Pair<String, String>? {
+    val parts = line.trim().split(' ').filter { it.isNotEmpty() }
+    if (parts.size < 2) return null
+    val method = parts[0]
+    val target = parts[1]
+    if (method.isEmpty() || !target.startsWith("/")) return null
+    return method to target
+  }
+
+  /** Case-insensitive header lookup, as HTTP requires and OkHttp clients assume. */
+  fun headerValue(headers: Map<String, String>, name: String): String? =
+    headers.entries.firstOrNull { it.key.equals(name, ignoreCase = true) }?.value
+}

package/android/src/main/java/com/mentra/acsmeeting/source/WhipIngestServer.kt

@@ -0,0 +1,356 @@
+package com.mentra.acsmeeting.source
+
+import android.util.Log
+import com.mentra.acsmeeting.trace.SoftApTrace
+import java.io.BufferedOutputStream
+import java.io.IOException
+import java.io.InputStream
+import java.net.InetAddress
+import java.net.InetSocketAddress
+import java.net.ServerSocket
+import java.net.Socket
+import java.net.SocketException
+import java.util.UUID
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * The WHIP endpoint, moved off Cloudflare and onto the phone.
+ *
+ * The glasses keep publishing exactly as they do today — POST an SDP offer, read the answer, DELETE
+ * the `Location` when done. Only the address changes, from an HTTPS Cloudflare URL to
+ * `http://192.168.43.x:port/whip` on the hotspot. Keeping the glasses as the offerer is what makes
+ * this a small change on the device that is hardest to debug.
+ *
+ * The listener is bound to the SoftAP [InetAddress] itself rather than to the wildcard address.
+ * `Network.bindSocket` has no `ServerSocket` overload, and it is not needed: binding to that one
+ * local address is what restricts which interface can accept these connections, and it keeps the
+ * endpoint off the phone's other networks. Binding libwebrtc's own UDP sockets is a separate
+ * problem and is handled by the host-only ICE configuration in [LocalWhipIngestSource] plus
+ * [com.mentra.acsmeeting.network.ScopedNetworkChangeDetector].
+ *
+ * Protocol decisions live in [WhipIngestProtocol]; this class owns sockets, threads and the session
+ * slot.
+ */
+class WhipIngestServer(
+  private val negotiator: Negotiator,
+  private val idFactory: () -> String = { UUID.randomUUID().toString().replace("-", "").take(12) },
+) {
+
+  /**
+   * Turns an offer into an answer. Separate from the server so the protocol and socket behaviour
+   * test without WebRTC, and so the peer can be owned by the session rather than by the listener.
+   */
+  interface Negotiator {
+    /**
+     * Called off the accept thread and expected to block until ICE gathering completes: WHIP
+     * requires the endpoint to gather fully before answering, since neither side does trickle
+     * `PATCH` here. Returning a failure produces `500` and frees the session slot.
+     */
+    fun negotiate(sessionId: String, offer: String): Result<String>
+
+    /** Release the peer for [sessionId]. Must be idempotent; DELETE and stop() can both call it. */
+    fun terminate(sessionId: String)
+
+    /**
+     * ICE on the live publisher is already dead. A second POST then replaces instead of 409:
+     * the glasses reconnect after `PeerConnection disconnected` without a DELETE that freed
+     * the slot, and 409 is what left the meeting black.
+     */
+    fun publisherFailed(): Boolean = false
+  }
+
+  private val lock = Any()
+  private var state = WhipIngestProtocol.State()
+  private var server: ServerSocket? = null
+  private var endpoint: WhipIngestProtocol.Endpoint? = null
+  private var acceptThread: Thread? = null
+  private val connections = Executors.newCachedThreadPool { runnable ->
+    Thread(runnable, "whip-ingest-conn").apply { isDaemon = true }
+  }
+  private val accepted = AtomicInteger()
+
+  /** Bound endpoint, or null before [start]. This is the URL the glasses must be told to POST to. */
+  val boundEndpoint: WhipIngestProtocol.Endpoint?
+    get() = synchronized(lock) { endpoint }
+
+  /**
+   * Binds and begins accepting.
+   *
+   * @param address the phone's own address on the SoftAP, from
+   *   [com.mentra.acsmeeting.network.ScopedSoftApNetwork.localIpv4]
+   * @param port 0 to let the OS choose, which is what production does; the fixed-port form exists
+   *   for tests
+   */
+  fun start(address: InetAddress, port: Int = 0): WhipIngestProtocol.Endpoint {
+    synchronized(lock) {
+      check(server == null) { "ingest server already started" }
+      val socket = ServerSocket()
+      socket.reuseAddress = true
+      socket.bind(InetSocketAddress(address, port), BACKLOG)
+      val bound = WhipIngestProtocol.Endpoint(address.hostAddress ?: "127.0.0.1", socket.localPort)
+      server = socket
+      endpoint = bound
+      state = WhipIngestProtocol.State()
+      acceptThread = Thread({ acceptLoop(socket) }, "whip-ingest-accept").apply {
+        isDaemon = true
+        start()
+      }
+      SoftApTrace.stage(
+        "whip_listener_bound",
+        "host" to bound.host,
+        "port" to bound.port,
+        "url" to "${bound.host}:${bound.port}${WhipIngestProtocol.BASE_PATH}",
+      )
+      return bound
+    }
+  }
+
+  /**
+   * Stops accepting new publishers and tears the live session down.
+   *
+   * The listener is not closed immediately. For [TOMBSTONE_MS] it stays up answering `410 Gone`, so
+   * a POST or DELETE already in flight from the glasses gets a real HTTP status instead of a
+   * connection reset — which a client cannot tell apart from a Wi-Fi glitch, and would retry.
+   */
+  fun stop() {
+    val live: String?
+    synchronized(lock) {
+      if (server == null) return
+      live = state.activeSessionId
+      state = WhipIngestProtocol.State(activeSessionId = null, stopped = true)
+    }
+    live?.let { runCatching { negotiator.terminate(it) } }
+    SoftApTrace.stage("whip_listener_tombstoned", "graceMs" to TOMBSTONE_MS, "session" to live)
+
+    val closer = Thread({
+      Thread.sleep(TOMBSTONE_MS)
+      closeListener()
+    }, "whip-ingest-tombstone")
+    closer.isDaemon = true
+    closer.start()
+  }
+
+  /** Closes the listener without waiting out the tombstone. For tests and hard teardown. */
+  fun closeNow() {
+    synchronized(lock) {
+      if (server == null) return
+      state = WhipIngestProtocol.State(activeSessionId = null, stopped = true)
+    }
+    closeListener()
+  }
+
+  private fun closeListener() {
+    val socket = synchronized(lock) {
+      val current = server
+      server = null
+      endpoint = null
+      current
+    } ?: return
+    runCatching { socket.close() }
+    connections.shutdownNow()
+    SoftApTrace.stage("whip_listener_closed", "accepted" to accepted.get())
+  }
+
+  private fun acceptLoop(socket: ServerSocket) {
+    while (!socket.isClosed) {
+      val connection = try {
+        socket.accept()
+      } catch (_: SocketException) {
+        return // closed under us; the only expected exit
+      } catch (error: IOException) {
+        Log.w(TAG, "accept failed", error)
+        return
+      }
+      accepted.incrementAndGet()
+      // Each connection on its own thread: a negotiation blocks for the length of an ICE gather,
+      // and a DELETE arriving during one must not queue behind it.
+      try {
+        connections.execute { serve(connection) }
+      } catch (_: java.util.concurrent.RejectedExecutionException) {
+        runCatching { connection.close() }
+      }
+    }
+  }
+
+  private fun serve(connection: Socket) {
+    connection.use { socket ->
+      socket.soTimeout = READ_TIMEOUT_MS
+      val output = BufferedOutputStream(socket.getOutputStream())
+      try {
+        val request = readRequest(socket.getInputStream())
+        if (request == null) {
+          write(output, WhipIngestProtocol.Response(400, "Bad Request", body = "malformed request"))
+          return
+        }
+        write(output, handle(request))
+      } catch (error: Exception) {
+        Log.w(TAG, "connection failed", error)
+        runCatching {
+          write(output, WhipIngestProtocol.Response(400, "Bad Request", body = "read failed"))
+        }
+      }
+    }
+  }
+
+  private fun handle(request: WhipIngestProtocol.Request): WhipIngestProtocol.Response {
+    val action: WhipIngestProtocol.Action
+    val endpointSnapshot: WhipIngestProtocol.Endpoint?
+    var deadSession: String? = null
+    synchronized(lock) {
+      val decided = WhipIngestProtocol.decide(request, state, idFactory())
+      endpointSnapshot = endpoint
+      val replaceDead =
+        decided is WhipIngestProtocol.Action.Reply &&
+          decided.response.status == 409 &&
+          negotiator.publisherFailed()
+      if (replaceDead) {
+        deadSession = state.activeSessionId
+        val replacement = WhipIngestProtocol.Action.Negotiate(idFactory(), request.body)
+        state = state.copy(activeSessionId = replacement.sessionId)
+        action = replacement
+      } else {
+        action = decided
+        // Reserve the slot inside the lock so a duplicate POST during a gather gets 409 rather than
+        // creating a second peer for the same publisher.
+        when (decided) {
+          is WhipIngestProtocol.Action.Negotiate ->
+            state = state.copy(activeSessionId = decided.sessionId)
+          is WhipIngestProtocol.Action.Terminate ->
+            state = state.copy(activeSessionId = null)
+          is WhipIngestProtocol.Action.Reply -> Unit
+        }
+      }
+    }
+    deadSession?.let { released ->
+      SoftApTrace.stage(
+        "whip_replace_dead_publisher",
+        "released" to released,
+        "session" to (action as? WhipIngestProtocol.Action.Negotiate)?.sessionId,
+      )
+      runCatching { negotiator.terminate(released) }
+    }
+
+    return when (action) {
+      is WhipIngestProtocol.Action.Reply -> action.response.also {
+        if (it.status >= 400) {
+          SoftApTrace.stage("whip_request_rejected", "status" to it.status, "path" to request.target)
+        }
+      }
+
+      is WhipIngestProtocol.Action.Terminate -> {
+        SoftApTrace.stage("whip_session_deleted", "session" to action.sessionId)
+        runCatching { negotiator.terminate(action.sessionId) }
+        WhipIngestProtocol.terminated()
+      }
+
+      is WhipIngestProtocol.Action.Negotiate -> {
+        SoftApTrace.stage(
+          "whip_offer_received",
+          "session" to action.sessionId,
+          "offerBytes" to action.offer.length,
+        )
+        val answer = runCatching { negotiator.negotiate(action.sessionId, action.offer) }
+          .getOrElse { Result.failure(it) }
+        answer.fold(
+          onSuccess = { sdp ->
+            val target = endpointSnapshot
+            if (target == null) {
+              releaseSlot(action.sessionId)
+              WhipIngestProtocol.respondNegotiationFailed("endpoint closed during negotiation")
+            } else {
+              SoftApTrace.stage(
+                "whip_answer_sent",
+                "session" to action.sessionId,
+                "answerBytes" to sdp.length,
+              )
+              WhipIngestProtocol.respondNegotiated(target, action.sessionId, sdp)
+            }
+          },
+          onFailure = { error ->
+            releaseSlot(action.sessionId)
+            val reason = error.message ?: error.javaClass.simpleName
+            SoftApTrace.failure(
+              "whip_negotiation_failed",
+              "reason" to reason,
+              "session" to action.sessionId,
+            )
+            WhipIngestProtocol.respondNegotiationFailed(reason)
+          },
+        )
+      }
+    }
+  }
+
+  /** Frees the slot only if this session still holds it, so a newer publisher is not evicted. */
+  private fun releaseSlot(sessionId: String) {
+    synchronized(lock) {
+      if (state.activeSessionId == sessionId) {
+        state = state.copy(activeSessionId = null)
+      }
+    }
+    runCatching { negotiator.terminate(sessionId) }
+  }
+
+  private fun write(output: BufferedOutputStream, response: WhipIngestProtocol.Response) {
+    output.write(WhipIngestProtocol.render(response).toByteArray(Charsets.UTF_8))
+    output.flush()
+  }
+
+  companion object {
+    private const val TAG = "ACS-SPIKE"
+    private const val BACKLOG = 4
+    private const val READ_TIMEOUT_MS = 10_000
+
+    /**
+     * How long the endpoint answers `410` after [stop]. Long enough for an in-flight request from
+     * the glasses to land, short enough not to hold the port across a rejoin.
+     */
+    const val TOMBSTONE_MS = 3_000L
+
+    /**
+     * Reads a request into [WhipIngestProtocol.Request]. Only `Content-Length` bodies are
+     * supported: the glasses' WHIP client sends one, and `chunked` would be a silent 400 otherwise,
+     * so it is rejected explicitly by the missing-length path below.
+     */
+    fun readRequest(stream: InputStream): WhipIngestProtocol.Request? {
+      val reader = stream.bufferedReader(Charsets.UTF_8)
+      val (method, target) = WhipIngestProtocol.parseRequestLine(
+        reader.readLine() ?: return null,
+      ) ?: return null
+
+      val headers = mutableMapOf<String, String>()
+      while (true) {
+        val line = reader.readLine() ?: break
+        if (line.isEmpty()) break
+        val separator = line.indexOf(':')
+        if (separator <= 0) continue
+        headers[line.substring(0, separator).trim()] = line.substring(separator + 1).trim()
+      }
+
+      val contentType = WhipIngestProtocol.headerValue(headers, "Content-Type")
+      val contentLength = WhipIngestProtocol.headerValue(headers, "Content-Length")?.toLongOrNull()
+
+      // Do not read a body we have already decided to refuse. decide() checks the length first for
+      // exactly this reason.
+      if (contentLength == null || contentLength <= 0 ||
+        contentLength > WhipIngestProtocol.MAX_BODY_BYTES
+      ) {
+        return WhipIngestProtocol.Request(method, target, contentType, contentLength)
+      }
+
+      val body = CharArray(contentLength.toInt())
+      var read = 0
+      while (read < body.size) {
+        val count = reader.read(body, read, body.size - read)
+        if (count < 0) break
+        read += count
+      }
+      return WhipIngestProtocol.Request(method, target, contentType, contentLength, String(body, 0, read))
+    }
+
+    /** Convenience for tests and teardown paths that must not outlive the tombstone. */
+    fun awaitTombstone() = TimeUnit.MILLISECONDS.sleep(TOMBSTONE_MS + 250)
+  }
+}