@barrysolomon/mobile-react-native 0.1.0-alpha

package/Dash0Mobile.podspec

@@ -0,0 +1,29 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name         = "Dash0Mobile"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["repository"]
+  s.license      = "Apache-2.0"
+  s.author       = { "Dash0" => "hello@dash0.com" }
+
+  s.platforms    = { :ios => "15.0" }
+  s.source       = { :path => "." }
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  # OTelMobileCallSink.swift is excluded from the pod because it depends on
+  # OTelMobileSDK, which in most RN apps is delivered via SwiftPM on the
+  # app's Xcode project — not through CocoaPods. The pod compiles without
+  # it; consumers copy OTelMobileCallSink.swift into their app target and
+  # call `Dash0MobileModule.installSink { OTelMobileCallSink() }` from
+  # AppDelegate to activate real telemetry.
+  s.exclude_files = [
+    "ios/Tests/**/*",
+    "ios/OTelMobileCallSink.swift",
+  ]
+  s.swift_version = "5.9"
+
+  s.dependency "React-Core"
+end

package/README.md

@@ -0,0 +1,117 @@
+# @dash0/mobile-react-native
+
+Dash0 Mobile Observability SDK for React Native. Bridges JS/TS into the
+existing native Android (`otel-android-mobile`) and iOS (`otel-ios-mobile`)
+SDKs — native owns buffering, policy evaluation, OTLP export, and crash
+recovery. JS stays thin.
+
+**Status:** Complete and validated end-to-end in Dash0. Both Android and iOS
+builds produce real binaries (140 MB APK, 239 MB .app) and telemetry lands in
+Dash0 within ~3 s. All 4 platforms (Android native, iOS native, RN Android,
+RN iOS) have a UAT matrix of 12/12 cells green. 83 Jest tests pass.
+
+## Quickstart
+
+```ts
+import { Dash0Mobile } from '@dash0/mobile-react-native';
+
+await Dash0Mobile.start({
+  serviceName: 'my-rn-app',
+  endpoint: 'https://ingress.us-west-2.aws.dash0.com/v1/logs',
+  authToken: process.env.DASH0_AUTH_TOKEN,
+  dataset: 'otel-mobile',
+});
+
+Dash0Mobile.log('cart.add_item', { 'shop.item_id': 'abc', qty: 2 });
+
+await Dash0Mobile.span('checkout', async () => {
+  await doCheckout();
+});
+```
+
+## Build & test
+
+```bash
+# Install dependencies (first time)
+npm install
+
+# Jest — bridge contract + auto-instrumentation (83 tests)
+npm test
+
+# Type-check
+npx tsc --noEmit
+
+# End-to-end (package + AstronomyShopRN demo, Jest mode — no simulator)
+../../scripts/test/validate-rn-end-to-end.sh --mode=jest
+```
+
+## Layout
+
+```text
+src/
+  bridge/
+    types.ts           # cross-repo seam — DO NOT change without coordinating
+    NativeBridge.ts    # debounced batching marshaller (50 ms batch window)
+  instrumentation/
+    fetch.ts           # fetch/XHR span auto-capture
+    xhr.ts             # XHR span auto-capture
+    errors.ts          # JS error log auto-capture
+    unhandledRejection.ts  # unhandled promise rejection capture
+    navigation.ts      # React Navigation screen-view auto-capture
+    touch.ts           # tap event auto-capture
+  otel-compat.ts       # OTel-API shim (third-party JS libs flow through bridge)
+  index.ts             # public API
+android/               # Kotlin ReactContextBaseJavaModule + BridgeCallSink
+ios/                   # Swift RCTDash0MobileModule + BridgeCallSink
+__tests__/             # Jest — 83 tests across bridge + instrumentation
+```
+
+## Auto-instrumentation
+
+Enabled by default when `Dash0Mobile.start()` is called. Opt out per signal:
+
+```ts
+await Dash0Mobile.start({
+  // ...
+  autoCapture: {
+    network: false,   // disable fetch/XHR spans
+    errors: false,    // disable JS error + rejection logs
+    lifecycle: false, // disable AppState fg/bg
+  },
+});
+```
+
+## Architecture
+
+The JS layer is a thin marshaller with a 50 ms batching window. All buffering,
+policy evaluation, export scheduling, and crash recovery happen inside the
+native SDK on each platform:
+
+```text
+JS (fetch/XHR/errors/nav/tap)
+  ↓  50 ms batch window
+NativeBridge.ts  →  NativeDash0Mobile  →  Android: OTelMobile (gRPC :4317)
+                                      →  iOS:     OTelMobile (HTTP :4318)
+                                                ↓
+                                          OTLP Collector → Dash0
+```
+
+**Transport note:** Android uses OTLP/gRPC on port 4317; iOS uses OTLP/HTTP on
+port 4318. The shared `otel-config.json` uses a per-platform port rewrite at
+startup — do not assume a single endpoint works for both.
+
+## Test strategy
+
+Three layers, all must pass on every PR:
+
+1. **Jest** — `npm test` in this directory; contract + bridge + instrumentation
+2. **Native unit** — `./gradlew :android:test` (Android) + `swift test` (iOS)
+3. **Real-app E2E** — `scripts/test/validate-rn-end-to-end.sh` boots
+   AstronomyShopRN on iOS Simulator + Android emulator, queries Dash0 after 75 s
+
+## Known limitations
+
+- **Expo** — not supported without eject (bare workflow only). An Expo config
+  plugin is planned as a follow-up.
+- **Realm / Amplify DataStore** — scoped in a separate epic.
+- **Web / desktop RN targets** — not supported.

