Reachability: cos'è, libreria di verifica della disponibilità della rete

Cos'è Reachability?

Reachability è una libreria di esempio di Apple che dimostra l'uso del framework SystemConfiguration per il monitoraggio della rete. Il codice sorgente è stato pubblicato nella Documentazione Apple Developer come esempio, ma la comunità lo ha adottato come strumento standard per verificare la connettività nei progetti iOS.

La libreria si basa su SCNetworkReachability — una funzione C di SystemConfiguration che valuta il raggiungimento di un host remoto o indirizzo IP. Durante la creazione di Reachability, si specifica un nome host (ad esempio google.com) o un indirizzo IP, e la libreria verifica in modo asincrono se questo host è raggiungibile attraverso le interfacce di rete correnti del dispositivo.

La popolarità di Reachability è dovuta alla sua semplicità: basta creare un'istanza, sottoscriversi alle notifiche tramite NotificationCenter e ascoltare kReachabilityChangedNotification. In risposta, l'app riceve uno stato: NotReachable, ReachableViaWiFi o ReachableViaWWAN (dati cellulari).

Storia e stato della libreria

Reachability è apparsa per la prima volta in iPhone OS 2 (2008) insieme al framework SystemConfiguration. Per un decennio è stato il solo modo nativo per monitorare lo stato della rete in iOS. Con il rilascio di iOS 12 e del framework Network, Apple raccomanda NWPathMonitor come sostituto, ma Reachability è ancora supportato.

Molti wrapper di terze parti — AFNetworking, Alamofire, AshleyDodd/Reachability.swift — utilizzano il meccanismo interno di SCNetworkReachability. Queste librerie aggiungono un'interfaccia comoda in Swift/Objective-C, memoizzazione dello stato e callback thread-safe, mantenendo la stessa base SystemConfiguration.

Come funziona Reachability internamente

Il meccanismo principale di Reachability è la funzione SCNetworkReachabilityCreateWithName, che crea un oggetto di tracciamento per l'host specificato. Quindi viene chiamato SCNetworkReachabilityGetFlags — un controllo sincrono che restituisce una maschera di bit SCNetworkReachabilityFlags con lo stato corrente della rete.

Per il monitoraggio asincrono viene utilizzato SCNetworkReachabilitySetCallback, che registra una funzione di callback C. Il callback viene eseguito sul RunLoop corrente quando lo stato di raggiungimento dell'host cambia. Reachability avvolge questo callback C in un metodo Objective-C e invia una notifica tramite NotificationCenter.

import SystemConfiguration

class Reachability {
    private var reachabilityRef: SCNetworkReachability?

    init?(hostname: String) {
        reachabilityRef = SCNetworkReachabilityCreateWithName(
            nil, hostname
        )
    }

    func checkReachability() -> Bool {
        var flags = SCNetworkReachabilityFlags()
        SCNetworkReachabilityGetFlags(
            reachabilityRef!, &flags
        )
        return isReachable(with: flags)
    }

    private func isReachable(with flags: SCNetworkReachabilityFlags) -> Bool {
        let reachable = flags.contains(.reachable)
        let connectionRequired = flags.contains(.connectionRequired)
        return reachable && !connectionRequired
    }
}

Flag di raggiungimento della rete

SCNetworkReachabilityFlags è una maschera di bit che codifica lo stato della rete. Il flag kSCNetworkReachabilityFlagsReachable indica che l'host è raggiungibile. kSCNetworkReachabilityFlagsConnectionRequired — è necessario stabilire una connessione. La combinazione dei flag determina se l'applicazione può inviare dati.

Flag aggiuntivi: kSCNetworkReachabilityFlagsIsWWAN — connessione tramite rete cellulare (iOS), kSCNetworkReachabilityFlagsInterventionRequired — intervento dell'utente necessario (ad esempio per VPN). Reachability considera questi flag per determinare il tipo di interfaccia.

Esempi di utilizzo di Reachability

Il modello standard di utilizzo di Reachability in un'app iOS include la creazione di un'istanza, la sottoscrizione alle notifiche e la reazione ai cambiamenti di stato. L'esempio seguente mostra l'integrazione con NotificationCenter per aggiornare l'interfaccia utente quando la rete cambia.

import Reachability
import UIKit

class ViewController: UIViewController {
    var reachability: Reachability?

