@barrysolomon/mobile-react-native 0.1.0-alpha

package/ios/BridgeCallSink.swift

@@ -0,0 +1,83 @@
+// Seam between the RN bridge and the native iOS OTel Mobile SDK.
+//
+// Production: OTelMobileCallSink forwards into OTelMobileSDK.OTelMobile.
+// Tests: a fake sink records calls so we can assert the module's dispatch
+// behavior without standing up the full SDK.
+
+import Foundation
+
+public protocol BridgeCallSink: AnyObject {
+    func start(_ config: BridgeStartConfig)
+    func emitLog(name: String, severity: Int, attributes: [String: Any], timeUnixNano: UInt64)
+    func startSpan(spanId: String, parentSpanId: String?, name: String, spanKind: String, attributes: [String: Any], startTimeUnixNano: UInt64)
+    func endSpan(spanId: String, status: String, statusMessage: String?, attributes: [String: Any], endTimeUnixNano: UInt64)
+    func recordMetric(name: String, instrumentType: String, value: Double, attributes: [String: Any], timeUnixNano: UInt64)
+    func flushWindow(minutes: Int)
+    func shutdown()
+
+    /// Synchronously flush every buffered telemetry record through the
+    /// underlying SDK's exporter, persisting any in-flight records to
+    /// disk on export failure. Called by `Dash0MobileBridgeDispatcher`
+    /// immediately after dispatching a FATAL-severity (>=21) log emit,
+    /// before continuing to the next payload in the batch.
+    ///
+    /// **Why this is in the protocol, not the dispatcher:** the
+    /// dispatcher could call something like `sink.flushWindow(...)`,
+    /// but that's selective + async. FATAL needs synchronous flush of
+    /// everything because the process is about to die on the calling
+    /// thread (RN's fatal reporter terminates via `abort()` / `_exit()`,
+    /// skipping `UIApplication.willTerminateNotification`). The sink
+    /// has the underlying SDK handle and knows how to do a real
+    /// synchronous flush; the dispatcher only knows the protocol.
+    ///
+    /// Default implementation is a no-op — sinks that don't have an
+    /// underlying SDK to flush (e.g. `NoopSink`, lightweight test
+    /// fakes) inherit safe behavior. Production sinks like
+    /// `OTelMobileCallSink` override.
+    func forceFlush()
+}
+
+extension BridgeCallSink {
+    public func forceFlush() {
+        // Default no-op. Override in concrete sinks that wrap a real
+        // exporter (e.g. OTelMobileCallSink calls `OTelMobile.forceFlush`).
+    }
+}
+
+public struct BridgeStartConfig: Equatable {
+    public let serviceName: String
+    public let serviceVersion: String?
+    public let endpoint: String
+    public let authToken: String?
+    public let dataset: String?
+    /// Extra resource attributes from the JS caller (RN bridge populates
+    /// `telemetry.distro.name` / `telemetry.distro.version` by default).
+    public let extraResourceAttributes: [String: String]
+    /// Native iOS auto-capture suites the JS caller wants enabled. Empty array
+    /// (default) means the iOS SDK installs no UI/network/error instrumentation
+    /// — RN apps get those signals from the JS-side shims (fetch + XHR +
+    /// ErrorUtils + unhandledRejection + withTapTelemetry). Apps wanting the
+    /// native iOS suite can opt in via `Dash0Mobile.start({ autoCapture: { vitals: true } })`.
+    ///
+    /// Supported tokens: "network", "errors", "lifecycle", "freeze", "vitals",
+    /// "screen", "deviceStats". Unknown tokens are ignored (forward compat).
+    public let nativeAutoCapture: [String]
+
+    public init(
+        serviceName: String,
+        serviceVersion: String?,
+        endpoint: String,
+        authToken: String?,
+        dataset: String?,
+        extraResourceAttributes: [String: String] = [:],
+        nativeAutoCapture: [String] = []
+    ) {
+        self.serviceName = serviceName
+        self.serviceVersion = serviceVersion
+        self.endpoint = endpoint
+        self.authToken = authToken
+        self.dataset = dataset
+        self.extraResourceAttributes = extraResourceAttributes
+        self.nativeAutoCapture = nativeAutoCapture
+    }
+}

