@keepsnappy/react-native 0.0.0-stage → 0.1.0-alpha.11

package/android/src/main/java/expo/modules/perflab/PerfLabModule.kt

@@ -0,0 +1,445 @@
+package expo.modules.perflab
+
+import android.app.Activity
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.Build
+import android.graphics.Color
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.os.Trace
+import android.util.Log
+import android.view.Gravity
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import android.widget.TextView
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import java.io.File
+import java.io.FileOutputStream
+import java.io.RandomAccessFile
+import java.net.HttpURLConnection
+import java.net.URL
+import java.security.DigestOutputStream
+import java.security.MessageDigest
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.zip.GZIPOutputStream
+
+private const val TAG = "PERF_LAB"
+
+// The element the test driver waits for after the flush link; same id as on iOS.
+private const val FLUSH_ELEMENT_ID = "perflab.flushed"
+private const val FLUSH_ELEMENT_TAG = "perflab.flushed.view"
+private const val FLUSH_ELEMENT_DP = 8
+// Alpha 1 of 255: drawn, so it counts as visible, but no pixel changes on screen.
+private const val FLUSH_ELEMENT_BACKGROUND = 0x01000000
+
+
+// logcat drops the tail of a line past ~4 KB, so long payloads go out in chunks.
+private const val LOG_CHUNK = 3000
+
+// The SDK keeps the journal near 2x its queue cap (16 MB); a larger file is read from its tail.
+private const val SPOOL_READ_MAX = 16L * 1024 * 1024
+
+// The API parses at most 64 MiB of a raw profile file (MAX_RAW_BYTES in apps/api cpu-worker.ts).
+private const val ARTIFACT_MAX_BYTES = 64L * 1024 * 1024
+private const val COPY_BUFFER = 64 * 1024
+
+// Files that lived in external storage before the move to filesDir.
+private val LEGACY_STATE_FILES = listOf("activation.json", "push-spool.jsonl")
+
+// Created by Expo at app start whether or not the SDK measures: nothing here may
+// do work before a function is called (a dormant build calls activationRead only).
+// UNTESTED ON DEVICE (activation, spool): compiled only, like the sampler.
+// NOT YET COMPILED: moveLegacyState and the streamed uploadArtifact (night of 2026-10-14).
+class PerfLabModule : Module() {
+  private val mainHandler = Handler(Looper.getMainLooper())
+
+  // GC before the action: the driver's command arrives as a broadcast, which pauses no activity (a link does, and the app
+  // reacts to that pause). Registered only while a run with a token measures; the result of the broadcast is the answer.
+  private var commandReceiver: BroadcastReceiver? = null
+  private val pendingCommands = ConcurrentHashMap<Int, BroadcastReceiver.PendingResult>()
+  // A pending broadcast is finished by native at the latest here, whatever JS does: the system raises an ANR after 10 s on
+  // the foreground queue. A safety bound on the wait, never a window edge; JS skips a command native already gave up on.
+  private val commandDeadlineMs = 5000L
+
+  private fun commandListen(on: Boolean) {
+    val context = appContext.reactContext?.applicationContext ?: return
+    synchronized(this) {
+      if (on && commandReceiver == null) {
+        val receiver = object : BroadcastReceiver() {
+          override fun onReceive(c: Context, intent: Intent) {
+            val cmd = intent.getStringExtra("cmd")
+            // `am broadcast --es n 3` and `--ei n 3` both reach here.
+            @Suppress("DEPRECATION")
+            val n = intent.extras?.get("n")?.toString()?.toIntOrNull()
+            if (cmd != "gc" || n == null || n < 1) {
+              resultCode = Activity.RESULT_CANCELED
+              resultData = "bad command"
+              return
+            }
+            val tNative = perfLabMonotonicMs()
+            pendingCommands.remove(n)?.finish()
+            val pending = goAsync()
+            pendingCommands[n] = pending
+            mainHandler.postDelayed({
+              if (pendingCommands.remove(n, pending)) {
+                pending.setResult(Activity.RESULT_CANCELED, "gc:$n timeout", null)
+                pending.finish()
+              }
+            }, commandDeadlineMs)
+            sendEvent("perflabCommand", mapOf("cmd" to cmd, "n" to n, "tNative" to tNative))
+          }
+        }
+        val filter = IntentFilter("${context.packageName}.perflab.COMMAND")
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+          context.registerReceiver(receiver, filter, Context.RECEIVER_EXPORTED)
+        } else {
+          context.registerReceiver(receiver, filter)
+        }
+        commandReceiver = receiver
+        writeLog("PERF_LAB command receiver on")
+      } else if (!on && commandReceiver != null) {
+        try { context.unregisterReceiver(commandReceiver) } catch (e: Exception) {}
+        commandReceiver = null
+        for (n in pendingCommands.keys.toList()) pendingCommands.remove(n)?.finish()
+        writeLog("PERF_LAB command receiver off")
+      }
+    }
+  }
+
+  private fun showFlushElement(status: String) {
+    val activity = appContext.currentActivity
+    if (activity == null) {
+      writeLog("PERF_LAB flush element not shown: no foreground activity ($status)")
+      return
+    }
+    mainHandler.post {
+      val decor = activity.window?.decorView as? ViewGroup ?: return@post
+      decor.findViewWithTag<View>(FLUSH_ELEMENT_TAG)?.let { decor.removeView(it) }
+      val view = TextView(activity).apply {
+        tag = FLUSH_ELEMENT_TAG
+        text = status
+        setTextColor(Color.TRANSPARENT)
+        // UiAutomator2 drops nodes Android reports as not visible to the user, and a 1 px view in the corner under the system bars was one. Measured on a Galaxy S23 (Android 16): found at 8 dp on the left edge, middle of the screen.
+        setBackgroundColor(FLUSH_ELEMENT_BACKGROUND)
+        contentDescription = FLUSH_ELEMENT_ID
+        importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES
+        isClickable = false
+        isFocusable = false
+      }
+      val density = activity.resources.displayMetrics.density
+      val side = (FLUSH_ELEMENT_DP * density).toInt().coerceAtLeast(1)
+      decor.addView(view, FrameLayout.LayoutParams(side, side, Gravity.CENTER_VERTICAL or Gravity.START))
+    }
+  }
+
+  private var samplerCreated = false
+  private val sampler by lazy {
+    samplerCreated = true
+    PerfLabSampler({ appContext.reactContext }, { appContext.currentActivity }, ::writeLog)
+  }
+  private val io: ExecutorService by lazy {
+    Executors.newSingleThreadExecutor { r -> Thread(r, "perflab-io") }
+  }
+
+  // activation.json and the push journal (run tokens) live in internal storage: on Android 9
+  // and older another app with storage permission could read or plant files in external storage.
+  private fun stateDir(create: Boolean): File? {
+    val context = appContext.reactContext ?: return null
+    val dir = File(context.filesDir ?: return null, "perf-lab")
+    moveLegacyState(context, dir)
+    if (create) dir.mkdirs()
+    return dir
+  }
+
+  @Volatile private var legacyChecked = false
+
+  // Once per process, on the first state access: an install from before the move still has
+  // activation.json and the journal (run tokens) in external storage. Each is moved in when
+  // internal storage has none yet, and the external copy is deleted either way.
+  private fun moveLegacyState(context: Context, dir: File) {
+    if (legacyChecked) return
+    synchronized(this) {
+      if (legacyChecked) return
+      legacyChecked = true
+      val external = try { context.getExternalFilesDir(null) } catch (e: Exception) { null }
+      val old = external?.let { File(it, "perf-lab") } ?: return
+      for (name in LEGACY_STATE_FILES) {
+        val from = File(old, name)
+        if (!from.exists()) continue
+        try {
+          val to = File(dir, name)
+          if (!to.exists()) {
+            dir.mkdirs()
+            from.copyTo(to)
+          }
+        } catch (e: Exception) {
+          // the line or activation is lost; the copy that anyone could read is not kept
+        }
+        from.delete()
+      }
+    }
+  }
+
+  private fun readTail(file: File, max: Long): String? = try {
+    RandomAccessFile(file, "r").use { raf ->
+      val length = raf.length()
+      val start = if (length > max) length - max else 0L
+      val bytes = ByteArray((length - start).toInt())
+      raf.seek(start)
+      raf.readFully(bytes)
+      val text = String(bytes, Charsets.UTF_8)
+      if (start == 0L) text else text.substringAfter('\n', "")
+    }
+  } catch (e: Exception) {
+    null
+  }
+
+  private fun writeAtomically(file: File, content: String): Boolean = try {
+    val tmp = File(file.parentFile, file.name + ".tmp")
+    tmp.writeText(content)
+    tmp.renameTo(file)
+  } catch (e: Exception) {
+    false
+  }
+
+  // A raw profile file of a run (plan 40 §3.6), from where writeText puts it: gzip,
+  // sha256 of the gzip, PUT to the signed URL the API handed out. status 0: no HTTP answer.
+  // The gzip is streamed to a temp file (hashed while written) and PUT from it, so neither
+  // the file nor its gzip is held in memory; a file over the API's cap is not read at all.
+  private fun uploadArtifact(fileName: String, url: String, headers: Map<String, String>, timeoutMs: Double): Map<String, Any?> {
+    val context = appContext.reactContext
+    val base = context?.getExternalFilesDir(null)
+    val file = base?.let { File(File(it, "perf-lab"), fileName.replace('/', '_')) }
+    if (context == null || file == null || !file.exists()) {
+      return mapOf("status" to 0, "error" to "file missing")
+    }
+    val length = file.length()
+    if (length > ARTIFACT_MAX_BYTES) {
+      return mapOf("status" to 413, "error" to "file is $length bytes, over $ARTIFACT_MAX_BYTES")
+    }
+    val gzFile = try {
+      File.createTempFile("perflab-upload-", ".gz", context.cacheDir)
+    } catch (e: Exception) {
+      return mapOf("status" to 0, "bytes" to length.toInt(), "error" to "temp file: $e")
+    }
+    try {
+      val digest = MessageDigest.getInstance("SHA-256")
+      try {
+        GZIPOutputStream(DigestOutputStream(FileOutputStream(gzFile), digest), COPY_BUFFER).use { gz ->
+          file.inputStream().use { it.copyTo(gz, COPY_BUFFER) }
+        }
+      } catch (e: Exception) {
+        return mapOf("status" to 0, "bytes" to length.toInt(), "error" to "gzip: $e")
+      }
+      val sha = digest.digest().joinToString("") { "%02x".format(it) }
+      val gzBytes = gzFile.length()
+      val out = mutableMapOf<String, Any?>("bytes" to length.toInt(), "gzBytes" to gzBytes.toInt(), "sha256" to sha)
+      var connection: HttpURLConnection? = null
+      try {
+        val conn = URL(url).openConnection() as HttpURLConnection
+        connection = conn
+        conn.requestMethod = "PUT"
+        conn.doOutput = true
+        conn.connectTimeout = timeoutMs.toInt()
+        conn.readTimeout = timeoutMs.toInt()
+        conn.setFixedLengthStreamingMode(gzBytes)
+        for ((key, value) in headers) {
+          conn.setRequestProperty(key, value)
+        }
+        conn.outputStream.use { sink -> gzFile.inputStream().use { it.copyTo(sink, COPY_BUFFER) } }
+        out["status"] = conn.responseCode
+      } catch (e: Exception) {
+        out["status"] = 0
+        out["error"] = e.toString()
+      } finally {
+        connection?.disconnect()
+      }
+      return out
+    } finally {
+      gzFile.delete()
+    }
+  }
+
+  private fun writeLog(message: String) {
+    if (message.length <= LOG_CHUNK) {
+      Log.i(TAG, message)
+    } else {
+      var start = 0
+      while (start < message.length) {
+        val end = minOf(start + LOG_CHUNK, message.length)
+        Log.i(TAG, message.substring(start, end))
+        start = end
+      }
+    }
+  }
+
+  override fun definition() = ModuleDefinition {
+    Name("PerfLab")
+
+    Events("perflabCommand")
+
+    // Sync functions: called on the JS thread through JSI, no bridge hop, so a
+    // marker lands at the moment JS asks for it.
+    Function("beginAsyncSection") { name: String, cookie: Int ->
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+        Trace.beginAsyncSection(name, cookie)
+      }
+    }
+
+    Function("endAsyncSection") { name: String, cookie: Int ->
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+        Trace.endAsyncSection(name, cookie)
+      }
+    }
+
+    Function("setCounter") { name: String, value: Double ->
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+        Trace.setCounter(name, value.toLong())
+      }
+    }
+
+    Function("isTracing") {
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) Trace.isEnabled() else false
+    }
+
+    Function("log") { message: String ->
+      writeLog(message)
+    }
+
+    Function("samplerConfigure") { mode: String, intervalMs: Double ->
+      sampler.configure(mode, intervalMs)
+    }
+
+    Function("samplerSample") { reason: String ->
+      sampler.sample(reason)
+    }
+
+    Function("samplerRequest") { reason: String ->
+      sampler.request(reason)
+    }
+
+    Function("samplerTake") { reason: String ->
+      sampler.take(reason)
+    }
+
+    Function("samplerRecent") { sinceT: Double ->
+      sampler.recent(sinceT)
+    }
+
+    Function("samplerNow") {
+      perfLabMonotonicMs()
+    }
+
+    OnDestroy {
+      if (samplerCreated) sampler.configure("off", 0.0)
+      commandListen(false)
+    }
+
+    Function("commandListen") { on: Boolean ->
+      commandListen(on)
+    }
+
+    Function("commandPending") { n: Int -> pendingCommands.containsKey(n) }
+
+    Function("commandDone") { n: Int, data: String ->
+      val pending = pendingCommands.remove(n) ?: return@Function false
+      pending.setResult(Activity.RESULT_OK, data, null)
+      pending.finish()
+      true
+    }
+
+    Function("activationRead") {
+      val file = stateDir(false)?.let { File(it, "activation.json") }
+      if (file != null && file.exists()) {
+        try { file.readText() } catch (e: Exception) { null }
+      } else {
+        null
+      }
+    }
+
+    Function("activationWrite") { json: String ->
+      val dir = stateDir(true) ?: return@Function false
+      writeAtomically(File(dir, "activation.json"), json)
+    }
+
+    // logcat only, never a file: a dormant build's answer to `dump=1`.
+    Function("osLog") { message: String ->
+      writeLog(message)
+    }
+
+    // iOS shows the flush result as an accessibility element; Android adds a 1x1 transparent view
+    // (contentDescription `perflab.flushed`, text = status) to the foreground activity's decor view;
+    // like iOS it stays until the next flush replaces it or the process ends. Always logged too.
+    Function("flushSignal") { status: String, detail: String ->
+      writeLog("PERF_LAB flushed $status $detail")
+      showFlushElement(status)
+    }
+
+    Function("spoolAppend") { record: String ->
+      io.execute {
+        val dir = stateDir(true) ?: return@execute
+        try {
+          FileOutputStream(File(dir, "push-spool.jsonl"), true).use { it.write((record + "\n").toByteArray()) }
+        } catch (e: Exception) {
+          // a lost journal line only loses the resume of that line
+        }
+      }
+    }
+
+    Function("spoolRead") {
+      io.submit<String?> {
+        val file = stateDir(false)?.let { File(it, "push-spool.jsonl") }
+        if (file != null && file.exists()) readTail(file, SPOOL_READ_MAX) else null
+      }.get()
+    }
+
+    Function("spoolReplace") { content: String ->
+      io.submit<Boolean> {
+        val dir = stateDir(true) ?: return@submit false
+        val file = File(dir, "push-spool.jsonl")
+        if (content.isEmpty()) {
+          !file.exists() || file.delete()
+        } else {
+          writeAtomically(file, content)
+        }
+      }.get()
+    }
+
+    // System.nanoTime() is CLOCK_MONOTONIC on Android, the same clock as
+    // performance.now() in RN and the MONOTONIC snapshot in Perfetto.
+    Function("clockSnapshot") {
+      mapOf(
+        "nanoTimeMs" to System.nanoTime() / 1_000_000.0,
+        "uptimeMillis" to SystemClock.uptimeMillis().toDouble(),
+        "elapsedRealtimeMs" to SystemClock.elapsedRealtimeNanos() / 1_000_000.0,
+        "wallMs" to System.currentTimeMillis().toDouble(),
+        "sdkInt" to Build.VERSION.SDK_INT,
+      )
+    }
+
+    // Called at flush only, never inside a measured window; runs off the JS thread.
+    AsyncFunction("artifactUpload") { fileName: String, url: String, headers: Map<String, String>, timeoutMs: Double ->
+      uploadArtifact(fileName, url, headers, timeoutMs)
+    }
+
+    // getExternalFilesDir needs no permission and `adb pull` reads it from a
+    // release (non-debuggable) build, where `run-as` does not work.
+    Function("writeText") { fileName: String, content: String ->
+      val context = appContext.reactContext ?: return@Function null
+      val base = context.getExternalFilesDir(null) ?: return@Function null
+      val dir = File(base, "perf-lab")
+      dir.mkdirs()
+      val file = File(dir, fileName.replace('/', '_'))
+      file.writeText(content)
+      file.absolutePath
+    }
+  }
+}