@mentra/crust 3.2.1 → 3.3.0-beta.1001

package/android/src/main/java/com/mentra/crust/jsc/JSCRuntime.kt

@@ -1,6 +1,7 @@
 package com.mentra.crust.jsc
 
 import android.content.Context
+import android.os.SystemClock
 import android.util.Log
 import com.dokar.quickjs.QuickJs
 import com.dokar.quickjs.binding.function
@@ -11,6 +12,7 @@ import java.util.concurrent.Executors
 import java.util.concurrent.ScheduledExecutorService
 import java.util.concurrent.ScheduledFuture
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicLong
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
 
@@ -133,6 +135,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
     val dispatcher: JSCDispatcher = JSCDispatcher(appContext)
 
     private val contexts = ConcurrentHashMap<String, ContextRecord>()
+    private val nextContextId = AtomicLong()
     private val polyfillBundle: String by lazy { loadPolyfillBundle() }
 
     // Schedule pool for timers; per-context the executor is the same as the
@@ -146,6 +149,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
         val packageName: String,
         val qjs: QuickJs,
         val executor: ExecutorService,
+        val contextId: Long,
         val pendingTimers: MutableMap<Int, ScheduledFuture<*>> = ConcurrentHashMap(),
         @Volatile var readyAcked: Boolean = false,
         @Volatile var readyNackTimer: ScheduledFuture<*>? = null,
@@ -273,6 +277,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
             packageName = packageName,
             qjs = qjs,
             executor = executor,
+            contextId = nextContextId.incrementAndGet(),
         )
         contexts[packageName] = record
 
