@grafana/faro-react-native 1.3.0 → 1.4.0

package/android/src/main/java/com/grafana/faro/reactnative/FaroCrashReporter.kt

@@ -34,6 +34,18 @@ object FaroCrashReporter {
     private const val PREFS_NAME = "com.grafana.faro.crash_reporter"
     private const val KEY_LAST_PROCESSED_TIMESTAMP = "last_processed_timestamp"
 
+    private data class ExitGroupKey(
+        val timestampMs: Long,
+        val pid: Int,
+        val processName: String,
+    )
+
+    private sealed interface ExportResult {
+        data class Report(val json: String) : ExportResult
+        data object Ignored : ExportResult
+        data object Failed : ExportResult
+    }
+
     /**
      * Persists a text tombstone backtrace for the next [REASON_CRASH_NATIVE] replay.
      *
@@ -50,13 +62,18 @@ object FaroCrashReporter {
      *
      * Returns a list of JSON strings, each representing a crash report.
      * The JSON format matches the iOS implementation for consistency.
-     * Only returns new crash reports since the last call.
+     * Retrieval is non-destructive. Reports remain pending until JavaScript
+     * acknowledges successful delivery or an intentional local filter.
      *
      * @param context Android context
      * @return List of crash report JSON strings, or null if no crashes or unsupported API
      */
+    @JvmOverloads
     @JvmStatic
-    fun getCrashReports(context: Context): List<String>? {
+    fun getCrashReports(
+        context: Context,
+        nowMs: Long = System.currentTimeMillis(),
+    ): List<String>? {
         FaroUncaughtExceptionHandler.install(context)
         // ApplicationExitInfo requires Android 11 (API 30)
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
@@ -76,59 +93,126 @@ object FaroCrashReporter {
             return null
         }
 
-        // Get the last processed timestamp to avoid duplicate reports
+        // Preserve the old watermark as a one-way migration boundary. New reports
+        // use stable IDs and are acknowledged only after delivery.
         val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
-        val lastProcessedTimestamp = prefs.getLong(KEY_LAST_PROCESSED_TIMESTAMP, 0)
+        val legacyLastProcessedTimestamp = prefs.getLong(KEY_LAST_PROCESSED_TIMESTAMP, 0)
 
-        val pendingTrace = FaroCrashTraceCache.peekPendingCrashTrace(context)
-        var usedPendingTrace = false
+        val pendingTrace = FaroCrashTraceCache.peekPendingCrashTrace(context, nowMs)
 
         val crashReports = mutableListOf<String>()
-        var latestTimestamp = lastProcessedTimestamp
-        val reportedTimestamps = mutableSetOf<Long>()
 
         // Android can return multiple ApplicationExitInfo rows for one fatal exit
         // (e.g. REASON_CRASH plus a companion row with no trace). Collapse to one
-        // report per timestamp and share the UncaughtExceptionHandler cache.
+        // report per process/timestamp and share the UncaughtExceptionHandler cache.
         val candidates = exitInfoList
-            .filter { it.timestamp > lastProcessedTimestamp && isCrashReason(it.reason) }
-            .groupBy { it.timestamp }
+            .filter {
+                it.timestamp > legacyLastProcessedTimestamp &&
+                    isCrashReason(it.reason)
+            }
+            .groupBy {
+                ExitGroupKey(
+                    timestampMs = it.timestamp,
+                    pid = it.pid,
+                    processName = it.processName.orEmpty(),
+                )
+            }
             .mapValues { (_, exits) -> pickBestExitInfo(exits) }
-            .toSortedMap()
-
-        for ((timestamp, exitInfo) in candidates) {
-            if (reportedTimestamps.contains(timestamp)) {
+            .entries
+            .sortedBy { it.key.timestampMs }
+
+        for ((_, exitInfo) in candidates) {
+            val reportId = FaroCrashIds.reportId(
+                packageName = context.packageName,
+                timestampMs = exitInfo.timestamp,
+                pid = exitInfo.pid,
+                processName = exitInfo.processName.orEmpty(),
+            )
+            if (FaroCrashSessionStore.isReportAcknowledged(context, reportId, nowMs)) {
                 continue
             }
-
-            if (exitInfo.timestamp > latestTimestamp) {
-                latestTimestamp = exitInfo.timestamp
+            if (!isWithinReplayWindow(exitInfo.timestamp, nowMs)) {
+                FaroCrashSessionStore.acknowledgeReports(
+                    context = context,
+                    reportIds = listOf(reportId),
+                    nowMs = nowMs,
+                )
+                continue
             }
 
-            val jsonString = exportExitInfoAsJSON(context, exitInfo, pendingTrace) { consumed ->
+            val sessionContext = FaroCrashSessionStore.contextForPendingReport(context, reportId, nowMs)
+                ?: FaroCrashSessionStore.findMatchingContext(
+                    context = context,
+                    crashTimestampMs = exitInfo.timestamp,
+                    pid = exitInfo.pid,
+                    processName = exitInfo.processName.orEmpty(),
+                    nowMs = nowMs,
+                )
+            var usedPendingTrace = false
+
+            val exportResult = exportExitInfoAsJSON(
+                context = context,
+                exitInfo = exitInfo,
+                reportId = reportId,
+                sessionContext = sessionContext,
+                pendingTrace = pendingTrace,
+            ) { consumed ->
                 if (consumed) {
                     usedPendingTrace = true
                 }
             }
 
-            if (jsonString != null) {
-                crashReports.add(jsonString)
-                reportedTimestamps.add(timestamp)
+            when (exportResult) {
+                is ExportResult.Report -> {
+                    FaroCrashSessionStore.rememberPendingReport(
+                        context = context,
+                        reportId = reportId,
+                        crashTimestampMs = exitInfo.timestamp,
+                        sessionContext = sessionContext,
+                        usesPendingTrace = usedPendingTrace,
+                        nowMs = nowMs,
+                    )
+                    crashReports.add(exportResult.json)
+                }
+                ExportResult.Ignored -> {
+                    // Prevent intentionally filtered companion or ANR rows from
+                    // being reconsidered on every subsequent app launch.
+                    FaroCrashSessionStore.acknowledgeReports(
+                        context = context,
+                        reportIds = listOf(reportId),
+                        nowMs = nowMs,
+                    )
+                }
+                ExportResult.Failed -> Unit
             }
         }
 
-        if (usedPendingTrace) {
+        return if (crashReports.isEmpty()) null else crashReports
+    }
+
+    @JvmStatic
+    fun acknowledgeCrashReports(
+        context: Context,
+        reportIds: Collection<String>,
+    ): Boolean {
+        val result = FaroCrashSessionStore.acknowledgeReports(context, reportIds)
+        if (!result.persisted) {
+            return false
+        }
+        if (result.clearPendingTrace) {
             FaroCrashTraceCache.clearPendingCrashTrace(context)
         }
+        return true
+    }
 
-        // Update the last processed timestamp
-        if (latestTimestamp > lastProcessedTimestamp) {
-            prefs.edit()
-                .putLong(KEY_LAST_PROCESSED_TIMESTAMP, latestTimestamp)
-                .apply()
+    internal fun isWithinReplayWindow(
+        crashTimestampMs: Long,
+        nowMs: Long,
+    ): Boolean {
+        if (crashTimestampMs <= 0L || crashTimestampMs > nowMs) {
+            return false
         }
-
-        return if (crashReports.isEmpty()) null else crashReports
+        return nowMs - crashTimestampMs <= FaroCrashSessionStore.MAX_CONTEXT_AGE_MS
     }
 
     /**
@@ -188,16 +272,20 @@ object FaroCrashReporter {
     private fun exportExitInfoAsJSON(
         context: Context,
         exitInfo: ApplicationExitInfo,
+        reportId: String,
+        sessionContext: FaroCrashSessionStore.SessionContext?,
         pendingTrace: FaroCrashTraceCache.PendingTrace?,
         onPendingTraceUsed: (Boolean) -> Unit,
-    ): String? {
+    ): ExportResult {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
-            return null
+            return ExportResult.Failed
         }
 
         return try {
             val json = JSONObject()
 
+            json.put("reportId", reportId)
+
             // Reason - maps to crash type
             json.put("reason", getReasonString(exitInfo.reason))
 
@@ -220,9 +308,17 @@ object FaroCrashReporter {
             // Importance (Android-specific)
             json.put("importance", exitInfo.importance)
 
+            if (sessionContext != null) {
+                json.put("sessionId", sessionContext.sessionId)
+                sessionContext.isSampled?.let { json.put("isSampled", it) }
+                sessionContext.appVersion?.let { json.put("appVersion", it) }
+                sessionContext.appRelease?.let { json.put("appRelease", it) }
+                sessionContext.appBundleId?.let { json.put("appBundleId", it) }
+            }
+
             if (isAnrTimeoutDescription(rawDescription)) {
                 // ANRInstrumentation reports these with type ANR.
-                return null
+                return ExportResult.Ignored
             }
 
             val parsedExitTrace = readExitTrace(exitInfo)
@@ -239,7 +335,7 @@ object FaroCrashReporter {
             ) {
                 // Suppress empty generic crash rows that duplicate a nearby ANR report.
                 // Real crashes with a trace still surface even when an ANR happened nearby.
-                return null
+                return ExportResult.Ignored
             }
 
             if (trace.isNotEmpty()) {
@@ -270,12 +366,12 @@ object FaroCrashReporter {
                         "[Faro crash native] Skipping CRASH_NATIVE without tombstone trace (traceInputStream was null and no cached native backtrace)",
                     )
                 }
-                return null
+                return ExportResult.Ignored
             }
 
-            json.toString()
-        } catch (e: Exception) {
-            null
+            ExportResult.Report(json.toString())
+        } catch (_: Exception) {
+            ExportResult.Failed
         }
     }
 

package/android/src/main/java/com/grafana/faro/reactnative/FaroCrashSessionStore.kt

@@ -0,0 +1,433 @@
+package com.grafana.faro.reactnative
+
+import android.content.Context
+import android.os.Process
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Persists the minimum process/session context needed to associate a historical
+ * ApplicationExitInfo crash with the Faro session that was active before process death.
+ */
+internal object FaroCrashSessionStore {
+    // Keep aligned with AndroidCrashReportingInstrumentation.MAX_REPLAY_AGE_MS.
+    internal const val MAX_CONTEXT_AGE_MS = 7L * 24L * 60L * 60L * 1000L
+
+    private const val PREFS_NAME = "com.grafana.faro.crash_session_store"
+    private const val KEY_SESSION_CONTEXTS = "session_contexts"
+    private const val KEY_PENDING_REPORTS = "pending_reports"
+    private const val KEY_ACKNOWLEDGED_REPORTS = "acknowledged_reports"
+    private const val MAX_SESSION_CONTEXTS = 100
+    private const val MAX_PENDING_REPORTS = 50
+    private const val MAX_ACKNOWLEDGED_REPORTS = 100
+    private const val SCHEMA_VERSION = 1
+
+    data class SessionContext(
+        val id: String,
+        val sessionId: String,
+        val activatedAtMs: Long,
+        val updatedAtMs: Long,
+        val pid: Int,
+        val processName: String,
+        val isSampled: Boolean?,
+        val appVersion: String?,
+        val appRelease: String?,
+        val appBundleId: String?,
+    )
+
+    private data class PendingReport(
+        val reportId: String,
+        val contextId: String?,
+        val crashTimestampMs: Long,
+        val usesPendingTrace: Boolean,
+    )
+
+    private data class AcknowledgedReport(
+        val reportId: String,
+        val acknowledgedAtMs: Long,
+    )
+
+    private data class State(
+        val contexts: MutableList<SessionContext>,
+        val pendingReports: MutableList<PendingReport>,
+        val acknowledgedReports: MutableList<AcknowledgedReport>,
+    )
+
+    data class AcknowledgeResult(
+        val persisted: Boolean,
+        val clearPendingTrace: Boolean,
+    )
+
+    @Synchronized
+    fun recordSessionContext(
+        context: Context,
+        sessionId: String,
+        activatedAtMs: Long,
+        isSampled: Boolean?,
+        appVersion: String?,
+        appRelease: String?,
+        appBundleId: String?,
+        nowMs: Long = System.currentTimeMillis(),
+        pid: Int = Process.myPid(),
+        processName: String = currentProcessName(context.applicationContext),
+    ): Boolean {
+        val normalizedSessionId = sessionId.trim()
+        if (normalizedSessionId.isEmpty() || activatedAtMs <= 0L) {
+            return false
+        }
+
+        val appContext = context.applicationContext
+        val normalizedProcessName = processName.trim()
+        if (pid <= 0 || normalizedProcessName.isEmpty()) {
+            return false
+        }
+        val prefs = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val state = readState(prefs, nowMs)
+        val existingIndex = state.contexts.indexOfFirst {
+            it.sessionId == normalizedSessionId &&
+                it.pid == pid &&
+                it.processName == normalizedProcessName
+        }
+
+        val existing = state.contexts.getOrNull(existingIndex)
+        val firstActivation = existing?.activatedAtMs ?: activatedAtMs
+        val sessionContext = SessionContext(
+            id = existing?.id ?: FaroCrashIds.sessionContextId(
+                normalizedSessionId,
+                firstActivation,
+                pid,
+                normalizedProcessName,
+            ),
+            sessionId = normalizedSessionId,
+            activatedAtMs = firstActivation,
+            updatedAtMs = nowMs,
+            pid = pid,
+            processName = normalizedProcessName,
+            isSampled = isSampled,
+            appVersion = appVersion.normalized(),
+            appRelease = appRelease.normalized(),
+            appBundleId = appBundleId.normalized(),
+        )
+
+        if (existingIndex >= 0) {
+            state.contexts[existingIndex] = sessionContext
+        } else {
+            state.contexts.add(sessionContext)
+        }
+
+        state.contexts.sortBy { it.activatedAtMs }
+        trimSessionContexts(state)
+        return writeState(prefs, state)
+    }
+
+    @Synchronized
+    fun findMatchingContext(
+        context: Context,
+        crashTimestampMs: Long,
+        pid: Int,
+        processName: String,
+        nowMs: Long = System.currentTimeMillis(),
+    ): SessionContext? {
+        if (crashTimestampMs <= 0L) {
+            return null
+        }
+
+        val normalizedProcessName = processName.trim()
+        if (pid <= 0 && normalizedProcessName.isEmpty()) {
+            return null
+        }
+
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        return readState(prefs, nowMs).contexts
+            .asSequence()
+            .filter { it.activatedAtMs <= crashTimestampMs }
+            .filter { pid <= 0 || it.pid == pid }
+            .filter { normalizedProcessName.isEmpty() || it.processName == normalizedProcessName }
+            .maxByOrNull { it.activatedAtMs }
+    }
+
+    @Synchronized
+    fun contextForPendingReport(
+        context: Context,
+        reportId: String,
+        nowMs: Long = System.currentTimeMillis(),
+    ): SessionContext? {
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val state = readState(prefs, nowMs)
+        val contextId = state.pendingReports.firstOrNull { it.reportId == reportId }?.contextId ?: return null
+        return state.contexts.firstOrNull { it.id == contextId }
+    }
+
+    @Synchronized
+    fun rememberPendingReport(
+        context: Context,
+        reportId: String,
+        crashTimestampMs: Long,
+        sessionContext: SessionContext?,
+        usesPendingTrace: Boolean,
+        nowMs: Long = System.currentTimeMillis(),
+    ) {
+        if (reportId.isBlank() || crashTimestampMs <= 0L) {
+            return
+        }
+
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val state = readState(prefs, nowMs)
+        val existingIndex = state.pendingReports.indexOfFirst { it.reportId == reportId }
+        val existing = state.pendingReports.getOrNull(existingIndex)
+        val pendingReport = PendingReport(
+            reportId = reportId,
+            contextId = existing?.contextId ?: sessionContext?.id,
+            crashTimestampMs = crashTimestampMs,
+            usesPendingTrace = existing?.usesPendingTrace == true || usesPendingTrace,
+        )
+
+        if (existingIndex >= 0) {
+            state.pendingReports[existingIndex] = pendingReport
+        } else {
+            state.pendingReports.add(pendingReport)
+        }
+
+        state.pendingReports.sortBy { it.crashTimestampMs }
+        trimOldest(state.pendingReports, MAX_PENDING_REPORTS)
+        writeState(prefs, state)
+    }
+
+    @Synchronized
+    fun isReportAcknowledged(
+        context: Context,
+        reportId: String,
+        nowMs: Long = System.currentTimeMillis(),
+    ): Boolean {
+        if (reportId.isBlank()) {
+            return false
+        }
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        return readState(prefs, nowMs).acknowledgedReports.any { it.reportId == reportId }
+    }
+
+    @Synchronized
+    fun acknowledgeReports(
+        context: Context,
+        reportIds: Collection<String>,
+        nowMs: Long = System.currentTimeMillis(),
+    ): AcknowledgeResult {
+        val normalizedIds = reportIds.map(String::trim).filter(String::isNotEmpty).toSet()
+        if (normalizedIds.isEmpty()) {
+            return AcknowledgeResult(persisted = true, clearPendingTrace = false)
+        }
+
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val state = readState(prefs, nowMs)
+        val acknowledgedMappings = state.pendingReports.filter { it.reportId in normalizedIds }
+        val contextIds = acknowledgedMappings.mapNotNull { it.contextId }.toSet()
+        val acknowledgedPendingTrace = acknowledgedMappings.any { it.usesPendingTrace }
+
+        state.pendingReports.removeAll { it.reportId in normalizedIds }
+        val remainingContextIds = state.pendingReports.mapNotNullTo(mutableSetOf()) { it.contextId }
+        state.contexts.removeAll { it.id in contextIds && it.id !in remainingContextIds }
+        val clearPendingTrace = acknowledgedPendingTrace && state.pendingReports.none { it.usesPendingTrace }
+
+        state.acknowledgedReports.removeAll { it.reportId in normalizedIds }
+        normalizedIds.forEach { reportId ->
+            state.acknowledgedReports.add(AcknowledgedReport(reportId, nowMs))
+        }
+        trimOldest(state.acknowledgedReports, MAX_ACKNOWLEDGED_REPORTS)
+        val persisted = writeState(prefs, state)
+
+        return AcknowledgeResult(
+            persisted = persisted,
+            clearPendingTrace = persisted && clearPendingTrace,
+        )
+    }
+
+    @Synchronized
+    internal fun sessionContextsForTest(
+        context: Context,
+        nowMs: Long,
+    ): List<SessionContext> {
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        return readState(prefs, nowMs).contexts
+    }
+
+    private fun currentProcessName(context: Context): String {
+        return FaroSessionProcess.identifier()
+            ?: context.applicationInfo.processName.orEmpty().ifBlank { context.packageName }
+    }
+
+    private fun readState(
+        prefs: android.content.SharedPreferences,
+        nowMs: Long,
+    ): State {
+        val cutoff = nowMs - MAX_CONTEXT_AGE_MS
+        val contexts = readArray(prefs, KEY_SESSION_CONTEXTS)
+            .mapNotNull(::sessionContextFromJson)
+            .filterTo(mutableListOf()) { it.updatedAtMs >= cutoff }
+        val pendingReports = readArray(prefs, KEY_PENDING_REPORTS)
+            .mapNotNull(::pendingReportFromJson)
+            .filterTo(mutableListOf()) { it.crashTimestampMs >= cutoff }
+        val acknowledgedReports = readArray(prefs, KEY_ACKNOWLEDGED_REPORTS)
+            .mapNotNull(::acknowledgedReportFromJson)
+            .filterTo(mutableListOf()) { it.acknowledgedAtMs >= cutoff }
+
+        return State(contexts, pendingReports, acknowledgedReports)
+    }
+
+    private fun writeState(
+        prefs: android.content.SharedPreferences,
+        state: State,
+    ): Boolean {
+        return prefs.edit()
+            .putString(KEY_SESSION_CONTEXTS, JSONArray(state.contexts.map(::sessionContextToJson)).toString())
+            .putString(KEY_PENDING_REPORTS, JSONArray(state.pendingReports.map(::pendingReportToJson)).toString())
+            .putString(
+                KEY_ACKNOWLEDGED_REPORTS,
+                JSONArray(state.acknowledgedReports.map(::acknowledgedReportToJson)).toString(),
+            )
+            .commit()
+    }
+
+    private fun readArray(
+        prefs: android.content.SharedPreferences,
+        key: String,
+    ): List<JSONObject> {
+        val array = try {
+            JSONArray(prefs.getString(key, "[]") ?: "[]")
+        } catch (_: Exception) {
+            JSONArray()
+        }
+
+        return buildList {
+            for (index in 0 until array.length()) {
+                array.optJSONObject(index)?.let(::add)
+            }
+        }
+    }
+
+    private fun sessionContextToJson(context: SessionContext): JSONObject {
+        return JSONObject()
+            .put("schemaVersion", SCHEMA_VERSION)
+            .put("id", context.id)
+            .put("sessionId", context.sessionId)
+            .put("activatedAt", context.activatedAtMs)
+            .put("updatedAt", context.updatedAtMs)
+            .put("pid", context.pid)
+            .put("processName", context.processName)
+            .putOptional("isSampled", context.isSampled)
+            .putOptional("appVersion", context.appVersion)
+            .putOptional("appRelease", context.appRelease)
+            .putOptional("appBundleId", context.appBundleId)
+    }
+
+    private fun sessionContextFromJson(json: JSONObject): SessionContext? {
+        if (json.optInt("schemaVersion", 0) != SCHEMA_VERSION) {
+            return null
+        }
+
+        val id = json.optString("id").trim()
+        val sessionId = json.optString("sessionId").trim()
+        val activatedAtMs = json.optLong("activatedAt", 0L)
+        val updatedAtMs = json.optLong("updatedAt", activatedAtMs)
+        val pid = json.optInt("pid", 0)
+        val processName = json.optString("processName").trim()
+        if (
+            id.isEmpty() ||
+            sessionId.isEmpty() ||
+            activatedAtMs <= 0L ||
+            updatedAtMs <= 0L ||
+            pid <= 0 ||
+            processName.isEmpty()
+        ) {
+            return null
+        }
+
+        return SessionContext(
+            id = id,
+            sessionId = sessionId,
+            activatedAtMs = activatedAtMs,
+            updatedAtMs = updatedAtMs,
+            pid = pid,
+            processName = processName,
+            isSampled = json.optionalBoolean("isSampled"),
+            appVersion = json.optionalString("appVersion"),
+            appRelease = json.optionalString("appRelease"),
+            appBundleId = json.optionalString("appBundleId"),
+        )
+    }
+
+    private fun pendingReportToJson(report: PendingReport): JSONObject {
+        return JSONObject()
+            .put("reportId", report.reportId)
+            .putOptional("contextId", report.contextId)
+            .put("crashTimestamp", report.crashTimestampMs)
+            .put("usesPendingTrace", report.usesPendingTrace)
+    }
+
+    private fun pendingReportFromJson(json: JSONObject): PendingReport? {
+        val reportId = json.optString("reportId").trim()
+        val crashTimestampMs = json.optLong("crashTimestamp", 0L)
+        if (reportId.isEmpty() || crashTimestampMs <= 0L) {
+            return null
+        }
+        return PendingReport(
+            reportId = reportId,
+            contextId = json.optionalString("contextId"),
+            crashTimestampMs = crashTimestampMs,
+            usesPendingTrace = json.optBoolean("usesPendingTrace", false),
+        )
+    }
+
+    private fun acknowledgedReportToJson(report: AcknowledgedReport): JSONObject {
+        return JSONObject()
+            .put("reportId", report.reportId)
+            .put("acknowledgedAt", report.acknowledgedAtMs)
+    }
+
+    private fun acknowledgedReportFromJson(json: JSONObject): AcknowledgedReport? {
+        val reportId = json.optString("reportId").trim()
+        val acknowledgedAtMs = json.optLong("acknowledgedAt", 0L)
+        if (reportId.isEmpty() || acknowledgedAtMs <= 0L) {
+            return null
+        }
+        return AcknowledgedReport(reportId, acknowledgedAtMs)
+    }
+
+    private fun JSONObject.putOptional(key: String, value: Any?): JSONObject {
+        if (value != null) {
+            put(key, value)
+        }
+        return this
+    }
+
+    private fun JSONObject.optionalString(key: String): String? {
+        if (!has(key) || isNull(key)) {
+            return null
+        }
+        return optString(key).normalized()
+    }
+
+    private fun JSONObject.optionalBoolean(key: String): Boolean? {
+        if (!has(key) || isNull(key)) {
+            return null
+        }
+        return optBoolean(key)
+    }
+
+    private fun String?.normalized(): String? {
+        return this?.trim()?.takeIf(String::isNotEmpty)
+    }
+
+    private fun trimSessionContexts(state: State) {
+        val referencedContextIds = state.pendingReports.mapNotNullTo(mutableSetOf()) { it.contextId }
+        while (state.contexts.size > MAX_SESSION_CONTEXTS) {
+            val removableIndex = state.contexts.indexOfFirst { it.id !in referencedContextIds }
+            state.contexts.removeAt(if (removableIndex >= 0) removableIndex else 0)
+        }
+    }
+
+    private fun <T> trimOldest(items: MutableList<T>, maximumSize: Int) {
+        while (items.size > maximumSize) {
+            items.removeAt(0)
+        }
+    }
+}