Add docs to the offline module

1 files changed, 22 insertions, 0 deletions

diff --git a/talpid-core/src/offline/macos.rs b/talpid-core/src/offline/macos.rs
index 46329f5585..8ba649856a 100644
--- a/talpid-core/src/offline/macos.rs
+++ b/talpid-core/src/offline/macos.rs
@@ -1,3 +1,25 @@
+//! This module has been reimplemented multiple times, often to no avail, with main issues being
+//! that the app gets stuck in an offline state, blocking all internet access and preventing the
+//! user from connecting to a relay.
+//!
+//! Currently, this functionality is implemented by using `route monitor -n` to observe routing
+//! table changes and then use the CLI once more to query if there exists a default route.
+//! Generally, it is assumed that a machine is online if there exists a route to a public IP
+//! address that isn't using a tunnel adapter. On macOS, there were various ways of deducing this:
+//! - watching the `State:/Network/Global/IPv4`  key in SystemConfiguration via
+//!  `system-configuration-rs`, relying on a CoreFoundation runloop to drive callbacks.
+//!   The issue with this is that sometimes during early boot or after a re-install, the callbacks
+//!   won't be called, often leaving the daemon stuck in an offline state.
+//! - setting a callback via [`SCNetworkReachability`]. The callback should be called whenever the
+//!   reachability of a remote host changes, but sometimes the callbacks just don't get called.
+//! - [`NWPathMonitor`] is a macOS native interface to watch changes in the routing table. It works
+//!   great, but it seems to deliver updates before they actually get added to the routing table,
+//!   effectively calling our callbacks with routes that aren't yet usable, so starting tunnels
+//!   would fail anyway. This would be the API to use if we were able to bind the sockets our tunnel
+//!   implementations would use, but that is far too much complexity.
+//!
+//! [`SCNetworkReachability`]: https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability-g7d
+//! [`NWPathMonitor`]: https://developer.apple.com/documentation/network/nwpathmonitor
 use futures::{channel::mpsc::UnboundedSender, Future, StreamExt};
 use std::sync::{Arc, Weak};
 use talpid_types::ErrorExt;