rn-network-quality 0.1.0

package/ios/NetworkQualityImpl.swift

@@ -0,0 +1,371 @@
+import Foundation
+import Network
+
+private enum PathLookupResult {
+  case path(NWPath)
+  case timedOut
+  case cancelled
+}
+
+@objc(NetworkQualityImpl)
+public final class NetworkQualityImpl: NSObject {
+  @objc public var onChange: (([String: Any]) -> Void)?
+
+  private let queue = DispatchQueue(label: "com.rnnetworkquality.monitor")
+  private let queueKey = DispatchSpecificKey<UInt8>()
+  private let cellularInfo = CellularInfo()
+  private var monitor: NWPathMonitor?
+  private var throttler: Throttler?
+  private var latestSnapshot: [String: Any]?
+  private var activeProbes: [UUID: NetworkProbe] = [:]
+  private var activeOneShots: [UUID: OneShotRequest] = [:]
+  private var invalidated = false
+
+  public override init() {
+    super.init()
+    queue.setSpecific(key: queueKey, value: 1)
+  }
+
+  @objc(getCurrentStateWithResolve:reject:)
+  public func getCurrentState(
+    resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    queue.async { [weak self] in
+      guard let self else { return }
+      guard !invalidated else {
+        reject("E_PROBE_FAILED", "NetworkQuality has been invalidated.", nil)
+        return
+      }
+      if let monitor {
+        let snapshot = latestSnapshot
+          ?? PathSnapshot.make(path: monitor.currentPath, cellularInfo: cellularInfo)
+        latestSnapshot = snapshot
+        resolve(snapshot)
+        return
+      }
+
+      withOneShotPath(timeoutMs: 2_000) { [weak self] result in
+        guard let self else { return }
+        switch result {
+        case let .path(path):
+          resolve(PathSnapshot.make(path: path, cellularInfo: cellularInfo))
+        case .timedOut:
+          resolve(PathSnapshot.unknownDisconnected())
+        case .cancelled:
+          reject(
+            "E_PROBE_FAILED",
+            "The network state request was cancelled because monitoring stopped.",
+            nil
+          )
+        }
+      }
+    }
+  }
+
+  @objc(startMonitoringWithThrottleMs:bandwidthChangeThresholdPct:)
+  public func startMonitoring(
+    throttleMs: NSNumber,
+    bandwidthChangeThresholdPct: NSNumber
+  ) {
+    queue.async { [weak self] in
+      guard let self else { return }
+      guard !invalidated else { return }
+      let throttle = max(0, throttleMs.doubleValue)
+      let threshold = max(0, bandwidthChangeThresholdPct.doubleValue)
+
+      if let throttler {
+        throttler.update(
+          throttleMs: throttle,
+          bandwidthChangeThresholdPct: threshold
+        )
+      } else {
+        throttler = makeThrottler(
+          throttleMs: throttle,
+          bandwidthChangeThresholdPct: threshold
+        )
+      }
+
+      guard monitor == nil else { return }
+      let pathMonitor = NWPathMonitor()
+      monitor = pathMonitor
+      pathMonitor.pathUpdateHandler = { [weak self] path in
+        self?.handle(path: path)
+      }
+      pathMonitor.start(queue: queue)
+      handle(path: pathMonitor.currentPath)
+    }
+  }
+
+  @objc public func stopMonitoring() {
+    queue.async { [weak self] in
+      self?.stopMonitoringOnQueue()
+    }
+  }
+
+  @objc(probeWithLatencyUrl:downloadUrl:latencySamples:timeoutMs:downloadMaxDurationMs:downloadMaxBytes:resolve:reject:)
+  public func probe(
+    latencyUrl: String,
+    downloadUrl: String?,
+    latencySamples: NSNumber,
+    timeoutMs: NSNumber,
+    downloadMaxDurationMs: NSNumber,
+    downloadMaxBytes: NSNumber,
+    resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String?, String?, Error?) -> Void
+  ) {
+    let probeStartedAt = NetworkProbe.monotonicMilliseconds()
+    guard let latencyURL = NetworkProbe.validatedURL(latencyUrl) else {
+      reject("E_INVALID_URL", "latencyUrl must be a valid HTTP or HTTPS URL.", nil)
+      return
+    }
+
+    let downloadURL: URL?
+    if let downloadUrl {
+      guard let validated = NetworkProbe.validatedURL(downloadUrl) else {
+        reject("E_INVALID_URL", "downloadUrl must be a valid HTTP or HTTPS URL.", nil)
+        return
+      }
+      downloadURL = validated
+    } else {
+      downloadURL = nil
+    }
+
+    let latencySampleValue = latencySamples.doubleValue
+    guard
+      latencySampleValue.isFinite,
+      latencySampleValue.rounded(.towardZero) == latencySampleValue,
+      latencySampleValue >= 1,
+      latencySampleValue <= 100
+    else {
+      reject(
+        "E_PROBE_FAILED",
+        "latencySamples must be an integer between 1 and 100.",
+        nil
+      )
+      return
+    }
+    let timeoutValue = timeoutMs.doubleValue
+    guard timeoutValue.isFinite, timeoutValue > 0, timeoutValue <= 2_147_483_647
+    else {
+      reject(
+        "E_PROBE_FAILED",
+        "timeoutMs must be greater than 0 and at most 2147483647.",
+        nil
+      )
+      return
+    }
+    let downloadMaxDurationValue = downloadMaxDurationMs.doubleValue
+    guard
+      downloadMaxDurationValue.isFinite,
+      downloadMaxDurationValue > 0,
+      downloadMaxDurationValue <= 2_147_483_647
+    else {
+      reject(
+        "E_PROBE_FAILED",
+        "downloadMaxDurationMs must be greater than 0 and at most 2147483647.",
+        nil
+      )
+      return
+    }
+    let downloadMaxBytesValue = downloadMaxBytes.doubleValue
+    guard
+      downloadMaxBytesValue.isFinite,
+      downloadMaxBytesValue.rounded(.towardZero) == downloadMaxBytesValue,
+      downloadMaxBytesValue > 0,
+      downloadMaxBytesValue <= 2_147_483_647
+    else {
+      reject(
+        "E_PROBE_FAILED",
+        "downloadMaxBytes must be an integer between 1 and 2147483647.",
+        nil
+      )
+      return
+    }
+
+    queue.async { [weak self] in
+      guard let self else { return }
+      guard !invalidated else {
+        reject("E_PROBE_FAILED", "NetworkQuality has been invalidated.", nil)
+        return
+      }
+      let pathBudgetMs = timeoutValue
+        - (NetworkProbe.monotonicMilliseconds() - probeStartedAt)
+      guard pathBudgetMs > 0 else {
+        reject("E_PROBE_TIMEOUT", "The network path check exceeded the probe timeout.", nil)
+        return
+      }
+      currentPath(timeoutMs: pathBudgetMs) { [weak self] result in
+        guard let self else { return }
+        guard !invalidated else {
+          reject("E_PROBE_FAILED", "NetworkQuality has been invalidated.", nil)
+          return
+        }
+
+        let path: NWPath
+        switch result {
+        case let .path(value):
+          path = value
+        case .timedOut:
+          reject(
+            "E_PROBE_TIMEOUT",
+            "The network path check exceeded the probe timeout.",
+            nil
+          )
+          return
+        case .cancelled:
+          reject("E_PROBE_FAILED", "The network probe was cancelled.", nil)
+          return
+        }
+
+        guard
+          NetworkProbe.monotonicMilliseconds() - probeStartedAt < timeoutValue
+        else {
+          reject("E_PROBE_TIMEOUT", "The network path check exceeded the probe timeout.", nil)
+          return
+        }
+        guard path.status == .satisfied else {
+          reject("E_OFFLINE", "No connected network is available for probing.", nil)
+          return
+        }
+
+        let identifier = UUID()
+        let networkProbe = NetworkProbe(
+          latencyURL: latencyURL,
+          downloadURL: downloadURL,
+          latencySamples: Int(latencySampleValue),
+          timeoutMs: timeoutValue,
+          downloadMaxDurationMs: downloadMaxDurationValue,
+          downloadMaxBytes: Int(downloadMaxBytesValue),
+          startedAt: probeStartedAt
+        ) { [weak self] result in
+          self?.queue.async {
+            self?.activeProbes.removeValue(forKey: identifier)
+          }
+          switch result {
+          case let .success(value):
+            resolve(value)
+          case let .failure(failure):
+            reject(failure.code, failure.message, failure.error)
+          }
+        }
+        activeProbes[identifier] = networkProbe
+        networkProbe.start()
+      }
+    }
+  }
+
+  @objc public func invalidate() {
+    performSynchronouslyOnQueue { [weak self] in
+      guard let self else { return }
+      guard !invalidated else { return }
+      invalidated = true
+      stopMonitoringOnQueue()
+      onChange = nil
+    }
+  }
+
+  private func makeThrottler(
+    throttleMs: Double,
+    bandwidthChangeThresholdPct: Double
+  ) -> Throttler {
+    Throttler(
+      throttleMs: throttleMs,
+      bandwidthChangeThresholdPct: bandwidthChangeThresholdPct,
+      clock: {
+        Double(DispatchTime.now().uptimeNanoseconds) / 1_000_000
+      },
+      scheduler: { [weak self] delayMs, action in
+        let item = DispatchWorkItem(block: action)
+        self?.queue.asyncAfter(deadline: .now() + delayMs / 1_000, execute: item)
+        return item
+      },
+      emit: { [weak self] snapshot in
+        self?.onChange?(snapshot)
+      }
+    )
+  }
+
+  private func handle(path: NWPath) {
+    let snapshot = PathSnapshot.make(path: path, cellularInfo: cellularInfo)
+    latestSnapshot = snapshot
+    throttler?.submit(snapshot)
+  }
+
+  private func stopMonitoringOnQueue() {
+    monitor?.pathUpdateHandler = nil
+    monitor?.cancel()
+    monitor = nil
+    latestSnapshot = nil
+    throttler?.reset()
+    throttler = nil
+    activeProbes.values.forEach { $0.cancel() }
+    activeProbes.removeAll()
+    Array(activeOneShots.keys).forEach {
+      finishOneShot($0, result: .cancelled)
+    }
+  }
+
+  private func currentPath(
+    timeoutMs: Double,
+    completion: @escaping (PathLookupResult) -> Void
+  ) {
+    if let monitor {
+      completion(.path(monitor.currentPath))
+    } else {
+      withOneShotPath(timeoutMs: timeoutMs, completion: completion)
+    }
+  }
+
+  private func withOneShotPath(
+    timeoutMs: Double,
+    completion: @escaping (PathLookupResult) -> Void
+  ) {
+    let oneShot = NWPathMonitor()
+    let identifier = UUID()
+    let timeoutItem = DispatchWorkItem { [weak self] in
+      self?.finishOneShot(identifier, result: .timedOut)
+    }
+    activeOneShots[identifier] = OneShotRequest(
+      monitor: oneShot,
+      timeoutItem: timeoutItem,
+      completion: completion
+    )
+
+    oneShot.pathUpdateHandler = { [weak self] path in
+      self?.finishOneShot(identifier, result: .path(path))
+    }
+    oneShot.start(queue: queue)
+    queue.asyncAfter(
+      deadline: .now() + max(0, timeoutMs) / 1_000,
+      execute: timeoutItem
+    )
+  }
+
+  private func finishOneShot(
+    _ identifier: UUID,
+    result: PathLookupResult
+  ) {
+    guard let request = activeOneShots.removeValue(forKey: identifier) else {
+      return
+    }
+    request.monitor.pathUpdateHandler = nil
+    request.monitor.cancel()
+    request.timeoutItem.cancel()
+    request.completion(result)
+  }
+
+  private func performSynchronouslyOnQueue(_ action: () -> Void) {
+    if DispatchQueue.getSpecific(key: queueKey) != nil {
+      action()
+    } else {
+      queue.sync(execute: action)
+    }
+  }
+}
+
+private struct OneShotRequest {
+  let monitor: NWPathMonitor
+  let timeoutItem: DispatchWorkItem
+  let completion: (PathLookupResult) -> Void
+}

