rn-network-quality 0.1.0

package/android/src/main/java/com/rnnetworkquality/NetworkQualityModule.kt

@@ -0,0 +1,287 @@
+package com.rnnetworkquality
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+
+internal class NetworkQualityModule(
+  private val reactContext: ReactApplicationContext,
+) : NativeNetworkQualitySpec(reactContext) {
+  private val lifecycleLock = Any()
+  private val connectivityManager =
+    reactContext.applicationContext.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+  private val snapshotBuilder = SnapshotBuilder(
+    connectivityManager,
+    CellularInfo(reactContext),
+  )
+  private val networkProbe = NetworkProbe(reactContext)
+
+  @Volatile
+  private var invalidated = false
+  private var nextGeneration = 0L
+  private var worker: MonitorRuntime? = null
+
+  override fun getName(): String = NAME
+
+  override fun getCurrentState(promise: Promise) {
+    if (invalidated) {
+      promise.reject(ERROR_STATE_FAILED, "NetworkQuality has been invalidated")
+      return
+    }
+
+    val runtime = synchronized(lifecycleLock) {
+      if (invalidated) {
+        null
+      } else {
+        ensureRuntimeLocked().also { it.pendingSnapshots += 1 }
+      }
+    }
+    if (runtime == null) {
+      promise.reject(ERROR_STATE_FAILED, "NetworkQuality has been invalidated")
+      return
+    }
+
+    if (!runtime.handler.post {
+        try {
+          resolveCurrentState(runtime.monitor, promise)
+        } finally {
+          completeSnapshot(runtime)
+        }
+      }
+    ) {
+      discardUnavailableRuntime(runtime)
+      promise.reject(ERROR_STATE_FAILED, "The network snapshot thread is unavailable")
+    }
+  }
+
+  override fun startMonitoring(options: ReadableMap) {
+    if (invalidated) return
+    val throttleMs = options.readFiniteDouble("throttleMs", DEFAULT_THROTTLE_MS).toLong()
+      .coerceAtLeast(0L)
+    val threshold = options.readFiniteDouble(
+      "bandwidthChangeThresholdPct",
+      DEFAULT_THRESHOLD_PERCENT,
+    ).coerceAtLeast(0.0)
+
+    val request = synchronized(lifecycleLock) {
+      if (invalidated) return
+      val runtime = ensureRuntimeLocked()
+      runtime.monitoring = true
+      runtime.commandVersion += 1
+      StartRequest(runtime, runtime.commandVersion)
+    }
+    if (!request.runtime.handler.post {
+        if (!isCurrentStart(request)) return@post
+        try {
+          if (!request.runtime.monitor.start(throttleMs, threshold)) {
+            completeFailedStart(request)
+          }
+        } catch (error: RuntimeException) {
+          Log.w(TAG, "Unable to start network monitoring", error)
+          try {
+            request.runtime.monitor.stop()
+          } catch (cleanupError: RuntimeException) {
+            Log.w(TAG, "Unable to roll back network monitoring", cleanupError)
+          }
+          completeFailedStart(request)
+        }
+      }
+    ) {
+      discardUnavailableRuntime(request.runtime)
+    }
+  }
+
+  override fun stopMonitoring() {
+    networkProbe.cancelActive()
+    val runtime = synchronized(lifecycleLock) {
+      val current = worker ?: return
+      if (!current.monitoring) return
+      current.monitoring = false
+      current.commandVersion += 1
+      current.stopPending = true
+      current
+    }
+    if (!runtime.handler.post {
+        try {
+          runtime.monitor.stop()
+        } catch (error: RuntimeException) {
+          Log.w(TAG, "Unable to stop network monitoring", error)
+        } finally {
+          completeStop(runtime)
+        }
+      }
+    ) {
+      discardUnavailableRuntime(runtime)
+    }
+  }
+
+  override fun probe(options: ReadableMap, promise: Promise) {
+    if (invalidated) {
+      promise.reject(ERROR_PROBE_FAILED, "NetworkQuality has been invalidated")
+      return
+    }
+    networkProbe.probe(options, promise)
+  }
+
+  override fun invalidate() {
+    val runtime = synchronized(lifecycleLock) {
+      if (invalidated) return
+      invalidated = true
+      worker.also { current ->
+        worker = null
+        current?.monitoring = false
+        current?.stopPending = true
+        current?.commandVersion = (current?.commandVersion ?: 0L) + 1
+      }
+    }
+    networkProbe.invalidate()
+    if (runtime != null) {
+      if (!runtime.handler.post {
+          try {
+            runtime.monitor.stop()
+          } catch (error: RuntimeException) {
+            Log.w(TAG, "Unable to invalidate network monitoring", error)
+          } finally {
+            runtime.thread.quitSafely()
+          }
+        }
+      ) {
+        runtime.thread.quitSafely()
+      }
+    }
+    super.invalidate()
+  }
+
+  /** Called with [lifecycleLock] held. At most one serialized handler exists at a time. */
+  private fun ensureRuntimeLocked(): MonitorRuntime {
+    worker?.let { return it }
+    val generation = ++nextGeneration
+    val thread = HandlerThread(MONITOR_THREAD_NAME).apply { start() }
+    val handler = Handler(thread.looper)
+    val monitor = NetworkMonitor(
+      context = reactContext,
+      connectivityManager = connectivityManager,
+      handler = handler,
+      snapshotBuilder = snapshotBuilder,
+      onSnapshot = { snapshot -> emitSnapshot(generation, snapshot) },
+    )
+    return MonitorRuntime(generation, thread, handler, monitor).also { worker = it }
+  }
+
+  private fun completeSnapshot(runtime: MonitorRuntime) {
+    synchronized(lifecycleLock) {
+      if (runtime.pendingSnapshots > 0) runtime.pendingSnapshots -= 1
+    }
+    releaseIfIdle(runtime)
+  }
+
+  private fun completeStop(runtime: MonitorRuntime) {
+    synchronized(lifecycleLock) {
+      runtime.stopPending = false
+    }
+    releaseIfIdle(runtime)
+  }
+
+  private fun completeFailedStart(request: StartRequest) {
+    synchronized(lifecycleLock) {
+      if (
+        worker === request.runtime &&
+        request.runtime.commandVersion == request.commandVersion
+      ) {
+        request.runtime.monitoring = false
+      }
+    }
+    releaseIfIdle(request.runtime)
+  }
+
+  private fun releaseIfIdle(runtime: MonitorRuntime) {
+    val shouldRelease = synchronized(lifecycleLock) {
+      if (
+        worker === runtime &&
+        !runtime.monitoring &&
+        !runtime.stopPending &&
+        runtime.pendingSnapshots == 0
+      ) {
+        worker = null
+        true
+      } else {
+        false
+      }
+    }
+    if (shouldRelease) runtime.thread.quitSafely()
+  }
+
+  private fun discardUnavailableRuntime(runtime: MonitorRuntime) {
+    synchronized(lifecycleLock) {
+      if (worker === runtime) worker = null
+      runtime.monitoring = false
+      runtime.stopPending = false
+      runtime.pendingSnapshots = 0
+    }
+    runtime.thread.quitSafely()
+  }
+
+  private fun isCurrentStart(request: StartRequest): Boolean = synchronized(lifecycleLock) {
+    !invalidated &&
+      worker === request.runtime &&
+      request.runtime.monitoring &&
+      request.runtime.commandVersion == request.commandVersion
+  }
+
+  private fun resolveCurrentState(monitor: NetworkMonitor, promise: Promise) {
+    try {
+      promise.resolve(monitor.readCurrentSnapshot().toWritableMap())
+    } catch (error: RuntimeException) {
+      promise.reject(ERROR_STATE_FAILED, "Unable to read the current network state", error)
+    }
+  }
+
+  private fun emitSnapshot(generation: Long, snapshot: NetworkSnapshot) {
+    val canEmit = synchronized(lifecycleLock) {
+      !invalidated && worker?.generation == generation && worker?.monitoring == true
+    }
+    if (!canEmit) return
+    try {
+      emitOnNetworkStateChange(snapshot.toWritableMap())
+    } catch (error: RuntimeException) {
+      Log.w(TAG, "Unable to emit a network state update", error)
+    }
+  }
+
+  private fun ReadableMap.readFiniteDouble(key: String, fallback: Double): Double = try {
+    getDouble(key).takeIf { it.isFinite() } ?: fallback
+  } catch (_: RuntimeException) {
+    fallback
+  }
+
+  private class MonitorRuntime(
+    val generation: Long,
+    val thread: HandlerThread,
+    val handler: Handler,
+    val monitor: NetworkMonitor,
+    var monitoring: Boolean = false,
+    var stopPending: Boolean = false,
+    var pendingSnapshots: Int = 0,
+    var commandVersion: Long = 0,
+  )
+
+  private data class StartRequest(
+    val runtime: MonitorRuntime,
+    val commandVersion: Long,
+  )
+
+  companion object {
+    const val NAME = "NetworkQuality"
+    private const val TAG = "RNNetworkQuality"
+    private const val MONITOR_THREAD_NAME = "RNNetworkQuality"
+    private const val DEFAULT_THROTTLE_MS = 1_000.0
+    private const val DEFAULT_THRESHOLD_PERCENT = 10.0
+    private const val ERROR_STATE_FAILED = "E_PROBE_FAILED"
+    private const val ERROR_PROBE_FAILED = "E_PROBE_FAILED"
+  }
+}

