@barrysolomon/mobile-react-native 0.1.0-alpha

package/ios/Tests/Dash0MobileBridgeDispatcherTests.swift

@@ -0,0 +1,341 @@
+// RN-013 unit tests for Dash0MobileBridgeDispatcher.
+//
+// Uses Swift Testing (aligns with the rest of otel-ios-mobile). These tests
+// drive the dispatcher through the same payload fixtures the Android module
+// tests use, to keep the cross-platform bridge contract aligned.
+
+import Testing
+@testable import Dash0MobileReactNative
+
+@Suite("Dash0MobileBridgeDispatcher")
+struct Dash0MobileBridgeDispatcherTests {
+
+    // ── start ─────────────────────────────────────────────────────────────
+
+    @Test
+    func start_forwards_all_fields() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "otel-rn-astronomy-shop",
+            "endpoint": "https://ingress/v1/logs",
+            "serviceVersion": "1.2.3",
+            "authToken": "tok",
+            "dataset": "otel-mobile",
+        ])
+        #expect(sink.starts.count == 1)
+        let got = sink.starts[0]
+        #expect(got.serviceName == "otel-rn-astronomy-shop")
+        #expect(got.endpoint == "https://ingress/v1/logs")
+        #expect(got.serviceVersion == "1.2.3")
+        #expect(got.authToken == "tok")
+        #expect(got.dataset == "otel-mobile")
+    }
+
+    @Test
+    func start_forwards_nativeAutoCapture_tokens() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "s",
+            "endpoint": "https://e",
+            "nativeAutoCapture": ["vitals", "deviceStats"],
+        ])
+        #expect(sink.starts.count == 1)
+        #expect(sink.starts[0].nativeAutoCapture == ["vitals", "deviceStats"])
+    }
+
+    @Test
+    func start_defaults_nativeAutoCapture_to_empty_when_absent() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "s",
+            "endpoint": "https://e",
+        ])
+        #expect(sink.starts[0].nativeAutoCapture == [])
+    }
+
+    @Test
+    func start_throws_when_serviceName_missing() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        #expect(throws: Dash0MobileBridgeError.self) {
+            try d.start(config: ["endpoint": "e"])
+        }
+        #expect(sink.starts.isEmpty)
+    }
+
+    // ── emitBatch: log ────────────────────────────────────────────────────
+
+    @Test
+    func emitBatch_dispatches_log() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.emitBatch([[
+            "kind": "log",
+            "name": "cart.add_item",
+            "severity": 9,
+            "timeUnixNano": "1713600000000000000",
+            "attributes": ["shop.item_id": "abc", "qty": 2, "urgent": true],
+        ]])
+        #expect(sink.logs.count == 1)
+        let l = sink.logs[0]
+        #expect(l.name == "cart.add_item")
+        #expect(l.severity == 9)
+        #expect(l.timeUnixNano == 1_713_600_000_000_000_000)
+        #expect(l.attributes["shop.item_id"] as? String == "abc")
+        #expect(l.attributes["urgent"] as? Bool == true)
+    }
+
+    // ── emitBatch: span pair ──────────────────────────────────────────────
+
+    @Test
+    func emitBatch_dispatches_spanStart_then_spanEnd() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.emitBatch([
+            [
+                "kind": "spanStart",
+                "spanId": "abc123def456789a",
+                "name": "checkout",
+                "spanKind": "INTERNAL",
+                "startTimeUnixNano": "0",
+                "attributes": ["shop.cart_size": 3],
+            ],
+            [
+                "kind": "spanEnd",
+                "spanId": "abc123def456789a",
+                "status": "OK",
+                "endTimeUnixNano": "50",
+                "attributes": ["http.response.status_code": 200],
+            ],
+        ])
+        #expect(sink.spanStarts.count == 1)
+        #expect(sink.spanEnds.count == 1)
+        #expect(sink.spanStarts[0].spanId == sink.spanEnds[0].spanId)
+        #expect(sink.spanEnds[0].status == "OK")
+    }
+
+    @Test
+    func emitBatch_dispatches_ERROR_with_statusMessage() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.emitBatch([[
+            "kind": "spanEnd",
+            "spanId": "aaaaaaaaaaaaaaaa",
+            "status": "ERROR",
+            "statusMessage": "nope",
+            "endTimeUnixNano": "0",
+            "attributes": [:],
+        ]])
+        #expect(sink.spanEnds[0].status == "ERROR")
+        #expect(sink.spanEnds[0].statusMessage == "nope")
+    }
+
+    // ── emitBatch: metric ─────────────────────────────────────────────────
+
+    @Test
+    func emitBatch_dispatches_counter_histogram_gauge() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        for t in ["counter", "histogram", "gauge"] {
+            d.emitBatch([[
+                "kind": "metric",
+                "name": "shop.x",
+                "instrumentType": t,
+                "value": 42.5,
+                "timeUnixNano": "0",
+                "attributes": [:],
+            ]])
+        }
+        #expect(sink.metrics.count == 3)
+        #expect(sink.metrics.map { $0.instrumentType } == ["counter", "histogram", "gauge"])
+        #expect(sink.metrics[0].value == 42.5)
+    }
+
+    // ── forward-compat ────────────────────────────────────────────────────
+
+    @Test
+    func emitBatch_silently_drops_unknown_kind() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.emitBatch([["kind": "martian", "name": "x"]])
+        #expect(sink.logs.isEmpty)
+        #expect(sink.metrics.isEmpty)
+        #expect(sink.spanStarts.isEmpty)
+        #expect(sink.spanEnds.isEmpty)
+    }
+
+    // ── flush / shutdown ──────────────────────────────────────────────────
+
+    @Test
+    func flushWindow_forwards_rounded_minutes() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.flushWindow(minutes: 5.0)
+        #expect(sink.flushMinutes == [5])
+    }
+
+    @Test
+    func shutdown_forwards() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.shutdown()
+        #expect(sink.shutdowns == 1)
+    }
+
+    // MARK: - FATAL-severity forceFlush hook
+
+    @Test
+    func emitLog_fatalSeverity_triggersForceFlush() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.emitBatch([[
+            "kind": "log",
+            "name": "app.error",
+            "severity": 21,
+            "attributes": [:],
+            "timeUnixNano": "1700000000000000000"
+        ]])
+        #expect(sink.logs.count == 1)
+        #expect(sink.forceFlushes == 1)
+    }
+
+    @Test
+    func emitLog_belowFatal_doesNotTriggerForceFlush() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        // 17 = ERROR in OTel semconv. Should NOT flush.
+        d.emitBatch([[
+            "kind": "log",
+            "name": "app.error",
+            "severity": 17,
+            "attributes": [:],
+            "timeUnixNano": "1700000000000000000"
+        ]])
+        #expect(sink.logs.count == 1)
+        #expect(sink.forceFlushes == 0)
+    }
+
+    @Test
+    func emitLog_fatalSeverity_flushOrderingIsPostEmitPrePeer() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        // FATAL log followed by another payload in the same batch. The
+        // dispatcher must emit the FATAL, force-flush, THEN dispatch
+        // the next payload — never the other way around. This preserves
+        // the invariant that the FATAL gets out of the RAM buffer before
+        // the next bridge call could clobber it (or the process dies).
+        d.emitBatch([
+            [
+                "kind": "log",
+                "name": "app.error",
+                "severity": 21,
+                "attributes": [:],
+                "timeUnixNano": "1700000000000000000"
+            ],
+            [
+                "kind": "log",
+                "name": "app.error.context",
+                "severity": 9,
+                "attributes": [:],
+                "timeUnixNano": "1700000000000000001"
+            ]
+        ])
+        // Expected order: emit FATAL, forceFlush, emit context.
+        #expect(sink.actionLog == [
+            "emitLog(app.error,21)",
+            "forceFlush",
+            "emitLog(app.error.context,9)"
+        ])
+    }
+
+    @Test
+    func emitLog_multipleFatalsInBatch_eachTriggersFlush() {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        // Two FATALs in a row — each gets its own flush. Wasteful but
+        // safer than batching: a flush after the first FATAL might
+        // succeed-then-die before reaching the second; flushing after
+        // each ensures both have a chance to reach disk independently.
+        d.emitBatch([
+            ["kind": "log", "name": "a", "severity": 21, "attributes": [:], "timeUnixNano": "1"],
+            ["kind": "log", "name": "b", "severity": 22, "attributes": [:], "timeUnixNano": "2"]
+        ])
+        #expect(sink.forceFlushes == 2)
+    }
+
+    @Test
+    func emitLog_fatalSeverityRangeBoundary() {
+        // OTel semconv: FATAL severity range is 21..24. Anything >= 21
+        // is FATAL. The dispatcher's threshold (>= 21) covers all.
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        d.emitBatch([
+            ["kind": "log", "name": "fatal2", "severity": 22, "attributes": [:], "timeUnixNano": "1"],
+            ["kind": "log", "name": "fatal3", "severity": 23, "attributes": [:], "timeUnixNano": "2"],
+            ["kind": "log", "name": "fatal4", "severity": 24, "attributes": [:], "timeUnixNano": "3"],
+            ["kind": "log", "name": "warn",   "severity": 13, "attributes": [:], "timeUnixNano": "4"]
+        ])
+        #expect(sink.forceFlushes == 3)
+    }
+}
+
+// ─── test double ──────────────────────────────────────────────────────────
+
+private struct LogCall { let name: String; let severity: Int; let attributes: [String: Any]; let timeUnixNano: UInt64 }
+private struct SpanStartCall { let spanId: String; let parentSpanId: String?; let name: String; let spanKind: String; let attributes: [String: Any]; let startTimeUnixNano: UInt64 }
+private struct SpanEndCall { let spanId: String; let status: String; let statusMessage: String?; let attributes: [String: Any]; let endTimeUnixNano: UInt64 }
+private struct MetricCall { let name: String; let instrumentType: String; let value: Double; let attributes: [String: Any]; let timeUnixNano: UInt64 }
+
+private final class RecordingSink: BridgeCallSink {
+    var starts: [BridgeStartConfig] = []
+    var logs: [LogCall] = []
+    var spanStarts: [SpanStartCall] = []
+    var spanEnds: [SpanEndCall] = []
+    var metrics: [MetricCall] = []
+    var flushMinutes: [Int] = []
+    var shutdowns = 0
+    /// Records the order of `(action, payloadIndex)` so tests can assert
+    /// that `forceFlush` runs AFTER the FATAL emit but BEFORE the next
+    /// payload in the same batch. The dispatcher contract says: dispatch
+    /// the log first (so it lands in the buffer), then force-flush so
+    /// the buffer drains before the next payload (which might carry a
+    /// span end the FATAL log's trace context references).
+    var actionLog: [String] = []
+    var forceFlushes = 0
+
+    func start(_ config: BridgeStartConfig) {
+        starts.append(config)
+        actionLog.append("start")
+    }
+    func emitLog(name: String, severity: Int, attributes: [String: Any], timeUnixNano: UInt64) {
+        logs.append(LogCall(name: name, severity: severity, attributes: attributes, timeUnixNano: timeUnixNano))
+        actionLog.append("emitLog(\(name),\(severity))")
+    }
+    func startSpan(spanId: String, parentSpanId: String?, name: String, spanKind: String, attributes: [String: Any], startTimeUnixNano: UInt64) {
+        spanStarts.append(SpanStartCall(spanId: spanId, parentSpanId: parentSpanId, name: name, spanKind: spanKind, attributes: attributes, startTimeUnixNano: startTimeUnixNano))
+        actionLog.append("startSpan(\(name))")
+    }
+    func endSpan(spanId: String, status: String, statusMessage: String?, attributes: [String: Any], endTimeUnixNano: UInt64) {
+        spanEnds.append(SpanEndCall(spanId: spanId, status: status, statusMessage: statusMessage, attributes: attributes, endTimeUnixNano: endTimeUnixNano))
+        actionLog.append("endSpan(\(spanId))")
+    }
+    func recordMetric(name: String, instrumentType: String, value: Double, attributes: [String: Any], timeUnixNano: UInt64) {
+        metrics.append(MetricCall(name: name, instrumentType: instrumentType, value: value, attributes: attributes, timeUnixNano: timeUnixNano))
+        actionLog.append("recordMetric(\(name))")
+    }
+    func flushWindow(minutes: Int) {
+        flushMinutes.append(minutes)
+        actionLog.append("flushWindow(\(minutes))")
+    }
+    func shutdown() {
+        shutdowns += 1
+        actionLog.append("shutdown")
+    }
+    func forceFlush() {
+        forceFlushes += 1
+        actionLog.append("forceFlush")
+    }
+}

