@tryterra/react-native 0.0.0-stage → 2.2.1

package/ios/TerraBridgeCore/Locked.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// State behind a lock. `Mutex` needs iOS 18, and the floor is 15.
+final class Locked<State>: @unchecked Sendable {
+    private let lock = NSLock()
+    private var state: State
+
+    init(_ state: State) { self.state = state }
+
+    func withLock<Result>(_ body: (inout State) throws -> Result) rethrows -> Result {
+        lock.lock()
+        defer { lock.unlock() }
+        return try body(&state)
+    }
+}

package/ios/TerraBridgeCore/README.md

@@ -0,0 +1 @@
+Copied from hybrid-common by scripts/vendor-bridge-core.js. Do not edit; change hybrid-common.

package/ios/TerraBridgeCore/Rejections.swift

@@ -0,0 +1,130 @@
+import Foundation
+import TerraSDK
+
+/// A thrown error as a value another language can switch on.
+///
+/// The code and retryability come from the SDK (`TerraError.code`, the vocabulary in
+/// `docs/sdk-reference.md`), so there is no table here to drift. What this owns is which parts of
+/// an error are safe to send: nothing in `message` or `details` may carry a health value or text
+/// written by code this SDK does not own.
+enum Rejections {
+
+    static func payload(for error: any Error) -> TerraErrorPayload {
+        switch error {
+        case let error as TerraError:
+            // The broker's own failures reach the SDK through the token provider, which wraps
+            // them. Unwrapped here so `bridge.token_timeout` stays distinct from a provider that
+            // answered with an error.
+            if case .tokenProviderFailed(let underlying) = error, let bridge = underlying as? BridgeError {
+                return payload(for: bridge)
+            }
+            return TerraErrorPayload(
+                code: error.code,
+                retryable: error.isRetryable,
+                message: message(error),
+                source: source(error),
+                details: details(error))
+        case let error as BridgeError:
+            return TerraErrorPayload(
+                code: error.code,
+                retryable: error.isRetryable,
+                message: message(error),
+                details: details(error))
+        case is CancellationError:
+            return platform("the call was cancelled")
+        default:
+            return platform("a platform call failed")
+        }
+    }
+
+    private static func platform(_ message: String) -> TerraErrorPayload {
+        TerraErrorPayload(code: "platform", retryable: false, message: message)
+    }
+
+    /// Two cases wrap an error this SDK did not raise, and its text is as likely to carry a token
+    /// or a reading as to describe the failure, so neither crosses.
+    private static func message(_ error: TerraError) -> String {
+        switch error {
+        case .tokenProviderFailed: return "the host's token provider failed"
+        case .platform: return "a platform call failed"
+        // The SDK's description embeds its cause's, which can be either of the two above.
+        case .rollbackIncomplete(let remaining, let cause):
+            return "the log failed (\(message(cause))) and \(remaining.count) sample(s) could not be removed"
+        default: return error.errorDescription ?? error.code
+        }
+    }
+
+    private static func message(_ error: BridgeError) -> String {
+        switch error {
+        case .notBootstrapped: return "the native bootstrap did not run"
+        case .unsupportedOnPlatform(let op): return "\(op) is not available on iOS"
+        case .tokenTimeout(let timeoutMs): return "the token provider did not answer within \(timeoutMs) ms"
+        case .invalidPayload(let path): return "the payload is invalid at \(path)"
+        }
+    }
+
+    private static func source(_ error: TerraError) -> Source? {
+        switch error {
+        case .notConnected(let source), .linkRevoked(let source), .devIDMismatch(let source),
+            .linkAlreadyRunning(let source):
+            return Conversions.source(source)
+        default:
+            return nil
+        }
+    }
+
+    private static func details(_ error: TerraError) -> BridgeJSON? {
+        switch error {
+        case .routeAwaitingConverter(let type): return bag(["dataType": type.rawValue])
+        case .syncAlreadyRunning(let type): return bag(["dataType": type.rawValue])
+        case .permissionDenied(let category): return bag(["category": category.rawValue])
+        case .sampleNotFound(let id): return bag(["id": id.uuidString])
+        // The cause travels as its code: a nested error's description carries its own detail.
+        case .rollbackIncomplete(let remaining, let cause):
+            return BridgeJSON(["remaining": .number(Double(remaining.count)), "cause": .string(cause.code)])
+        case .distanceNotAttributable(let activity):
+            return bag(["activity": Conversions.sortKey(Conversions.activity(activity))])
+        case .network(let failure): return details(failure)
+        case .tokenProviderFailed, .platform:
+            return nil
+        case .healthDataUnavailable, .notConnected, .tokenUnavailable, .tokenRejected,
+            .userLimitReached, .upgradeRequired, .deviceKeyUnavailable, .signatureRejected,
+            .clockSkewed, .linkRevoked, .devIDMismatch, .linkConflict, .linkAlreadyRunning,
+            .storeLocked, .storeUnreadable, .deadlineExceeded, .authorizationNotDetermined,
+            .bloodPressureIncomplete, .plannedWorkoutUnnamed, .authorizationUnavailableInExtension:
+            return nil
+        @unknown default:
+            return nil
+        }
+    }
+
+    private static func details(_ failure: TerraError.Network) -> BridgeJSON? {
+        switch failure {
+        case .serverError(let status): return number("status", status)
+        case .throttled(let retryAfter):
+            return retryAfter.map { number("retryAfterSeconds", Int($0.rounded(.up))) }
+        // A URLError code says nothing a caller can act on beyond the code itself.
+        case .transport, .offline, .timedOut, .malformedResponse:
+            return nil
+        @unknown default:
+            return nil
+        }
+    }
+
+    private static func details(_ error: BridgeError) -> BridgeJSON? {
+        switch error {
+        case .notBootstrapped(let line): return bag(["line": line])
+        case .unsupportedOnPlatform(let op): return bag(["op": op])
+        case .tokenTimeout(let timeoutMs): return number("timeoutMs", timeoutMs)
+        case .invalidPayload(let path): return bag(["path": path])
+        }
+    }
+
+    private static func bag(_ values: [String: String]) -> BridgeJSON {
+        BridgeJSON(values.mapValues { .string($0) })
+    }
+
+    private static func number(_ key: String, _ value: Int) -> BridgeJSON {
+        BridgeJSON([key: .number(Double(value))])
+    }
+}