package/android/src/main/java/com/rnnetworkquality/NetworkQualityPackage.kt

@@ -0,0 +1,25 @@
+package com.rnnetworkquality
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class NetworkQualityPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+    if (name == NetworkQualityModule.NAME) NetworkQualityModule(reactContext) else null
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider {
+    mapOf(
+      NetworkQualityModule.NAME to ReactModuleInfo(
+        name = NetworkQualityModule.NAME,
+        className = NetworkQualityModule::class.java.name,
+        canOverrideExistingModule = false,
+        needsEagerInit = false,
+        isCxxModule = false,
+        isTurboModule = true,
+      )
+    )
+  }
+}

package/android/src/main/java/com/rnnetworkquality/NetworkSnapshot.kt

@@ -0,0 +1,83 @@
+package com.rnnetworkquality
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+
+/** A complete point-in-time view of Android's default network. */
+internal data class NetworkSnapshot(
+  val isConnected: Boolean,
+  val isValidated: Boolean?,
+  val isCaptivePortal: Boolean?,
+  val transport: String,
+  val isVpn: Boolean?,
+  val isExpensive: Boolean,
+  val isConstrained: Boolean,
+  val isRoaming: Boolean?,
+  val downlinkKbps: Int?,
+  val uplinkKbps: Int?,
+  val signalStrength: Int?,
+  val cellularGeneration: String?,
+  val supportsIPv4: Boolean?,
+  val supportsIPv6: Boolean?,
+  val supportsDNS: Boolean?,
+  val unsatisfiedReason: String?,
+  val timestamp: Long,
+) {
+  fun equalsIgnoringTimestamp(other: NetworkSnapshot): Boolean =
+    copy(timestamp = other.timestamp) == other
+
+  fun toWritableMap(): WritableMap = Arguments.createMap().apply {
+    putBoolean("isConnected", isConnected)
+    putNullableBoolean("isValidated", isValidated)
+    putNullableBoolean("isCaptivePortal", isCaptivePortal)
+    putString("transport", transport)
+    putNullableBoolean("isVpn", isVpn)
+    putBoolean("isExpensive", isExpensive)
+    putBoolean("isConstrained", isConstrained)
+    putNullableBoolean("isRoaming", isRoaming)
+    putNullableNumber("downlinkKbps", downlinkKbps)
+    putNullableNumber("uplinkKbps", uplinkKbps)
+    putNullableNumber("signalStrength", signalStrength)
+    putNullableString("cellularGeneration", cellularGeneration)
+    putNullableBoolean("supportsIPv4", supportsIPv4)
+    putNullableBoolean("supportsIPv6", supportsIPv6)
+    putNullableBoolean("supportsDNS", supportsDNS)
+    putNullableString("unsatisfiedReason", unsatisfiedReason)
+    putDouble("timestamp", timestamp.toDouble())
+  }
+
+  private fun WritableMap.putNullableBoolean(key: String, value: Boolean?) {
+    if (value == null) putNull(key) else putBoolean(key, value)
+  }
+
+  private fun WritableMap.putNullableNumber(key: String, value: Int?) {
+    if (value == null) putNull(key) else putDouble(key, value.toDouble())
+  }
+
+  private fun WritableMap.putNullableString(key: String, value: String?) {
+    if (value == null) putNull(key) else putString(key, value)
+  }
+
+  companion object {
+    fun disconnected(timestamp: Long, isConstrained: Boolean): NetworkSnapshot =
+      NetworkSnapshot(
+        isConnected = false,
+        isValidated = false,
+        isCaptivePortal = false,
+        transport = "none",
+        isVpn = false,
+        isExpensive = false,
+        isConstrained = isConstrained,
+        isRoaming = null,
+        downlinkKbps = null,
+        uplinkKbps = null,
+        signalStrength = null,
+        cellularGeneration = null,
+        supportsIPv4 = null,
+        supportsIPv6 = null,
+        supportsDNS = null,
+        unsatisfiedReason = null,
+        timestamp = timestamp,
+      )
+  }
+}

