clips-proxy-gov: rule-based governor for proxy pool routing
clips-proxy-gov is an online governor that continuously steers request traffic toward the best-performing proxy providers. For every service it watches the live health of each pool and adjusts that pool’s routing weight, the share of traffic it receives. Weight gets pulled away from pools that start to degrade and handed back gradually as they recover. The goal is to keep overall success rates and latency good without a human reacting to every incident.
The decision logic is a rule-based expert system written in
CLIPS (gov.clp).
A small C harness (main.c)
feeds it observations one cycle at a time and applies the weight
changes it emits. Because the policy is just rules, operators can
read and audit it without touching the harness.
Goals
- Keep aggregate success rate and latency healthy by shifting traffic away from degrading pools and back to them as they recover, automatically on every cycle.
- Express the policy as rules, so operators can read and audit what the governor will do before it does it.
- Separate concerns cleanly: CLIPS owns operational state across cycles (degradation status, healthy-since timers); the harness owns the effective-weight matrix and carries it forward.
- Stay safe under wide failure: when too many of a service’s pools are degraded at once, suspend cuts rather than gut the whole service.
How it works
Routing is expressed as integer weights per (pool, service). Each
pool has a base weight (the operator’s default preference) and
an effective weight (what the governor is currently using). The
governor only ever moves the effective weight within
min_weight ≤ effective_weight ≤ base_weight, so it
can throttle a bad pool down to a floor and restore it up to, but
never above, its baseline.
Each cycle, fresh per-pool/per-service observations are injected as
facts: success rate, response time, timeout rate, SSL-error rate,
plus the rolling average and standard deviation of success rate and
response time. CLIPS fires its rules to detect degradation, roll
degradation up to a service-wide view, reduce weight on degrading
pools, and restore weight on recovered ones. The harness then
applies whatever weight-adjustment and
alert facts the rules produced.
A pool is flagged as degraded when response time exceeds
avg + σ×stddev (or a hard ceiling), success
rate falls below avg − σ×stddev (or a
hard floor), SSL errors exceed 5%, or timeouts exceed 10%. A first
reduction multiplies the weight by weight_reduction;
severe departures (>3σ) get cut again. Restoration is
deliberately gradual: a pool that has been healthy longer than
restore_cooldown steps its weight back up by
base_weight / 4 per cycle, so a flapping pool
doesn’t immediately reclaim full traffic.
Running it
The project targets OpenBSD: the build uses BSD
make, and the binary calls pledge(2) and
unveil(2). It runs in two modes:
- Simulation.
./gov-simgenerates synthetic pool health (periodic incidents and recoveries) to exercise the rules end to end. - Replay.
./gov-sim -r scenarios/foo.ppsdrives the governor from a recorded scenario file, so the same observation stream can be replayed against different parameter settings. Seescenario.hfor the file format andscenario.Rfor tooling to read, write, generate, and analyze scenarios.
Where to start reading
README.md. The design doc. Draws a hard line between what the rules implement today and what is still intended (capacity awareness, time-of-day shifts, probation/flap handling, trend detection).gov.clp. The rule base. When this and the README disagree, the rules are what actually runs.main.c. The harness that drives the cycle loop, seedingservice-configfacts and applying weight adjustments.scenarios/. Recorded observation streams for replay.
License
AGPL-3.0-or-later · Copyright © 2026 SWGY, Inc. See LICENSE for the full text.