Implement Linux support for connectivity detection

[velocitysystems]

Summary

Implement Linux support for connection_status().
The types, command, permissions, and JS/TS bindings have already been merged in #2.

Linux exposes NetworkManager over D-Bus (org.freedesktop.NetworkManager): overall connectivity, metered state, and the active connection's transport type. Cellular roaming requires cross-referencing ModemManager (org.freedesktop.ModemManager1). On systems without NetworkManager (systemd-networkd-only, minimal containers, Alpine), the backend should gracefully degrade to a best-effort status rather than error.

Out of Scope

• Windows, iOS, and Android backends — separate follow-ups.
• Change-notification / observer APIs for status transitions.
• Data-limit fields (approaching_data_limit, over_data_limit) — not exposed on Linux

[gabref]

@velocitysystems #I went through the NetworkManager + ModemManager docs to align on behavior before starting implementation. I’d suggest the following approach for Linux, but would appreciate confirmation before proceeding:

---

1. connected source of truth (NetworkManager)

Based on the docs:

• Connectivity: https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nm-dbus-types.html#NMConnectivityState
• State: https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nm-dbus-types.html#NMState

NetworkManager exposes two related but different signals here:

• CheckConnectivity() returns the current connectivity state, i.e. internet reachability
• state() returns the overall networking state managed by NetworkManager

Based on that, I think we could treat:

• CheckConnectivity() as the primary source for connected
• if connectivity is UNKNOWN, fall back to state() (e.g. CONNECTED_GLOBAL)
• only fall back to non-NetworkManager heuristics if NetworkManager is unavailable entirely

This seems like the most natural mapping, since connectivity is the more direct signal for actual reachability, while state() is a broader view of networking status.

---

2. Fallback behavior when NetworkManager is unavailable

On systems without NetworkManager (e.g. systemd-networkd, Alpine, containers), I think we could degrade as follows:

Possible fallback strategies:

• connected:
  • check for an active interface (/sys/class/net, ip route, etc.)
  • optionally attempt a simple reachability check (e.g. DNS or ping)
• connection_type:
  • infer from interface name (wlan* → wifi, eth* → ethernet), otherwise unknown
• metered:
  • likely not reliably detectable → default to false
• constrained:
  • no reliable signal → default to false

If no reliable signal is available at all:

{
  connected: false,
  metered: false,
  constrained: false,
  connection_type: "unknown"
}

This keeps behavior predictable while still attempting a best-effort detection.

---

3. Definition of constrained (ModemManager)

Docs:

• https://www.freedesktop.org/software/ModemManager/doc/latest/ModemManager/ModemManager-Flags-and-Enumerations.html

Since Linux does not expose data-limit signals like Windows, I see two possible interpretations:

Option A (strict):

• constrained = true only when:

  • connection type is cellular
  • AND modem is in roaming state (via ModemManager)

• otherwise false

Option B (broader):

• constrained = true for:

  • roaming cellular
  • OR explicitly metered cellular connections

My preference would be Option A, since it keeps semantics narrow and predictable.

Also, if ModemManager is not available, I’d default constrained = false even for cellular.

---

4. ModemManager versioning

Docs used:

• https://www.freedesktop.org/software/ModemManager/doc/latest/ModemManager/ModemManager-Flags-and-Enumerations.html

For implementation, I’m planning to rely only on stable D-Bus properties (e.g. roaming state flags), so I assume we don’t need to pin to a specific ModemManager version.

Does it make sense to:

• target the generic D-Bus API (no version pin), and
• just handle missing properties gracefully?

---

Let me know if this direction makes sense

[velocitysystems]

Thanks @gabref. Should we make the command async to allow blocking calls? Do we need to handle timeouts when querying system APIs on Linux? In response to your questions:

1. connected source of truth

Consider using Connectivity D-Bus property (cached), instead of CheckConnectivity() (issues HTTP probe)

• Map only NM_CONNECTIVITY_FULL → connected: true. PORTAL/LIMITED/NONE all → false
• Fallback to State == CONNECTED_GLOBAL when Connectivity == UNKNOWN

2. Fallback behavior when NetworkManager is unavailable

Can we scale this back slightly:

• No active probing. This API is about checking state; it shouldn't generate side effects
• Interface-name patterns may be unreliable; infer transport from sysfs
• Look for a non-loopback default route in /proc/net/route. If found, connected: true. Otherwise ConnectionStatus::disconnected()

3. Definition of constrained (ModemManager)

Neither A nor B — both narrow the type's documented contract. Should we use constrained = true if any of:

• ModemManager reports Modem3gpp.RegistrationState as ROAMING (5), OR
• The primary device's Metered property is NM_METERED_YES or NM_METERED_GUESS_YES

Metered lives on org.freedesktop.NetworkManager.Device, not Connection.Active — resolve via NM's PrimaryConnection → Devices → Metered. Default to false when no signal

4. ModemManager versioning

Agreed — generic D-Bus, no version pin. Two additions:

• Probe org.freedesktop.ModemManager1 service presence before checking; absent ⇒ skip cellular checks silently
• Treat MM D-Bus errors as "no roaming signal", not whole-call failure