feat: network-awarness [rn] by choudlet · Pull Request #24 · metarouterio/react-native-sdk

choudlet · 2026-04-08T01:59:04Z

Summary

PR 1 of 2 of Network Awareness. This PR Adds in Network Monitoring + Awareness to stop transmitting events via HTTP when there is no network connection (offline mode).

The risk window is: extended offline + high event volume = dropped events. For most real-world mobile sessions (brief subway tunnels, elevator rides, spotty coverage), 2000 in-memory events is plenty. The Part 2 disk overflow is for the long-tail case — hours offline with continuous event generation.

New NetworkMonitor TypeScript wrapper (src/analytics/utils/networkMonitor.ts) — wraps native bridge module with NetworkReachability interface, StubNetworkMonitor test double, and graceful fallback to always-connected when native module unavailable
iOS native module (ios/MetaRouterNetworkMonitor.m) — NWPathMonitor on a background serial queue, emits onConnectivityChange events via NativeEventEmitter
Android native module (android/.../MetaRouterNetworkMonitorModule.kt) — ConnectivityManager.NetworkCallback with NET_CAPABILITY_INTERNET, ACCESS_NETWORK_STATE permission declared
CircuitBreaker.reset() — clears all stale state (failures, openCount, backoff) on offline→online transition
Dispatcher network guard — isNetworkAvailable callback short-circuits flush loop when offline; resetCircuitBreaker() exposed for reconnect
MetaRouterAnalyticsClient wiring — DI via deps constructor param, subscribes to network changes in init(), resets circuit breaker + triggers flush on reconnect, networkStatus in getDebugInfo(), cleanup in reset()
maxOfflineDiskEvents added to InitOptions (plumbed through for PR 2: offline disk overflow)

Key design decisions

Flush loop continues ticking while offline; flush() short-circuits via isNetworkAvailable() guard (simpler than pause/resume, no conflicts with app lifecycle)
Native bridge modules use same platform APIs as iOS/Android native SDKs
Constructor deps param for DI keeps testing concerns out of InitOptions

Ticket: https://app.shortcut.com/metarouter/story/36910/network-monitoring-dispatcher-awareness-react-native
Pt. 2: https://app.shortcut.com/metarouter/story/37597/offline-disk-overflow-event-capping-react-native

Test plan

183/183 tests pass (npx jest --no-cache)
TypeScript compiles cleanly (npx tsc --noEmit)
StubNetworkMonitor: transitions, dedup, stop/unsub
NetworkMonitor: graceful fallback in test env
CircuitBreaker.reset(): OPEN→CLOSED, clears openCount/failures
Dispatcher: offline guard (no HTTP), online flush, resetCircuitBreaker
Client: networkStatus in debugInfo, offline→online flush, reset cleanup
Manual: verify iOS NWPathMonitor events in RN app
Manual: verify Android ConnectivityManager events in RN app

Add network connectivity awareness to the React Native SDK so events queue in memory while offline and flush on reconnect. - NetworkMonitor TS wrapper + native bridge modules (iOS NWPathMonitor, Android ConnectivityManager) - CircuitBreaker.reset() clears stale backoff on reconnect - Dispatcher guards flush with isNetworkAvailable() - MetaRouterAnalyticsClient wires network monitor via DI - Add maxOfflineDiskEvents to InitOptions (for PR 2) - Comprehensive tests for all new behavior Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…wareness

choudlet · 2026-04-09T16:11:06Z

@@ -0,0 +1,119 @@
+package com.metarouter.reactnative


native kotlin monitor

choudlet · 2026-04-09T16:15:23Z

+
+    override fun getName(): String = "MetaRouterNetworkMonitor"
+
+    @Volatile


ensure that reads + writes go to main memory, ensures that if two threads are on diff cores we aren't reading stale cached copy. Helps to ensure we don't run into subtle caching issues.

choudlet · 2026-04-09T16:16:16Z

