balancer-lite-lua

balancer-lite-lua

Hysteresis WAN failover watchdog + signed webhook outbox for OpenWrt 22.03, written in Lua 5.1.

What this is: A thin-layer Lua daemon that adds flap/DEGRADED hysteresis and signed webhook alerts on top of OpenWrt's existing mwan3/netifd infrastructure. It does NOT replace those — it complements them. The daemon runs the state machine, emits signed webhook events on state transitions, and can re-point WireGuard endpoints when a WAN flips.

What this is NOT: A full netifd/mwan3 replacement. It has no built-in routing or interface management — that is mwan3's job.

Modules

File	Responsibility
sha256.lua	SHA-256 / HMAC-SHA256 via openssl dgst
state.lua	8-state hysteresis machine (INIT, WAN_A/B_PRIMARY, SWITCHING_TO_A/B, DEGRADED, BOTH_DOWN)
probes.lua	ICMP (ping), TCP (nc), DNS (nslookup) health checks
store.lua	JSONL append-only event log + compaction
outbox.lua	Signed webhook retry queue with exponential backoff + circuit breaker
config.lua	UCI config file parser
main.lua	procd-compatible poll loop daemon

Requirements (OpenWrt 22.03)

opkg install lua openssl-util coreutils-sort ip-full wireguard-tools kmod-wireguard

Quick Start

# Copy init script and config
cp etc/config/balancerlite /etc/config/
cp etc/init.d/balancerlite /etc/init.d/
chmod +x /etc/init.d/balancerlite

# Edit config
vi /etc/config/balancerlite

# Enable and start
/etc/init.d/balancerlite enable
/etc/init.d/balancerlite start
logread -f | grep balancerlite

Configuration (UCI)

config balancerlite 'global'
    option enabled '1'
    option state_dir '/root/.balancerlite'
    option webhook_url 'https://your-endpoint.example.com/ingest'
    option webhook_secret 'your-hmac-secret'

config wan 'wan_a'
    option interface 'wan'
    option probe_target '8.8.8.8'
    option probe_type 'icmp'
    option enabled '1'

config wan 'wan_b'
    option interface 'wan2'
    option probe_target '1.1.1.1'
    option probe_type 'icmp'
    option enabled '1'

Architecture

probes.lua  →  state.lua (feed)  →  store.lua (append event)
                              ↓
                         outbox.lua (signed webhook)
                              ↓
                         main.lua (procd poll loop)

Build / Test on Host

# Lint (Lua 5.1)
make lint

# Unit tests
make test

# Dry-run (parse config only)
lua5.1 src/balancerlite/main.lua --dry-run --config etc/config/balancerlite

Signing

Webhook payloads are signed with HMAC-SHA256. The signature header is:

X-Balancerlite-Signature: sha256=<hex-hmac>

License

Same as balancer-lite (GPL / MIT — pending)