@scalebun-release/react-native 2.5.0

package/ios/Outbox/OutboxUploader.swift

@@ -0,0 +1,578 @@
+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 var lastRetryAfterMs: Int64 = 0
+
+    /// Lanes parked by a quota block (shared contract v1). Guarded by `quotaLock` (not confined to
+    /// `queue`) so a park requested from the bridge takes effect MID-drain: it is re-checked per item.
+    /// A parked lane is neither drained nor counted as due work, so it never arms the retry timer.
+    private var quotaBlockedLanes = Set<String>()
+    private let quotaLock = NSLock()
+    /// Called (on the upload queue) 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).
+    var onQuotaExceeded: ((Int, String, Int64, String) -> Void)?
+    /// Called (on the upload queue) 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.
+    var onLaneParked: ((String) -> Void)?
+
+    /// 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.
+    static let QUOTA_FEATURE_LANES: [String: String] = [
+        "frames": NativeOutbox.FRAMES, "networkRequests": "network", "events": "events",
+    ]
+
+    private enum Outcome { case success, networkUnavailable, serverTransient, serverPermanent, quotaExceeded }
+
+    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
+            }
+        }
+    }
+
+    /// Park (and purge) or un-park a lane for a per-feature quota block. The parked set changes
+    /// immediately (the drain re-checks it per item); the purge runs on `queue`, serialized with any
+    /// in-flight upload. 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.
+    func setLaneQuotaBlocked(_ lane: String, _ blocked: Bool) {
+        guard OutboxUploader.QUOTA_FEATURE_LANES.values.contains(lane) else { return }
+        quotaLock.lock()
+        let unparked = blocked ? false : (quotaBlockedLanes.remove(lane) != nil)
+        if blocked { quotaBlockedLanes.insert(lane) }
+        quotaLock.unlock()
+        if blocked {
+            queue.async { self.outbox.purgeLane(lane) }
+        } else if unparked {
+            flush()
+        }
+    }
+
+    private func isLaneParked(_ lane: String) -> Bool {
+        quotaLock.lock(); defer { quotaLock.unlock() }
+        return quotaBlockedLanes.contains(lane)
+    }
+
+    /// The limited feature a 402 body refuses, or nil when it is not `code: "quota_exceeded"` for a
+    /// limited feature (such a 402 is an ordinary permanent 4xx).
+    private static func refusedFeature(_ body: String) -> String? {
+        guard let o = (try? JSONSerialization.jsonObject(with: Data(body.utf8))) as? [String: Any],
+              (o["code"] as? String) == "quota_exceeded",
+              let f = o["feature"] as? String,
+              f == "sessions" || QUOTA_FEATURE_LANES[f] != nil else { return nil }
+        return f
+    }
+
+    /// The limited feature a 2xx PARTIAL grant (`quota.refused > 0`) exhausted, or nil.
+    private static func partialGrantFeature(_ body: String) -> String? {
+        guard body.contains("\"quota\""),
+              let o = (try? JSONSerialization.jsonObject(with: Data(body.utf8))) as? [String: Any],
+              let q = o["quota"] as? [String: Any],
+              let f = q["feature"] as? String, QUOTA_FEATURE_LANES[f] != nil else { return nil }
+        let refused = (q["refused"] as? NSNumber)?.intValue ?? 0
+        return refused > 0 ? f : nil
+    }
+
+    /// Must run on `queue`. Park + purge a lane (sets the flag first so the drain stops at once).
+    private func parkLane(_ lane: String, _ why: String) {
+        quotaLock.lock(); quotaBlockedLanes.insert(lane); quotaLock.unlock()
+        onLaneParked?(lane) // after releasing quotaLock: the host takes its own lock
+        let removed = outbox.purgeLane(lane)
+        ReplayLogger.warn("outbox: \(lane) \(why) — lane parked, \(removed) file(s) purged")
+    }
+
+    /// Must run on `queue`. 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 func handleQuotaRefusal(_ sessionId: String) {
+        let feature = OutboxUploader.refusedFeature(lastResponseBody) ?? ""
+        if feature == "sessions" {
+            outbox.purgeSession(sessionId)
+            ReplayLogger.warn("outbox: session \(sessionId) refused for quota (sessions) — its stored data deleted")
+        } else if let lane = OutboxUploader.QUOTA_FEATURE_LANES[feature] {
+            parkLane(lane, "refused for quota (HTTP 402, \(feature))")
+        }
+        onQuotaExceeded?(402, lastResponseBody, lastRetryAfterMs, sessionId)
+    }
+
+    /// Must run on `queue`, right after a 2xx: a partial grant spends the allowance.
+    private func checkPartialGrant(_ sessionId: String) {
+        guard let f = OutboxUploader.partialGrantFeature(lastResponseBody),
+              let lane = OutboxUploader.QUOTA_FEATURE_LANES[f] else { return }
+        parkLane(lane, "partially granted (\(f) allowance spent)")
+        onQuotaExceeded?(lastResponseCode, lastResponseBody, lastRetryAfterMs, sessionId)
+    }
+
+    /// 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() {
+            if !isLaneParked(NativeOutbox.FRAMES) { uploadFrames(sessionId, now) }
+            for lane in NativeOutbox.TELEMETRY_LANES where !isLaneParked(lane) {
+                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 !isLaneParked(NativeOutbox.FRAMES),
+               !outbox.dueFrameMetas(sessionId, now).isEmpty { return true }
+            for lane in NativeOutbox.TELEMETRY_LANES where !isLaneParked(lane) {
+                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) }; checkPartialGrant(sessionId) }
+                else if outcome == .quotaExceeded {
+                    handleQuotaRefusal(sessionId)
+                    metas.forEach { outbox.deleteFrame($0.file) } // never retried (no-op if purged)
+                }
+                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) }; checkPartialGrant(sessionId) }
+        else if inline == .quotaExceeded {
+            handleQuotaRefusal(sessionId)
+            metas.forEach { outbox.deleteFrame($0.file) } // never retried (no-op if purged)
+        }
+        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 {
+        // 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.
+        var presignFrames: [[String: Any]] = []
+        var imageBytes: [String: Data] = [:]
+        for (m, metaFile) in metas {
+            guard let fid = m["frameId"] as? String,
+                  let img = outbox.frameImageFor(metaFile),
+                  let bytes = try? Data(contentsOf: img) else { return .serverTransient }
+            imageBytes[fid] = bytes
+            presignFrames.append([
+                "frameId": fid,
+                "contentType": (m["contentType"] as? String) ?? "image/webp",
+                "format": (m["format"] as? String) ?? "webp",
+                "sizeBytes": bytes.count,
+            ])
+        }
+        let presign = postJson("/ingestion/sessions/\(sessionId)/frames/presign", ["frames": presignFrames])
+        let pOutcome = classify(presign)
+        if pOutcome != .success { return pOutcome }
+        // Partial grant: URLs only up to the remaining allowance, plus a `quota` block → park frames.
+        checkPartialGrant(sessionId)
+        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 }
+        }
+        // A frame WITHOUT a URL was refused for quota: dropped (the caller deletes every claimed
+        // item on .success), never retried.
+        let granted = metas.filter { byId[($0.meta["frameId"] as? String) ?? ""] != nil }
+        if granted.count < metas.count {
+            ReplayLogger.warn("outbox: presign granted \(granted.count)/\(metas.count) frame(s); the rest are dropped (quota)")
+        }
+        if granted.isEmpty { return .success }
+        for (m, _) in granted {
+            guard let fid = m["frameId"] as? String, let p = byId[fid],
+                  let uploadUrl = p["uploadUrl"] as? String,
+                  let bytes = imageBytes[fid] 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 granted {
+            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 }
+        // Visible scroll containers at capture time — JS sanitized it before commit. This builder
+        // enumerates fields, so a field it does not name never uploads.
+        if let scrollState = m["scrollState"] as? [Any] { row["scrollState"] = scrollState }
+        return row
+    }
+
+    // ─── Telemetry segments ─────────────────────────────────────────────
+
+    private func uploadSegments(_ sessionId: String, _ lane: String, _ now: Int64) {
+        for metaFile in outbox.dueSegments(sessionId, lane, now) {
+            // Re-checked per segment: a park can arrive from the bridge mid-drain.
+            if isLaneParked(lane) { return }
+            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)
+                checkPartialGrant(sessionId)
+            } else if outcome == .quotaExceeded {
+                // 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 {
+                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 .quotaExceeded:
+            // 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) }
+        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, retryAfterMs):
+            lastResponseCode = code
+            lastResponseBody = body
+            lastRetryAfterMs = retryAfterMs
+            if (200...299).contains(code) { return .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.
+            if code == 402 {
+                return OutboxUploader.refusedFeature(body) != nil ? .quotaExceeded : .serverPermanent
+            }
+            // 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() }
+    }
+}

package/ios/Performance/ScaleBunPerformanceBridge.m

@@ -0,0 +1,32 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+/**
+ * ObjC bridge exposing ScaleBunPerformance Swift module to React Native.
+ */
+@interface RCT_EXTERN_MODULE(ScaleBunPerformance, RCTEventEmitter)
+
+RCT_EXTERN_METHOD(initialize:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getAppStartInfo:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(startFrameMetrics:(double)intervalMs
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(stopFrameMetrics:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(startHangDetection:(double)thresholdMs
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(stopHangDetection:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(destroy:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end