python Case study
WireGuard Soft-fix Watchdog
A WireGuard tunnel reports itself as connected long after it has stopped passing traffic. That gap is the whole problem: the interface looks fine, the work does not, and you find out from a failing command rather than from the VPN.
The business problem
WireGuard is connectionless, so an interface being up says nothing about whether packets are reaching the other end. The practical symptom is a tunnel that silently stops working, usually after the machine sleeps or the network changes, and the fix is always the same manual restart. Doing that by hand means noticing first, which is the part that does not happen reliably.
What I delivered
- A macOS-side watchdog that checks connection health continuously rather than on demand.
- Health checks that test whether traffic actually reaches the far side, since interface state is not evidence of a working tunnel.
- Automatic recovery of the session when a check fails, so the common case is repaired without anyone noticing it broke.
- A record of failures over time, which is what turns a recurring annoyance into something with a diagnosable pattern.
Technical approach
- Health is defined as traffic reaching the other end. Any check based on interface or process state would report the failure mode this exists to catch as healthy.
- Recovery restarts the session rather than attempting a partial repair, because on a connectionless tunnel the reliable fix is the blunt one.
- Failures are logged rather than only acted on. The log is what distinguishes a flaky network from a configuration problem.
- It runs on the client machine, which is the only place with a view of whether the tunnel is working from where it is actually used.
Result and evidence
The tunnel repairs itself in the ordinary case, and the failure log made the pattern visible rather than anecdotal, which is what the manual version never produced.
Commercial value
Small recurring interruptions are expensive in a way that is easy to underestimate, because the cost is attention rather than time.
Readable implementation brief
implementation_brief {
project: "WireGuard Soft-Fix Watchdog"
runs_on: "the client machine (macOS)"
health_definition: "traffic reaches the far side --
NOT interface or process state"
recovery: "restart the session; blunt and reliable"
record: "failures logged over time to expose the pattern"
triggers_it_catches: "sleep/wake, network change, silent stall"
}What this project shows
Defining health as traffic rather than as interface state is the entire point of the tool. A watchdog that checks the wrong signal reports green during the outage.
Logging failures rather than just fixing them is what turned this from a workaround into something that told me what was actually wrong.