NetPulseKit

NetPulseKit is a lightweight iOS Swift Package that monitors network quality in real time.

It combines real signals available to normal iOS apps:

• connectivity status (NWPathMonitor)
• active interface type
• expensive/constrained path flags
• periodic latency probes via URLSession
• estimated packet loss from rolling probe failures

Why NetPulseKit

Most apps only track online/offline state. NetPulseKit helps you react to quality shifts (for example, reducing bitrate, delaying large syncs, or softening retry policies) using a pragmatic, deterministic model.

Honesty About Telemetry

NetPulseKit does not claim exact OS-reported packet loss or jitter telemetry.

packetLossPercent is an estimate based on a rolling window of probe success/failure outcomes. This is intentional and explicit in the API.

Installation (Swift Package Manager)

In Xcode:

1. File → Add Packages...
2. Enter https://github.com/Ahsan-Pitafi/NetPulseKit.git
3. Add NetPulseKit to your target

Or in Package.swift:

dependencies: [
    .package(url: "https://github.com/Ahsan-Pitafi/NetPulseKit.git", from: "1.0.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "NetPulseKit", package: "NetPulseKit")
        ]
    )
]

Installation (CocoaPods)

NetPulseKit is available on CocoaPods: https://cocoapods.org/pods/NetPulseKit

Add this to your Podfile:

platform :ios, '15.0'

target 'YourApp' do
  use_frameworks!
  pod 'NetPulseKit', '~> 1.0'
end

Then run:

pod install

Quick Start

import NetPulseKit

let monitor = NetworkQualityMonitor()

monitor.onUpdate = { snapshot in
    print("Grade:", snapshot.grade)
    print("Latency:", snapshot.latencyMs ?? 0)
    print("Estimated Loss:", snapshot.packetLossPercent ?? 0)
}

monitor.start()

AsyncStream API

Task {
    for await snapshot in monitor.updates {
        print(snapshot)
    }
}

Combine Publisher API

import Combine
import NetPulseKit

var cancellables = Set<AnyCancellable>()

monitor.publisher
    .sink { snapshot in
        print(snapshot.grade)
    }
    .store(in: &cancellables)

Optional SwiftUI-Friendly Adapter

import NetPulseKit

let model = NetworkQualityObservableModel()
model.start()

Use model.snapshot in your SwiftUI layer via @StateObject or @ObservedObject.

Configuration

import NetPulseKit

let config = NetworkQualityConfiguration(
    probeURL: URL(string: "https://www.apple.com/library/test/success.html")!,
    probeInterval: 5,
    requestTimeout: 3,
    rollingSampleSize: 20,
    latencyThresholds: .init(
        excellentMaxMs: 120,
        goodMaxMs: 300,
        fairMaxMs: 800,
        poorMinMs: 800
    ),
    enableLogging: false
)

let monitor = NetworkQualityMonitor(configuration: config)

Public API Overview

• ConnectivityStatus: .online, .offline, .requiresConnection
• NetworkInterfaceKind: .wifi, .cellular, .wiredEthernet, .loopback, .other, .unknown
• NetworkQualityGrade: .offline, .poor, .fair, .good, .excellent
• NetworkQualitySnapshot: full point-in-time signal bundle
• NetworkQualityConfiguration: probe + thresholds + estimator tuning
• NetworkQualityMonitor: façade with closure, AsyncStream, and Combine delivery

Classification Defaults

• offline: no satisfied path
• excellent: latency < 120 ms
• good: 120–300 ms
• fair: 300–800 ms
• poor: > 800 ms or frequent probe failures
• constrained paths are downgraded
• expensive paths may be downgraded when loss indicates instability

Testing

The package includes unit tests for:

• threshold classification behavior
• downgrade rules
• packet-loss rolling-window math
• snapshot state/reducer flow

Run tests:

swift test

Roadmap

• adaptive probe intervals based on app foreground/background context
• optional weighted smoothing for latency samples
• richer quality diagnostics for analytics/debug overlays
• additional API conveniences for retry/backoff integration