    override func viewDidLoad() {
        super.viewDidLoad()
        reachability = Reachability(hostname: "google.com")
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(reachabilityChanged),
            name: .reachabilityChanged,
            object: nil
        )
        reachability?.startNotifier()
    }

    @objc func reachabilityChanged(notification: Notification) {
        if let reachability = notification.object as? Reachability {
            switch reachability.connection {
            case .wifi:
                print("Connesso via Wi-Fi")
            case .cellular:
                print("Connesso via cellulare")
            case .unavailable:
                print("Nessuna connessione")
            }
        }
    }
}

Verifica della rete prima di una richiesta

Prima di eseguire una richiesta HTTP, è possibile verificare la disponibilità della rete in modo sincrono: reachability.connection != .unavailable. Ciò non garantisce il successo della richiesta (il server potrebbe essere non disponibile), ma previene richieste che falliranno sicuramente e migliora l'UX — l'app non mostra uno spinner in modalità offline.

Per una verifica più accurata, combina Reachability con i timeout di URLSession. Se Reachability mostra raggiungibile ma la richiesta fallisce entro il timeout — probabilmente c'è un problema lato server o un portale captive. In tal caso, si può mostrare all'utente un messaggio di server non disponibile.

Tipi di connessione in Reachability

Reachability distingue tre stati principali di connessione: Wi-Fi, dati cellulari (WWAN) e non disponibile. WWAN include tutti i tipi di connessione cellulare — 2G, 3G, 4G/LTE, 5G. La libreria non fornisce granularità all'interno di WWAN, quindi per distinguere 4G e 5G è necessario CoreTelephony.

Limitazioni di Reachability per tipo di rete

Reachability non distingue Ethernet, tunnel VPN o connessioni multipath — tutte le interfacce non-WWAN sono classificate come Wi-Fi. Questa limitazione deriva dall'architettura di SystemConfiguration, che non fornisce informazioni dettagliate sulle interfacce di rete oltre la classificazione di base.

Per determinare il tipo specifico di connessione cellulare (4G vs 5G), è necessario CTTelephonyNetworkInfo da CoreTelephony. La combinazione di Reachability con CoreTelephony consente all'app di selezionare la qualità del contenuto: su 5G — streaming in 4K, su 4G/LTE — HD, su 3G — SD o solo audio.

Migrazione da Reachability a NWPathMonitor

Apple raccomanda di sostituire Reachability con NWPathMonitor in tutti i nuovi progetti a partire da iOS 12. Il motivo principale è che NWPathMonitor fa parte del framework Network moderno, è scritto in Swift, supporta Combine e fornisce informazioni dettagliate sul percorso di rete senza usare compatibilità C.

Il processo di migrazione include la sostituzione di SCNetworkReachability con NWPathMonitor, il passaggio da NotificationCenter a una closure pathUpdateHandler o un publisher Combine. L'algoritmo e la logica di gestione dello stato della rete rimangono gli stessi — cambia solo l'API di monitoraggio.

protocol NetworkMonitorProtocol {
    var isReachable: Bool { get }
    var connectionType: ConnectionType { get }
    func startMonitoring()
    func stopMonitoring()
}

enum ConnectionType {
    case wifi, cellular, ethernet, unavailable
}

// Implementazione moderna che utilizza NWPathMonitor
class ModernNetworkMonitor: NetworkMonitorProtocol {
    private let monitor = NWPathMonitor()
    private let queue = DispatchQueue("Network")
    private var currentPath: NWPath?

    var isReachable: Bool {
        currentPath?.status == .satisfied
    }

    func startMonitoring() {
        monitor.pathUpdateHandler = { [weak self] path in
            self?.currentPath = path
        }
        monitor.start(on: queue)
    }

    func stopMonitoring() {
        monitor.cancel()
    }
}

Raccomandazioni per la migrazione

Per i progetti con supporto iOS 12+, sostituisci completamente Reachability con NWPathMonitor. Per i progetti che supportano iOS 11, utilizza la compilazione condizionale #available(iOS 12, *) con NWPathMonitor e Reachability come fallback. Ciò consente una migrazione graduale senza perdere il supporto per i dispositivi vecchi.

Il vantaggio principale della migrazione è la granularità del percorso di rete. NWPathMonitor riporta non solo “raggiungibile/non raggiungibile” ma anche il tipo di ciascuna interfaccia, i loro costi, priorità, supporto proxy e VPN. Ciò fornisce allo sviluppatore più dati per adattare il comportamento dell'applicazione alle condizioni di rete correnti.