package/ios/PathSnapshot.swift

@@ -0,0 +1,109 @@
+import Foundation
+import Network
+
+enum PathSnapshot {
+  static let comparableKeys = [
+    "isConnected",
+    "isValidated",
+    "isCaptivePortal",
+    "transport",
+    "isVpn",
+    "isExpensive",
+    "isConstrained",
+    "isRoaming",
+    "downlinkKbps",
+    "uplinkKbps",
+    "signalStrength",
+    "cellularGeneration",
+    "supportsIPv4",
+    "supportsIPv6",
+    "supportsDNS",
+    "unsatisfiedReason",
+  ]
+
+  static func make(path: NWPath, cellularInfo: CellularInfo) -> [String: Any] {
+    let isConnected = path.status == .satisfied
+    let transport = transport(path: path, isConnected: isConnected)
+    let isCellular = transport == "cellular"
+
+    return [
+      "isConnected": isConnected,
+      "isValidated": NSNull(),
+      "isCaptivePortal": NSNull(),
+      "transport": transport,
+      "isVpn": NSNull(),
+      "isExpensive": path.isExpensive,
+      "isConstrained": path.isConstrained,
+      "isRoaming": NSNull(),
+      "downlinkKbps": NSNull(),
+      "uplinkKbps": NSNull(),
+      "signalStrength": NSNull(),
+      "cellularGeneration": nullable(cellularInfo.generation(isCellular: isCellular)),
+      "supportsIPv4": path.supportsIPv4,
+      "supportsIPv6": path.supportsIPv6,
+      "supportsDNS": path.supportsDNS,
+      "unsatisfiedReason": nullable(unsatisfiedReason(path: path)),
+      "timestamp": Date().timeIntervalSince1970 * 1_000,
+    ]
+  }
+
+  static func unknownDisconnected() -> [String: Any] {
+    [
+      "isConnected": false,
+      "isValidated": NSNull(),
+      "isCaptivePortal": NSNull(),
+      "transport": "unknown",
+      "isVpn": NSNull(),
+      "isExpensive": false,
+      "isConstrained": false,
+      "isRoaming": NSNull(),
+      "downlinkKbps": NSNull(),
+      "uplinkKbps": NSNull(),
+      "signalStrength": NSNull(),
+      "cellularGeneration": NSNull(),
+      "supportsIPv4": NSNull(),
+      "supportsIPv6": NSNull(),
+      "supportsDNS": NSNull(),
+      "unsatisfiedReason": "unknown",
+      "timestamp": Date().timeIntervalSince1970 * 1_000,
+    ]
+  }
+
+  private static func transport(path: NWPath, isConnected: Bool) -> String {
+    guard isConnected else { return "none" }
+    if path.usesInterfaceType(.wifi) { return "wifi" }
+    if path.usesInterfaceType(.cellular) { return "cellular" }
+    if path.usesInterfaceType(.wiredEthernet) { return "ethernet" }
+    if path.usesInterfaceType(.other) || path.usesInterfaceType(.loopback) {
+      return "other"
+    }
+    return "other"
+  }
+
+  private static func unsatisfiedReason(path: NWPath) -> String? {
+    guard path.status != .satisfied else { return nil }
+
+    if #available(iOS 17.0, *), path.unsatisfiedReason == .vpnInactive {
+      return "vpnInactive"
+    }
+
+    switch path.unsatisfiedReason {
+    case .notAvailable:
+      return "notAvailable"
+    case .cellularDenied:
+      return "cellularDenied"
+    case .wifiDenied:
+      return "wifiDenied"
+    case .localNetworkDenied:
+      return "localNetworkDenied"
+    case .vpnInactive:
+      return "vpnInactive"
+    @unknown default:
+      return "unknown"
+    }
+  }
+
+  private static func nullable(_ value: String?) -> Any {
+    value ?? NSNull()
+  }
+}

