rossedman/brownout

Dim an endpoint,
keep serving.

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
~ go run ./examples/basic
$ curl localhost:8080/reports/q3
hello from /reports/q3
$ curl -X PUT localhost:9090/rules/reports \
-d '{"path":"/reports/*","ttl":"10m"}'
{"id":"reports","path":"/reports/*",…}
$ curl -i localhost:8080/reports/q3
HTTP/1.1 503 Service Unavailable
$ curl -X DELETE localhost:9090/rules/reports
  • 21 nsper request with no rules installed
  • 0allocations on requests no rule matches
  • 0dependencies outside the standard library
  • 3ways to change rules: Go, HTTP or a watched file

The problem

A dependency is drowning.
Turn the load down.

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.

  • Takes effect on the next request: rules are swapped atomically
  • Shed all of a route, or let a set percentage of it through
  • Rules with a TTL lift by themselves, so a forgotten brownout can't outlast the incident
reportsshed expires in 10m

GET /reports/q3

Matched /reports/*, the first rule that applies
HTTP/1.1 503 Service Unavailable Content-Type: text/plain; charset=utf-8 Retry-After: 60 Service Unavailable
no rulepassed 0 allocs

GET /orders

No rule matches, so your handler serves it untouched

Core ideas

One small rule.
Three decisions.

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.

Match

path and method

An exact path, a prefix ending in *, or * for everything, optionally limited to some methods.

{"path": "/api/*",
 "methods": ["POST", "DELETE"]}

Let some through

partial brownouts

The default sheds everything. Set a percentage to cut load without switching the feature off.

{"path": "/search",
 "allow_percent": 20}

Expire

self-healing

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

Built for the request path.
Controlled from anywhere.

Lock-free hot path

Rules are read through an atomic pointer. Unmatched requests take no locks and make no allocations, and TestHotPathAllocations keeps it that way.

JSON admin API

Six endpoints to list, set, replace and remove rules. Mount it on an internal port, or behind your own auth.

Watched rules file

WatchFile reloads a JSON file when it changes, which fits a Kubernetes ConfigMap. An invalid file keeps the current rules.

Exceptions by order

The first matching rule decides, so an allow_percent 100 rule before a broad one exempts a path.

Your response, your metrics

WithResponder writes the shed response, WithOnShed counts it, and Check lets you degrade instead of reject.

Plain net/http

Standard http.Handler middleware with no dependencies. It works with any router built on net/http, on Go 1.24 and newer.

Quick start

Wire it in
in three steps.

You need Go 1.24 or newer and an existing http.Handler.

Full getting-started guide
  1. Install

    $ go get github.com/rossedman/brownout
  2. Wrap your app

    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())
  3. Brown out a route

    Shed /reports/* for ten minutes.

    $ curl -X PUT localhost:9090/rules/reports -d '{"path":"/reports/*","ttl":"10m"}'

Have the switch ready before you need it.

Free and open source under the MIT license.