@scalebun/react-native 1.0.0 → 1.0.2

package/android/src/main/java/com/scalebun/replaysdk/outbox/OutboxUploader.kt

@@ -1,407 +1,407 @@
-package com.scalebun.replaysdk.outbox
-
-import android.util.Base64
-import com.scalebun.replaysdk.core.ReplayLogger
-import org.json.JSONArray
-import org.json.JSONObject
-import java.io.File
-import java.net.ConnectException
-import java.net.HttpURLConnection
-import java.net.NoRouteToHostException
-import java.net.SocketException
-import java.net.SocketTimeoutException
-import java.net.URL
-import java.net.UnknownHostException
-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.AtomicBoolean
-import javax.net.ssl.SSLException
-
-/**
- * Native uploader that drains [NativeOutbox] against the /ingestion contract.
- *
- * Frame flow (object storage):  presign → PUT bytes → commit key-only metadata.
- * Frame flow (storage disabled): inline base64 commit (bytes go over HTTP to the
- *   backend, NEVER over the JS bridge).
- * Telemetry flow: read a closed JSONL segment → POST the lane batch.
- *
- * Network-aware retry (section 6). Every attempt is classified into exactly one
- * outcome and routed through the two-counter model on [NativeOutbox]:
- *   SUCCESS            → delete on ACK
- *   NETWORK_UNAVAILABLE→ keep pending, bump networkFailureCount only, never dead
- *   SERVER_TRANSIENT   → bump serverAttemptCount, dead at maxUploadAttempts
- *   SERVER_PERMANENT   → poison, dead at poisonMaxAttempts
- *
- * Upload loop (section 7) is event-driven: [flush] is called on immediate triggers
- * (batch full, segment closed, session end, foreground, startup, network restored).
- * A coalesced 3s retry timer is armed ONLY when there is pending work AND network is
- * available AND something is due; it is cancelled when the queue empties or network
- * drops. No wakeups while idle or offline.
- */
-class OutboxUploader(
-    private val outbox: NativeOutbox,
-    @Volatile private var apiBaseUrl: String,
-    @Volatile private var clientKey: String,
-    private val useObjectStorageForFrames: Boolean,
-    /** serverAttemptCount cap → dead (nativeOutboxMaxUploadAttempts, default 30). */
-    private val maxUploadAttempts: Int = 30,
-    private val frameBatch: Int = 20,
-    /** retry cadence when the timer is armed (nativeOutboxRetryIntervalMs, default 3000). */
-    private val retryIntervalMs: Long = 3000,
-    /** poison (4xx≠429) attempts before dead (nativeOutboxPoisonMaxAttempts, default 2). */
-    private val poisonMaxAttempts: Int = 2,
-    /** honor a Retry-After response header (nativeOutboxRespectRetryAfter, default true). */
-    private val respectRetryAfter: Boolean = true,
-    /** stay at 3s forever vs. switch to backoff after 10 attempts (default false → backoff). */
-    private val strictThreeSecondRetry: Boolean = false,
-) {
-    private val executor = Executors.newSingleThreadExecutor { r -> Thread(r, "ReplaySdk-Outbox") }
-    private val timer: ScheduledExecutorService =
-        Executors.newSingleThreadScheduledExecutor { r -> Thread(r, "ReplaySdk-OutboxTimer") }
-    private val running = AtomicBoolean(false)
-    private val rerun = AtomicBoolean(false)
-    @Volatile private var armed: ScheduledFuture<*>? = null
-    // Default true so the first attempt is allowed even before the monitor reports in.
-    @Volatile private var networkAvailable: Boolean = true
-    // Latched off for the rest of the process once the backend reports storage disabled.
-    @Volatile private var objectStorageActive = useObjectStorageForFrames
-    // Last HTTP status seen by classify(); used to log the real code on poison/dead.
-    @Volatile private var lastResponseCode: Int = 0
-    @Volatile private var lastResponseBody: String = ""
-
-    private enum class Outcome { SUCCESS, NETWORK_UNAVAILABLE, SERVER_TRANSIENT, SERVER_PERMANENT }
-
-    fun updateConfig(apiBaseUrl: String, clientKey: String) {
-        this.apiBaseUrl = apiBaseUrl
-        this.clientKey = clientKey
-    }
-
-    /** Called by the ConnectivityManager.NetworkCallback in the module. */
-    fun setNetworkAvailable(available: Boolean) {
-        val was = networkAvailable
-        networkAvailable = available
-        if (available && !was) {
-            // Network restored → wake immediately and drain (section 7 trigger).
-            flush()
-        } else if (!available) {
-            // Offline → cancel the retry timer; rely on the listener to wake us.
-            cancelTimer()
-        }
-    }
-
-    /** Trigger a non-blocking drain. Safe from any thread / any lifecycle hook. */
-    fun flush() {
-        if (clientKey.isEmpty() || apiBaseUrl.isEmpty()) return
-        executor.execute {
-            if (!running.compareAndSet(false, true)) {
-                // A drain is already in progress → coalesce into a single rerun.
-                rerun.set(true)
-                return@execute
-            }
-            try {
-                do {
-                    rerun.set(false)
-                    drain()
-                } while (rerun.get())
-            } catch (e: Exception) {
-                ReplayLogger.warn("outbox.flush error: ${e.message}")
-            } finally {
-                running.set(false)
-                reconcileTimer()
-            }
-        }
-    }
-
-    private fun drain() {
-        // Offline → do not attempt, do not spin. The connectivity listener wakes us.
-        if (!networkAvailable) return
-        val now = System.currentTimeMillis()
-        for (sessionId in outbox.listSessionIds()) {
-            uploadFrames(sessionId, now)
-            for (lane in NativeOutbox.TELEMETRY_LANES) uploadSegments(sessionId, lane, now)
-        }
-        outbox.enforceLimits()
-    }
-
-    // ─── Timer arming (section 7) ───────────────────────────────────────
-
-    /** Arm the 3s timer ONLY if pending work exists, network is up, and a batch is due. */
-    private fun reconcileTimer() {
-        val now = System.currentTimeMillis()
-        val due = networkAvailable && hasDueWork(now)
-        if (due) {
-            if (armed == null || armed?.isDone == true) {
-                armed = timer.schedule({ flush() }, retryIntervalMs, TimeUnit.MILLISECONDS)
-            }
-        } else {
-            cancelTimer()
-        }
-    }
-
-    private fun cancelTimer() {
-        armed?.cancel(false)
-        armed = null
-    }
-
-    private fun hasDueWork(now: Long): Boolean {
-        for (sessionId in outbox.listSessionIds()) {
-            if (outbox.dueFrameMetas(sessionId, now).isNotEmpty()) return true
-            for (lane in NativeOutbox.TELEMETRY_LANES) {
-                if (outbox.dueSegments(sessionId, lane, now).isNotEmpty()) return true
-            }
-        }
-        return false
-    }
-
-    // ─── Frames ─────────────────────────────────────────────────────────
-
-    private fun uploadFrames(sessionId: String, now: Long) {
-        val due = outbox.dueFrameMetas(sessionId, now).take(frameBatch)
-        if (due.isEmpty()) return
-        val claimed = due.mapNotNull { outbox.moveFrameToUploading(it) }
-        if (claimed.isEmpty()) return
-        val metas = claimed.mapNotNull { f -> runCatching { JSONObject(f.readText()) to f }.getOrNull() }
-
-        if (objectStorageActive) {
-            val outcome = uploadFramesViaStorage(sessionId, metas)
-            if (objectStorageActive) {
-                // Storage still active → this outcome is authoritative for the batch.
-                if (outcome == Outcome.SUCCESS) metas.forEach { outbox.deleteFrame(it.second) }
-                else applyFrameOutcome(metas, outcome)
-                return
-            }
-            // else: backend reported storage disabled mid-flight → fall through to inline.
-        }
-        val inline = commitFramesInline(sessionId, metas)
-        if (inline == Outcome.SUCCESS) metas.forEach { outbox.deleteFrame(it.second) }
-        else applyFrameOutcome(metas, inline)
-    }
-
-    private fun applyFrameOutcome(metas: List<Pair<JSONObject, File>>, outcome: Outcome) {
-        metas.forEach { failItem(it.second, isFrame = true, outcome = outcome, retryAfterMs = 0L) }
-    }
-
-    /** Returns the batch outcome; SUCCESS means PUT(s)+commit all acknowledged. */
-    private fun uploadFramesViaStorage(sessionId: String, metas: List<Pair<JSONObject, File>>): Outcome {
-        val presignReq = JSONArray()
-        for ((m, _) in metas) {
-            presignReq.put(JSONObject()
-                .put("frameId", m.getString("frameId"))
-                .put("contentType", m.optString("contentType", "image/webp"))
-                .put("format", m.optString("format", "webp")))
-        }
-        val presign = postJson("/ingestion/sessions/$sessionId/frames/presign", JSONObject().put("frames", presignReq))
-        val pOutcome = classify(presign)
-        if (pOutcome != Outcome.SUCCESS) return pOutcome
-        val body = runCatching { JSONObject((presign as NetResult.Response).body) }.getOrNull()
-            ?: return Outcome.SERVER_TRANSIENT
-        if (!body.optBoolean("enabled", false)) {
-            objectStorageActive = false
-            ReplayLogger.info("outbox: object storage disabled server-side; falling back to inline")
-            // objectStorageActive is now false → caller re-checks it and falls through to
-            // inline, so this return value is not used to fail/delete the batch.
-            return Outcome.SUCCESS
-        }
-        val byId = HashMap<String, JSONObject>()
-        val arr = body.optJSONArray("frames") ?: JSONArray()
-        for (i in 0 until arr.length()) { val p = arr.getJSONObject(i); byId[p.getString("frameId")] = p }
-        for ((m, metaFile) in metas) {
-            val p = byId[m.getString("frameId")] ?: return Outcome.SERVER_TRANSIENT
-            val img = outbox.frameImageFor(metaFile) ?: return Outcome.SERVER_TRANSIENT
-            val putOutcome = classify(putBytes(p.getString("uploadUrl"), img.readBytes(),
-                p.optString("contentType", m.optString("contentType"))))
-            if (putOutcome != Outcome.SUCCESS) return putOutcome
-        }
-        val commit = JSONArray()
-        for ((m, _) in metas) {
-            val p = byId[m.getString("frameId")]!!
-            commit.put(frameCommitMeta(m).put("storageKey", p.getString("storageKey")).put("contentType", p.optString("contentType")))
-        }
-        return classify(postJson("/ingestion/sessions/$sessionId/frames", JSONObject().put("frames", commit)))
-    }
-
-    private fun commitFramesInline(sessionId: String, metas: List<Pair<JSONObject, File>>): Outcome {
-        val commit = JSONArray()
-        for ((m, metaFile) in metas) {
-            val img = outbox.frameImageFor(metaFile) ?: return Outcome.SERVER_TRANSIENT
-            val b64 = Base64.encodeToString(img.readBytes(), Base64.NO_WRAP)
-            commit.put(frameCommitMeta(m).put("imageData", b64))
-        }
-        return classify(postJson("/ingestion/sessions/$sessionId/frames", JSONObject().put("frames", commit)))
-    }
-
-    /** The committed frame metadata (mirrors BackendSessionAdapter._frameMeta). */
-    private fun frameCommitMeta(m: JSONObject): JSONObject = JSONObject()
-        .put("frameId", m.getString("frameId"))
-        .put("sessionId", m.getString("sessionId"))
-        .put("timestamp", m.optLong("timestamp"))
-        .put("sequenceNumber", m.optInt("sequenceNumber"))
-        .put("frameType", m.optString("frameType", "keyframe"))
-        .put("baseFrameId", m.opt("baseFrameId"))
-        .put("screenName", m.optString("screenName", ""))
-        .put("trigger", m.optString("trigger", ""))
-        .put("format", m.optString("format", "webp"))
-        .put("width", m.optInt("width"))
-        .put("height", m.optInt("height"))
-        .put("sizeBytes", m.optInt("sizeBytes"))
-        .put("masked", m.optBoolean("masked", false))
-
-    // ─── Telemetry segments ─────────────────────────────────────────────
-
-    private fun uploadSegments(sessionId: String, lane: String, now: Long) {
-        for (metaFile in outbox.dueSegments(sessionId, lane, now)) {
-            val claimed = outbox.moveSegmentToUploading(metaFile) ?: continue
-            val data = outbox.segmentDataFor(claimed)
-            if (data == null) { outbox.deleteSegment(claimed); continue }
-            val records = JSONArray()
-            data.forEachLine { line -> if (line.isNotBlank()) runCatching { records.put(JSONObject(line)) } }
-            val payload = JSONObject().put(laneBodyKey(lane), records)
-            val resp = postJson("/ingestion/sessions/$sessionId/$lane", payload)
-            val outcome = classify(resp)
-            if (outcome == Outcome.SUCCESS) {
-                outbox.deleteSegment(claimed)
-            } else {
-                val retryAfter = if (resp is NetResult.Response) resp.retryAfterMs else 0L
-                failItem(claimed, isFrame = false, outcome = outcome, retryAfterMs = retryAfter)
-            }
-        }
-    }
-
-    private fun laneBodyKey(lane: String): String = when (lane) {
-        "network" -> "requests"
-        "errors" -> "errors"
-        "performance" -> "metrics"
-        "logs" -> "logs"
-        else -> "events"
-    }
-
-    // ─── Outcome routing ────────────────────────────────────────────────
-
-    private fun failItem(metaFile: File, isFrame: Boolean, outcome: Outcome, retryAfterMs: Long) {
-        when (outcome) {
-            Outcome.NETWORK_UNAVAILABLE ->
-                outbox.recordNetworkFailure(metaFile, isFrame, retryIntervalMs)
-            Outcome.SERVER_TRANSIENT -> {
-                val attempt = currentServerAttempt(metaFile)
-                val backoff = when {
-                    respectRetryAfter && retryAfterMs > 0 -> retryAfterMs
-                    strictThreeSecondRetry || attempt < 10 -> retryIntervalMs
-                    else -> expoBackoff(attempt)
-                }
-                outbox.recordServerFailure(metaFile, isFrame, attemptCap = maxUploadAttempts, backoffMs = backoff)
-            }
-            Outcome.SERVER_PERMANENT ->
-                outbox.recordServerFailure(metaFile, isFrame, attemptCap = poisonMaxAttempts,
-                    backoffMs = retryIntervalMs, permanent = true,
-                    statusCode = lastResponseCode, bodySnippet = lastResponseBody)
-            Outcome.SUCCESS -> { /* handled by caller */ }
-        }
-    }
-
-    private fun currentServerAttempt(metaFile: File): Int =
-        runCatching { JSONObject(metaFile.readText()).optInt("serverAttemptCount", 0) }.getOrDefault(0)
-
-    /** Map an HTTP result onto one of the four outcomes (section 6). */
-    private fun classify(r: NetResult?): Outcome = when (r) {
-        null, NetResult.NetworkError -> Outcome.NETWORK_UNAVAILABLE
-        is NetResult.Response -> {
-            lastResponseCode = r.code
-            lastResponseBody = r.body
-            classifyResponse(r)
-        }
-    }
-
-    private fun classifyResponse(r: NetResult.Response): Outcome = when {
-        r.code in 200..299 -> Outcome.SUCCESS
-        // 404 here always means the /ingestion/sessions/{id} row is not created
-        // yet (JS posts INGESTION_START asynchronously; native frame upload is
-        // ungated). Treat as transient so frames retry until the row exists,
-        // instead of poisoning valid frames in poisonMaxAttempts.
-        r.code == 404 || r.code == 429 || r.code in 500..599 -> Outcome.SERVER_TRANSIENT
-        r.code in 400..499 -> Outcome.SERVER_PERMANENT
-        else -> Outcome.SERVER_TRANSIENT
-    }
-
-    private fun expoBackoff(attempt: Int): Long {
-        val capped = (attempt - 10).coerceIn(0, 10)
-        val base = retryIntervalMs * (1L shl capped)
-        val jitter = (Math.random() * 0.2 * base).toLong()
-        return (base + jitter).coerceAtMost(30 * 60_000L)
-    }
-
-    // ─── HTTP ───────────────────────────────────────────────────────────
-
-    private sealed interface NetResult {
-        /** A response WAS received from the server. */
-        data class Response(val code: Int, val body: String, val retryAfterMs: Long) : NetResult
-        /** The request never reached the server (no connectivity/DNS/TLS/timeout). */
-        object NetworkError : NetResult
-    }
-
-    private fun postJson(path: String, body: JSONObject): NetResult {
-        var conn: HttpURLConnection? = null
-        return try {
-            conn = (URL("$apiBaseUrl$path").openConnection() as HttpURLConnection).apply {
-                requestMethod = "POST"
-                setRequestProperty("Content-Type", "application/json")
-                setRequestProperty("x-scalebun-client-key", clientKey)
-                setRequestProperty("User-Agent", "ReplaySdk-Android-Outbox/0.1.0")
-                connectTimeout = 30_000; readTimeout = 30_000; doOutput = true
-            }
-            conn.outputStream.use { it.write(body.toString().toByteArray()) }
-            val code = conn.responseCode
-            val stream = if (code in 200..299) conn.inputStream else conn.errorStream
-            val text = stream?.bufferedReader()?.use { it.readText() } ?: ""
-            NetResult.Response(code, text, parseRetryAfter(conn.getHeaderField("Retry-After")))
-        } catch (e: Exception) {
-            ReplayLogger.warn("outbox POST $path: ${classifyException(e)}")
-            // Fail-safe: any transport exception is treated as NETWORK_UNAVAILABLE so a
-            // valid batch is NEVER marched to dead while the user is merely offline.
-            NetResult.NetworkError
-        } finally {
-            conn?.disconnect()
-        }
-    }
-
-    private fun putBytes(uploadUrl: String, bytes: ByteArray, contentType: String): NetResult {
-        var conn: HttpURLConnection? = null
-        return try {
-            conn = (URL(uploadUrl).openConnection() as HttpURLConnection).apply {
-                requestMethod = "PUT"
-                setRequestProperty("Content-Type", contentType)
-                connectTimeout = 30_000; readTimeout = 60_000; doOutput = true
-                setFixedLengthStreamingMode(bytes.size)
-            }
-            conn.outputStream.use { it.write(bytes) }
-            val code = conn.responseCode
-            // Capture the body on failure so signature/permission errors (e.g. R2
-            // SignatureDoesNotMatch) surface in the poison log instead of "".
-            val errBody = if (code in 200..299) "" else
-                conn.errorStream?.bufferedReader()?.use { it.readText() } ?: ""
-            NetResult.Response(code, errBody, parseRetryAfter(conn.getHeaderField("Retry-After")))
-        } catch (e: Exception) {
-            ReplayLogger.warn("outbox PUT: ${classifyException(e)}")
-            NetResult.NetworkError
-        } finally {
-            conn?.disconnect()
-        }
-    }
-
-    private fun classifyException(e: Exception): String = when (e) {
-        is UnknownHostException, is ConnectException, is NoRouteToHostException,
-        is SSLException, is SocketTimeoutException, is SocketException -> "network-unavailable (${e.javaClass.simpleName})"
-        else -> "network-unavailable (${e.message})"
-    }
-
-    private fun parseRetryAfter(header: String?): Long {
-        if (header.isNullOrBlank()) return 0L
-        return header.toLongOrNull()?.times(1000) ?: 0L  // seconds → ms (HTTP-date form ignored)
-    }
-
-    fun destroy() {
-        executor.shutdownNow()
-        timer.shutdownNow()
-    }
-}
+package com.scalebun.replaysdk.outbox
+
+import android.util.Base64
+import com.scalebun.replaysdk.core.ReplayLogger
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import java.net.ConnectException
+import java.net.HttpURLConnection
+import java.net.NoRouteToHostException
+import java.net.SocketException
+import java.net.SocketTimeoutException
+import java.net.URL
+import java.net.UnknownHostException
+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.AtomicBoolean
+import javax.net.ssl.SSLException
+
+/**
+ * Native uploader that drains [NativeOutbox] against the /ingestion contract.
+ *
+ * Frame flow (object storage):  presign → PUT bytes → commit key-only metadata.
+ * Frame flow (storage disabled): inline base64 commit (bytes go over HTTP to the
+ *   backend, NEVER over the JS bridge).
+ * Telemetry flow: read a closed JSONL segment → POST the lane batch.
+ *
+ * Network-aware retry (section 6). Every attempt is classified into exactly one
+ * outcome and routed through the two-counter model on [NativeOutbox]:
+ *   SUCCESS            → delete on ACK
+ *   NETWORK_UNAVAILABLE→ keep pending, bump networkFailureCount only, never dead
+ *   SERVER_TRANSIENT   → bump serverAttemptCount, dead at maxUploadAttempts
+ *   SERVER_PERMANENT   → poison, dead at poisonMaxAttempts
+ *
+ * Upload loop (section 7) is event-driven: [flush] is called on immediate triggers
+ * (batch full, segment closed, session end, foreground, startup, network restored).
+ * A coalesced 3s retry timer is armed ONLY when there is pending work AND network is
+ * available AND something is due; it is cancelled when the queue empties or network
+ * drops. No wakeups while idle or offline.
+ */
+class OutboxUploader(
+    private val outbox: NativeOutbox,
+    @Volatile private var apiBaseUrl: String,
+    @Volatile private var clientKey: String,
+    private val useObjectStorageForFrames: Boolean,
+    /** serverAttemptCount cap → dead (nativeOutboxMaxUploadAttempts, default 30). */
+    private val maxUploadAttempts: Int = 30,
+    private val frameBatch: Int = 20,
+    /** retry cadence when the timer is armed (nativeOutboxRetryIntervalMs, default 3000). */
+    private val retryIntervalMs: Long = 3000,
+    /** poison (4xx≠429) attempts before dead (nativeOutboxPoisonMaxAttempts, default 2). */
+    private val poisonMaxAttempts: Int = 2,
+    /** honor a Retry-After response header (nativeOutboxRespectRetryAfter, default true). */
+    private val respectRetryAfter: Boolean = true,
+    /** stay at 3s forever vs. switch to backoff after 10 attempts (default false → backoff). */
+    private val strictThreeSecondRetry: Boolean = false,
+) {
+    private val executor = Executors.newSingleThreadExecutor { r -> Thread(r, "ReplaySdk-Outbox") }
+    private val timer: ScheduledExecutorService =
+        Executors.newSingleThreadScheduledExecutor { r -> Thread(r, "ReplaySdk-OutboxTimer") }
+    private val running = AtomicBoolean(false)
+    private val rerun = AtomicBoolean(false)
+    @Volatile private var armed: ScheduledFuture<*>? = null
+    // Default true so the first attempt is allowed even before the monitor reports in.
+    @Volatile private var networkAvailable: Boolean = true
+    // Latched off for the rest of the process once the backend reports storage disabled.
+    @Volatile private var objectStorageActive = useObjectStorageForFrames
+    // Last HTTP status seen by classify(); used to log the real code on poison/dead.
+    @Volatile private var lastResponseCode: Int = 0
+    @Volatile private var lastResponseBody: String = ""
+
+    private enum class Outcome { SUCCESS, NETWORK_UNAVAILABLE, SERVER_TRANSIENT, SERVER_PERMANENT }
+
+    fun updateConfig(apiBaseUrl: String, clientKey: String) {
+        this.apiBaseUrl = apiBaseUrl
+        this.clientKey = clientKey
+    }
+
+    /** Called by the ConnectivityManager.NetworkCallback in the module. */
+    fun setNetworkAvailable(available: Boolean) {
+        val was = networkAvailable
+        networkAvailable = available
+        if (available && !was) {
+            // Network restored → wake immediately and drain (section 7 trigger).
+            flush()
+        } else if (!available) {
+            // Offline → cancel the retry timer; rely on the listener to wake us.
+            cancelTimer()
+        }
+    }
+
+    /** Trigger a non-blocking drain. Safe from any thread / any lifecycle hook. */
+    fun flush() {
+        if (clientKey.isEmpty() || apiBaseUrl.isEmpty()) return
+        executor.execute {
+            if (!running.compareAndSet(false, true)) {
+                // A drain is already in progress → coalesce into a single rerun.
+                rerun.set(true)
+                return@execute
+            }
+            try {
+                do {
+                    rerun.set(false)
+                    drain()
+                } while (rerun.get())
+            } catch (e: Exception) {
+                ReplayLogger.warn("outbox.flush error: ${e.message}")
+            } finally {
+                running.set(false)
+                reconcileTimer()
+            }
+        }
+    }
+
+    private fun drain() {
+        // Offline → do not attempt, do not spin. The connectivity listener wakes us.
+        if (!networkAvailable) return
+        val now = System.currentTimeMillis()
+        for (sessionId in outbox.listSessionIds()) {
+            uploadFrames(sessionId, now)
+            for (lane in NativeOutbox.TELEMETRY_LANES) uploadSegments(sessionId, lane, now)
+        }
+        outbox.enforceLimits()
+    }
+
+    // ─── Timer arming (section 7) ───────────────────────────────────────
+
+    /** Arm the 3s timer ONLY if pending work exists, network is up, and a batch is due. */
+    private fun reconcileTimer() {
+        val now = System.currentTimeMillis()
+        val due = networkAvailable && hasDueWork(now)
+        if (due) {
+            if (armed == null || armed?.isDone == true) {
+                armed = timer.schedule({ flush() }, retryIntervalMs, TimeUnit.MILLISECONDS)
+            }
+        } else {
+            cancelTimer()
+        }
+    }
+
+    private fun cancelTimer() {
+        armed?.cancel(false)
+        armed = null
+    }
+
+    private fun hasDueWork(now: Long): Boolean {
+        for (sessionId in outbox.listSessionIds()) {
+            if (outbox.dueFrameMetas(sessionId, now).isNotEmpty()) return true
+            for (lane in NativeOutbox.TELEMETRY_LANES) {
+                if (outbox.dueSegments(sessionId, lane, now).isNotEmpty()) return true
+            }
+        }
+        return false
+    }
+
+    // ─── Frames ─────────────────────────────────────────────────────────
+
+    private fun uploadFrames(sessionId: String, now: Long) {
+        val due = outbox.dueFrameMetas(sessionId, now).take(frameBatch)
+        if (due.isEmpty()) return
+        val claimed = due.mapNotNull { outbox.moveFrameToUploading(it) }
+        if (claimed.isEmpty()) return
+        val metas = claimed.mapNotNull { f -> runCatching { JSONObject(f.readText()) to f }.getOrNull() }
+
+        if (objectStorageActive) {
+            val outcome = uploadFramesViaStorage(sessionId, metas)
+            if (objectStorageActive) {
+                // Storage still active → this outcome is authoritative for the batch.
+                if (outcome == Outcome.SUCCESS) metas.forEach { outbox.deleteFrame(it.second) }
+                else applyFrameOutcome(metas, outcome)
+                return
+            }
+            // else: backend reported storage disabled mid-flight → fall through to inline.
+        }
+        val inline = commitFramesInline(sessionId, metas)
+        if (inline == Outcome.SUCCESS) metas.forEach { outbox.deleteFrame(it.second) }
+        else applyFrameOutcome(metas, inline)
+    }
+
+    private fun applyFrameOutcome(metas: List<Pair<JSONObject, File>>, outcome: Outcome) {
+        metas.forEach { failItem(it.second, isFrame = true, outcome = outcome, retryAfterMs = 0L) }
+    }
+
+    /** Returns the batch outcome; SUCCESS means PUT(s)+commit all acknowledged. */
+    private fun uploadFramesViaStorage(sessionId: String, metas: List<Pair<JSONObject, File>>): Outcome {
+        val presignReq = JSONArray()
+        for ((m, _) in metas) {
+            presignReq.put(JSONObject()
+                .put("frameId", m.getString("frameId"))
+                .put("contentType", m.optString("contentType", "image/webp"))
+                .put("format", m.optString("format", "webp")))
+        }
+        val presign = postJson("/ingestion/sessions/$sessionId/frames/presign", JSONObject().put("frames", presignReq))
+        val pOutcome = classify(presign)
+        if (pOutcome != Outcome.SUCCESS) return pOutcome
+        val body = runCatching { JSONObject((presign as NetResult.Response).body) }.getOrNull()
+            ?: return Outcome.SERVER_TRANSIENT
+        if (!body.optBoolean("enabled", false)) {
+            objectStorageActive = false
+            ReplayLogger.info("outbox: object storage disabled server-side; falling back to inline")
+            // objectStorageActive is now false → caller re-checks it and falls through to
+            // inline, so this return value is not used to fail/delete the batch.
+            return Outcome.SUCCESS
+        }
+        val byId = HashMap<String, JSONObject>()
+        val arr = body.optJSONArray("frames") ?: JSONArray()
+        for (i in 0 until arr.length()) { val p = arr.getJSONObject(i); byId[p.getString("frameId")] = p }
+        for ((m, metaFile) in metas) {
+            val p = byId[m.getString("frameId")] ?: return Outcome.SERVER_TRANSIENT
+            val img = outbox.frameImageFor(metaFile) ?: return Outcome.SERVER_TRANSIENT
+            val putOutcome = classify(putBytes(p.getString("uploadUrl"), img.readBytes(),
+                p.optString("contentType", m.optString("contentType"))))
+            if (putOutcome != Outcome.SUCCESS) return putOutcome
+        }
+        val commit = JSONArray()
+        for ((m, _) in metas) {
+            val p = byId[m.getString("frameId")]!!
+            commit.put(frameCommitMeta(m).put("storageKey", p.getString("storageKey")).put("contentType", p.optString("contentType")))
+        }
+        return classify(postJson("/ingestion/sessions/$sessionId/frames", JSONObject().put("frames", commit)))
+    }
+
+    private fun commitFramesInline(sessionId: String, metas: List<Pair<JSONObject, File>>): Outcome {
+        val commit = JSONArray()
+        for ((m, metaFile) in metas) {
+            val img = outbox.frameImageFor(metaFile) ?: return Outcome.SERVER_TRANSIENT
+            val b64 = Base64.encodeToString(img.readBytes(), Base64.NO_WRAP)
+            commit.put(frameCommitMeta(m).put("imageData", b64))
+        }
+        return classify(postJson("/ingestion/sessions/$sessionId/frames", JSONObject().put("frames", commit)))
+    }
+
+    /** The committed frame metadata (mirrors BackendSessionAdapter._frameMeta). */
+    private fun frameCommitMeta(m: JSONObject): JSONObject = JSONObject()
+        .put("frameId", m.getString("frameId"))
+        .put("sessionId", m.getString("sessionId"))
+        .put("timestamp", m.optLong("timestamp"))
+        .put("sequenceNumber", m.optInt("sequenceNumber"))
+        .put("frameType", m.optString("frameType", "keyframe"))
+        .put("baseFrameId", m.opt("baseFrameId"))
+        .put("screenName", m.optString("screenName", ""))
+        .put("trigger", m.optString("trigger", ""))
+        .put("format", m.optString("format", "webp"))
+        .put("width", m.optInt("width"))
+        .put("height", m.optInt("height"))
+        .put("sizeBytes", m.optInt("sizeBytes"))
+        .put("masked", m.optBoolean("masked", false))
+
+    // ─── Telemetry segments ─────────────────────────────────────────────
+
+    private fun uploadSegments(sessionId: String, lane: String, now: Long) {
+        for (metaFile in outbox.dueSegments(sessionId, lane, now)) {
+            val claimed = outbox.moveSegmentToUploading(metaFile) ?: continue
+            val data = outbox.segmentDataFor(claimed)
+            if (data == null) { outbox.deleteSegment(claimed); continue }
+            val records = JSONArray()
+            data.forEachLine { line -> if (line.isNotBlank()) runCatching { records.put(JSONObject(line)) } }
+            val payload = JSONObject().put(laneBodyKey(lane), records)
+            val resp = postJson("/ingestion/sessions/$sessionId/$lane", payload)
+            val outcome = classify(resp)
+            if (outcome == Outcome.SUCCESS) {
+                outbox.deleteSegment(claimed)
+            } else {
+                val retryAfter = if (resp is NetResult.Response) resp.retryAfterMs else 0L
+                failItem(claimed, isFrame = false, outcome = outcome, retryAfterMs = retryAfter)
+            }
+        }
+    }
+
+    private fun laneBodyKey(lane: String): String = when (lane) {
+        "network" -> "requests"
+        "errors" -> "errors"
+        "performance" -> "metrics"
+        "logs" -> "logs"
+        else -> "events"
+    }
+
+    // ─── Outcome routing ────────────────────────────────────────────────
+
+    private fun failItem(metaFile: File, isFrame: Boolean, outcome: Outcome, retryAfterMs: Long) {
+        when (outcome) {
+            Outcome.NETWORK_UNAVAILABLE ->
+                outbox.recordNetworkFailure(metaFile, isFrame, retryIntervalMs)
+            Outcome.SERVER_TRANSIENT -> {
+                val attempt = currentServerAttempt(metaFile)
+                val backoff = when {
+                    respectRetryAfter && retryAfterMs > 0 -> retryAfterMs
+                    strictThreeSecondRetry || attempt < 10 -> retryIntervalMs
+                    else -> expoBackoff(attempt)
+                }
+                outbox.recordServerFailure(metaFile, isFrame, attemptCap = maxUploadAttempts, backoffMs = backoff)
+            }
+            Outcome.SERVER_PERMANENT ->
+                outbox.recordServerFailure(metaFile, isFrame, attemptCap = poisonMaxAttempts,
+                    backoffMs = retryIntervalMs, permanent = true,
+                    statusCode = lastResponseCode, bodySnippet = lastResponseBody)
+            Outcome.SUCCESS -> { /* handled by caller */ }
+        }
+    }
+
+    private fun currentServerAttempt(metaFile: File): Int =
+        runCatching { JSONObject(metaFile.readText()).optInt("serverAttemptCount", 0) }.getOrDefault(0)
+
+    /** Map an HTTP result onto one of the four outcomes (section 6). */
+    private fun classify(r: NetResult?): Outcome = when (r) {
+        null, NetResult.NetworkError -> Outcome.NETWORK_UNAVAILABLE
+        is NetResult.Response -> {
+            lastResponseCode = r.code
+            lastResponseBody = r.body
+            classifyResponse(r)
+        }
+    }
+
+    private fun classifyResponse(r: NetResult.Response): Outcome = when {
+        r.code in 200..299 -> Outcome.SUCCESS
+        // 404 here always means the /ingestion/sessions/{id} row is not created
+        // yet (JS posts INGESTION_START asynchronously; native frame upload is
+        // ungated). Treat as transient so frames retry until the row exists,
+        // instead of poisoning valid frames in poisonMaxAttempts.
+        r.code == 404 || r.code == 429 || r.code in 500..599 -> Outcome.SERVER_TRANSIENT
+        r.code in 400..499 -> Outcome.SERVER_PERMANENT
+        else -> Outcome.SERVER_TRANSIENT
+    }
+
+    private fun expoBackoff(attempt: Int): Long {
+        val capped = (attempt - 10).coerceIn(0, 10)
+        val base = retryIntervalMs * (1L shl capped)
+        val jitter = (Math.random() * 0.2 * base).toLong()
+        return (base + jitter).coerceAtMost(30 * 60_000L)
+    }
+
+    // ─── HTTP ───────────────────────────────────────────────────────────
+
+    private sealed interface NetResult {
+        /** A response WAS received from the server. */
+        data class Response(val code: Int, val body: String, val retryAfterMs: Long) : NetResult
+        /** The request never reached the server (no connectivity/DNS/TLS/timeout). */
+        object NetworkError : NetResult
+    }
+
+    private fun postJson(path: String, body: JSONObject): NetResult {
+        var conn: HttpURLConnection? = null
+        return try {
+            conn = (URL("$apiBaseUrl$path").openConnection() as HttpURLConnection).apply {
+                requestMethod = "POST"
+                setRequestProperty("Content-Type", "application/json")
+                setRequestProperty("x-scalebun-client-key", clientKey)
+                setRequestProperty("User-Agent", "ReplaySdk-Android-Outbox/0.1.0")
+                connectTimeout = 30_000; readTimeout = 30_000; doOutput = true
+            }
+            conn.outputStream.use { it.write(body.toString().toByteArray()) }
+            val code = conn.responseCode
+            val stream = if (code in 200..299) conn.inputStream else conn.errorStream
+            val text = stream?.bufferedReader()?.use { it.readText() } ?: ""
+            NetResult.Response(code, text, parseRetryAfter(conn.getHeaderField("Retry-After")))
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox POST $path: ${classifyException(e)}")
+            // Fail-safe: any transport exception is treated as NETWORK_UNAVAILABLE so a
+            // valid batch is NEVER marched to dead while the user is merely offline.
+            NetResult.NetworkError
+        } finally {
+            conn?.disconnect()
+        }
+    }
+
+    private fun putBytes(uploadUrl: String, bytes: ByteArray, contentType: String): NetResult {
+        var conn: HttpURLConnection? = null
+        return try {
+            conn = (URL(uploadUrl).openConnection() as HttpURLConnection).apply {
+                requestMethod = "PUT"
+                setRequestProperty("Content-Type", contentType)
+                connectTimeout = 30_000; readTimeout = 60_000; doOutput = true
+                setFixedLengthStreamingMode(bytes.size)
+            }
+            conn.outputStream.use { it.write(bytes) }
+            val code = conn.responseCode
+            // Capture the body on failure so signature/permission errors (e.g. R2
+            // SignatureDoesNotMatch) surface in the poison log instead of "".
+            val errBody = if (code in 200..299) "" else
+                conn.errorStream?.bufferedReader()?.use { it.readText() } ?: ""
+            NetResult.Response(code, errBody, parseRetryAfter(conn.getHeaderField("Retry-After")))
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox PUT: ${classifyException(e)}")
+            NetResult.NetworkError
+        } finally {
+            conn?.disconnect()
+        }
+    }
+
+    private fun classifyException(e: Exception): String = when (e) {
+        is UnknownHostException, is ConnectException, is NoRouteToHostException,
+        is SSLException, is SocketTimeoutException, is SocketException -> "network-unavailable (${e.javaClass.simpleName})"
+        else -> "network-unavailable (${e.message})"
+    }
+
+    private fun parseRetryAfter(header: String?): Long {
+        if (header.isNullOrBlank()) return 0L
+        return header.toLongOrNull()?.times(1000) ?: 0L  // seconds → ms (HTTP-date form ignored)
+    }
+
+    fun destroy() {
+        executor.shutdownNow()
+        timer.shutdownNow()
+    }
+}