package/ios/Dash0MobileBridgeDispatcher.swift

@@ -0,0 +1,142 @@
+// Dispatches RN bridge payloads onto a BridgeCallSink.
+//
+// Kept as a free-standing type (not an RCTBridgeModule subclass) so it can
+// be unit-tested without importing React/RCTBridgeModule.h. The
+// RCTDash0MobileModule wrapper (Objective-C bridge + thin Swift shim) just
+// calls through into this.
+
+import Foundation
+
+public enum Dash0MobileBridgeError: Error {
+    case missingField(String)
+    case invalidConfig(String)
+}
+
+public final class Dash0MobileBridgeDispatcher {
+    private let sink: BridgeCallSink
+
+    public init(sink: BridgeCallSink) {
+        self.sink = sink
+    }
+
+    public func start(config: [String: Any]) throws {
+        guard let serviceName = config["serviceName"] as? String else {
+            throw Dash0MobileBridgeError.missingField("serviceName")
+        }
+        guard let endpoint = config["endpoint"] as? String else {
+            throw Dash0MobileBridgeError.missingField("endpoint")
+        }
+        let extras: [String: String] = (config["extraResourceAttributes"] as? [String: Any])?
+            .compactMapValues { $0 as? String } ?? [:]
+        let nativeAutoCapture = (config["nativeAutoCapture"] as? [Any])?.compactMap { $0 as? String } ?? []
+        sink.start(BridgeStartConfig(
+            serviceName: serviceName,
+            serviceVersion: config["serviceVersion"] as? String,
+            endpoint: endpoint,
+            authToken: config["authToken"] as? String,
+            dataset: config["dataset"] as? String,
+            extraResourceAttributes: extras,
+            nativeAutoCapture: nativeAutoCapture
+        ))
+    }
+
+    public func emitBatch(_ payloads: [[String: Any]]) {
+        for p in payloads {
+            dispatch(p)
+        }
+    }
+
+    public func flushWindow(minutes: Double) {
+        sink.flushWindow(minutes: Int(minutes))
+    }
+
+    public func shutdown() {
+        sink.shutdown()
+    }
+
+    private func dispatch(_ p: [String: Any]) {
+        guard let kind = p["kind"] as? String else { return }
+        let attrs = (p["attributes"] as? [String: Any]) ?? [:]
+        switch kind {
+        case "log":
+            guard let name = p["name"] as? String else { return }
+            let severity = intValue(p["severity"]) ?? 9
+            sink.emitLog(
+                name: name,
+                severity: severity,
+                attributes: attrs,
+                timeUnixNano: stringAsUInt64(p["timeUnixNano"])
+            )
+            // FATAL-severity logs (OTel semconv 21..24) are the crash
+            // path. JS-side bypasses the 50ms debounce via emitSync, but
+            // the payload still sits in MobileLogRecordProcessor's RAM
+            // buffer. The willTerminate observer (1a69c7e) doesn't fire
+            // on RN's abort()/_exit() termination, so we eagerly flush
+            // here BEFORE the next payload in the batch. The sink's
+            // forceFlush() is synchronous: it drains RAM and persists
+            // any export failures to disk so the next launch can recover.
+            //
+            // Lives in the dispatcher rather than each sink so every
+            // BridgeCallSink consumer benefits — was previously wired
+            // demo-app-locally in OTelMobileCallSink.emitLog, which left
+            // non-RN consumers exposed to the same bridge-RAM-buffer
+            // race.
+            if severity >= 21 {
+                sink.forceFlush()
+            }
+        case "spanStart":
+            guard
+                let spanId = p["spanId"] as? String,
+                let name = p["name"] as? String
+            else { return }
+            sink.startSpan(
+                spanId: spanId,
+                parentSpanId: p["parentSpanId"] as? String,
+                name: name,
+                spanKind: (p["spanKind"] as? String) ?? "INTERNAL",
+                attributes: attrs,
+                startTimeUnixNano: stringAsUInt64(p["startTimeUnixNano"])
+            )
+        case "spanEnd":
+            guard let spanId = p["spanId"] as? String else { return }
+            sink.endSpan(
+                spanId: spanId,
+                status: (p["status"] as? String) ?? "UNSET",
+                statusMessage: p["statusMessage"] as? String,
+                attributes: attrs,
+                endTimeUnixNano: stringAsUInt64(p["endTimeUnixNano"])
+            )
+        case "metric":
+            guard let name = p["name"] as? String else { return }
+            sink.recordMetric(
+                name: name,
+                instrumentType: (p["instrumentType"] as? String) ?? "counter",
+                value: doubleValue(p["value"]) ?? 0,
+                attributes: attrs,
+                timeUnixNano: stringAsUInt64(p["timeUnixNano"])
+            )
+        default:
+            // Unknown kinds silently dropped — forward-compatible with future
+            // payload shapes the SDK's newer JS versions might send.
+            return
+        }
+    }
+
+    // NSNumber crossing the bridge may arrive as Int or Double. Be liberal.
+    private func intValue(_ v: Any?) -> Int? {
+        if let n = v as? Int { return n }
+        if let n = v as? Double { return Int(n) }
+        if let n = v as? NSNumber { return n.intValue }
+        return nil
+    }
+    private func doubleValue(_ v: Any?) -> Double? {
+        if let n = v as? Double { return n }
+        if let n = v as? Int { return Double(n) }
+        if let n = v as? NSNumber { return n.doubleValue }
+        return nil
+    }
+    private func stringAsUInt64(_ v: Any?) -> UInt64 {
+        if let s = v as? String, let n = UInt64(s) { return n }
+        return 0
+    }
+}

