@scalebun/react-native 1.0.1 → 1.0.2

package/ios/Outbox/OutboxUploader.swift

@@ -1,431 +1,431 @@
-import Foundation
-import Network
-
-/// Native uploader that drains `NativeOutbox` against the /ingestion contract.
-/// Swift mirror of the Android `OutboxUploader.kt`.
-///
-/// 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 of
-/// SUCCESS / NETWORK_UNAVAILABLE / SERVER_TRANSIENT / SERVER_PERMANENT and routed
-/// through the two-counter model on `NativeOutbox`. Offline never marches a batch to
-/// dead.
-///
-/// Upload loop (section 7): event-driven `flush()` on immediate triggers; a coalesced
-/// 3s retry timer armed ONLY when pending work exists AND network is up AND a batch is
-/// due; cancelled when the queue empties or the network drops. An `NWPathMonitor`
-/// wakes the loop the moment connectivity returns.
-final class OutboxUploader {
-
-    private let outbox: NativeOutbox
-    private var apiBaseUrl: String
-    private var clientKey: String
-    private let useObjectStorageForFrames: Bool
-    private let maxUploadAttempts: Int
-    private let frameBatch: Int
-    private let retryIntervalMs: Int64
-    private let poisonMaxAttempts: Int
-    private let respectRetryAfter: Bool
-    private let strictThreeSecondRetry: Bool
-
-    private let queue = DispatchQueue(label: "com.scalebun.replaysdk.outbox.upload")
-    private var running = false
-    private var rerun = false
-    private var objectStorageActive: Bool
-    private var networkAvailable = true
-    private var armed: DispatchWorkItem?
-    private let pathMonitor = NWPathMonitor()
-    private let monitorQueue = DispatchQueue(label: "com.scalebun.replaysdk.outbox.netmon")
-    // Last HTTP status/body seen by classify(); used to log the real code on poison/dead.
-    private var lastResponseCode = 0
-    private var lastResponseBody = ""
-
-    private enum Outcome { case success, networkUnavailable, serverTransient, serverPermanent }
-
-    private enum NetResult {
-        /// A response WAS received from the server.
-        case response(code: Int, body: String, retryAfterMs: Int64)
-        /// The request never reached the server (no connectivity/DNS/TLS/timeout).
-        case networkError
-    }
-
-    private lazy var session: URLSession = {
-        let cfg = URLSessionConfiguration.default
-        cfg.timeoutIntervalForRequest = 30
-        cfg.timeoutIntervalForResource = 90
-        return URLSession(configuration: cfg)
-    }()
-
-    init(outbox: NativeOutbox, apiBaseUrl: String, clientKey: String,
-         useObjectStorageForFrames: Bool, maxUploadAttempts: Int = 30, frameBatch: Int = 20,
-         retryIntervalMs: Int64 = 3000, poisonMaxAttempts: Int = 2,
-         respectRetryAfter: Bool = true, strictThreeSecondRetry: Bool = false) {
-        self.outbox = outbox
-        self.apiBaseUrl = apiBaseUrl
-        self.clientKey = clientKey
-        self.useObjectStorageForFrames = useObjectStorageForFrames
-        self.objectStorageActive = useObjectStorageForFrames
-        self.maxUploadAttempts = maxUploadAttempts
-        self.frameBatch = frameBatch
-        self.retryIntervalMs = retryIntervalMs
-        self.poisonMaxAttempts = poisonMaxAttempts
-        self.respectRetryAfter = respectRetryAfter
-        self.strictThreeSecondRetry = strictThreeSecondRetry
-        startPathMonitor()
-    }
-
-    func updateConfig(apiBaseUrl: String, clientKey: String) {
-        queue.async {
-            self.apiBaseUrl = apiBaseUrl
-            self.clientKey = clientKey
-        }
-    }
-
-    // ─── Connectivity (NWPathMonitor, section 6/7) ──────────────────────
-
-    private func startPathMonitor() {
-        pathMonitor.pathUpdateHandler = { [weak self] path in
-            self?.setNetworkAvailable(path.status == .satisfied)
-        }
-        pathMonitor.start(queue: monitorQueue)
-    }
-
-    func setNetworkAvailable(_ available: Bool) {
-        queue.async {
-            let was = self.networkAvailable
-            self.networkAvailable = available
-            if available && !was {
-                self.flushLocked()      // network restored → wake immediately
-            } else if !available {
-                self.cancelTimer()      // offline → park; rely on the monitor to wake us
-            }
-        }
-    }
-
-    /// Non-blocking drain. Safe from any thread / lifecycle hook.
-    func flush() {
-        if clientKey.isEmpty || apiBaseUrl.isEmpty { return }
-        queue.async { self.flushLocked() }
-    }
-
-    /// Must run on `queue`.
-    private func flushLocked() {
-        if clientKey.isEmpty || apiBaseUrl.isEmpty { return }
-        if running { rerun = true; return }   // coalesce concurrent wakes into one rerun
-        running = true
-        repeat {
-            rerun = false
-            drain()
-        } while rerun
-        running = false
-        reconcileTimer()
-    }
-
-    private func drain() {
-        if !networkAvailable { return }   // offline → don't attempt, don't spin
-        let now = nowMs()
-        for sessionId in outbox.listSessionIds() {
-            uploadFrames(sessionId, now)
-            for lane in NativeOutbox.TELEMETRY_LANES { uploadSegments(sessionId, lane, now) }
-        }
-        outbox.enforceLimits()
-    }
-
-    // ─── Timer arming (section 7) ───────────────────────────────────────
-
-    private func reconcileTimer() {
-        let now = nowMs()
-        if networkAvailable && hasDueWork(now) {
-            if armed == nil {
-                let work = DispatchWorkItem { [weak self] in
-                    self?.armed = nil
-                    self?.flushLocked()
-                }
-                armed = work
-                queue.asyncAfter(deadline: .now() + .milliseconds(Int(retryIntervalMs)), execute: work)
-            }
-        } else {
-            cancelTimer()
-        }
-    }
-
-    private func cancelTimer() {
-        armed?.cancel()
-        armed = nil
-    }
-
-    private func hasDueWork(_ now: Int64) -> Bool {
-        for sessionId in outbox.listSessionIds() {
-            if !outbox.dueFrameMetas(sessionId, now).isEmpty { return true }
-            for lane in NativeOutbox.TELEMETRY_LANES {
-                if !outbox.dueSegments(sessionId, lane, now).isEmpty { return true }
-            }
-        }
-        return false
-    }
-
-    // ─── Frames ─────────────────────────────────────────────────────────
-
-    private func uploadFrames(_ sessionId: String, _ now: Int64) {
-        let due = Array(outbox.dueFrameMetas(sessionId, now).prefix(frameBatch))
-        if due.isEmpty { return }
-        let claimed = due.compactMap { outbox.moveFrameToUploading($0) }
-        if claimed.isEmpty { return }
-        let metas: [(meta: [String: Any], file: URL)] = claimed.compactMap { f in
-            guard let data = try? Data(contentsOf: f),
-                  let obj = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else { return nil }
-            return (meta: obj, file: f)
-        }
-
-        if objectStorageActive {
-            let outcome = uploadFramesViaStorage(sessionId, metas)
-            if objectStorageActive {
-                if outcome == .success { metas.forEach { outbox.deleteFrame($0.file) } }
-                else { applyFrameOutcome(metas, outcome) }
-                return
-            }
-            // backend reported storage disabled mid-flight → fall through to inline.
-        }
-        let inline = commitFramesInline(sessionId, metas)
-        if inline == .success { metas.forEach { outbox.deleteFrame($0.file) } }
-        else { applyFrameOutcome(metas, inline) }
-    }
-
-    private func applyFrameOutcome(_ metas: [(meta: [String: Any], file: URL)], _ outcome: Outcome) {
-        metas.forEach { failItem($0.file, isFrame: true, outcome: outcome, retryAfterMs: 0) }
-    }
-
-    private func uploadFramesViaStorage(_ sessionId: String, _ metas: [(meta: [String: Any], file: URL)]) -> Outcome {
-        var presignFrames: [[String: Any]] = []
-        for (m, _) in metas {
-            presignFrames.append([
-                "frameId": m["frameId"] ?? "",
-                "contentType": (m["contentType"] as? String) ?? "image/webp",
-                "format": (m["format"] as? String) ?? "webp",
-            ])
-        }
-        let presign = postJson("/ingestion/sessions/\(sessionId)/frames/presign", ["frames": presignFrames])
-        let pOutcome = classify(presign)
-        if pOutcome != .success { return pOutcome }
-        guard case let .response(_, body, _) = presign,
-              let parsed = (try? JSONSerialization.jsonObject(with: Data(body.utf8))) as? [String: Any]
-        else { return .serverTransient }
-        if (parsed["enabled"] as? Bool) != true {
-            objectStorageActive = false
-            ReplayLogger.info("outbox: object storage disabled server-side; falling back to inline")
-            // objectStorageActive now false → caller re-checks and falls through to inline.
-            return .success
-        }
-        var byId: [String: [String: Any]] = [:]
-        for p in (parsed["frames"] as? [[String: Any]]) ?? [] {
-            if let fid = p["frameId"] as? String { byId[fid] = p }
-        }
-        for (m, metaFile) in metas {
-            guard let fid = m["frameId"] as? String, let p = byId[fid],
-                  let uploadUrl = p["uploadUrl"] as? String,
-                  let img = outbox.frameImageFor(metaFile),
-                  let bytes = try? Data(contentsOf: img) else { return .serverTransient }
-            let ct = (p["contentType"] as? String) ?? (m["contentType"] as? String) ?? "image/webp"
-            let putOutcome = classify(putBytes(uploadUrl, bytes, ct))
-            if putOutcome != .success { return putOutcome }
-        }
-        var commit: [[String: Any]] = []
-        for (m, _) in metas {
-            guard let fid = m["frameId"] as? String, let p = byId[fid] else { return .serverTransient }
-            var row = frameCommitMeta(m)
-            row["storageKey"] = p["storageKey"]
-            row["contentType"] = p["contentType"]
-            commit.append(row)
-        }
-        return classify(postJson("/ingestion/sessions/\(sessionId)/frames", ["frames": commit]))
-    }
-
-    private func commitFramesInline(_ sessionId: String, _ metas: [(meta: [String: Any], file: URL)]) -> Outcome {
-        var commit: [[String: Any]] = []
-        for (m, metaFile) in metas {
-            guard let img = outbox.frameImageFor(metaFile),
-                  let bytes = try? Data(contentsOf: img) else { return .serverTransient }
-            var row = frameCommitMeta(m)
-            row["imageData"] = bytes.base64EncodedString()
-            commit.append(row)
-        }
-        return classify(postJson("/ingestion/sessions/\(sessionId)/frames", ["frames": commit]))
-    }
-
-    private func frameCommitMeta(_ m: [String: Any]) -> [String: Any] {
-        var row: [String: Any] = [
-            "frameId": m["frameId"] ?? "",
-            "sessionId": m["sessionId"] ?? "",
-            "timestamp": m["timestamp"] ?? 0,
-            "sequenceNumber": m["sequenceNumber"] ?? 0,
-            "frameType": (m["frameType"] as? String) ?? "keyframe",
-            "screenName": (m["screenName"] as? String) ?? "",
-            "trigger": (m["trigger"] as? String) ?? "",
-            "format": (m["format"] as? String) ?? "webp",
-            "width": m["width"] ?? 0,
-            "height": m["height"] ?? 0,
-            "sizeBytes": m["sizeBytes"] ?? 0,
-            "masked": (m["masked"] as? Bool) ?? false,
-        ]
-        if let base = m["baseFrameId"] as? String, !base.isEmpty { row["baseFrameId"] = base }
-        return row
-    }
-
-    // ─── Telemetry segments ─────────────────────────────────────────────
-
-    private func uploadSegments(_ sessionId: String, _ lane: String, _ now: Int64) {
-        for metaFile in outbox.dueSegments(sessionId, lane, now) {
-            guard let claimed = outbox.moveSegmentToUploading(metaFile) else { continue }
-            guard let dataFile = outbox.segmentDataFor(claimed),
-                  let text = try? String(contentsOf: dataFile, encoding: .utf8) else {
-                outbox.deleteSegment(claimed); continue
-            }
-            var records: [[String: Any]] = []
-            for line in text.split(separator: "\n") {
-                let s = line.trimmingCharacters(in: .whitespaces)
-                if s.isEmpty { continue }
-                if let obj = (try? JSONSerialization.jsonObject(with: Data(s.utf8))) as? [String: Any] {
-                    records.append(obj)
-                }
-            }
-            let payload: [String: Any] = [laneBodyKey(lane): records]
-            let resp = postJson("/ingestion/sessions/\(sessionId)/\(lane)", payload)
-            let outcome = classify(resp)
-            if outcome == .success {
-                outbox.deleteSegment(claimed)
-            } else {
-                var retryAfter: Int64 = 0
-                if case let .response(_, _, ra) = resp { retryAfter = ra }
-                failItem(claimed, isFrame: false, outcome: outcome, retryAfterMs: retryAfter)
-            }
-        }
-    }
-
-    private func laneBodyKey(_ lane: String) -> String {
-        switch lane {
-        case "network": return "requests"
-        case "errors": return "errors"
-        case "performance": return "metrics"
-        case "logs": return "logs"
-        default: return "events"
-        }
-    }
-
-    // ─── Outcome routing ────────────────────────────────────────────────
-
-    private func failItem(_ metaFile: URL, isFrame: Bool, outcome: Outcome, retryAfterMs: Int64) {
-        switch outcome {
-        case .networkUnavailable:
-            outbox.recordNetworkFailure(metaFile, isFrame: isFrame, retryIntervalMs: retryIntervalMs)
-        case .serverTransient:
-            let attempt = currentServerAttempt(metaFile)
-            let backoff: Int64
-            if respectRetryAfter && retryAfterMs > 0 { backoff = retryAfterMs }
-            else if strictThreeSecondRetry || attempt < 10 { backoff = retryIntervalMs }
-            else { backoff = expoBackoff(attempt) }
-            outbox.recordServerFailure(metaFile, isFrame: isFrame, attemptCap: maxUploadAttempts, backoffMs: backoff)
-        case .serverPermanent:
-            outbox.recordServerFailure(metaFile, isFrame: isFrame, attemptCap: poisonMaxAttempts,
-                                       backoffMs: retryIntervalMs, permanent: true,
-                                       statusCode: lastResponseCode, bodySnippet: lastResponseBody)
-        case .success:
-            break
-        }
-    }
-
-    private func currentServerAttempt(_ metaFile: URL) -> Int {
-        guard let d = try? Data(contentsOf: metaFile),
-              let o = (try? JSONSerialization.jsonObject(with: d)) as? [String: Any] else { return 0 }
-        return int(o["serverAttemptCount"])
-    }
-
-    private func classify(_ r: NetResult) -> Outcome {
-        switch r {
-        case .networkError: return .networkUnavailable
-        case let .response(code, body, _):
-            lastResponseCode = code
-            lastResponseBody = body
-            if (200...299).contains(code) { return .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.
-            if code == 404 || code == 429 || (500...599).contains(code) { return .serverTransient }
-            if (400...499).contains(code) { return .serverPermanent }
-            return .serverTransient
-        }
-    }
-
-    private func expoBackoff(_ attempt: Int) -> Int64 {
-        let capped = min(max(attempt - 10, 0), 10)
-        let base = retryIntervalMs * (Int64(1) << capped)
-        let jitter = Int64(Double.random(in: 0...0.2) * Double(base))
-        return min(base + jitter, 30 * 60_000)
-    }
-
-    // ─── HTTP (synchronous on the serial queue via semaphore) ───────────
-
-    private func postJson(_ path: String, _ body: [String: Any]) -> NetResult {
-        guard let url = URL(string: "\(apiBaseUrl)\(path)") else { return .networkError }
-        var req = URLRequest(url: url)
-        req.httpMethod = "POST"
-        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
-        req.setValue(clientKey, forHTTPHeaderField: "x-scalebun-client-key")
-        req.setValue("ReplaySdk-iOS-Outbox/0.1.0", forHTTPHeaderField: "User-Agent")
-        req.httpBody = try? JSONSerialization.data(withJSONObject: body)
-        return sendSync(req)
-    }
-
-    private func putBytes(_ uploadUrl: String, _ bytes: Data, _ contentType: String) -> NetResult {
-        guard let url = URL(string: uploadUrl) else { return .networkError }
-        var req = URLRequest(url: url)
-        req.httpMethod = "PUT"
-        req.setValue(contentType, forHTTPHeaderField: "Content-Type")
-        req.httpBody = bytes
-        return sendSync(req)
-    }
-
-    private func sendSync(_ req: URLRequest) -> NetResult {
-        let sem = DispatchSemaphore(value: 0)
-        var result: NetResult = .networkError   // fail-safe default: never reached server
-        let task = session.dataTask(with: req) { data, response, error in
-            defer { sem.signal() }
-            // Any transport error → NETWORK_UNAVAILABLE so a valid batch is never marched
-            // to dead while the user is merely offline (section 6 fail-safe).
-            if error != nil { result = .networkError; return }
-            guard let http = response as? HTTPURLResponse else { result = .networkError; return }
-            let text = data.flatMap { String(data: $0, encoding: .utf8) } ?? ""
-            let retryAfter = self.parseRetryAfter(http.value(forHTTPHeaderField: "Retry-After"))
-            result = .response(code: http.statusCode, body: text, retryAfterMs: retryAfter)
-        }
-        task.resume()
-        if sem.wait(timeout: .now() + 95) == .timedOut {
-            // A hung socket that never returned bytes → treat as offline, fully retryable.
-            return .networkError
-        }
-        return result
-    }
-
-    private func parseRetryAfter(_ header: String?) -> Int64 {
-        guard let h = header, let s = Int64(h.trimmingCharacters(in: .whitespaces)) else { return 0 }
-        return s * 1000 // seconds → ms (HTTP-date form ignored)
-    }
-
-    // ─── helpers ────────────────────────────────────────────────────────
-
-    private func nowMs() -> Int64 { Int64(Date().timeIntervalSince1970 * 1000) }
-
-    private func int(_ v: Any?) -> Int {
-        if let n = v as? Int { return n }
-        if let n = v as? NSNumber { return n.intValue }
-        return 0
-    }
-
-    func destroy() {
-        pathMonitor.cancel()
-        queue.async { self.cancelTimer() }
-    }
-}
+import Foundation
+import Network
+
+/// Native uploader that drains `NativeOutbox` against the /ingestion contract.
+/// Swift mirror of the Android `OutboxUploader.kt`.
+///
+/// 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 of
+/// SUCCESS / NETWORK_UNAVAILABLE / SERVER_TRANSIENT / SERVER_PERMANENT and routed
+/// through the two-counter model on `NativeOutbox`. Offline never marches a batch to
+/// dead.
+///
+/// Upload loop (section 7): event-driven `flush()` on immediate triggers; a coalesced
+/// 3s retry timer armed ONLY when pending work exists AND network is up AND a batch is
+/// due; cancelled when the queue empties or the network drops. An `NWPathMonitor`
+/// wakes the loop the moment connectivity returns.
+final class OutboxUploader {
+
+    private let outbox: NativeOutbox
+    private var apiBaseUrl: String
+    private var clientKey: String
+    private let useObjectStorageForFrames: Bool
+    private let maxUploadAttempts: Int
+    private let frameBatch: Int
+    private let retryIntervalMs: Int64
+    private let poisonMaxAttempts: Int
+    private let respectRetryAfter: Bool
+    private let strictThreeSecondRetry: Bool
+
+    private let queue = DispatchQueue(label: "com.scalebun.replaysdk.outbox.upload")
+    private var running = false
+    private var rerun = false
+    private var objectStorageActive: Bool
+    private var networkAvailable = true
+    private var armed: DispatchWorkItem?
+    private let pathMonitor = NWPathMonitor()
+    private let monitorQueue = DispatchQueue(label: "com.scalebun.replaysdk.outbox.netmon")
+    // Last HTTP status/body seen by classify(); used to log the real code on poison/dead.
+    private var lastResponseCode = 0
+    private var lastResponseBody = ""
+
+    private enum Outcome { case success, networkUnavailable, serverTransient, serverPermanent }
+
+    private enum NetResult {
+        /// A response WAS received from the server.
+        case response(code: Int, body: String, retryAfterMs: Int64)
+        /// The request never reached the server (no connectivity/DNS/TLS/timeout).
+        case networkError
+    }
+
+    private lazy var session: URLSession = {
+        let cfg = URLSessionConfiguration.default
+        cfg.timeoutIntervalForRequest = 30
+        cfg.timeoutIntervalForResource = 90
+        return URLSession(configuration: cfg)
+    }()
+
+    init(outbox: NativeOutbox, apiBaseUrl: String, clientKey: String,
+         useObjectStorageForFrames: Bool, maxUploadAttempts: Int = 30, frameBatch: Int = 20,
+         retryIntervalMs: Int64 = 3000, poisonMaxAttempts: Int = 2,
+         respectRetryAfter: Bool = true, strictThreeSecondRetry: Bool = false) {
+        self.outbox = outbox
+        self.apiBaseUrl = apiBaseUrl
+        self.clientKey = clientKey
+        self.useObjectStorageForFrames = useObjectStorageForFrames
+        self.objectStorageActive = useObjectStorageForFrames
+        self.maxUploadAttempts = maxUploadAttempts
+        self.frameBatch = frameBatch
+        self.retryIntervalMs = retryIntervalMs
+        self.poisonMaxAttempts = poisonMaxAttempts
+        self.respectRetryAfter = respectRetryAfter
+        self.strictThreeSecondRetry = strictThreeSecondRetry
+        startPathMonitor()
+    }
+
+    func updateConfig(apiBaseUrl: String, clientKey: String) {
+        queue.async {
+            self.apiBaseUrl = apiBaseUrl
+            self.clientKey = clientKey
+        }
+    }
+
+    // ─── Connectivity (NWPathMonitor, section 6/7) ──────────────────────
+
+    private func startPathMonitor() {
+        pathMonitor.pathUpdateHandler = { [weak self] path in
+            self?.setNetworkAvailable(path.status == .satisfied)
+        }
+        pathMonitor.start(queue: monitorQueue)
+    }
+
+    func setNetworkAvailable(_ available: Bool) {
+        queue.async {
+            let was = self.networkAvailable
+            self.networkAvailable = available
+            if available && !was {
+                self.flushLocked()      // network restored → wake immediately
+            } else if !available {
+                self.cancelTimer()      // offline → park; rely on the monitor to wake us
+            }
+        }
+    }
+
+    /// Non-blocking drain. Safe from any thread / lifecycle hook.
+    func flush() {
+        if clientKey.isEmpty || apiBaseUrl.isEmpty { return }
+        queue.async { self.flushLocked() }
+    }
+
+    /// Must run on `queue`.
+    private func flushLocked() {
+        if clientKey.isEmpty || apiBaseUrl.isEmpty { return }
+        if running { rerun = true; return }   // coalesce concurrent wakes into one rerun
+        running = true
+        repeat {
+            rerun = false
+            drain()
+        } while rerun
+        running = false
+        reconcileTimer()
+    }
+
+    private func drain() {
+        if !networkAvailable { return }   // offline → don't attempt, don't spin
+        let now = nowMs()
+        for sessionId in outbox.listSessionIds() {
+            uploadFrames(sessionId, now)
+            for lane in NativeOutbox.TELEMETRY_LANES { uploadSegments(sessionId, lane, now) }
+        }
+        outbox.enforceLimits()
+    }
+
+    // ─── Timer arming (section 7) ───────────────────────────────────────
+
+    private func reconcileTimer() {
+        let now = nowMs()
+        if networkAvailable && hasDueWork(now) {
+            if armed == nil {
+                let work = DispatchWorkItem { [weak self] in
+                    self?.armed = nil
+                    self?.flushLocked()
+                }
+                armed = work
+                queue.asyncAfter(deadline: .now() + .milliseconds(Int(retryIntervalMs)), execute: work)
+            }
+        } else {
+            cancelTimer()
+        }
+    }
+
+    private func cancelTimer() {
+        armed?.cancel()
+        armed = nil
+    }
+
+    private func hasDueWork(_ now: Int64) -> Bool {
+        for sessionId in outbox.listSessionIds() {
+            if !outbox.dueFrameMetas(sessionId, now).isEmpty { return true }
+            for lane in NativeOutbox.TELEMETRY_LANES {
+                if !outbox.dueSegments(sessionId, lane, now).isEmpty { return true }
+            }
+        }
+        return false
+    }
+
+    // ─── Frames ─────────────────────────────────────────────────────────
+
+    private func uploadFrames(_ sessionId: String, _ now: Int64) {
+        let due = Array(outbox.dueFrameMetas(sessionId, now).prefix(frameBatch))
+        if due.isEmpty { return }
+        let claimed = due.compactMap { outbox.moveFrameToUploading($0) }
+        if claimed.isEmpty { return }
+        let metas: [(meta: [String: Any], file: URL)] = claimed.compactMap { f in
+            guard let data = try? Data(contentsOf: f),
+                  let obj = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else { return nil }
+            return (meta: obj, file: f)
+        }
+
+        if objectStorageActive {
+            let outcome = uploadFramesViaStorage(sessionId, metas)
+            if objectStorageActive {
+                if outcome == .success { metas.forEach { outbox.deleteFrame($0.file) } }
+                else { applyFrameOutcome(metas, outcome) }
+                return
+            }
+            // backend reported storage disabled mid-flight → fall through to inline.
+        }
+        let inline = commitFramesInline(sessionId, metas)
+        if inline == .success { metas.forEach { outbox.deleteFrame($0.file) } }
+        else { applyFrameOutcome(metas, inline) }
+    }
+
+    private func applyFrameOutcome(_ metas: [(meta: [String: Any], file: URL)], _ outcome: Outcome) {
+        metas.forEach { failItem($0.file, isFrame: true, outcome: outcome, retryAfterMs: 0) }
+    }
+
+    private func uploadFramesViaStorage(_ sessionId: String, _ metas: [(meta: [String: Any], file: URL)]) -> Outcome {
+        var presignFrames: [[String: Any]] = []
+        for (m, _) in metas {
+            presignFrames.append([
+                "frameId": m["frameId"] ?? "",
+                "contentType": (m["contentType"] as? String) ?? "image/webp",
+                "format": (m["format"] as? String) ?? "webp",
+            ])
+        }
+        let presign = postJson("/ingestion/sessions/\(sessionId)/frames/presign", ["frames": presignFrames])
+        let pOutcome = classify(presign)
+        if pOutcome != .success { return pOutcome }
+        guard case let .response(_, body, _) = presign,
+              let parsed = (try? JSONSerialization.jsonObject(with: Data(body.utf8))) as? [String: Any]
+        else { return .serverTransient }
+        if (parsed["enabled"] as? Bool) != true {
+            objectStorageActive = false
+            ReplayLogger.info("outbox: object storage disabled server-side; falling back to inline")
+            // objectStorageActive now false → caller re-checks and falls through to inline.
+            return .success
+        }
+        var byId: [String: [String: Any]] = [:]
+        for p in (parsed["frames"] as? [[String: Any]]) ?? [] {
+            if let fid = p["frameId"] as? String { byId[fid] = p }
+        }
+        for (m, metaFile) in metas {
+            guard let fid = m["frameId"] as? String, let p = byId[fid],
+                  let uploadUrl = p["uploadUrl"] as? String,
+                  let img = outbox.frameImageFor(metaFile),
+                  let bytes = try? Data(contentsOf: img) else { return .serverTransient }
+            let ct = (p["contentType"] as? String) ?? (m["contentType"] as? String) ?? "image/webp"
+            let putOutcome = classify(putBytes(uploadUrl, bytes, ct))
+            if putOutcome != .success { return putOutcome }
+        }
+        var commit: [[String: Any]] = []
+        for (m, _) in metas {
+            guard let fid = m["frameId"] as? String, let p = byId[fid] else { return .serverTransient }
+            var row = frameCommitMeta(m)
+            row["storageKey"] = p["storageKey"]
+            row["contentType"] = p["contentType"]
+            commit.append(row)
+        }
+        return classify(postJson("/ingestion/sessions/\(sessionId)/frames", ["frames": commit]))
+    }
+
+    private func commitFramesInline(_ sessionId: String, _ metas: [(meta: [String: Any], file: URL)]) -> Outcome {
+        var commit: [[String: Any]] = []
+        for (m, metaFile) in metas {
+            guard let img = outbox.frameImageFor(metaFile),
+                  let bytes = try? Data(contentsOf: img) else { return .serverTransient }
+            var row = frameCommitMeta(m)
+            row["imageData"] = bytes.base64EncodedString()
+            commit.append(row)
+        }
+        return classify(postJson("/ingestion/sessions/\(sessionId)/frames", ["frames": commit]))
+    }
+
+    private func frameCommitMeta(_ m: [String: Any]) -> [String: Any] {
+        var row: [String: Any] = [
+            "frameId": m["frameId"] ?? "",
+            "sessionId": m["sessionId"] ?? "",
+            "timestamp": m["timestamp"] ?? 0,
+            "sequenceNumber": m["sequenceNumber"] ?? 0,
+            "frameType": (m["frameType"] as? String) ?? "keyframe",
+            "screenName": (m["screenName"] as? String) ?? "",
+            "trigger": (m["trigger"] as? String) ?? "",
+            "format": (m["format"] as? String) ?? "webp",
+            "width": m["width"] ?? 0,
+            "height": m["height"] ?? 0,
+            "sizeBytes": m["sizeBytes"] ?? 0,
+            "masked": (m["masked"] as? Bool) ?? false,
+        ]
+        if let base = m["baseFrameId"] as? String, !base.isEmpty { row["baseFrameId"] = base }
+        return row
+    }
+
+    // ─── Telemetry segments ─────────────────────────────────────────────
+
+    private func uploadSegments(_ sessionId: String, _ lane: String, _ now: Int64) {
+        for metaFile in outbox.dueSegments(sessionId, lane, now) {
+            guard let claimed = outbox.moveSegmentToUploading(metaFile) else { continue }
+            guard let dataFile = outbox.segmentDataFor(claimed),
+                  let text = try? String(contentsOf: dataFile, encoding: .utf8) else {
+                outbox.deleteSegment(claimed); continue
+            }
+            var records: [[String: Any]] = []
+            for line in text.split(separator: "\n") {
+                let s = line.trimmingCharacters(in: .whitespaces)
+                if s.isEmpty { continue }
+                if let obj = (try? JSONSerialization.jsonObject(with: Data(s.utf8))) as? [String: Any] {
+                    records.append(obj)
+                }
+            }
+            let payload: [String: Any] = [laneBodyKey(lane): records]
+            let resp = postJson("/ingestion/sessions/\(sessionId)/\(lane)", payload)
+            let outcome = classify(resp)
+            if outcome == .success {
+                outbox.deleteSegment(claimed)
+            } else {
+                var retryAfter: Int64 = 0
+                if case let .response(_, _, ra) = resp { retryAfter = ra }
+                failItem(claimed, isFrame: false, outcome: outcome, retryAfterMs: retryAfter)
+            }
+        }
+    }
+
+    private func laneBodyKey(_ lane: String) -> String {
+        switch lane {
+        case "network": return "requests"
+        case "errors": return "errors"
+        case "performance": return "metrics"
+        case "logs": return "logs"
+        default: return "events"
+        }
+    }
+
+    // ─── Outcome routing ────────────────────────────────────────────────
+
+    private func failItem(_ metaFile: URL, isFrame: Bool, outcome: Outcome, retryAfterMs: Int64) {
+        switch outcome {
+        case .networkUnavailable:
+            outbox.recordNetworkFailure(metaFile, isFrame: isFrame, retryIntervalMs: retryIntervalMs)
+        case .serverTransient:
+            let attempt = currentServerAttempt(metaFile)
+            let backoff: Int64
+            if respectRetryAfter && retryAfterMs > 0 { backoff = retryAfterMs }
+            else if strictThreeSecondRetry || attempt < 10 { backoff = retryIntervalMs }
+            else { backoff = expoBackoff(attempt) }
+            outbox.recordServerFailure(metaFile, isFrame: isFrame, attemptCap: maxUploadAttempts, backoffMs: backoff)
+        case .serverPermanent:
+            outbox.recordServerFailure(metaFile, isFrame: isFrame, attemptCap: poisonMaxAttempts,
+                                       backoffMs: retryIntervalMs, permanent: true,
+                                       statusCode: lastResponseCode, bodySnippet: lastResponseBody)
+        case .success:
+            break
+        }
+    }
+
+    private func currentServerAttempt(_ metaFile: URL) -> Int {
+        guard let d = try? Data(contentsOf: metaFile),
+              let o = (try? JSONSerialization.jsonObject(with: d)) as? [String: Any] else { return 0 }
+        return int(o["serverAttemptCount"])
+    }
+
+    private func classify(_ r: NetResult) -> Outcome {
+        switch r {
+        case .networkError: return .networkUnavailable
+        case let .response(code, body, _):
+            lastResponseCode = code
+            lastResponseBody = body
+            if (200...299).contains(code) { return .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.
+            if code == 404 || code == 429 || (500...599).contains(code) { return .serverTransient }
+            if (400...499).contains(code) { return .serverPermanent }
+            return .serverTransient
+        }
+    }
+
+    private func expoBackoff(_ attempt: Int) -> Int64 {
+        let capped = min(max(attempt - 10, 0), 10)
+        let base = retryIntervalMs * (Int64(1) << capped)
+        let jitter = Int64(Double.random(in: 0...0.2) * Double(base))
+        return min(base + jitter, 30 * 60_000)
+    }
+
+    // ─── HTTP (synchronous on the serial queue via semaphore) ───────────
+
+    private func postJson(_ path: String, _ body: [String: Any]) -> NetResult {
+        guard let url = URL(string: "\(apiBaseUrl)\(path)") else { return .networkError }
+        var req = URLRequest(url: url)
+        req.httpMethod = "POST"
+        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        req.setValue(clientKey, forHTTPHeaderField: "x-scalebun-client-key")
+        req.setValue("ReplaySdk-iOS-Outbox/0.1.0", forHTTPHeaderField: "User-Agent")
+        req.httpBody = try? JSONSerialization.data(withJSONObject: body)
+        return sendSync(req)
+    }
+
+    private func putBytes(_ uploadUrl: String, _ bytes: Data, _ contentType: String) -> NetResult {
+        guard let url = URL(string: uploadUrl) else { return .networkError }
+        var req = URLRequest(url: url)
+        req.httpMethod = "PUT"
+        req.setValue(contentType, forHTTPHeaderField: "Content-Type")
+        req.httpBody = bytes
+        return sendSync(req)
+    }
+
+    private func sendSync(_ req: URLRequest) -> NetResult {
+        let sem = DispatchSemaphore(value: 0)
+        var result: NetResult = .networkError   // fail-safe default: never reached server
+        let task = session.dataTask(with: req) { data, response, error in
+            defer { sem.signal() }
+            // Any transport error → NETWORK_UNAVAILABLE so a valid batch is never marched
+            // to dead while the user is merely offline (section 6 fail-safe).
+            if error != nil { result = .networkError; return }
+            guard let http = response as? HTTPURLResponse else { result = .networkError; return }
+            let text = data.flatMap { String(data: $0, encoding: .utf8) } ?? ""
+            let retryAfter = self.parseRetryAfter(http.value(forHTTPHeaderField: "Retry-After"))
+            result = .response(code: http.statusCode, body: text, retryAfterMs: retryAfter)
+        }
+        task.resume()
+        if sem.wait(timeout: .now() + 95) == .timedOut {
+            // A hung socket that never returned bytes → treat as offline, fully retryable.
+            return .networkError
+        }
+        return result
+    }
+
+    private func parseRetryAfter(_ header: String?) -> Int64 {
+        guard let h = header, let s = Int64(h.trimmingCharacters(in: .whitespaces)) else { return 0 }
+        return s * 1000 // seconds → ms (HTTP-date form ignored)
+    }
+
+    // ─── helpers ────────────────────────────────────────────────────────
+
+    private func nowMs() -> Int64 { Int64(Date().timeIntervalSince1970 * 1000) }
+
+    private func int(_ v: Any?) -> Int {
+        if let n = v as? Int { return n }
+        if let n = v as? NSNumber { return n.intValue }
+        return 0
+    }
+
+    func destroy() {
+        pathMonitor.cancel()
+        queue.async { self.cancelTimer() }
+    }
+}