package/ios/TerraBridgeCore/RuntimeAttachment.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+public final class RuntimeAttachment: Sendable {
+    private struct State {
+        var attached: BridgeSession?
+        var invalidated = false
+    }
+
+    private let state = Locked(State())
+    private let attach: @Sendable () throws(BridgeRejection) -> BridgeSession
+
+    /// Attaches to what `BridgeBootstrap` parked. `missingLine` is what `bridge.not_bootstrapped` names.
+    public convenience init(
+        missingLine: String,
+        emit: @escaping @Sendable (_ subscriptionId: String, _ message: String) -> Void
+    ) {
+        self.init { () throws(BridgeRejection) -> BridgeSession in
+            try BridgeBootstrap.attach(missingLine: missingLine, emit: emit)
+        }
+    }
+
+    init(attach: @escaping @Sendable () throws(BridgeRejection) -> BridgeSession) {
+        self.attach = attach
+    }
+
+    public func session() throws(BridgeRejection) -> BridgeSession? {
+        let attach = attach
+        let outcome: Result<BridgeSession?, BridgeRejection> = state.withLock { state in
+            if state.invalidated { return .success(nil) }
+            if let attached = state.attached { return .success(attached) }
+            do throws(BridgeRejection) {
+                let session = try attach()
+                state.attached = session
+                return .success(session)
+            } catch {
+                return .failure(error)
+            }
+        }
+        return try outcome.get()
+    }
+
+    /// The attached session, without attaching one.
+    public func current() -> BridgeSession? {
+        state.withLock { $0.attached }
+    }
+
+    public var isInvalidated: Bool {
+        state.withLock { $0.invalidated }
+    }
+
+    @discardableResult
+    public func invalidate() -> Task<Void, Never> {
+        let session = state.withLock { state -> BridgeSession? in
+            state.invalidated = true
+            defer { state.attached = nil }
+            return state.attached
+        }
+        return Task { await session?.invalidate() }
+    }
+}

