Feat/auto-restart tunnels on stale handshake or ping failure 1036 EXPERIMENTAL

[naonak]

Auto-restart tunnels on stale handshake or ping failure (EXPERIMENTAL)

WORK IN PROGRESS.

Summary

Adds an optional auto-restart mechanism that monitors the active WireGuard tunnel and automatically restarts it when a connection problem is detected. The feature is entirely opt-in and configurable through a new screen under Settings → Tunnel Monitoring → Auto-restart.

---

Problem

WireGuard tunnels can silently stop passing traffic when:

• The last handshake becomes stale (~3.5 min without a successful re-key)
• All configured ping targets are unreachable for several consecutive intervals

Without manual intervention the tunnel stays "Up" in the UI while being effectively dead.

---

What's new

Functional

• Auto-restart on stale handshake — restarts the tunnel when the WireGuard handshake threshold is exceeded, without requiring the user to toggle the tunnel manually
• Restart on ping failure — optionally also restarts after N consecutive ping-failure intervals reported by the existing ping monitor
• Pre-restart verification — when ping is enabled, performs a fresh ping series just before each restart attempt; skips the restart if any target is reachable (tunnel recovered on its own)
• Exponential backoff — optionally doubles the cooldown between each attempt, up to a configurable number of attempts
• Give-up action — after max attempts: either keep monitoring (do nothing) or stop the tunnel entirely
• Recovery notifications — notifies the user when the tunnel that was restarting comes back healthy
• Real-time status in tunnel list — the tunnel card shows live restart progress: attempt count, countdown to next retry, trigger reason (stale handshake / ping failure), and failing ping targets

Configuration

Setting	Default	Description
Restart cooldown	30s	Minimum time between restart attempts
Startup grace period	15s	Delay before first check after tunnel start
Restart on ping failure	off	Use ping failures as an additional trigger
Consecutive failures before restart	3	Ping failure streak required
Exponential backoff	off	Double cooldown on each attempt
Max attempts (backoff)	5	Give up after N attempts with backoff
Max attempts (no backoff)	10	Max attempts per hour without backoff
Give-up action	Do nothing	Do nothing or stop tunnel
Recovery notifications	on	Notify when tunnel recovers

---

Technical design

HandshakeRestartHandler

The core of the feature. A monitoring coroutine is started when the tunnel comes up and cancelled when it goes down (via activeTunnels StateFlow). A Mutex serialises job lifecycle.

Trigger logic (shouldTrigger)

1. Stale handshake — always checked first (WireGuard already waits ~3.5 min)
2. Ping failure — all attempted pings unreachable, gated on isPingMonitoringEnabled

False-positive protection

• Startup grace — waits for the tunnel to reach a healthy state before the first check; prevents false triggers from stale kernel stats retained across tunnel restarts
• Ping streak threshold — ping failures must repeat for N consecutive intervals; waits for an actual new ping cycle (not just any stats update) using lastPingAttemptMillis comparison
• Pre-restart verification — re-pings targets fresh before committing to a restart, using NetworkUtils.pingWithStats()
• Post-restart grace — mirrors startup grace after each restart; prevents rapid-fire loops when cooldown < WireGuard re-keying time, since isTunnelStale() can still fire on stale stats before the new handshake completes

Rate limiting

• Timestamps are recorded in an ArrayDeque<Long>
• Without backoff: timestamps older than 1 hour are pruned on each check
• With backoff: cooldown × 2^(attempt-1), capped at attempt 31 to prevent Long overflow

Network change reactivity

• networkChangeFlow observes connectivity state changes (WiFi ↔ Cellular ↔ Ethernet) and wakes the monitoring loop immediately after a 3 s grace, avoiding the full ~3.5 min stale-handshake wait after a network switch

Give-up

• DO_NOTHING — suspends until the tunnel recovers or goes down, then resets timestamps and resumes monitoring
• STOP_TUNNEL — calls stopTunnel(id) and returns (job terminates)

Database

• MonitoringSettings entity extended with 9 new fields (all with sane defaults via auto-migration)
• DB version 29 → 31 (two auto-migrations)
• MaxAttemptsAction stored as a string enum via DatabaseConverters
• TunnelRestartProgress is a pure domain state type — not persisted, lives only in memory

UI

• AutoRestartScreen exposes all settings through MonitoringViewModel (Orbit MVI pattern)
• AutoRestartScreen shows a warning banner when battery optimization is enabled, with a direct tap-to-disable shortcut — battery optimization can prevent auto-restart from firing reliably on some devices
• LabelledNumberDropdown added as a reusable component for numeric option lists
• Backoff give-up dropdown shows estimated total wait time (e.g. 5 attempts (~4m35s)) computed from computeCooldown() so the user can reason about the effective timeout
• TunnelRestartProgress flows from HandshakeRestartHandler → TunnelManager → SharedAppViewModel → TunnelsUiState → TunnelList

---

Also included

fix: reduce network change grace period from 10 s to 3 s

HandshakeRestartHandler observes network transitions (WiFi ↔ LTE ↔ Ethernet) and wakes the restart loop early to avoid waiting the full ~3.5 min stale-handshake window. The previous grace period of 10 s was longer than necessary: 3 s is enough to distinguish a real network switch from a momentary drop, while still reacting quickly enough to restart the tunnel before the user notices the outage.

fix: show battery optimization warning in auto-restart screen

If Android battery optimization is active, the app process can be throttled or delayed in the background, preventing auto-restart from firing reliably (especially on devices running Android < 14 with aggressive OEM power management). A contextual warning banner is now shown at the top of the Auto-restart screen whenever battery optimization is not disabled, with a tap action that opens the system exemption prompt directly.

---

Test plan

• Enable auto-restart, disconnect network — tunnel restarts within cooldown + grace period
• Enable ping failure trigger, block ICMP — restart triggers after N consecutive failures
• Verify pre-restart verification skips restart when tunnel self-recovers mid-cooldown
• Enable backoff — confirm cooldown doubles each attempt
• Reach max attempts with STOP_TUNNEL action — tunnel stops, notification shown
• Reach max attempts with DO_NOTHING — monitoring resumes after manual recovery
• Toggle tunnel off manually during auto-restart — restart cancelled cleanly
• Startup grace: toggle tunnel on/off rapidly — no spurious restart on startup
• Recovery notification shown when tunnel comes back healthy

[naonak]

#1036

[naonak]

new version #1182