GET /reports/q3
/reports/*, the first rule that appliesrossedman/brownout
Go HTTP middleware that sheds some or all traffic to the routes you choose, while the server keeps running. No restart, no deploy, no dependencies.
go get github.com/rossedman/brownout
The problem
When the database behind your reports page starts to fall over, the fix in the moment is to stop sending it traffic. Usually that means a config change and a redeploy, in the middle of an incident. brownout lets you shed that one route right now, then lift the rule when the incident is over.
/reports/*, the first rule that appliesCore ideas
A rule says which requests it matches, how many of them to let through, and when to stop applying. Rules are checked in order, and the first match decides.
An exact path, a prefix ending in *, or * for everything, optionally limited to some methods.
{"path": "/api/*",
"methods": ["POST", "DELETE"]}
The default sheds everything. Set a percentage to cut load without switching the feature off.
{"path": "/search",
"allow_percent": 20}
Give a rule a TTL through the admin API, or an ExpiresAt in Go, and it lifts by itself.
{"path": "/reports/*",
"ttl": "10m"}
Why brownout
Rules are read through an atomic pointer. Unmatched requests take no locks and make no allocations, and TestHotPathAllocations keeps it that way.
Six endpoints to list, set, replace and remove rules. Mount it on an internal port, or behind your own auth.
WatchFile reloads a JSON file when it changes, which fits a Kubernetes ConfigMap. An invalid file keeps the current rules.
The first matching rule decides, so an allow_percent 100 rule before a broad one exempts a path.
WithResponder writes the shed response, WithOnShed counts it, and Check lets you degrade instead of reject.
Standard http.Handler middleware with no dependencies. It works with any router built on net/http, on Go 1.24 and newer.
Quick start
You need Go 1.24 or newer and an existing http.Handler.
$ go get github.com/rossedman/brownout
Serve the admin API on an internal-only listener.
c := brownout.New()
go http.ListenAndServe(":8080", c.Middleware(app))
http.ListenAndServe("127.0.0.1:9090", c.AdminHandler())
Shed /reports/* for ten minutes.
$ curl -X PUT localhost:9090/rules/reports -d '{"path":"/reports/*","ttl":"10m"}'
Documentation
Free and open source under the MIT license.