package/ios/OTelMobileCallSink.swift

@@ -0,0 +1,262 @@
+// Production BridgeCallSink for iOS. Forwards RN bridge calls into the
+// existing OTelMobileSDK.OTelMobile facade.
+//
+// This file is compiled ONLY when OTelMobileSDK is linkable. When the RN
+// package is built standalone (CI cold-compile without a host app) the
+// RCTDash0MobileModule falls back to NoopSink.
+
+#if canImport(OTelMobileSDK)
+import Foundation
+import OpenTelemetryApi
+import OTelMobileSDK
+
+final class OTelMobileCallSink: BridgeCallSink {
+    private var otel: OTelMobile?
+    private let spanLock = NSLock()
+    private var liveSpans: [String: Span] = [:]
+
+    func start(_ config: BridgeStartConfig) {
+        guard otel == nil else { return }
+
+        // Dash0 OTLP ingress wants Bearer auth + Dash0-Dataset as explicit
+        // headers, not as separate MobileConfig fields. Build them here so
+        // the rest of the SDK sees a uniform headers map.
+        var extraHeaders: [String: String] = [:]
+        if let dataset = config.dataset, !dataset.isEmpty {
+            extraHeaders["Dash0-Dataset"] = dataset
+        }
+
+        // UAT launch-arg overrides: when present, the native side controls
+        // export mode and injects cell_id so the UAT matrix can drive all
+        // 12 cells without rebuilding the app.
+        let exportMode = Self.exportModeFromArgs() ?? .continuous
+        var mergedAttrs = config.extraResourceAttributes
+        if let mode = Self.launchArg("-DASH0_EXPORT_MODE") {
+            mergedAttrs["dash0.test.export_mode"] = mode
+        }
+        if let cellId = Self.launchArg("-DASH0_CELL_ID"), !cellId.isEmpty {
+            mergedAttrs["dash0.test.cell_id"] = cellId
+        }
+
+        let mobileConfig = MobileConfig(
+            serviceName: config.serviceName,
+            serviceVersion: config.serviceVersion ?? "unknown",
+            endpoint: config.endpoint,
+            authToken: config.authToken,
+            exportMode: exportMode,
+            extraHeaders: extraHeaders,
+            extraResourceAttributes: mergedAttrs
+        )
+        do {
+            otel = try OTelMobile.start(config: mobileConfig)
+        } catch {
+            // Start failure is logged but non-fatal — JS side stays operational
+            // and future emitBatch calls become no-ops until a successful start.
+            NSLog("[@dash0/mobile-react-native] OTelMobile.start failed: \(error)")
+        }
+    }
+
+    func emitLog(
+        name: String,
+        severity: Int,
+        attributes: [String: Any],
+        timeUnixNano: UInt64
+    ) {
+        guard let logger = otel?.logger else { return }
+        var builder = logger.logRecordBuilder()
+            .setBody(AttributeValue.string(name))
+            .setSeverity(Self.mapSeverity(severity))
+            .setTimestamp(Self.dateFromUnixNano(timeUnixNano))
+        let otelAttrs = Self.toAttributeValues(attributes)
+        if !otelAttrs.isEmpty {
+            builder = builder.setAttributes(otelAttrs)
+        }
+        builder.emit()
+    }
+
+    func startSpan(
+        spanId: String,
+        name: String,
+        spanKind: String,
+        attributes: [String: Any],
+        startTimeUnixNano: UInt64
+    ) {
+        guard let tracer = otel?.tracer else { return }
+        let span = tracer.spanBuilder(spanName: name)
+            .setStartTime(time: Self.dateFromUnixNano(startTimeUnixNano))
+            .setSpanKind(kind: Self.mapSpanKind(spanKind))
+            .startSpan()
+        for (k, v) in Self.toAttributeValues(attributes) {
+            span.setAttribute(key: k, value: v)
+        }
+        spanLock.lock()
+        liveSpans[spanId] = span
+        spanLock.unlock()
+    }
+
+    func endSpan(
+        spanId: String,
+        status: String,
+        statusMessage: String?,
+        attributes: [String: Any],
+        endTimeUnixNano: UInt64
+    ) {
+        spanLock.lock()
+        let span = liveSpans.removeValue(forKey: spanId)
+        spanLock.unlock()
+        guard let span = span else { return }
+
+        for (k, v) in Self.toAttributeValues(attributes) {
+            span.setAttribute(key: k, value: v)
+        }
+        switch status {
+        case "OK":
+            span.status = .ok
+        case "ERROR":
+            span.status = .error(description: statusMessage ?? "")
+        default:
+            break
+        }
+        span.end(time: Self.dateFromUnixNano(endTimeUnixNano))
+    }
+
+    func recordMetric(
+        name: String,
+        instrumentType: String,
+        value: Double,
+        attributes: [String: Any],
+        timeUnixNano: UInt64
+    ) {
+        guard let meter = otel?.meter else { return }
+        let otelAttrs = Self.toAttributeValues(attributes)
+        switch instrumentType {
+        case "histogram":
+            meter.histogramBuilder(name: name).build()
+                .record(value: value, attributes: otelAttrs)
+        case "gauge":
+            // OTel-Swift async gauges require an observer callback; for the
+            // bridge's fire-and-forget contract we record a single value via
+            // a histogram of size 1 so the last-value aggregation in the
+            // backend surfaces the reading. Purpose-built sync gauges land
+            // if/when upstream exposes them.
+            meter.histogramBuilder(name: name).build()
+                .record(value: value, attributes: otelAttrs)
+        default:
+            // counter — integer values are the common case. Fractional
+            // counters aren't expressible through OTel-Swift's long counter,
+            // so truncate and log once if the JS side ever sends a non-int.
+            meter.counterBuilder(name: name).build()
+                .add(value: Int(value), attributes: otelAttrs)
+        }
+    }
+
+    func flushWindow(minutes: Int) {
+        guard let otel = otel else { return }
+        Task.detached { [otel] in
+            _ = await otel.flushWindow(minutes: UInt64(max(0, minutes)))
+        }
+    }
+
+    func shutdown() {
+        otel = nil
+        spanLock.lock()
+        liveSpans.removeAll()
+        spanLock.unlock()
+    }
+
+    /// Drain all RAM-buffered telemetry through the OTLP exporter,
+    /// persisting on export failure. Called by `Dash0MobileBridgeDispatcher`
+    /// after dispatching a FATAL-severity log emit, before continuing
+    /// to the next payload in the same batch.
+    ///
+    /// `OTelMobile.forceFlush` is synchronous and routes both logs and
+    /// pending spans through the configured persistence path
+    /// (`MobileLogRecordProcessor` for logs, `BatchSpanProcessor`'s
+    /// shutdown drain for spans). On RN's abort()/_exit() termination
+    /// path this is the only thing that gives the FATAL log a chance
+    /// to land in Dash0 — the willTerminate observer doesn't fire on
+    /// abort().
+    func forceFlush() {
+        guard let otel = otel else { return }
+        _ = otel.forceFlush()
+    }
+
+    // MARK: - Helpers
+
+    private static func toAttributeValues(_ raw: [String: Any]) -> [String: AttributeValue] {
+        var out: [String: AttributeValue] = [:]
+        for (k, v) in raw {
+            if let s = v as? String {
+                out[k] = .string(s)
+            } else if let b = v as? Bool {
+                out[k] = .bool(b)
+            } else if let i = v as? Int {
+                out[k] = .int(i)
+            } else if let n = v as? NSNumber {
+                // React Native bridges numerics as NSNumber. Integer-valued
+                // NSNumbers should land as ints so attribute keys like `qty`
+                // don't surface as `2.0` in backends — mirrors the Android
+                // OTelMobileCallSink behavior.
+                if CFNumberIsFloatType(n) {
+                    out[k] = .double(n.doubleValue)
+                } else {
+                    out[k] = .int(n.intValue)
+                }
+            } else if let d = v as? Double {
+                out[k] = .double(d)
+            } else {
+                out[k] = .string(String(describing: v))
+            }
+        }
+        return out
+    }
+
+    private static func dateFromUnixNano(_ nano: UInt64) -> Date {
+        Date(timeIntervalSince1970: TimeInterval(nano) / 1_000_000_000.0)
+    }
+
+    private static func mapSeverity(_ raw: Int) -> Severity {
+        // OTel severity numbers: 1=TRACE, 5=DEBUG, 9=INFO, 13=WARN, 17=ERROR,
+        // 21=FATAL. JS sends the numeric value directly — fall back to INFO
+        // when the value is outside the known range so log records never
+        // get dropped silently.
+        switch raw {
+        case 1...4:   return .trace
+        case 5...8:   return .debug
+        case 9...12:  return .info
+        case 13...16: return .warn
+        case 17...20: return .error
+        case 21...:   return .fatal
+        default:      return .info
+        }
+    }
+
+    private static func mapSpanKind(_ raw: String) -> SpanKind {
+        switch raw {
+        case "CLIENT":   return .client
+        case "SERVER":   return .server
+        case "PRODUCER": return .producer
+        case "CONSUMER": return .consumer
+        default:         return .internal
+        }
+    }
+
+    // MARK: - UAT launch-arg helpers
+
+    private static func launchArg(_ flag: String) -> String? {
+        let args = CommandLine.arguments
+        guard let idx = args.firstIndex(of: flag), idx + 1 < args.count else { return nil }
+        return args[idx + 1]
+    }
+
+    private static func exportModeFromArgs() -> ExportMode? {
+        guard let raw = launchArg("-DASH0_EXPORT_MODE") else { return nil }
+        switch raw.lowercased() {
+        case "cont", "continuous": return .continuous
+        case "cond", "conditional": return .conditional
+        case "hyb", "hybrid": return .hybrid
+        default: return nil
+        }
+    }
+}
+#endif

