Reachability: o que é, biblioteca de verificação de disponibilidade de rede

O que é Reachability?

Reachability é uma biblioteca de exemplo da Apple que demonstra o uso do framework SystemConfiguration para monitoramento de rede. O código fonte foi publicado na Documentação Apple Developer como exemplo, mas a comunidade o adotou como ferramenta padrão para verificar conectividade em projetos iOS.

A biblioteca é baseada no SCNetworkReachability — uma função C do SystemConfiguration que avalia o alcance de um host remoto ou endereço IP. Ao criar o Reachability, especifica-se um hostname (por exemplo, google.com) ou um endereço IP, e a biblioteca verifica assincronamente se este host está acessível através das interfaces de rede atuais do dispositivo.

A popularidade do Reachability se deve à sua simplicidade: basta criar uma instância, inscrever-se em notificações via NotificationCenter e ouvir kReachabilityChangedNotification. Em resposta, o aplicativo recebe um status: NotReachable, ReachableViaWiFi ou ReachableViaWWAN (dados celulares).

História e status da biblioteca

Reachability apareceu pela primeira vez no iPhone OS 2 (2008) junto com o framework SystemConfiguration. Por uma década foi a única forma nativa de monitorar o status da rede no iOS. Com o lançamento do iOS 12 e do framework Network, a Apple recomenda o NWPathMonitor como substituto, mas o Reachability ainda é suportado.

Muitos wrappers de terceiros — AFNetworking, Alamofire, AshleyDodd/Reachability.swift — usam o mecanismo interno do SCNetworkReachability. Essas bibliotecas adicionam uma interface conveniente em Swift/Objective-C, memoização de status e callbacks thread-safe, mantendo a mesma base do SystemConfiguration.

Como Reachability funciona internamente

O mecanismo principal do Reachability é a função SCNetworkReachabilityCreateWithName, que cria um objeto de rastreamento para o host especificado. Em seguida, SCNetworkReachabilityGetFlags é chamada — uma verificação síncrona que retorna uma máscara de bits SCNetworkReachabilityFlags com o estado atual da rede.

Para monitoramento assíncrono, é usado SCNetworkReachabilitySetCallback, que registra uma função de callback em C. O callback é executado no RunLoop atual quando o estado de alcance do host muda. Reachability envolve este callback C em um método Objective-C e envia uma notificação através do 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
    }
}

Flags de alcance de rede

SCNetworkReachabilityFlags é uma máscara de bits que codifica o estado da rede. A flag kSCNetworkReachabilityFlagsReachable indica que o host está acessível. kSCNetworkReachabilityFlagsConnectionRequired — é necessário estabelecer uma conexão. A combinação de flags determina se o aplicativo pode enviar dados.

Flags adicionais: kSCNetworkReachabilityFlagsIsWWAN — conexão via rede celular (iOS), kSCNetworkReachabilityFlagsInterventionRequired — intervenção do usuário necessária (por exemplo, para VPN). Reachability considera essas flags para determinar o tipo de interface.

Exemplos de uso do Reachability

O padrão típico de uso do Reachability em um aplicativo iOS inclui criar uma instância, inscrever-se em notificações e reagir a mudanças de status. O exemplo abaixo mostra a integração com NotificationCenter para atualizar a interface do usuário quando a rede muda.

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("Conectado via Wi-Fi")
            case .cellular:
                print("Conectado via celular")
            case .unavailable:
                print("Sem conexão")
            }
        }
    }
}

Verificação de rede antes de uma requisição

Antes de fazer uma requisição HTTP, pode-se verificar a disponibilidade da rede de forma síncrona: reachability.connection != .unavailable. Isso não garante o sucesso da requisição (o servidor pode estar indisponível), mas evita requisições que certamente falharão e melhora a experiência do usuário — o aplicativo não mostra um spinner no modo offline.

Para uma verificação mais precisa, combine o Reachability com timeouts do URLSession. Se o Reachability mostra acessível mas a requisição falha dentro do timeout — provavelmente há um problema no servidor ou um portal cativo. Nesse caso, pode-se mostrar ao usuário uma mensagem de servidor indisponível.

Tipos de conexão no Reachability

Reachability distingue três estados principais de conexão: Wi-Fi, dados celulares (WWAN) e indisponível. WWAN inclui todos os tipos de conexão celular — 2G, 3G, 4G/LTE, 5G. A biblioteca não fornece granularidade dentro do WWAN, portanto, para distinguir 4G de 5G é necessário o CoreTelephony.

Limitações do Reachability por tipo de rede

Reachability não distingue Ethernet, túneis VPN ou conexões multipath — todas as interfaces não-WWAN são classificadas como Wi-Fi. Essa limitação decorre da arquitetura do SystemConfiguration, que não fornece informações detalhadas sobre interfaces de rede além da classificação básica.

Para determinar o tipo específico de conexão celular (4G vs 5G), é necessário CTTelephonyNetworkInfo do CoreTelephony. Combinar Reachability com CoreTelephony permite que o aplicativo selecione a qualidade do conteúdo: em 5G — streaming em 4K, em 4G/LTE — HD, em 3G — SD ou apenas áudio.

Migração do Reachability para NWPathMonitor

A Apple recomenda substituir o Reachability pelo NWPathMonitor em todos os novos projetos a partir do iOS 12. A principal razão é que o NWPathMonitor faz parte do framework moderno Network, é escrito em Swift, suporta Combine e fornece informações detalhadas sobre o caminho de rede sem usar compatibilidade com C.

O processo de migração inclui substituir SCNetworkReachability por NWPathMonitor, migrar do NotificationCenter para um closure pathUpdateHandler ou publisher Combine. O algoritmo e a lógica de tratamento de status da rede permanecem os mesmos — apenas a API de monitoramento muda.

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

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

// Implementação moderna usando 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()
    }
}

Recomendações de migração

Para projetos com suporte básico ao iOS 12+, substitua o Reachability pelo NWPathMonitor completamente. Para projetos que suportam iOS 11, use compilação condicional #available(iOS 12, *) com NWPathMonitor e Reachability como fallback. Isso permite uma migração gradual sem perder suporte para dispositivos antigos.

A principal vantagem da migração é a granularidade do caminho de rede. O NWPathMonitor informa não apenas “acessível/inacessível” mas também o tipo de cada interface, seus custos, prioridade, suporte a proxy e VPN. Isso dá ao desenvolvedor mais dados para adaptar o comportamento do aplicativo às condições atuais da rede.