package/ios/TerraBridgeCore/StreamRegistry.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+/// One native stream per subscriber, started on subscribe and cancelled on unsubscribe.
+///
+/// What arrives is already framed, endings included, by the generated `BridgeStreamDispatch`.
+final class StreamRegistry: Sendable {
+    typealias Sink = @Sendable (_ subscriptionId: String, _ message: String) -> Void
+
+    private struct State {
+        var next = 0
+        var tasks: [String: Task<Void, Never>] = [:]
+        var closed = false
+    }
+
+    private let state = Locked(State())
+
+    /// Forwards `source`, already framed with its ending by `BridgeStreamDispatch`, until it ends
+    /// or is cancelled, and answers the id that cancels it.
+    ///
+    /// The task is created under the lock, so its own removal at the end cannot run before its
+    /// insertion - a source that finishes at once would otherwise leave its entry behind forever.
+    func start(sink: @escaping Sink, source: AsyncStream<Data>) -> String {
+        state.withLock { state in
+            state.next += 1
+            let id = "sub-\(state.next)"
+            guard !state.closed else { return id }
+            state.tasks[id] = Task {
+                for await message in source {
+                    // A cancelled source still frames an ending; the subscriber asked for silence.
+                    guard !Task.isCancelled else { break }
+                    sink(id, String(decoding: message, as: UTF8.self))
+                }
+                self.finished(id)
+            }
+            return id
+        }
+    }
+
+    /// An unknown id is ignored: a second unsubscribe is not an error.
+    func cancel(_ id: String) {
+        state.withLock { $0.tasks.removeValue(forKey: id) }?.cancel()
+    }
+
+    /// Cancels everything and starts nothing new, for a host runtime that is going away.
+    func close() {
+        let tasks = state.withLock { state in
+            state.closed = true
+            defer { state.tasks = [:] }
+            return Array(state.tasks.values)
+        }
+        for task in tasks { task.cancel() }
+    }
+
+    var count: Int { state.withLock { $0.tasks.count } }
+
+    private func finished(_ id: String) {
+        state.withLock { _ = $0.tasks.removeValue(forKey: id) }
+    }
+}

package/ios/TerraBridgeCore/TerraBridge.swift