package/ios/RCTDash0MobileModule.m

@@ -0,0 +1,28 @@
+// Objective-C interface required by React Native's RCTBridgeModule macro.
+// The real implementation lives in RCTDash0MobileModule.swift and is
+// resolved via the {ModuleName}-Swift.h header at build time.
+
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(Dash0Mobile, NSObject)
+
+RCT_EXTERN_METHOD(start:(NSDictionary *)config
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(emitBatch:(NSArray *)payloads
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(flushWindow:(double)minutes
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(shutdown:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
++ (BOOL)requiresMainQueueSetup {
+    return NO;
+}
+
+@end

package/ios/RCTDash0MobileModule.swift

@@ -0,0 +1,104 @@
+// Swift half of the RN native module. The ObjC side (RCTDash0MobileModule.m)
+// declares the RN-visible interface; this file implements the methods.
+//
+// Deliberately thin — all dispatch logic is in Dash0MobileBridgeDispatcher.
+
+import Foundation
+
+@objc(Dash0Mobile)
+public final class Dash0MobileModule: NSObject {
+    private let dispatcher: Dash0MobileBridgeDispatcher
+
+    /// Host-injected sink factory. When the RN bridge pod can't see the
+    /// native SDK at compile time (common in hybrid CocoaPods+SwiftPM
+    /// setups — the pod builds without the app's Swift Package graph),
+    /// the host app calls `Dash0MobileModule.installSink(...)` from its
+    /// AppDelegate to wire the real `OTelMobileCallSink`. Without that,
+    /// we fall back to a no-op sink so the JS surface stays functional
+    /// in tests / SSR / apps that haven't opted in yet.
+    ///
+    /// Not `@objc` — the closure's parameter type is a Swift-only protocol.
+    /// App-side callers must `import Dash0Mobile` and invoke it from Swift.
+    public static var sinkFactory: () -> BridgeCallSink = { NoopSink() }
+
+    public static func installSink(_ factory: @escaping () -> BridgeCallSink) {
+        NSLog("[Dash0Mobile] installSink called")
+        sinkFactory = factory
+    }
+
+    override init() {
+        let sink = Dash0MobileModule.sinkFactory()
+        NSLog("[Dash0Mobile] Module init with sink type: \(type(of: sink))")
+        self.dispatcher = Dash0MobileBridgeDispatcher(sink: sink)
+        super.init()
+    }
+
+    // MARK: - For tests
+
+    init(dispatcher: Dash0MobileBridgeDispatcher) {
+        self.dispatcher = dispatcher
+        super.init()
+    }
+
+    // MARK: - RN-visible methods
+
+    @objc(start:resolver:rejecter:)
+    func start(
+        config: [String: Any],
+        resolver: @escaping (Any?) -> Void,
+        rejecter: @escaping (String, String?, Error?) -> Void
+    ) {
+        do {
+            try dispatcher.start(config: config)
+            resolver(nil)
+        } catch {
+            rejecter("Dash0Mobile.start", error.localizedDescription, error)
+        }
+    }
+
+    @objc(emitBatch:resolver:rejecter:)
+    func emitBatch(
+        payloads: [[String: Any]],
+        resolver: @escaping (Any?) -> Void,
+        rejecter: @escaping (String, String?, Error?) -> Void
+    ) {
+        dispatcher.emitBatch(payloads)
+        resolver(nil)
+    }
+
+    @objc(flushWindow:resolver:rejecter:)
+    func flushWindow(
+        minutes: Double,
+        resolver: @escaping (Any?) -> Void,
+        rejecter: @escaping (String, String?, Error?) -> Void
+    ) {
+        dispatcher.flushWindow(minutes: minutes)
+        resolver(nil)
+    }
+
+    @objc(shutdown:rejecter:)
+    func shutdown(
+        resolver: @escaping (Any?) -> Void,
+        rejecter: @escaping (String, String?, Error?) -> Void
+    ) {
+        dispatcher.shutdown()
+        resolver(nil)
+    }
+}
+
+// Fallback used when no host-provided sink has been installed. Swallows
+// calls so the module can be instantiated in CI builds that only verify
+// the RN surface. Apps opt in to real telemetry by calling
+// `Dash0MobileModule.installSink { OTelMobileCallSink() }` from their
+// AppDelegate (OTelMobileCallSink lives in the app target so it can see
+// the app's SwiftPM-attached OTelMobileSDK).
+public final class NoopSink: BridgeCallSink {
+    public init() {}
+    public func start(_ config: BridgeStartConfig) {}
+    public func emitLog(name: String, severity: Int, attributes: [String: Any], timeUnixNano: UInt64) {}
+    public func startSpan(spanId: String, parentSpanId: String?, name: String, spanKind: String, attributes: [String: Any], startTimeUnixNano: UInt64) {}
+    public func endSpan(spanId: String, status: String, statusMessage: String?, attributes: [String: Any], endTimeUnixNano: UInt64) {}
+    public func recordMetric(name: String, instrumentType: String, value: Double, attributes: [String: Any], timeUnixNano: UInt64) {}
+    public func flushWindow(minutes: Int) {}
+    public func shutdown() {}
+}