package/android/src/main/java/com/rnnetworkquality/SnapshotBuilder.kt

@@ -0,0 +1,92 @@
+package com.rnnetworkquality
+
+import android.net.ConnectivityManager
+import android.net.LinkProperties
+import android.net.Network
+import android.net.NetworkCapabilities
+import android.os.Build
+import java.net.Inet4Address
+import java.net.Inet6Address
+
+/** Converts Android connectivity primitives into the cross-platform snapshot contract. */
+internal class SnapshotBuilder(
+  private val connectivityManager: ConnectivityManager,
+  private val cellularInfo: CellularInfo,
+) {
+  fun build(
+    network: Network?,
+    capabilities: NetworkCapabilities?,
+    linkProperties: LinkProperties?,
+    timestamp: Long = System.currentTimeMillis(),
+  ): NetworkSnapshot {
+    if (network == null || capabilities == null) {
+      return NetworkSnapshot.disconnected(timestamp, isConstrained())
+    }
+
+    val hasWifi = capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)
+    val hasCellular = capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR)
+    val hasEthernet = capabilities.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET)
+    val hasUsb =
+      Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
+        capabilities.hasTransport(NetworkCapabilities.TRANSPORT_USB)
+    val hasBluetooth = capabilities.hasTransport(NetworkCapabilities.TRANSPORT_BLUETOOTH)
+    val hasVpn = capabilities.hasTransport(NetworkCapabilities.TRANSPORT_VPN)
+    val transportMapping = Mappers.mapTransport(
+      hasNetwork = true,
+      hasWifi = hasWifi,
+      hasCellular = hasCellular,
+      hasEthernet = hasEthernet,
+      hasUsb = hasUsb,
+      hasBluetooth = hasBluetooth,
+      hasVpn = hasVpn,
+    )
+
+    val temporarilyNotMetered =
+      Build.VERSION.SDK_INT >= Build.VERSION_CODES.R &&
+        capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_TEMPORARILY_NOT_METERED)
+    val isExpensive =
+      !capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED) &&
+        !temporarilyNotMetered
+
+    val downlink = capabilities.linkDownstreamBandwidthKbps.takeIf { it > 0 }
+    val uplink = capabilities.linkUpstreamBandwidthKbps.takeIf { it > 0 }
+    val signal = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+      capabilities.signalStrength.takeUnless {
+        it == NetworkCapabilities.SIGNAL_STRENGTH_UNSPECIFIED
+      }
+    } else {
+      null
+    }
+
+    return NetworkSnapshot(
+      isConnected = capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET),
+      isValidated = capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED),
+      isCaptivePortal = capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_CAPTIVE_PORTAL),
+      transport = transportMapping.transport,
+      isVpn = transportMapping.isVpn,
+      isExpensive = isExpensive,
+      isConstrained = isConstrained(),
+      isRoaming = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+        !capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_ROAMING)
+      } else {
+        null
+      },
+      downlinkKbps = downlink,
+      uplinkKbps = uplink,
+      signalStrength = signal,
+      cellularGeneration = cellularInfo.generation(transportMapping.transport == "cellular"),
+      supportsIPv4 = linkProperties?.linkAddresses?.any { it.address is Inet4Address },
+      supportsIPv6 = linkProperties?.linkAddresses?.any { it.address is Inet6Address },
+      supportsDNS = linkProperties?.dnsServers?.isNotEmpty(),
+      unsatisfiedReason = null,
+      timestamp = timestamp,
+    )
+  }
+
+  fun isConstrained(): Boolean = try {
+    connectivityManager.restrictBackgroundStatus ==
+      ConnectivityManager.RESTRICT_BACKGROUND_STATUS_ENABLED
+  } catch (_: RuntimeException) {
+    false
+  }
+}