@@ -0,0 +1,122 @@
+import Foundation
+import TerraSDK
+
+/// The process-wide half: the client, and the broker it was built with.
+///
+/// Built once, at launch, by the native bootstrap - before any JavaScript or Dart exists, because
+/// background sync needs a live client then. A runtime that comes and goes (a JS reload, a Flutter
+/// engine) attaches a `BridgeSession` to it and detaches by invalidating that session.
+///
+/// Nothing here may mention a framework: no promise type, no `NSDictionary`, no `FlutterResult`.
+public final class TerraBridge: Sendable {
+    public typealias TokenProvider = @Sendable () async throws -> String
+
+    /// The client, for the bootstrap that registers it with `BackgroundSync`.
+    public let terra: Terra
+
+    let host: any BridgeHost
+    let broker: TokenBroker
+    let deviceZone: @Sendable () -> TimeZone
+
+    /// `client` receives the provider the client must be built with. The broker exists before the
+    /// client because the client captures its provider at construction: a broker made afterwards
+    /// would be one the SDK never asks.
+    public init(
+        host: any BridgeHost,
+        deviceZone: @escaping @Sendable () -> TimeZone = { .current },
+        client: (_ tokenProvider: @escaping TokenProvider) throws -> Terra
+    ) rethrows {
+        let broker = TokenBroker()
+        self.broker = broker
+        self.host = host
+        self.deviceZone = deviceZone
+        self.terra = try client { try await broker.provide() }
+    }
+
+    /// One session per runtime. `emit` receives `(subscriptionId, StreamMessage JSON)`.
+    public func attach(emit: @escaping @Sendable (_ subscriptionId: String, _ message: String) -> Void) -> BridgeSession {
+        BridgeSession(bridge: self, emit: emit)
+    }
+}
+
+/// What a framework layer calls: dispatch, subscribe, unsubscribe, invalidate.
+///
+/// A React Native TurboModule forwards `invoke` to `dispatch` and its emitter to `emit`. A Flutter
+/// `MethodChannel` is `dispatch(call.method, call.arguments)` and an `EventChannel` wraps
+/// `subscribe`.
+public final class BridgeSession: Sendable {
+    private let bridge: TerraBridge
+    private let emit: @Sendable (String, String) -> Void
+    private let subscriptions = StreamRegistry()
+    private let audience = TokenAudience()
+    private let ops: BridgeDispatch
+    private let streams: BridgeStreamDispatch
+
+    init(bridge: TerraBridge, emit: @escaping @Sendable (String, String) -> Void) {
+        self.bridge = bridge
+        self.emit = emit
+        self.ops = BridgeDispatch(ops: TerraBridgeOpsImpl(
+            terra: bridge.terra, host: bridge.host, broker: bridge.broker, audience: audience))
+        self.streams = BridgeStreamDispatch(
+            streams: TerraBridgeStreamsImpl(terra: bridge.terra, audience: audience, deviceZone: bridge.deviceZone),
+            errorPayload: { Rejections.payload(for: $0) })
+    }
+
+    /// A session dropped without `invalidate` still stops its streams: they would otherwise keep
+    /// a source polling for a runtime that is gone.
+    deinit {
+        audience.close()
+        subscriptions.close()
+    }
+
+    /// Runs one op and answers its response JSON. Never throws a raw SDK error: the framework layer
+    /// rejects with `rejection.payload`, so the error table lives here once rather than in each
+    /// wrapper.
+    public func dispatch(op: String, payload: String) async throws(BridgeRejection) -> String {
+        do {
+            let response = try await ops(op: op, payload: Data(payload.utf8))
+            return String(decoding: response, as: UTF8.self)
+        } catch {
+            throw BridgeRejection(payload: Rejections.payload(for: error))
+        }
+    }
+
+    /// Starts one native stream for this subscriber and answers the id that cancels it. Messages
+    /// arrive through `emit` under that id. The source is open before this returns.
+    public func subscribe(stream: String, params: String) async throws(BridgeRejection) -> String {
+        do {
+            let source = try await streams.open(stream: stream, params: Data(params.utf8))
+            return subscriptions.start(sink: emit, source: source)
+        } catch {
+            throw BridgeRejection(payload: Rejections.payload(for: error))
+        }
+    }
+
+    public func unsubscribe(id: String) {
+        subscriptions.cancel(id)
+    }
+
+    /// For a runtime that is going away. The client outlives it, so what is torn down is everything
+    /// that pointed at this runtime: its streams, and the token asks it was sent.
+    public func invalidate() async {
+        audience.close()
+        subscriptions.close()
+        await bridge.broker.invalidate(audience)
+    }
+
+    /// Visible for tests.
+    var liveSubscriptions: Int { subscriptions.count }
+}
+
+/// What the framework layer turns into a rejected promise.
+public struct BridgeRejection: Error, Sendable {
+    public let payload: TerraErrorPayload
+
+    public var code: String { payload.code }
+
+    /// The payload as the wire spells it, for a layer that rejects with a JSON string.
+    public var json: String {
+        (try? String(decoding: BridgeDispatch.makeEncoder().encode(payload), as: UTF8.self))
+            ?? #"{"code":"\#(payload.code)","message":"","retryable":\#(payload.retryable)}"#
+    }
+}