+    private var networkCallback: ConnectivityManager.NetworkCallback? = null
+
+    init {
+        connectivityManager = try {


grab reference to connectivity service

choudlet · 2026-04-09T16:17:07Z

+    @Volatile
+    private var isConnected: Boolean = true
+
+    private var connectivityManager: ConnectivityManager? = null


allow null for graceful degradation if not avail

choudlet · 2026-04-09T16:17:56Z

+        }
+
+        // Snapshot initial state
+        connectivityManager?.let { cm ->


this .let means skip entire block if null

choudlet · 2026-04-09T16:19:24Z

+
+        // Snapshot initial state
+        connectivityManager?.let { cm ->
+            isConnected = try {


sets initial state

choudlet · 2026-04-09T16:22:03Z

+                }
+
+                override fun onLost(network: Network) {
+                    val activeNet = cm.activeNetwork


this is a bit smarter bc if wifi drops we can't just respond to the onLost event we need to check if cellular connection still exists via the activeNet

choudlet · 2026-04-09T16:24:42Z

+                override fun onAvailable(network: Network) {
+                    if (!isConnected) {
+                        isConnected = true
+                        sendEvent(true)


this sendEvent is sending the event across the react native bridge 💪 🌉 .

choudlet · 2026-04-09T16:24:50Z

+                    ) == true
+                    if (!hasInternet && isConnected) {
+                        isConnected = false
+                        sendEvent(false)


send false, no longer connected

choudlet · 2026-04-09T16:27:23Z

+
+            try {
+                cm.registerNetworkCallback(request, cb)
+                networkCallback = cb


register with the service then save callback for cleanup

choudlet · 2026-04-09T16:28:01Z

+
+    private fun sendEvent(connected: Boolean) {
+        val params = Arguments.createMap().apply {
+            putBoolean("isConnected", connected)


defining shape of JS bridge event {isConnected: boolean}

choudlet · 2026-04-09T16:28:14Z

+        }
+    }
+
+    @ReactMethod


react methods we expose

choudlet · 2026-04-09T16:28:52Z

+        promise.resolve(isConnected)
+    }
+
+    @ReactMethod


need to have these events otherwise there are warnings, no-op

choudlet · 2026-04-09T16:29:31Z

+        // Required for RN event emitter
+    }
+
+    override fun invalidate() {


unregister callback on termination

choudlet · 2026-04-09T16:31:57Z

 import com.facebook.react.uimanager.ViewManager

-class MetaRouterQueueStoragePackage : ReactPackage {
+class MetaRouterPackage : ReactPackage {


renaming bc now the native modules include more than just queue

choudlet · 2026-04-09T16:32:21Z

@@ -1,3 +1,4 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.metarouter.reactnative">
+  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />


we need this in the sdk now since we are accessing network state, this gets merged with the consuming app's manifest

choudlet · 2026-04-09T16:32:51Z

@@ -0,0 +1,76 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>


objective c implentation

choudlet · 2026-04-09T16:43:11Z

+
+@implementation MetaRouterNetworkMonitor {
+  nw_path_monitor_t _monitor;
+  dispatch_queue_t _monitorQueue;


for iOS we need to set up this queue so _isConnected is only ever read or written from one thread on a time. Objective c concurrency pattern

choudlet · 2026-04-09T16:44:28Z

+
+RCT_EXPORT_MODULE()
+
+ (BOOL)requiresMainQueueSetup {


don't initialize or block main thread while setting up

choudlet · 2026-04-09T16:44:59Z

+  if (self) {
+    _isConnected = YES; // optimistic default
+    _hasListeners = NO;
+    _monitorQueue = dispatch_queue_create("com.metarouter.network.monitor", DISPATCH_QUEUE_SERIAL);


info on the queue: https://en.wikipedia.org/wiki/Grand_Central_Dispatch

choudlet · 2026-04-09T16:50:39Z

+    _monitorQueue = dispatch_queue_create("com.metarouter.network.monitor", DISPATCH_QUEUE_SERIAL);
+    _monitor = nw_path_monitor_create();
+
+    __weak typeof(self) weakSelf = self;


using weak reference here so that this can be properly deallocated

choudlet · 2026-04-09T17:17:20Z

+
+    __weak typeof(self) weakSelf = self;
+    nw_path_monitor_set_update_handler(_monitor, ^(nw_path_t path) {
+      __strong typeof(weakSelf) strongSelf = weakSelf;


if this is nil (so reference was deallocated) then we go ahead and return.

choudlet · 2026-04-09T17:18:07Z

+      __strong typeof(weakSelf) strongSelf = weakSelf;
+      if (!strongSelf) return;
+
+      BOOL connected = (nw_path_get_status(path) == nw_path_status_satisfied);


nw path gives us overall status. not wifi vs. cellular

choudlet · 2026-04-09T17:18:33Z

@@ -1,6 +1,6 @@
-import CircuitBreaker from "./circuitBreaker";


quotes cleanup again

choudlet · 2026-04-09T17:19:21Z

    expect(breaker.nextAllowedAt()).toBe(nowMs + 400);
  });
+
+  describe('reset()', () => {


testing the reset circuit breaker function we added that is utilized with online to offline transitions

choudlet · 2026-04-09T17:21:08Z

+
+  constructor() {
+    try {
+      const { NativeModules, NativeEventEmitter } = require('react-native');


wire up native module

choudlet · 2026-04-09T17:23:24Z

+      // Get initial state from native — skip if a live event already arrived
+      MetaRouterNetworkMonitor.getCurrentStatus()
+        .then((connected: boolean) => {
+          if (this.receivedNativeEvent) return;


if a real event comes through we use that rather than initial state from connection

choudlet · 2026-04-09T17:23:37Z

+  }
+}
+
+export class StubNetworkMonitor implements NetworkReachability {


for testing

choudlet · 2026-04-09T17:25:13Z

  });

+  describe('network awareness', () => {
+    it('events enqueue while offline, no HTTP attempts', async () => {


current behavior, we just queue in memory but will be adding writes to disk based queue in the upcoming story

choudlet · 2026-04-09T17:27:52Z

+      expect(d.getQueueRef().length).toBe(0);
+    });
+
+    it('resetCircuitBreaker() resets circuit state', async () => {


covers case where circuit breaker is set to open (requests are paused), device goes offline, then on state change back online we want to clear state of circuit breaker to enable requests to freely flow.

choudlet · 2026-04-09T17:28:28Z


    const doFlush = async () => {
      while (this.queue.length) {
+        if (!this.opts.isNetworkAvailable()) {


don't make requests while offline 🎊

choudlet · 2026-04-09T17:29:37Z

-  constructor(options: InitOptions) {
+  constructor(
+    options: InitOptions,
+    deps?: { networkMonitor?: NetworkReachability }


DI for testing

choudlet · 2026-04-09T17:30:19Z

  debug?: boolean;
  /** Max bytes (UTF-8) held in memory queue; oldest are dropped once cap is hit (default: 5MB) */
  maxQueueBytes?: number;
+  /** Max events stored on disk during extended offline periods (default: 10000) */


this is just the plumbing for us to start flushing events to disk while offline in next story

choudlet · 2026-04-09T20:20:14Z

+            const wasOffline = this.networkStatus === 'disconnected';
+            this.networkStatus = status;
+
+            if (wasOffline && status === 'connected') {


i'm adding a debounce to this in an upcoming story : sc-37713

brandon-metarouter

Again, left just a few take it or leave it logging related comments.

brandon-metarouter · 2026-04-10T13:56:45Z

+        connectivityManager = try {
+            reactContext.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+        } catch (_: Exception) {
+            null


Log here for debugging or intentionally swallowing exception when setting connectivityManager to null?

brandon-metarouter · 2026-04-10T13:59:30Z

+                val caps = network?.let { cm.getNetworkCapabilities(it) }
+                caps?.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) == true
+            } catch (_: Exception) {
+                true // fallback


Same here, wasn't sure if you wanted to log the exception at lest.

brandon-metarouter · 2026-04-10T14:00:38Z

+                cm.registerNetworkCallback(request, cb)
+                networkCallback = cb
+            } catch (_: SecurityException) {
+                // Missing ACCESS_NETWORK_STATE — fallback to always connected


brandon-metarouter · 2026-04-10T14:02:25Z

+                .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                .emit("onConnectivityChange", params)
+        } catch (_: Exception) {
+            // JS runtime not ready yet — ignore


brandon-metarouter · 2026-04-10T14:05:43Z

+          }
+        })
+        .catch(() => {
+          /* fallback: stay connected */


Again, just Logging checks (if needed)

brandon-metarouter · 2026-04-10T14:06:42Z

+
+  /** Simulate a network transition from tests */
+  simulate(status: NetworkStatus): void {
+    if (status !== this._currentStatus) {


This simulate is checking if (status !== this._currentStatus) 💪

* feat: network reachability monitor + dispatcher integration [rn] Add network connectivity awareness to the React Native SDK so events queue in memory while offline and flush on reconnect. - NetworkMonitor TS wrapper + native bridge modules (iOS NWPathMonitor, Android ConnectivityManager) - CircuitBreaker.reset() clears stale backoff on reconnect - Dispatcher guards flush with isNetworkAvailable() - MetaRouterAnalyticsClient wires network monitor via DI - Add maxOfflineDiskEvents to InitOptions (for PR 2) - Comprehensive tests for all new behavior * fix: review cleaning up race conditions * fix: package naming * fix: adding network monitor logging ---------

choudlet and others added 4 commits April 7, 2026 19:58

Merge branch 'main' into chrish/sc-36910/story-network-reachability-a…

dc22d23

…wareness

fix: review cleaning up race conditions

24119d1

Merge branch 'main' into chrish/sc-36910/story-network-reachability-a…

d859cf0

…wareness

choudlet commented Apr 9, 2026

View reviewed changes

fix: package naming

9c3abf3

choudlet commented Apr 9, 2026

View reviewed changes

choudlet assigned brandon-metarouter, nickmr and SamP692 Apr 9, 2026

choudlet commented Apr 9, 2026

View reviewed changes

choudlet force-pushed the chrish/sc-36910/story-network-reachability-awareness branch from 4ff5823 to 9c3abf3 Compare April 9, 2026 22:02

brandon-metarouter approved these changes Apr 10, 2026

View reviewed changes

fix: adding network monitor logging

602c45d

choudlet merged commit 54dd4a7 into main Apr 10, 2026
2 checks passed

choudlet mentioned this pull request Apr 10, 2026

feat: offline disk overflow and network-aware persistence [rn] #29

Merged

16 tasks


		override fun getName(): String = "MetaRouterNetworkMonitor"

		@Volatile

		@@ -0,0 +1,76 @@
		#import <React/RCTBridgeModule.h>
		#import <React/RCTEventEmitter.h>

		@@ -1,6 +1,6 @@
		import CircuitBreaker from "./circuitBreaker";


		RCT_EXPORT_MODULE()

		+ (BOOL)requiresMainQueueSetup {

Uh oh!

Conversation

choudlet commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key design decisions

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

choudlet Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandon-metarouter left a comment

Choose a reason for hiding this comment

choudlet commented Apr 8, 2026 •

edited

Loading

choudlet Apr 9, 2026 •

edited

Loading