package/android/src/main/java/com/rnnetworkquality/Throttler.kt

@@ -0,0 +1,100 @@
+package com.rnnetworkquality
+
+internal fun interface Cancellable {
+  fun cancel()
+}
+
+internal fun interface Clock {
+  fun nowMs(): Long
+}
+
+internal fun interface Scheduler {
+  fun schedule(delayMs: Long, task: () -> Unit): Cancellable
+}
+
+/**
+ * De-duplicates snapshots and applies leading/trailing throttling to minor signal changes.
+ * All calls must be serialized by the owner; the class itself has no platform dependencies.
+ */
+internal class Throttler(
+  private val clock: Clock,
+  private val scheduler: Scheduler,
+  private val emit: (NetworkSnapshot) -> Unit,
+  throttleMs: Long,
+  bandwidthChangeThresholdPct: Double,
+) {
+  private var throttleMs = throttleMs.coerceAtLeast(0L)
+  private var bandwidthChangeThresholdPct = bandwidthChangeThresholdPct.coerceAtLeast(0.0)
+  private var lastEmitted: NetworkSnapshot? = null
+  private var lastEmitTime = 0L
+  private var pending: NetworkSnapshot? = null
+  private var timer: Cancellable? = null
+
+  fun updateOptions(throttleMs: Long, bandwidthChangeThresholdPct: Double) {
+    this.throttleMs = throttleMs.coerceAtLeast(0L)
+    this.bandwidthChangeThresholdPct = bandwidthChangeThresholdPct.coerceAtLeast(0.0)
+
+    val latestPending = pending ?: return
+    cancelPending()
+    submit(latestPending)
+  }
+
+  fun submit(snapshot: NetworkSnapshot) {
+    val previous = lastEmitted
+    if (previous == null) {
+      emitNow(snapshot)
+      return
+    }
+
+    if (snapshot.equalsIgnoringTimestamp(previous)) {
+      cancelPending()
+      return
+    }
+
+    if (Mappers.isSignificantChange(previous, snapshot)) {
+      cancelPending()
+      emitNow(snapshot)
+      return
+    }
+
+    if (!Mappers.exceedsAnyMinorThreshold(previous, snapshot, bandwidthChangeThresholdPct)) {
+      cancelPending()
+      return
+    }
+
+    val elapsed = (clock.nowMs() - lastEmitTime).coerceAtLeast(0L)
+    if (elapsed >= throttleMs) {
+      cancelPending()
+      emitNow(snapshot)
+      return
+    }
+
+    pending = snapshot
+    if (timer == null) {
+      timer = scheduler.schedule(throttleMs - elapsed) {
+        timer = null
+        val trailing = pending
+        pending = null
+        if (trailing != null) emitNow(trailing)
+      }
+    }
+  }
+
+  fun reset() {
+    cancelPending()
+    lastEmitted = null
+    lastEmitTime = 0L
+  }
+
+  private fun emitNow(snapshot: NetworkSnapshot) {
+    lastEmitted = snapshot
+    lastEmitTime = clock.nowMs()
+    emit(snapshot)
+  }
+
+  private fun cancelPending() {
+    timer?.cancel()
+    timer = null
+    pending = null
+  }
+}

