rn-network-quality 0.1.0

package/android/build.gradle

@@ -0,0 +1,60 @@
+buildscript {
+  ext.RNNetworkQuality = [
+    kotlinVersion: "2.2.0",
+    minSdkVersion: 24,
+    compileSdkVersion: 37
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return RNNetworkQuality[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:9.2.1"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+
+if (project.extensions.findByName("kotlin") == null) {
+  apply plugin: "kotlin-android"
+}
+
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.rnnetworkquality"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  testOptions {
+    unitTests.returnDefaultValues = true
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  testImplementation "junit:junit:4.13.2"
+}

package/android/src/main/AndroidManifest.xml

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

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

@@ -0,0 +1,34 @@
+package com.rnnetworkquality
+
+import android.Manifest
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.pm.PackageManager
+import android.telephony.TelephonyManager
+import androidx.core.content.ContextCompat
+
+/** Reads optional cellular generation only when the host app granted phone-state access. */
+internal class CellularInfo(context: Context) {
+  private val appContext = context.applicationContext
+  private val telephonyManager =
+    appContext.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+
+  @SuppressLint("MissingPermission")
+  fun generation(isCellular: Boolean): String? {
+    if (!isCellular || telephonyManager == null) return null
+    if (
+      ContextCompat.checkSelfPermission(appContext, Manifest.permission.READ_PHONE_STATE) !=
+      PackageManager.PERMISSION_GRANTED
+    ) {
+      return null
+    }
+
+    return try {
+      Mappers.mapCellularGeneration(telephonyManager.dataNetworkType)
+    } catch (_: SecurityException) {
+      null
+    } catch (_: RuntimeException) {
+      null
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+package com.rnnetworkquality
+
+internal object DownloadPolicy {
+  const val MINIMUM_BYTES = 64 * 1_024L
+  const val MINIMUM_DURATION_MS = 100.0
+
+  fun shouldStop(
+    bytesReceived: Long,
+    elapsedMs: Double,
+    maximumBytes: Long,
+    maximumDurationMs: Long,
+  ): Boolean = bytesReceived >= maximumBytes || elapsedMs >= maximumDurationMs
+
+  fun measurementError(bytesReceived: Long, elapsedMs: Double): String? = when {
+    bytesReceived < MINIMUM_BYTES -> "too-little-data"
+    elapsedMs < MINIMUM_DURATION_MS -> "too-fast-to-measure"
+    else -> null
+  }
+
+  fun throughputKbps(bytesReceived: Long, elapsedMs: Double): Double? =
+    if (measurementError(bytesReceived, elapsedMs) == null) {
+      bytesReceived * 8.0 / elapsedMs
+    } else {
+      null
+    }
+}

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

@@ -0,0 +1,106 @@
+package com.rnnetworkquality
+
+import kotlin.math.abs
+
+/** Pure platform-value mappings shared by the Android implementation and JVM tests. */
+internal object Mappers {
+  data class TransportMapping(
+    val transport: String,
+    val isVpn: Boolean,
+  )
+
+  fun mapTransport(
+    hasNetwork: Boolean,
+    hasWifi: Boolean,
+    hasCellular: Boolean,
+    hasEthernet: Boolean,
+    hasUsb: Boolean,
+    hasBluetooth: Boolean,
+    hasVpn: Boolean,
+  ): TransportMapping {
+    val transport = when {
+      !hasNetwork -> "none"
+      hasWifi -> "wifi"
+      hasCellular -> "cellular"
+      hasEthernet || hasUsb -> "ethernet"
+      hasBluetooth -> "bluetooth"
+      hasVpn -> "vpn"
+      else -> "other"
+    }
+    return TransportMapping(
+      transport = transport,
+      isVpn = hasNetwork && hasVpn,
+    )
+  }
+
+  /** Maps TelephonyManager.NETWORK_TYPE_* integer values without Android dependencies. */
+  fun mapCellularGeneration(networkType: Int): String? = when (networkType) {
+    1, // GPRS
+    2, // EDGE
+    4, // CDMA
+    7, // 1xRTT
+    11, // IDEN
+    16, // GSM
+    -> "2g"
+
+    3, // UMTS
+    5, // EVDO_0
+    6, // EVDO_A
+    8, // HSDPA
+    9, // HSUPA
+    10, // HSPA
+    12, // EVDO_B
+    14, // EHRPD
+    15, // HSPAP
+    17, // TD_SCDMA
+    -> "3g"
+
+    13, // LTE
+    18, // IWLAN
+    -> "4g"
+
+    20, // NR
+    -> "5g"
+
+    else -> null
+  }
+
+  fun isSignificantChange(
+    previous: NetworkSnapshot?,
+    current: NetworkSnapshot,
+  ): Boolean {
+    if (previous == null) return true
+
+    return previous.isConnected != current.isConnected ||
+      previous.isValidated != current.isValidated ||
+      previous.isCaptivePortal != current.isCaptivePortal ||
+      previous.transport != current.transport ||
+      previous.isVpn != current.isVpn ||
+      previous.isExpensive != current.isExpensive ||
+      previous.isConstrained != current.isConstrained ||
+      previous.isRoaming != current.isRoaming ||
+      previous.cellularGeneration != current.cellularGeneration ||
+      previous.supportsIPv4 != current.supportsIPv4 ||
+      previous.supportsIPv6 != current.supportsIPv6 ||
+      previous.supportsDNS != current.supportsDNS ||
+      previous.unsatisfiedReason != current.unsatisfiedReason
+  }
+
+  fun exceedsThreshold(oldValue: Int?, newValue: Int?, thresholdPct: Double): Boolean {
+    if (oldValue == newValue) return false
+    if (oldValue == null || newValue == null) return true
+    if (oldValue == 0) return newValue != 0
+
+    val percentChange = abs(newValue.toDouble() - oldValue) / abs(oldValue.toDouble()) * 100.0
+    return percentChange >= thresholdPct.coerceAtLeast(0.0)
+  }
+
+  fun exceedsAnyMinorThreshold(
+    previous: NetworkSnapshot,
+    current: NetworkSnapshot,
+    thresholdPct: Double,
+  ): Boolean =
+    exceedsThreshold(previous.downlinkKbps, current.downlinkKbps, thresholdPct) ||
+      exceedsThreshold(previous.uplinkKbps, current.uplinkKbps, thresholdPct) ||
+      exceedsThreshold(previous.signalStrength, current.signalStrength, thresholdPct)
+}

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

@@ -0,0 +1,263 @@
+package com.rnnetworkquality
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.net.ConnectivityManager
+import android.net.LinkProperties
+import android.net.Network
+import android.net.NetworkCapabilities
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.core.content.ContextCompat
+
+/** Owns the event-driven default-network callback and Data Saver receiver. */
+internal class NetworkMonitor(
+  context: Context,
+  private val connectivityManager: ConnectivityManager,
+  private val handler: Handler,
+  private val snapshotBuilder: SnapshotBuilder,
+  onSnapshot: (NetworkSnapshot) -> Unit,
+) {
+  private val appContext = context.applicationContext
+  private val throttler = Throttler(
+    clock = Clock { android.os.SystemClock.elapsedRealtime() },
+    scheduler = HandlerScheduler(handler),
+    emit = onSnapshot,
+    throttleMs = DEFAULT_THROTTLE_MS,
+    bandwidthChangeThresholdPct = DEFAULT_THRESHOLD_PERCENT,
+  )
+
+  private var running = false
+  private var callbackRegistered = false
+  private var receiverRegistered = false
+  private var latestNetwork: Network? = null
+  private var latestCapabilities: NetworkCapabilities? = null
+  private var latestLinkProperties: LinkProperties? = null
+
+  private val networkCallback = object : ConnectivityManager.NetworkCallback() {
+    override fun onAvailable(network: Network) = dispatch {
+      if (!running || currentActiveNetwork() != network) return@dispatch
+      latestNetwork = network
+      latestCapabilities = safeCapabilities(network)
+      latestLinkProperties = safeLinkProperties(network)
+      rebuildSnapshot()
+    }
+
+    override fun onCapabilitiesChanged(network: Network, capabilities: NetworkCapabilities) =
+      dispatch {
+        if (!running || currentActiveNetwork() != network) return@dispatch
+        if (latestNetwork != network) {
+          latestNetwork = network
+          latestLinkProperties = safeLinkProperties(network)
+        }
+        latestCapabilities = capabilities
+        rebuildSnapshot()
+      }
+
+    override fun onLinkPropertiesChanged(network: Network, linkProperties: LinkProperties) =
+      dispatch {
+        if (!running || currentActiveNetwork() != network) return@dispatch
+        if (latestNetwork != network) {
+          latestNetwork = network
+          latestCapabilities = safeCapabilities(network)
+        }
+        latestLinkProperties = linkProperties
+        rebuildSnapshot()
+      }
+
+    override fun onLost(network: Network) = dispatch {
+      if (!running || (latestNetwork != null && latestNetwork != network)) return@dispatch
+      val activeNetwork = currentActiveNetwork()
+      if (activeNetwork != null && activeNetwork != network) {
+        refreshFromSystem()
+        return@dispatch
+      }
+      latestNetwork = null
+      latestCapabilities = null
+      latestLinkProperties = null
+      throttler.submit(
+        NetworkSnapshot.disconnected(
+          timestamp = System.currentTimeMillis(),
+          isConstrained = snapshotBuilder.isConstrained(),
+        )
+      )
+    }
+
+    override fun onBlockedStatusChanged(network: Network, blocked: Boolean) = dispatch {
+      if (!running || currentActiveNetwork() != network) return@dispatch
+      refreshFromSystem()
+    }
+  }
+
+  private val dataSaverReceiver = object : BroadcastReceiver() {
+    override fun onReceive(context: Context?, intent: Intent?) {
+      if (intent?.action == ConnectivityManager.ACTION_RESTRICT_BACKGROUND_CHANGED) {
+        dispatch {
+          if (running) refreshFromSystem()
+        }
+      }
+    }
+  }
+
+  fun start(throttleMs: Long, bandwidthChangeThresholdPct: Double): Boolean {
+    checkHandlerThread()
+    throttler.updateOptions(throttleMs, bandwidthChangeThresholdPct)
+    if (running) return true
+
+    throttler.reset()
+    running = true
+    if (!registerNetworkCallback()) {
+      refreshFromSystem()
+      running = false
+      return false
+    }
+    if (!registerDataSaverReceiver()) {
+      unregisterNetworkCallback()
+      refreshFromSystem()
+      running = false
+      return false
+    }
+    refreshFromSystem()
+    return true
+  }
+
+  fun stop() {
+    checkHandlerThread()
+    running = false
+    unregisterNetworkCallback()
+    unregisterDataSaverReceiver()
+    latestNetwork = null
+    latestCapabilities = null
+    latestLinkProperties = null
+    throttler.reset()
+  }
+
+  /** Must be called on the monitor handler. Reads current state even when monitoring is stopped. */
+  fun readCurrentSnapshot(): NetworkSnapshot {
+    checkHandlerThread()
+    val network = currentActiveNetwork()
+    return snapshotBuilder.build(
+      network = network,
+      capabilities = network?.let(::safeCapabilities),
+      linkProperties = network?.let(::safeLinkProperties),
+    )
+  }
+
+  private fun registerNetworkCallback(): Boolean = try {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      connectivityManager.registerDefaultNetworkCallback(networkCallback, handler)
+    } else {
+      connectivityManager.registerDefaultNetworkCallback(networkCallback)
+    }
+    callbackRegistered = true
+    true
+  } catch (error: RuntimeException) {
+    callbackRegistered = false
+    Log.w(TAG, "Unable to register default-network callback", error)
+    false
+  }
+
+  private fun registerDataSaverReceiver(): Boolean = try {
+    ContextCompat.registerReceiver(
+      appContext,
+      dataSaverReceiver,
+      IntentFilter(ConnectivityManager.ACTION_RESTRICT_BACKGROUND_CHANGED),
+      ContextCompat.RECEIVER_NOT_EXPORTED,
+    )
+    receiverRegistered = true
+    true
+  } catch (error: RuntimeException) {
+    receiverRegistered = false
+    Log.w(TAG, "Unable to register Data Saver receiver", error)
+    false
+  }
+
+  private fun unregisterNetworkCallback() {
+    if (!callbackRegistered) return
+    try {
+      connectivityManager.unregisterNetworkCallback(networkCallback)
+    } catch (error: RuntimeException) {
+      Log.w(TAG, "Unable to unregister default-network callback", error)
+    } finally {
+      callbackRegistered = false
+    }
+  }
+
+  private fun unregisterDataSaverReceiver() {
+    if (!receiverRegistered) return
+    try {
+      appContext.unregisterReceiver(dataSaverReceiver)
+    } catch (error: RuntimeException) {
+      Log.w(TAG, "Unable to unregister Data Saver receiver", error)
+    } finally {
+      receiverRegistered = false
+    }
+  }
+
+  private fun refreshFromSystem() {
+    val network = currentActiveNetwork()
+    latestNetwork = network
+    latestCapabilities = network?.let(::safeCapabilities)
+    latestLinkProperties = network?.let(::safeLinkProperties)
+    rebuildSnapshot()
+  }
+
+  private fun rebuildSnapshot() {
+    throttler.submit(
+      snapshotBuilder.build(
+        network = latestNetwork,
+        capabilities = latestCapabilities,
+        linkProperties = latestLinkProperties,
+      )
+    )
+  }
+
+  private fun safeCapabilities(network: Network): NetworkCapabilities? = try {
+    connectivityManager.getNetworkCapabilities(network)
+  } catch (error: RuntimeException) {
+    Log.w(TAG, "Unable to read network capabilities", error)
+    null
+  }
+
+  private fun safeLinkProperties(network: Network): LinkProperties? = try {
+    connectivityManager.getLinkProperties(network)
+  } catch (error: RuntimeException) {
+    Log.w(TAG, "Unable to read link properties", error)
+    null
+  }
+
+  private fun currentActiveNetwork(): Network? = try {
+    connectivityManager.activeNetwork
+  } catch (error: RuntimeException) {
+    Log.w(TAG, "Unable to read the active network", error)
+    null
+  }
+
+  private fun dispatch(block: () -> Unit) {
+    if (Looper.myLooper() == handler.looper) block() else handler.post(block)
+  }
+
+  private fun checkHandlerThread() {
+    check(Looper.myLooper() == handler.looper) {
+      "NetworkMonitor must only be accessed from its handler thread"
+    }
+  }
+
+  private class HandlerScheduler(private val handler: Handler) : Scheduler {
+    override fun schedule(delayMs: Long, task: () -> Unit): Cancellable {
+      val runnable = Runnable(task)
+      handler.postDelayed(runnable, delayMs.coerceAtLeast(0L))
+      return Cancellable { handler.removeCallbacks(runnable) }
+    }
+  }
+
+  companion object {
+    private const val TAG = "RNNetworkQuality"
+    private const val DEFAULT_THROTTLE_MS = 1_000L
+    private const val DEFAULT_THRESHOLD_PERCENT = 10.0
+  }
+}