@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,559 @@
+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 = ""
+    @Volatile private var lastRetryAfterMs: Long = 0L
+
+    /**
+     * Lanes parked by a per-feature quota block (shared contract v1). A parked lane is neither
+     * drained nor counted as due work, so it never arms the retry timer; the drain re-checks it per
+     * item, so a park from the bridge takes effect mid-drain. Concurrent set: written from the bridge
+     * thread and the upload executor.
+     */
+    private val quotaBlockedLanes: MutableSet<String> = java.util.concurrent.ConcurrentHashMap.newKeySet()
+
+    /**
+     * Called (on the upload executor) after the server refused (402 quota_exceeded) or partially
+     * granted (2xx with quota.refused > 0) a LIMITED feature: (HTTP status, response body, Retry-After
+     * ms). By then the feature's lane is parked + purged — or, for `sessions`, only that session's
+     * directory is deleted. JS records the refusal from the body and re-syncs every lane's state.
+     */
+    /** Arguments: (HTTP status, response body, Retry-After ms, sessionId of the refused write). */
+    @Volatile var onQuotaExceeded: ((Int, String, Long, String) -> Unit)? = null
+
+    /**
+     * Called (on the upload executor) the moment the uploader parks a lane ITSELF (402 / partial
+     * grant), so the host module's parked set — which gates enqueue, commit and capture-to-file —
+     * updates immediately instead of waiting for JS to round-trip a sync.
+     */
+    @Volatile var onLaneParked: ((String) -> Unit)? = null
+
+    companion object {
+        /**
+         * Limited feature → the outbox lane that carries it. `sessions` has no lane; errors, logs and
+         * performance are never limited, so they can never be parked.
+         */
+        val QUOTA_FEATURE_LANES: Map<String, String> = mapOf(
+            "frames" to NativeOutbox.FRAMES, "networkRequests" to "network", "events" to "events",
+        )
+
+        /** The limited feature a 402 body refuses, or null when it is not code "quota_exceeded". */
+        fun refusedFeature(body: String): String? = try {
+            val o = JSONObject(body)
+            val f = o.optString("feature", "")
+            if (o.optString("code", "") == "quota_exceeded" && (f == "sessions" || QUOTA_FEATURE_LANES.containsKey(f))) f else null
+        } catch (e: Exception) { null }
+
+        /** The limited feature a 2xx PARTIAL grant (quota.refused > 0) exhausted, or null. */
+        fun partialGrantFeature(body: String): String? = try {
+            if (!body.contains("\"quota\"")) null else {
+                val q = JSONObject(body).optJSONObject("quota")
+                val f = q?.optString("feature", "") ?: ""
+                if (q != null && QUOTA_FEATURE_LANES.containsKey(f) && q.optInt("refused", 0) > 0) f else null
+            }
+        } catch (e: Exception) { null }
+    }
+
+    private enum class Outcome { SUCCESS, NETWORK_UNAVAILABLE, SERVER_TRANSIENT, SERVER_PERMANENT, QUOTA_EXCEEDED }
+
+    /**
+     * Park (and purge) or un-park a lane for a quota block. The parked set changes immediately (the
+     * drain re-checks it per item); the purge runs on the upload executor, serialized with any
+     * in-flight drain. JS sends the FULL lane state on every quota sync, so a lane parked here by a
+     * 402 is un-parked by the next sync that no longer lists its feature.
+     */
+    fun setLaneQuotaBlocked(lane: String, blocked: Boolean) {
+        if (lane !in QUOTA_FEATURE_LANES.values) return
+        if (blocked) {
+            quotaBlockedLanes.add(lane)
+            try { executor.execute { outbox.purgeLane(lane) } } catch (e: Exception) { outbox.purgeLane(lane) }
+        } else if (quotaBlockedLanes.remove(lane)) {
+            flush()
+        }
+    }
+
+    /** Runs on the upload executor. Park + purge a lane (flag first so the drain stops at once). */
+    private fun parkLane(lane: String, why: String) {
+        quotaBlockedLanes.add(lane)
+        try { onLaneParked?.invoke(lane) } catch (e: Exception) { }
+        val removed = outbox.purgeLane(lane)
+        ReplayLogger.warn("outbox: $lane $why — lane parked, $removed file(s) purged")
+    }
+
+    /**
+     * Runs on the upload executor. A 402 quota_exceeded came back for a write of [sessionId]. The lane
+     * parked is the one of the feature NAMED IN THE BODY — never simply the lane the response came
+     * back on. `sessions` (the backend answers every child lane of a refused session that way)
+     * deletes only that session's directory and parks nothing.
+     */
+    private fun handleQuotaRefusal(sessionId: String) {
+        val feature = refusedFeature(lastResponseBody) ?: ""
+        if (feature == "sessions") {
+            outbox.purgeSession(sessionId)
+            ReplayLogger.warn("outbox: session $sessionId refused for quota (sessions) — its stored data deleted")
+        } else {
+            QUOTA_FEATURE_LANES[feature]?.let { parkLane(it, "refused for quota (HTTP 402, $feature)") }
+        }
+        try { onQuotaExceeded?.invoke(402, lastResponseBody, lastRetryAfterMs, sessionId) } catch (e: Exception) { }
+    }
+
+    /** Runs on the upload executor, right after a 2xx: a partial grant spends the allowance. */
+    private fun checkPartialGrant(sessionId: String) {
+        val f = partialGrantFeature(lastResponseBody) ?: return
+        val lane = QUOTA_FEATURE_LANES[f] ?: return
+        parkLane(lane, "partially granted ($f allowance spent)")
+        try { onQuotaExceeded?.invoke(lastResponseCode, lastResponseBody, lastRetryAfterMs, sessionId) } catch (e: Exception) { }
+    }
+
+    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()) {
+            if (NativeOutbox.FRAMES !in quotaBlockedLanes) uploadFrames(sessionId, now)
+            for (lane in NativeOutbox.TELEMETRY_LANES) {
+                if (lane !in quotaBlockedLanes) 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 (NativeOutbox.FRAMES !in quotaBlockedLanes &&
+                outbox.dueFrameMetas(sessionId, now).isNotEmpty()) return true
+            for (lane in NativeOutbox.TELEMETRY_LANES) {
+                if (lane in quotaBlockedLanes) continue
+                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) }; checkPartialGrant(sessionId) }
+                else if (outcome == Outcome.QUOTA_EXCEEDED) {
+                    handleQuotaRefusal(sessionId)
+                    metas.forEach { outbox.deleteFrame(it.second) } // never retried (no-op if purged)
+                }
+                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) }; checkPartialGrant(sessionId) }
+        else if (inline == Outcome.QUOTA_EXCEEDED) {
+            handleQuotaRefusal(sessionId)
+            metas.forEach { outbox.deleteFrame(it.second) } // never retried (no-op if purged)
+        }
+        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 {
+        // Read every image FIRST: `sizeBytes` must be the exact bytes we will PUT (the backend signs
+        // that Content-Length into the URL), and a partial grant may purge the frames lane — images
+        // already in memory are still PUT for the frames that were granted.
+        val presignReq = JSONArray()
+        val imageBytes = HashMap<String, ByteArray>()
+        for ((m, metaFile) in metas) {
+            val fid = m.getString("frameId")
+            val img = outbox.frameImageFor(metaFile) ?: return Outcome.SERVER_TRANSIENT
+            val bytes = runCatching { img.readBytes() }.getOrNull() ?: return Outcome.SERVER_TRANSIENT
+            imageBytes[fid] = bytes
+            presignReq.put(JSONObject()
+                .put("frameId", fid)
+                .put("contentType", m.optString("contentType", "image/webp"))
+                .put("format", m.optString("format", "webp"))
+                .put("sizeBytes", bytes.size))
+        }
+        val presign = postJson("/ingestion/sessions/$sessionId/frames/presign", JSONObject().put("frames", presignReq))
+        val pOutcome = classify(presign)
+        if (pOutcome != Outcome.SUCCESS) return pOutcome
+        // Partial grant: URLs only up to the remaining allowance, plus a `quota` block → park frames.
+        checkPartialGrant(sessionId)
+        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 }
+        // A frame WITHOUT a URL was refused for quota: dropped (the caller deletes every claimed item
+        // on SUCCESS), never retried.
+        val granted = metas.filter { byId.containsKey(it.first.getString("frameId")) }
+        if (granted.size < metas.size) {
+            ReplayLogger.warn("outbox: presign granted ${granted.size}/${metas.size} frame(s); the rest are dropped (quota)")
+        }
+        if (granted.isEmpty()) return Outcome.SUCCESS
+        for ((m, _) in granted) {
+            val fid = m.getString("frameId")
+            val p = byId[fid] ?: return Outcome.SERVER_TRANSIENT
+            val bytes = imageBytes[fid] ?: return Outcome.SERVER_TRANSIENT
+            val putOutcome = classify(putBytes(p.getString("uploadUrl"), bytes,
+                p.optString("contentType", m.optString("contentType"))))
+            if (putOutcome != Outcome.SUCCESS) return putOutcome
+        }
+        val commit = JSONArray()
+        for ((m, _) in granted) {
+            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))
+        // Visible scroll containers at capture time — JS sanitized it before commit. Enumerated
+        // here on purpose: this builder lists fields, so a field it does not name never uploads.
+        .apply { m.optJSONArray("scrollState")?.let { put("scrollState", it) } }
+
+    // ─── Telemetry segments ─────────────────────────────────────────────
+
+    private fun uploadSegments(sessionId: String, lane: String, now: Long) {
+        for (metaFile in outbox.dueSegments(sessionId, lane, now)) {
+            // Re-checked per segment: a park can arrive from the bridge mid-drain.
+            if (lane in quotaBlockedLanes) return
+            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)
+                checkPartialGrant(sessionId)
+            } else if (outcome == Outcome.QUOTA_EXCEEDED) {
+                // Never retried. The body names the feature: its lane is parked + purged, or for
+                // `sessions` only this session's directory is deleted.
+                handleQuotaRefusal(sessionId)
+                outbox.deleteSegment(claimed) // no-op if already purged
+                return
+            } 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.QUOTA_EXCEEDED ->
+                // Routed to handleQuotaRefusal by the callers; if one ever lands here, drop the item —
+                // a quota refusal must not be retried.
+                if (isFrame) outbox.deleteFrame(metaFile) else outbox.deleteSegment(metaFile)
+            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
+            lastRetryAfterMs = r.retryAfterMs
+            classifyResponse(r)
+        }
+    }
+
+    private fun classifyResponse(r: NetResult.Response): Outcome = when {
+        r.code in 200..299 -> Outcome.SUCCESS
+        // 402 with code "quota_exceeded" for a limited feature (contract v1): never retried; the
+        // caller parks the lane of the feature the BODY names (or drops a refused session). Any other
+        // 402 is an ordinary permanent 4xx.
+        r.code == 402 && refusedFeature(r.body) != null -> Outcome.QUOTA_EXCEEDED
+        // 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/android/src/main/java/com/scalebun/replaysdk/privacy/PrivacyMaskProcessor.kt

@@ -0,0 +1,126 @@
+package com.scalebun.replaysdk.privacy
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.Rect
+import android.view.View
+import android.view.ViewGroup
+import android.widget.EditText
+import android.widget.ImageView
+import com.scalebun.replaysdk.core.ReplayConfig
+import com.scalebun.replaysdk.core.ReplayLogger
+
+/**
+ * Privacy mask processor for Android.
+ *
+ * Walks the view hierarchy before/after capture to:
+ * - Mask text inputs (EditText) with filled rectangles
+ * - Mask images (ImageView) if configured
+ * - Mask elements with specific testIDs/tags
+ *
+ * Strategy: Before capture, overlay masking content on views.
+ * After capture, restore original state.
+ *
+ * Alternative approach: Post-process the bitmap to paint over
+ * regions corresponding to sensitive views. This avoids state mutation.
+ */
+object PrivacyMaskProcessor {
+
+    /**
+     * Apply masking overlays to the bitmap based on the view hierarchy.
+     * This post-processes the captured bitmap — no view mutation needed.
+     */
+    fun applyMasking(
+        bitmap: Bitmap,
+        rootView: View,
+        config: ReplayConfig,
+        scaleX: Float = 1f,
+        scaleY: Float = 1f
+    ): Bitmap {
+        if (!config.maskTextInputs && !config.maskImages && config.maskedElementIds.isEmpty()) {
+            return bitmap
+        }
+
+        val mutableBitmap = bitmap.copy(Bitmap.Config.ARGB_8888, true)
+        val canvas = Canvas(mutableBitmap)
+        val maskPaint = Paint().apply {
+            color = Color.parseColor("#2A2A2A")
+            style = Paint.Style.FILL
+        }
+
+        val maskRects = mutableListOf<Rect>()
+        collectMaskRects(rootView, config, maskRects, IntArray(2).also { rootView.getLocationOnScreen(it) })
+
+        for (rect in maskRects) {
+            val scaledRect = Rect(
+                (rect.left * scaleX).toInt(),
+                (rect.top * scaleY).toInt(),
+                (rect.right * scaleX).toInt(),
+                (rect.bottom * scaleY).toInt()
+            )
+            canvas.drawRect(scaledRect, maskPaint)
+        }
+
+        if (maskRects.isNotEmpty()) {
+            ReplayLogger.debug("Applied ${maskRects.size} privacy masks")
+        }
+
+        return mutableBitmap
+    }
+
+    /**
+     * Walk the view hierarchy and collect rectangles for views that should be masked.
+     */
+    private fun collectMaskRects(
+        view: View,
+        config: ReplayConfig,
+        rects: MutableList<Rect>,
+        rootLocation: IntArray
+    ) {
+        if (view.visibility != View.VISIBLE) return
+
+        val shouldMask = when {
+            // Mask EditText if configured
+            config.maskTextInputs && view is EditText -> true
+            // Mask ImageView if configured
+            config.maskImages && view is ImageView -> true
+            // Mask by tag/testID
+            config.maskedElementIds.isNotEmpty() && shouldMaskById(view, config.maskedElementIds) -> true
+            else -> false
+        }
+
+        if (shouldMask) {
+            val location = IntArray(2)
+            view.getLocationOnScreen(location)
+            val rect = Rect(
+                location[0] - rootLocation[0],
+                location[1] - rootLocation[1],
+                location[0] - rootLocation[0] + view.width,
+                location[1] - rootLocation[1] + view.height
+            )
+            rects.add(rect)
+        }
+
+        // Recurse into children
+        if (view is ViewGroup) {
+            for (i in 0 until view.childCount) {
+                collectMaskRects(view.getChildAt(i), config, rects, rootLocation)
+            }
+        }
+    }
+
+    private fun shouldMaskById(view: View, maskedIds: List<String>): Boolean {
+        // Check tag
+        val tag = view.tag as? String
+        if (tag != null && maskedIds.contains(tag)) return true
+
+        // Check content description (used as testID in RN)
+        val contentDesc = view.contentDescription?.toString()
+        if (contentDesc != null && maskedIds.contains(contentDesc)) return true
+
+        return false
+    }
+}