package/ios/CellularInfo.swift

@@ -0,0 +1,47 @@
+import CoreTelephony
+import Foundation
+
+final class CellularInfo {
+  private let networkInfo = CTTelephonyNetworkInfo()
+
+  func generation(isCellular: Bool) -> String? {
+    guard isCellular else { return nil }
+
+    let technology: String?
+    if #available(iOS 12.0, *) {
+      guard let serviceIdentifier = networkInfo.dataServiceIdentifier else {
+        return nil
+      }
+      technology = networkInfo.serviceCurrentRadioAccessTechnology?[serviceIdentifier]
+    } else {
+      technology = networkInfo.currentRadioAccessTechnology
+    }
+
+    guard let technology else { return nil }
+    return Self.map(technology)
+  }
+
+  private static func map(_ technology: String) -> String? {
+    switch technology {
+    case CTRadioAccessTechnologyGPRS,
+      CTRadioAccessTechnologyEdge,
+      CTRadioAccessTechnologyCDMA1x:
+      return "2g"
+    case CTRadioAccessTechnologyWCDMA,
+      CTRadioAccessTechnologyHSDPA,
+      CTRadioAccessTechnologyHSUPA,
+      CTRadioAccessTechnologyCDMAEVDORev0,
+      CTRadioAccessTechnologyCDMAEVDORevA,
+      CTRadioAccessTechnologyCDMAEVDORevB,
+      CTRadioAccessTechnologyeHRPD:
+      return "3g"
+    case CTRadioAccessTechnologyLTE:
+      return "4g"
+    case CTRadioAccessTechnologyNR,
+      CTRadioAccessTechnologyNRNSA:
+      return "5g"
+    default:
+      return nil
+    }
+  }
+}