@@ -288,10 +293,10 @@ class JSCRuntime private constructor(private val appContext: Context) {
                 runBlocking {
                     installGlobals(qjs, packageName)
                     if (bundle.isNotEmpty()) {
-                        qjs.evaluate<Any?>(bundle, filename = "mentrajs:startup.js")
+                        qjs.evaluateForEffect(bundle, filename = "mentrajs:startup.js")
                     }
                     if (miniappJs.isNotEmpty()) {
-                        qjs.evaluate<Any?>(miniappJs, filename = "mentrajs:miniapp.js")
+                        qjs.evaluateForEffect(miniappJs, filename = "mentrajs:miniapp.js")
                     }
                 }
                 Log.i(TAG, "spawned $packageName")
@@ -415,7 +420,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
                 record.executor.submit {
                     runBlocking {
                         try {
-                            record.qjs.evaluate<Any?>(
+                            record.qjs.evaluateForEffect(
                                 "globalThis.__deliverTimer && globalThis.__deliverTimer($token);",
                                 filename = "mentrajs:timer-$token.js",
                             )
@@ -457,10 +462,23 @@ class JSCRuntime private constructor(private val appContext: Context) {
      * Push a `{kind: "event"|"response", …}` envelope into the named
      * context's globalThis.__deliver. Hops onto the per-context executor.
      */
-    fun dispatchToJs(packageName: String, envelopeJson: String) {
-        val record = contexts[packageName] ?: return
+    fun dispatchToJs(packageName: String, envelopeJson: String, deliveryId: Long? = null) {
+        val record = contexts[packageName]
+        // Only host-generated PINGs carry this ID. Ordinary media/event deliveries stay quiet.
+        val diagnostic = deliveryId?.let {
+            JSDeliveryDiagnostics(it, record?.contextId, SystemClock::elapsedRealtime) { metadata ->
+                reportDeliveryDiagnostic(packageName, metadata)
+            }
+        }
+        diagnostic?.entry()
+        if (record == null) {
+            diagnostic?.dropped("context-missing")
+            return
+        }
+        diagnostic?.queued()
         try {
             record.executor.submit {
+                diagnostic?.started()
                 // Arm only once evaluate is about to run. Queue wait during a
                 // long previous turn (WHIP start, etc.) must not count — that
                 // was firing ready_nack while the context was merely busy.
@@ -489,14 +507,26 @@ class JSCRuntime private constructor(private val appContext: Context) {
                     kill(packageName)
                 }, WATCHDOG_KILL_MS, TimeUnit.MILLISECONDS)
                 record.watchdogTimer = killTimer
+                var failure: Throwable? = null
                 try {
                     val source = "globalThis.__deliver(${jsStringLiteral(envelopeJson)});"
                     runBlocking {
-                        record.qjs.evaluate<Any?>(source, filename = "mentrajs:deliver.js")
+                        record.qjs.evaluateForEffect(source, filename = "mentrajs:deliver.js")
                     }
                 } catch (e: Throwable) {
+                    failure = e
                     Log.w(TAG, "dispatchToJs threw in $packageName: ${e.message}", e)
+                    if (diagnostic == null) {
+                        reportDeliveryDiagnostic(packageName, mapOf(
+                            "event" to "native-delivery-failed",
+                            "contextId" to record.contextId,
+                            "phase" to "evaluate-failed",
+                            "errorClass" to e.javaClass.simpleName,
+                            "causeClass" to e.cause?.javaClass?.simpleName,
+                        ))
+                    }
                 } finally {
+                    diagnostic?.finished(failure)
                     // Success or throw: the host observed the turn end.
                     record.readyNackTimer?.cancel(false)
                     record.readyNackTimer = null
@@ -505,8 +535,26 @@ class JSCRuntime private constructor(private val appContext: Context) {
                     if (record.watchdogTimer === killTimer) record.watchdogTimer = null
                 }
             }
-        } catch (_: java.util.concurrent.RejectedExecutionException) {
-            // Context killed mid-flight — drop. dispatchToJs is best-effort.
+        } catch (e: java.util.concurrent.RejectedExecutionException) {
+            diagnostic?.dropped("executor-rejected", e)
+            Log.w(TAG, "dispatchToJs rejected for $packageName", e)
+        }
+    }
+
+    private fun reportDeliveryDiagnostic(packageName: String, metadata: Map<String, Any?>) {
+        val line = org.json.JSONObject(metadata as Map<*, *>).toString()
+        Log.i(TAG, line)
+        // Use the existing miniapp log route so console interception includes this in reports.
+        try {
+            deliverOrDrop(OutboundMessage(packageName, mapOf(
+                "packageName" to packageName,
+                "iface" to "__log",
+                "method" to if (metadata["errorClass"] == null) "log" else "warn",
+                "argsJson" to org.json.JSONArray().put(org.json.JSONObject(metadata as Map<*, *>)).toString(),
+            )))
+        } catch (e: Throwable) {
+            // Observability cannot change delivery or hide its original failure.
+            Log.w(TAG, "delivery diagnostic forwarding failed: ${e.javaClass.simpleName}")
         }
     }
 
@@ -542,6 +590,15 @@ class JSCRuntime private constructor(private val appContext: Context) {
 
     // ------------------------------------------------------------------
 
+    /**
+     * Evaluate for side effects. A completion value is never converted to
+     * Kotlin: quickjs-kt 1.0.15 hangs converting a Set, Map or array that
+     * contains itself, and miniapp code chooses its bundle's last value.
+     */
+    private suspend fun QuickJs.evaluateForEffect(source: String, filename: String) {
+        evaluate<Any?>("$source\n;undefined", filename = filename)
+    }
+
     private fun parseArgsEnvelope(argsJson: String): Pair<List<Any?>, String?> {
         return try {
             if (argsJson.startsWith("{")) {

package/android/src/main/java/com/mentra/crust/jsc/JSDeliveryDiagnostics.kt

@@ -0,0 +1,44 @@
+package com.mentra.crust.jsc
+
+/** Metadata for one host PING. Never retains the envelope or exception message. */
+internal class JSDeliveryDiagnostics(
+    private val deliveryId: Long,
+    private val contextId: Long?,
+    private val clockMs: () -> Long,
+    private val emit: (Map<String, Any?>) -> Unit,
+) {
+    private val enteredAtMs = clockMs()
+    private var queuedAtMs: Long? = null
+    private var startedAtMs: Long? = null
+
+    fun entry() = report("native-entry")
+
+    fun queued() {
+        queuedAtMs = clockMs()
+        report("queued")
+    }
+
+    fun started() {
+        startedAtMs = clockMs()
+        report("started")
+    }
+
+    fun finished(error: Throwable? = null) = report(if (error == null) "finished" else "evaluate-failed", error)
+
+    fun dropped(reason: String, error: Throwable? = null) = report(reason, error)
+
+    private fun report(phase: String, error: Throwable? = null) {
+        val now = clockMs()
+        emit(mapOf(
+            "event" to "native-ping-delivery",
+            "deliveryId" to deliveryId,
+            "contextId" to contextId,
+            "phase" to phase,
+            "elapsedMs" to now - enteredAtMs,
+            "queueWaitMs" to queuedAtMs?.let { (startedAtMs ?: now) - it },
+            "evaluateMs" to startedAtMs?.let { now - it },
+            "errorClass" to error?.javaClass?.simpleName,
+            "causeClass" to error?.cause?.javaClass?.simpleName,
+        ))
+    }
+}

package/android/src/main/java/com/mentra/crust/navigation/NavigationManager.kt

@@ -461,6 +461,7 @@ object NavigationManager {
         override fun onRoutesReady(routes: List<NavigationRoute>, routerOrigin: String) {
           if (!sessionGuard.acceptsCallback(session)) return
           if (routes.isEmpty()) {
+            stop()
             callbacks.onError("no route found")
             return
           }
@@ -477,12 +478,15 @@ object NavigationManager {
           if (!sessionGuard.acceptsCallback(session)) return
           val msg = reasons.firstOrNull()?.message ?: "route request failed"
           Log.e(TAG, "requestRoutes failed: $msg")
+          stop()
           callbacks.onError(msg)
         }
 
         override fun onCanceled(routeOptions: RouteOptions, routerOrigin: String) {
           if (!sessionGuard.acceptsCallback(session)) return
           Log.w(TAG, "route request canceled")
+          stop()
+          callbacks.onError("route request canceled")
         }
       },
     )

package/android/src/main/java/com/mentra/crust/preview/PixelCopyPreview.kt

@@ -0,0 +1,76 @@
+package com.mentra.crust.preview
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.graphics.Rect
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import android.view.PixelCopy
+import android.view.View
+import java.io.File
+import kotlin.coroutines.resumeWithException
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withContext
+
+/** Copies the displayed miniapp pixels without invoking WebView's software renderer. */
+object PixelCopyPreview {
+  @OptIn(ExperimentalCoroutinesApi::class)
+  suspend fun capture(activity: Activity, viewTag: Int): String =
+    withContext(Dispatchers.Main.immediate) {
+      check(!activity.isFinishing && !activity.isDestroyed) { "Screenshot activity is unavailable" }
+      val window = activity.window
+      val decor = window.decorView
+      val view = decor.findViewById<View>(viewTag)
+        ?: error("Screenshot view $viewTag is unavailable")
+      check(view.isAttachedToWindow && view.isLaidOut && view.width > 0 && view.height > 0) {
+        "Screenshot view is not ready"
+      }
+
+      val location = IntArray(2)
+      view.getLocationInWindow(location)
+      val bounds = Rect(location[0], location[1], location[0] + view.width, location[1] + view.height)
+      check(Rect(0, 0, decor.width, decor.height).contains(bounds)) {
+        "Screenshot view must be fully inside the window"
+      }
+
+      val bitmap = Bitmap.createBitmap(bounds.width(), bounds.height(), Bitmap.Config.ARGB_8888)
+      val captured = suspendCancellableCoroutine<Bitmap> { continuation ->
+        try {
+          PixelCopy.request(window, bounds, bitmap, { result ->
+            if (result == PixelCopy.SUCCESS) {
+              // A cancelled request still owns its bitmap until PixelCopy finishes.
+              continuation.resume(bitmap) { bitmap.recycle() }
+            } else {
+              bitmap.recycle()
+              continuation.resumeWithException(IllegalStateException("PixelCopy failed: $result"))
+            }
+          }, Handler(Looper.getMainLooper()))
+        } catch (error: Exception) {
+          bitmap.recycle()
+          continuation.resumeWithException(error)
+        }
+      }
+
+      try {
+        withContext(Dispatchers.IO) {
+          val file = File.createTempFile("miniapp-preview-", ".jpg", activity.cacheDir)
+          try {
+            file.outputStream().use { output ->
+              check(captured.compress(Bitmap.CompressFormat.JPEG, 50, output)) {
+                "Unable to encode miniapp screenshot"
+              }
+            }
+            Uri.fromFile(file).toString()
+          } catch (error: Exception) {
+            file.delete()
+            throw error
+          }
+        }
+      } finally {
+        captured.recycle()
+      }
+    }
+}

package/android/src/test/java/com/mentra/crust/http/NativeHttpFailureTest.kt

@@ -0,0 +1,44 @@
+package com.mentra.crust.http
+
+import java.io.IOException
+import java.io.InterruptedIOException
+import java.net.ConnectException
+import java.net.NoRouteToHostException
+import java.net.SocketException
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLHandshakeException
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class NativeHttpFailureTest {
+    @Test fun `preserves failure category without exception text`() {
+        val privateMessage = "https://private.example?token=secret SSID private-address"
+        val cases = listOf(
+            UnknownHostException(privateMessage) to "E_NATIVE_HTTP_DNS",
+            ConnectException(privateMessage) to "E_NATIVE_HTTP_CONNECT",
+            NoRouteToHostException(privateMessage) to "E_NATIVE_HTTP_CONNECT",
+            SocketTimeoutException(privateMessage) to "E_NATIVE_HTTP_TIMEOUT",
+            SSLHandshakeException(privateMessage) to "E_NATIVE_HTTP_TLS",
+            SocketException(privateMessage) to "E_NATIVE_HTTP_SOCKET",
+            InterruptedIOException(privateMessage) to "E_NATIVE_HTTP_INTERRUPTED",
+            IOException(privateMessage) to "E_NATIVE_HTTP_IO",
+            IllegalStateException(privateMessage) to "E_NATIVE_HTTP_OTHER",
+        )
+        cases.forEach { (error, expected) -> assertEquals(expected, nativeHttpFailureCode(error)) }
+    }
+
+    @Test fun `retains a specific cause inside a generic native wrapper`() {
+        val wrapped = IOException("private wrapper", UnknownHostException("private hostname"))
+        assertEquals("E_NATIVE_HTTP_DNS", nativeHttpFailureCode(wrapped))
+        assertEquals("E_NATIVE_HTTP_IO", nativeHttpFailureCode(IllegalStateException(IOException("private"))))
+    }
+
+    @Test fun `never parses a category from private error text and bounds cyclic causes`() {
+        assertEquals("E_NATIVE_HTTP_OTHER", nativeHttpFailureCode(Exception("E_NATIVE_HTTP_DNS")))
+        val first = Exception("private one")
+        val second = Exception("private two", first)
+        first.initCause(second)
+        assertEquals("E_NATIVE_HTTP_OTHER", nativeHttpFailureCode(first))
+    }
+}

package/android/src/test/java/com/mentra/crust/http/NativeHttpRequestsTest.kt

@@ -0,0 +1,133 @@
+package com.mentra.crust.http
+
+import java.io.IOException
+import java.net.ServerSocket
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.OkHttpClient
+import okhttp3.Protocol
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.ResponseBody.Companion.toResponseBody
+import okio.Timeout
+import org.junit.Assert.*
+import org.junit.Test
+
+class NativeHttpRequestsTest {
+    private val request = Request.Builder().url("https://example.com/report").build()
+
+    private class PendingCall(private val request: Request) : Call {
+        var callback: Callback? = null
+        var cancelled = false
+        var onEnqueue: (() -> Unit)? = null
+        override fun request() = request
+        override fun execute(): Response = error("Test only exercises asynchronous calls")
+        override fun enqueue(responseCallback: Callback) {
+            callback = responseCallback
+            onEnqueue?.invoke()
+        }
+        override fun cancel() {cancelled = true}
+        override fun isExecuted() = callback != null
+        override fun isCanceled() = cancelled
+        override fun timeout() = Timeout.NONE
+        override fun clone(): Call = PendingCall(request)
+    }
+
+    @Test fun `register before enqueue and cancel only the requested call`() {
+        val calls = mutableListOf<PendingCall>()
+        val owner = NativeHttpRequests(Call.Factory { req -> PendingCall(req).also {calls.add(it)} })
+        owner.enqueue("one", request, {}, {throw it})
+        calls[0].onEnqueue = {assertEquals(2, owner.activeCount)}
+        owner.enqueue("two", request, {}, {throw it})
+        assertEquals(2, owner.activeCount)
+        owner.cancel("one")
+        assertTrue(calls[0].cancelled)
+        assertFalse(calls[1].cancelled)
+        assertEquals(1, owner.activeCount)
+        owner.cancel("not-owned")
+        assertEquals(1, owner.activeCount)
+        owner.cancelAll()
+        assertTrue(calls[1].cancelled)
+        assertEquals(0, owner.activeCount)
+    }
+
+    @Test fun `completion removes the active request and preserves the response`() {
+        val call = PendingCall(request)
+        val owner = NativeHttpRequests(Call.Factory {call})
+        var result: NativeHttpRequests.Result? = null
+        call.onEnqueue = {assertEquals(1, owner.activeCount)}
+        owner.enqueue("complete", request, {result = it}, {throw it})
+        call.callback!!.onResponse(call, Response.Builder().request(request).protocol(Protocol.HTTP_1_1)
+            .code(200).message("OK").header("Content-Type", "application/json").body("{}".toResponseBody()).build())
+        assertEquals("{}", result!!.body)
+        assertEquals("application/json", result!!.headers["content-type"])
+        assertEquals(0, owner.activeCount)
+        owner.cancel("complete")
+        assertFalse(call.cancelled)
+    }
+
+    @Test fun `network failure and synchronous enqueue failure leave no registry entries`() {
+        val call = PendingCall(request)
+        val owner = NativeHttpRequests(Call.Factory {call})
+        var failures = 0
+        owner.enqueue("failed", request, {}, {failures++})
+        call.callback!!.onFailure(call, IOException("offline"))
+        assertEquals(0, owner.activeCount)
+        call.onEnqueue = {throw IllegalStateException("dispatcher closed")}
+        owner.enqueue("enqueue-failed", request, {}, {failures++})
+        assertEquals(0, owner.activeCount)
+        assertEquals(2, failures)
+    }
+
+    @Test fun `duplicate IDs cannot replace existing ownership and destruction prevents later requests`() {
+        val calls = mutableListOf<PendingCall>()
+        val owner = NativeHttpRequests(Call.Factory {req -> PendingCall(req).also {calls.add(it)} })
+        var failures = 0
+        owner.enqueue("one", request, {}, {failures++})
+        owner.enqueue("one", request, {}, {failures++})
+        assertEquals(1, failures)
+        assertEquals(1, owner.activeCount)
+        assertNull(calls[1].callback)
+        owner.cancelAll()
+        assertTrue(calls[0].cancelled)
+        owner.enqueue("later", request, {}, {failures++})
+        assertEquals(2, failures)
+        assertEquals(2, calls.size)
+        assertEquals(0, owner.activeCount)
+    }
+
+    @Test fun `cancel interrupts an actual OkHttp response body and closes the server socket`() {
+        val client = OkHttpClient()
+        val owner = NativeHttpRequests(client)
+        val bodyStarted = CountDownLatch(1)
+        val socketClosed = CountDownLatch(1)
+        val failed = CountDownLatch(1)
+        ServerSocket(0, 1, java.net.InetAddress.getLoopbackAddress()).use {server ->
+            val thread = Thread {
+                server.accept().use {socket ->
+                    socket.soTimeout = 5_000
+                    val reader = socket.getInputStream().bufferedReader()
+                    while (!reader.readLine().isNullOrEmpty()) {}
+                    socket.getOutputStream().write("HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\n".toByteArray())
+                    socket.getOutputStream().flush()
+                    bodyStarted.countDown()
+                    if (socket.getInputStream().read() == -1) socketClosed.countDown()
+                }
+            }
+            thread.isDaemon = true
+            thread.start()
+            val req = Request.Builder().url("http://127.0.0.1:${server.localPort}/report").build()
+            owner.enqueue("stalled-body", req, {fail("Cancelled body must not complete")}, {failed.countDown()})
+            assertTrue("server started body", bodyStarted.await(5, TimeUnit.SECONDS))
+            owner.cancel("stalled-body")
+            assertTrue("native request rejected", failed.await(5, TimeUnit.SECONDS))
+            assertTrue("socket closed", socketClosed.await(5, TimeUnit.SECONDS))
+            assertEquals(0, owner.activeCount)
+            thread.join(5_000)
+        }
+        client.dispatcher.executorService.shutdownNow()
+        client.connectionPool.evictAll()
+    }
+}