package/ios/PrivacyInfo.xcprivacy

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>NSPrivacyTracking</key>
+  <false/>
+  <key>NSPrivacyTrackingDomains</key>
+  <array/>
+  <key>NSPrivacyCollectedDataTypes</key>
+  <array/>
+  <key>NSPrivacyAccessedAPITypes</key>
+  <array>
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>35F9.1</string>
+      </array>
+    </dict>
+  </array>
+</dict>
+</plist>

package/ios/Throttler.swift

@@ -0,0 +1,174 @@
+import Foundation
+
+protocol NetworkQualityScheduledTask: AnyObject {
+  func cancel()
+}
+
+extension DispatchWorkItem: NetworkQualityScheduledTask {}
+
+final class Throttler {
+  typealias Clock = () -> Double
+  typealias Scheduler = (
+    _ delayMs: Double,
+    _ action: @escaping () -> Void
+  ) -> NetworkQualityScheduledTask
+  typealias Emitter = ([String: Any]) -> Void
+
+  private static let numericKeys = [
+    "downlinkKbps",
+    "uplinkKbps",
+    "signalStrength",
+  ]
+
+  private var throttleMs: Double
+  private var bandwidthChangeThresholdPct: Double
+  private let clock: Clock
+  private let scheduler: Scheduler
+  private let emit: Emitter
+
+  private var lastEmitted: [String: Any]?
+  private var lastEmitTime = -Double.infinity
+  private var pending: [String: Any]?
+  private var timer: NetworkQualityScheduledTask?
+
+  init(
+    throttleMs: Double,
+    bandwidthChangeThresholdPct: Double,
+    clock: @escaping Clock,
+    scheduler: @escaping Scheduler,
+    emit: @escaping Emitter
+  ) {
+    self.throttleMs = max(0, throttleMs)
+    self.bandwidthChangeThresholdPct = max(0, bandwidthChangeThresholdPct)
+    self.clock = clock
+    self.scheduler = scheduler
+    self.emit = emit
+  }
+
+  func update(throttleMs: Double, bandwidthChangeThresholdPct: Double) {
+    self.throttleMs = max(0, throttleMs)
+    self.bandwidthChangeThresholdPct = max(0, bandwidthChangeThresholdPct)
+    guard let pending else { return }
+    cancelPending()
+    submit(pending)
+  }
+
+  func submit(_ snapshot: [String: Any]) {
+    guard let previous = lastEmitted else {
+      emitNow(snapshot)
+      return
+    }
+
+    if Self.equalsIgnoringTimestamp(previous, snapshot) {
+      cancelPending()
+      return
+    }
+
+    if Self.isSignificantChange(previous, snapshot) {
+      cancelPending()
+      emitNow(snapshot)
+      return
+    }
+
+    let changedNumericKeys = Self.numericKeys.filter {
+      !Self.valuesEqual(previous[$0], snapshot[$0])
+    }
+    let crossesThreshold = changedNumericKeys.contains {
+      Self.exceedsThreshold(
+        oldValue: previous[$0],
+        newValue: snapshot[$0],
+        thresholdPct: bandwidthChangeThresholdPct
+      )
+    }
+    guard crossesThreshold else {
+      cancelPending()
+      return
+    }
+
+    let now = clock()
+    let elapsed = now - lastEmitTime
+    if elapsed >= throttleMs {
+      cancelPending()
+      emitNow(snapshot)
+      return
+    }
+
+    pending = snapshot
+    guard timer == nil else { return }
+    timer = scheduler(max(0, throttleMs - elapsed)) { [weak self] in
+      guard let self else { return }
+      self.timer = nil
+      guard let pending = self.pending else { return }
+      self.pending = nil
+      self.emitNow(pending)
+    }
+  }
+
+  func reset() {
+    cancelPending()
+    lastEmitted = nil
+    lastEmitTime = -Double.infinity
+  }
+
+  static func equalsIgnoringTimestamp(
+    _ first: [String: Any],
+    _ second: [String: Any]
+  ) -> Bool {
+    PathSnapshot.comparableKeys.allSatisfy {
+      valuesEqual(first[$0], second[$0])
+    }
+  }
+
+  static func isSignificantChange(
+    _ first: [String: Any],
+    _ second: [String: Any]
+  ) -> Bool {
+    PathSnapshot.comparableKeys
+      .filter { !numericKeys.contains($0) }
+      .contains { !valuesEqual(first[$0], second[$0]) }
+  }
+
+  static func exceedsThreshold(
+    oldValue: Any?,
+    newValue: Any?,
+    thresholdPct: Double
+  ) -> Bool {
+    let oldNumber = numericValue(oldValue)
+    let newNumber = numericValue(newValue)
+    if oldNumber == nil || newNumber == nil {
+      return oldNumber != nil || newNumber != nil
+    }
+    guard let oldNumber, let newNumber else { return false }
+    if oldNumber == newNumber { return false }
+    if oldNumber == 0 { return true }
+    return abs(newNumber - oldNumber) / abs(oldNumber) * 100 >= thresholdPct
+  }
+
+  private func emitNow(_ snapshot: [String: Any]) {
+    lastEmitted = snapshot
+    lastEmitTime = clock()
+    emit(snapshot)
+  }
+
+  private func cancelPending() {
+    timer?.cancel()
+    timer = nil
+    pending = nil
+  }
+
+  private static func numericValue(_ value: Any?) -> Double? {
+    guard !(value is NSNull) else { return nil }
+    return (value as? NSNumber)?.doubleValue
+  }
+
+  private static func valuesEqual(_ first: Any?, _ second: Any?) -> Bool {
+    switch (first, second) {
+    case (nil, nil):
+      return true
+    case let (first as NSObject, second as NSObject):
+      return first.isEqual(second)
+    default:
+      return false
+    }
+  }
+}

package/lib/module/NativeNetworkQuality.js

@@ -0,0 +1,5 @@
+"use strict";
+
+import { TurboModuleRegistry } from 'react-native';
+export default TurboModuleRegistry.get('NetworkQuality');
+//# sourceMappingURL=NativeNetworkQuality.js.map

package/lib/module/NativeNetworkQuality.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"..\\..\\src","sources":["NativeNetworkQuality.ts"],"mappings":";;AAAA,SACEA,mBAAmB,QAGd,cAAc;AAqDrB,eAAeA,mBAAmB,CAACC,GAAG,CAAO,gBAAgB,CAAC","ignoreList":[]}