# 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

```sh
# 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)

```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

```sh
# 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)