package/lib/src/NativeDash0Mobile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * TurboModule codegen spec for @dash0/mobile-react-native.
+ *
+ * This file is intentionally NOT imported by `src/index.ts` — it exists
+ * solely to drive RN codegen (0.68+ / Fabric). The runtime code path goes
+ * through `require('react-native').NativeModules.Dash0Mobile` so we keep
+ * working on both old-arch and new-arch.
+ *
+ * Codegen constraints (from React Native docs):
+ *   - methods must return `Promise<T>` or `void`
+ *   - parameters must be primitives, `Object`, `Array`, or `{ readonly ... }`
+ *   - no union types as parameters (codegen rejects)
+ *
+ * The shapes below are deliberately looser than `bridge/types.ts` (Object
+ * instead of discriminated unions) because codegen can't narrow on `kind`.
+ * The native side runtime-dispatches on the `kind` string.
+ */
+import type { TurboModule } from 'react-native';
+export interface Spec extends TurboModule {
+    start(config: Object): Promise<void>;
+    emitBatch(payloads: Object[]): Promise<void>;
+    flushWindow(minutes: number): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare const _default: Spec;
+export default _default;
+//# sourceMappingURL=NativeDash0Mobile.d.ts.map

package/lib/src/NativeDash0Mobile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeDash0Mobile.d.ts","sourceRoot":"","sources":["../../src/NativeDash0Mobile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;;AAED,wBAAqE"}

package/lib/src/NativeDash0Mobile.js

@@ -0,0 +1,19 @@
+/**
+ * TurboModule codegen spec for @dash0/mobile-react-native.
+ *
+ * This file is intentionally NOT imported by `src/index.ts` — it exists
+ * solely to drive RN codegen (0.68+ / Fabric). The runtime code path goes
+ * through `require('react-native').NativeModules.Dash0Mobile` so we keep
+ * working on both old-arch and new-arch.
+ *
+ * Codegen constraints (from React Native docs):
+ *   - methods must return `Promise<T>` or `void`
+ *   - parameters must be primitives, `Object`, `Array`, or `{ readonly ... }`
+ *   - no union types as parameters (codegen rejects)
+ *
+ * The shapes below are deliberately looser than `bridge/types.ts` (Object
+ * instead of discriminated unions) because codegen can't narrow on `kind`.
+ * The native side runtime-dispatches on the `kind` string.
+ */
+import { TurboModuleRegistry } from 'react-native';
+export default TurboModuleRegistry.getEnforcing('Dash0Mobile');

package/lib/src/bridge/NativeBridge.d.ts

@@ -0,0 +1,38 @@
+import type { BridgePayload, NativeDash0MobileModule } from './types';
+export declare const DEBOUNCE_MS = 50;
+export declare const MAX_QUEUE = 10000;
+export declare class NativeBridge {
+    private readonly native;
+    private queue;
+    private timer;
+    private inFlight;
+    constructor(native: NativeDash0MobileModule);
+    emit(payload: BridgePayload): void;
+    /**
+     * Synchronous fast-path for FATAL-severity payloads. Cancels any pending
+     * debounce, drains the queue + the new payload in a single
+     * `native.emitBatch` call made SYNCHRONOUSLY on the current stack frame.
+     *
+     * Why not just `emit(); flush()`? Because `flush()` is `async`, and its
+     * `await this.drain()` places the call to `native.emitBatch` on the
+     * microtask queue. On a crash path (JS throw → ErrorUtils global handler
+     * → previous(error, isFatal) → RN fatal reporter → process exit) the
+     * handler's synchronous continuation wins the race against the
+     * microtask — the payload never crosses the bridge.
+     *
+     * This method is intentionally fire-and-forget: per the RN bridge
+     * contract, argument marshaling is synchronous, so the payload arrives
+     * on the native side by the time `native.emitBatch(...)` returns. The
+     * Promise resolution (native-side completion signal) is async and we
+     * don't await it — we only need the payload to cross the bridge before
+     * the process dies. `.catch(() => {})` prevents unhandledRejection
+     * warnings if the native side fails.
+     *
+     * See docs/superpowers/specs/2026-04-22-rn-fatal-bridge-bypass-design.md.
+     */
+    emitSync(payload: BridgePayload): void;
+    flush(): Promise<void>;
+    private drain;
+    private sendWithRetry;
+}
+//# sourceMappingURL=NativeBridge.d.ts.map

package/lib/src/bridge/NativeBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeBridge.d.ts","sourceRoot":"","sources":["../../../src/bridge/NativeBridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEtE,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,eAAO,MAAM,SAAS,QAAS,CAAC;AAIhC,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,QAAQ,CAA8B;gBAElC,MAAM,EAAE,uBAAuB;IAI3C,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAalC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAgBhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAQd,KAAK;YAYL,aAAa;CAY5B"}

package/lib/src/bridge/NativeBridge.js

@@ -0,0 +1,95 @@
+export const DEBOUNCE_MS = 50;
+export const MAX_QUEUE = 10000;
+const RETRY_BASE_MS = 100;
+const RETRY_MAX_ATTEMPTS = 5;
+export class NativeBridge {
+    constructor(native) {
+        this.queue = [];
+        this.timer = null;
+        this.inFlight = null;
+        this.native = native;
+    }
+    emit(payload) {
+        this.queue.push(payload);
+        if (this.queue.length > MAX_QUEUE) {
+            this.queue.splice(0, this.queue.length - MAX_QUEUE);
+        }
+        if (this.timer === null) {
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                void this.drain();
+            }, DEBOUNCE_MS);
+        }
+    }
+    /**
+     * Synchronous fast-path for FATAL-severity payloads. Cancels any pending
+     * debounce, drains the queue + the new payload in a single
+     * `native.emitBatch` call made SYNCHRONOUSLY on the current stack frame.
+     *
+     * Why not just `emit(); flush()`? Because `flush()` is `async`, and its
+     * `await this.drain()` places the call to `native.emitBatch` on the
+     * microtask queue. On a crash path (JS throw → ErrorUtils global handler
+     * → previous(error, isFatal) → RN fatal reporter → process exit) the
+     * handler's synchronous continuation wins the race against the
+     * microtask — the payload never crosses the bridge.
+     *
+     * This method is intentionally fire-and-forget: per the RN bridge
+     * contract, argument marshaling is synchronous, so the payload arrives
+     * on the native side by the time `native.emitBatch(...)` returns. The
+     * Promise resolution (native-side completion signal) is async and we
+     * don't await it — we only need the payload to cross the bridge before
+     * the process dies. `.catch(() => {})` prevents unhandledRejection
+     * warnings if the native side fails.
+     *
+     * See docs/superpowers/specs/2026-04-22-rn-fatal-bridge-bypass-design.md.
+     */
+    emitSync(payload) {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const batch = this.queue.length > 0 ? [...this.queue, payload] : [payload];
+        this.queue = [];
+        this.native.emitBatch(batch).catch(() => {
+            // Swallow — on the crash path, the process is dying anyway and
+            // there's no caller alive to observe the error. On non-crash paths
+            // (if any caller uses emitSync for non-FATAL severity) the payload
+            // is lost on failure, which matches the implicit "best-effort"
+            // contract of the RN bridge under adverse conditions.
+        });
+    }
+    async flush() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        await this.drain();
+    }
+    async drain() {
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue;
+        this.queue = [];
+        this.inFlight = this.sendWithRetry(batch);
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    async sendWithRetry(batch) {
+        for (let attempt = 0; attempt < RETRY_MAX_ATTEMPTS; attempt++) {
+            try {
+                await this.native.emitBatch(batch);
+                return;
+            }
+            catch {
+                if (attempt === RETRY_MAX_ATTEMPTS - 1)
+                    return;
+                const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+}