package/android/build.gradle

@@ -0,0 +1,68 @@
+// @dash0/mobile-react-native — Android native module build.
+//
+// When consumed via RN autolinking, the host app's buildscript owns AGP + the
+// Kotlin plugin versions. We apply the plugins here but let the host provide
+// them — hardcoding classpath versions here forced an old AGP/Kotlin combo
+// that conflicted with host-provided stdlib.
+
+// Default matches RN 0.85's Kotlin (2.1.20). Older RN consumers can override
+// via -PDash0Mobile_kotlinVersion.
+ext.kotlin_version = project.findProperty('Dash0Mobile_kotlinVersion') ?: '2.1.20'
+ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+android {
+    namespace 'com.dash0.mobile.reactnative'
+    compileSdk safeExtGet('compileSdkVersion', 34)
+
+    defaultConfig {
+        minSdk safeExtGet('minSdkVersion', 26)
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+
+    testOptions {
+        targetSdk safeExtGet('targetSdkVersion', 34)
+        unitTests {
+            includeAndroidResources = true
+        }
+    }
+
+    lint {
+        targetSdk safeExtGet('targetSdkVersion', 34)
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-android:+"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    // Depend on the existing native Android SDK. Must be `implementation`
+    // (not `compileOnly`) so Kotlin can resolve transitive config classes
+    // (TextInputConfig, BreadcrumbConfig, VitalsConfig, etc.) referenced
+    // through MobileConfig's constructor signature.
+    implementation 'io.opentelemetry.android:mobile:0.1.0-alpha'
+    implementation 'io.opentelemetry:opentelemetry-api:1.58.0'
+
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation 'org.mockito:mockito-core:5.12.0'
+    testImplementation 'org.mockito.kotlin:mockito-kotlin:5.4.0'
+    testImplementation 'io.opentelemetry.android:mobile:0.1.0-alpha'
+    testImplementation 'io.opentelemetry:opentelemetry-api:1.58.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/dash0/mobile/reactnative/BridgeCallSink.kt

@@ -0,0 +1,67 @@
+/*
+ * Seam between the RN bridge and the native OTel Mobile SDK.
+ *
+ * The production implementation (`OTelMobileCallSink`) forwards calls into
+ * `io.opentelemetry.android.mobile.OTelMobile`. Tests provide a fake so we
+ * can assert forwarding behavior without standing up Android's Application,
+ * emulator, or the full OTel SDK.
+ */
+package com.dash0.mobile.reactnative
+
+interface BridgeCallSink {
+    fun start(config: StartConfig)
+    fun emitLog(name: String, severity: Int, attributes: Map<String, Any?>, timeUnixNano: Long)
+    fun startSpan(spanId: String, parentSpanId: String?, name: String, spanKind: String, attributes: Map<String, Any?>, startTimeUnixNano: Long)
+    fun endSpan(spanId: String, status: String, statusMessage: String?, attributes: Map<String, Any?>, endTimeUnixNano: Long)
+    fun recordMetric(name: String, instrumentType: String, value: Double, attributes: Map<String, Any?>, timeUnixNano: Long)
+    fun flushWindow(minutes: Int)
+    fun shutdown()
+
+    /**
+     * Synchronously drain every buffered telemetry record through the
+     * underlying SDK exporter, persisting any in-flight records to disk
+     * on export failure. Called by `Dash0MobileModule.dispatch`
+     * immediately after dispatching a FATAL-severity (severity ≥ 21)
+     * log emit, before continuing to the next payload in the batch.
+     *
+     * Mirrors the iOS [`BridgeCallSink.forceFlush`](../../../../../../../ios/BridgeCallSink.swift)
+     * contract introduced in commit `39bd258`. Default no-op so test
+     * fakes and lightweight non-RN consumers inherit safe behavior;
+     * production sinks override.
+     *
+     * Kept as a default method so existing implementations (test
+     * fakes from earlier RN-bridge work) compile without needing to
+     * be touched. Production [`OTelMobileCallSink.forceFlush`]
+     * overrides this to call [io.opentelemetry.android.mobile.buffering.MobileLogRecordProcessor.forceFlush].
+     */
+    fun forceFlush() = Unit
+}
+
+data class StartConfig(
+    val serviceName: String,
+    val serviceVersion: String?,
+    val endpoint: String,
+    val authToken: String?,
+    val dataset: String?,
+    /**
+     * Extra resource attributes supplied by the JS caller. The RN bridge
+     * populates `telemetry.distro.name` / `telemetry.distro.version` by
+     * default; apps can add their own keys through `Dash0Mobile.start`.
+     */
+    val extraResourceAttributes: Map<String, String>? = null,
+    /**
+     * Native-only auto-capture capability tokens the JS caller explicitly
+     * opted into. Default empty = no native auto-capture (RN apps get
+     * network/errors/lifecycle coverage from the JS-side shims).
+     *
+     * Supported tokens: "network", "errors", "lifecycle", "tap", "scroll",
+     * "textInput", "screen", "freeze", "vitals", "deviceStats".
+     *
+     * Today the Android MobileConfig's auto-capture is driven separately by
+     * the host app's `OTelMobileBuilder` — these tokens are accepted here
+     * for cross-platform bridge parity but not yet consumed. When the
+     * Android SDK gains a unified `autoCaptureOptions` on MobileConfig, the
+     * sink will translate them the same way the iOS sink does today.
+     */
+    val nativeAutoCapture: List<String> = emptyList(),
+)

package/android/src/main/java/com/dash0/mobile/reactnative/Dash0MobileModule.kt

@@ -0,0 +1,198 @@
+/*
+ * Dash0MobileModule — React Native bridge for @dash0/mobile-react-native.
+ *
+ * Responsibilities (kept deliberately thin):
+ *   1. Decode JS payloads (ReadableMap / ReadableArray) into native types.
+ *   2. Dispatch on the payload `kind` field.
+ *   3. Forward to a BridgeCallSink (production: OTelMobileCallSink).
+ *
+ * All buffering / policy / export / crash recovery lives in the existing
+ * io.opentelemetry.android.mobile.OTelMobile SDK — not here.
+ */
+package com.dash0.mobile.reactnative
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+
+class Dash0MobileModule internal constructor(
+    reactContext: ReactApplicationContext,
+    private val sink: BridgeCallSink,
+) : ReactContextBaseJavaModule(reactContext) {
+
+    constructor(reactContext: ReactApplicationContext) :
+        this(reactContext, OTelMobileCallSink(reactContext.applicationContext))
+
+    override fun getName(): String = NAME
+
+    @ReactMethod
+    fun start(config: ReadableMap, promise: Promise) {
+        try {
+            sink.start(
+                StartConfig(
+                    serviceName = config.getString("serviceName")
+                        ?: error("serviceName is required"),
+                    serviceVersion = config.getStringOrNull("serviceVersion"),
+                    endpoint = config.getString("endpoint")
+                        ?: error("endpoint is required"),
+                    authToken = config.getStringOrNull("authToken"),
+                    dataset = config.getStringOrNull("dataset"),
+                    extraResourceAttributes = config
+                        .getMapOrNull("extraResourceAttributes")
+                        ?.toStringMap(),
+                    nativeAutoCapture = config
+                        .getArrayOrNull("nativeAutoCapture")
+                        ?.toStringList()
+                        ?: emptyList(),
+                ),
+            )
+            promise.resolve(null)
+        } catch (t: Throwable) {
+            promise.reject("Dash0Mobile.start", t)
+        }
+    }
+
+    @ReactMethod
+    fun emitBatch(payloads: ReadableArray, promise: Promise) {
+        try {
+            for (i in 0 until payloads.size()) {
+                val p = payloads.getMap(i) ?: continue
+                dispatch(p)
+            }
+            promise.resolve(null)
+        } catch (t: Throwable) {
+            promise.reject("Dash0Mobile.emitBatch", t)
+        }
+    }
+
+    @ReactMethod
+    fun flushWindow(minutes: Double, promise: Promise) {
+        try {
+            sink.flushWindow(minutes.toInt())
+            promise.resolve(null)
+        } catch (t: Throwable) {
+            promise.reject("Dash0Mobile.flushWindow", t)
+        }
+    }
+
+    @ReactMethod
+    fun shutdown(promise: Promise) {
+        try {
+            sink.shutdown()
+            promise.resolve(null)
+        } catch (t: Throwable) {
+            promise.reject("Dash0Mobile.shutdown", t)
+        }
+    }
+
+    private fun dispatch(p: ReadableMap) {
+        val kind = p.getString("kind") ?: return
+        val attrs = p.getMapOrNull("attributes")?.toAttributeMap() ?: emptyMap()
+        when (kind) {
+            "log" -> {
+                val severity = p.getInt("severity")
+                sink.emitLog(
+                    name = p.getString("name") ?: return,
+                    severity = severity,
+                    attributes = attrs,
+                    timeUnixNano = p.getStringAsLong("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 waiting for the
+                // periodic flush. Eagerly drain BEFORE the next payload
+                // in the batch so the FATAL has a chance to reach disk
+                // (and from there OTLP) even if the next payload's
+                // dispatch path or the JS reporter terminates the
+                // process. Mirrors iOS dispatcher commit `39bd258`.
+                if (severity >= 21) {
+                    sink.forceFlush()
+                }
+            }
+            "spanStart" -> sink.startSpan(
+                spanId = p.getString("spanId") ?: return,
+                parentSpanId = p.getStringOrNull("parentSpanId"),
+                name = p.getString("name") ?: return,
+                spanKind = p.getString("spanKind") ?: "INTERNAL",
+                attributes = attrs,
+                startTimeUnixNano = p.getStringAsLong("startTimeUnixNano"),
+            )
+            "spanEnd" -> sink.endSpan(
+                spanId = p.getString("spanId") ?: return,
+                status = p.getString("status") ?: "UNSET",
+                statusMessage = p.getStringOrNull("statusMessage"),
+                attributes = attrs,
+                endTimeUnixNano = p.getStringAsLong("endTimeUnixNano"),
+            )
+            "metric" -> sink.recordMetric(
+                name = p.getString("name") ?: return,
+                instrumentType = p.getString("instrumentType") ?: "counter",
+                value = p.getDouble("value"),
+                attributes = attrs,
+                timeUnixNano = p.getStringAsLong("timeUnixNano"),
+            )
+            else -> Unit // unknown kinds are silently dropped (forward-compat)
+        }
+    }
+
+    companion object {
+        const val NAME = "Dash0Mobile"
+    }
+}
+
+// ─── ReadableMap helpers ─────────────────────────────────────────────────────
+
+private fun ReadableMap.getStringOrNull(key: String): String? =
+    if (hasKey(key) && !isNull(key)) getString(key) else null
+
+private fun ReadableMap.getMapOrNull(key: String): ReadableMap? =
+    if (hasKey(key) && !isNull(key)) getMap(key) else null
+
+private fun ReadableMap.getArrayOrNull(key: String): ReadableArray? =
+    if (hasKey(key) && !isNull(key)) getArray(key) else null
+
+private fun ReadableArray.toStringList(): List<String> {
+    val out = ArrayList<String>(size())
+    for (i in 0 until size()) {
+        if (getType(i) == ReadableType.String) {
+            getString(i)?.let { out.add(it) }
+        }
+    }
+    return out
+}
+
+private fun ReadableMap.getStringAsLong(key: String): Long =
+    getStringOrNull(key)?.toLongOrNull() ?: 0L
+
+private fun ReadableMap.toStringMap(): Map<String, String> {
+    val iter = keySetIterator()
+    val out = LinkedHashMap<String, String>()
+    while (iter.hasNextKey()) {
+        val k = iter.nextKey()
+        if (getType(k) == ReadableType.String) {
+            getString(k)?.let { out[k] = it }
+        }
+    }
+    return out
+}
+
+private fun ReadableMap.toAttributeMap(): Map<String, Any?> {
+    val iter = keySetIterator()
+    val out = LinkedHashMap<String, Any?>()
+    while (iter.hasNextKey()) {
+        val k = iter.nextKey()
+        out[k] = when (getType(k)) {
+            ReadableType.Null -> null
+            ReadableType.Boolean -> getBoolean(k)
+            ReadableType.Number -> getDouble(k)
+            ReadableType.String -> getString(k)
+            else -> null // RN bridge doesn't send nested Map/Array as attribute values
+        }
+    }
+    return out
+}

package/android/src/main/java/com/dash0/mobile/reactnative/Dash0MobilePackage.kt

@@ -0,0 +1,14 @@
+package com.dash0.mobile.reactnative
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class Dash0MobilePackage : ReactPackage {
+    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+        listOf(Dash0MobileModule(reactContext))
+
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+        emptyList()
+}