rproxy: circuit breaker for asks to waf (closes #392)

Five asks that get no answer in time within five seconds open the
breaker. While open, a request takes
SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION without asking waf, except
one ask a second; the first answer closes it. Slow answers count as
failures. SPEC.md describes it.

The sww test that stops and restarts waf now waits for the breaker to
close before it expects the ban again.

Model: opus-5-5

README.md

@@ -2,7 +2,20 @@
 
 `smallwebwaf` is an MIT-licensed web application firewall, written in Go by
 [@sneak](https://sneak.berlin), for self-hosted web apps. It refuses the
-requests of scrapers, scanners and other abusers before they reach an app.
+requests of misbehaving scrapers, scanners and other abusers before they reach
+an app.
+
+With the default settings, a client is banned when it does any of these:
+
+- makes more than 120 requests in a minute, 1500 in an hour or 6000 in a day;
+- moves more than `50G` of request and response bodies in an hour, or `100G` in
+  a day;
+- asks for a secret or backup file, such as `/.env` or `/.git/config`;
+- sends a user agent that names a security scanner, such as `sqlmap` or `nikto`;
+- has more than 30 requests in a minute refused as probes or attacks.
+
+A scraper that does none of these is left alone. A scraper that waits 15 seconds
+between requests stays under the rate limits.
 
 ## What it does
 
@@ -10,11 +23,10 @@ A web application firewall reads each request on its way to a web app and
 refuses the ones that look like abuse. `smallwebwaf` is one program, `sww`,
 shipped in one image, with two commands that do this together:
 
-- `sww rproxy` is a small reverse proxy in front of one app. It sits behind the
-  reverse proxy that terminates TLS, such as traefik, nginx or Caddy. It asks
-  `waf` about each request, passes the allowed ones to the app, and passes the
-  app's answers back. It keeps nothing between requests and writes nothing to
-  disk.
+- `sww rproxy` is a small reverse proxy in front of one app. It sits behind a
+  TLS-terminating proxy, such as traefik, nginx or Caddy. It asks `waf` about
+  each request, passes the allowed ones to the app, and passes the app's answers
+  back. It writes nothing to disk.
 - `sww waf` decides. It runs the checks and keeps the bans, the counters and
   each client's history. One `waf` serves many sites: a client banned through
   one site is refused on all of them, and its requests on all of them count
@@ -23,7 +35,26 @@ shipped in one image, with two commands that do this together:
 The site keeps answering while `waf` is down, slow or restarting: without an
 answer in time, `rproxy` passes the request to the app.
 
-It protects against:
+`rproxy` also protects the app on its own, whether or not `waf` answers. With
+the default settings, `rproxy`:
+
+- answers `400` to a malformed request, such as a broken header line or a
+  missing `Host`;
+- answers `405` to a method it does not pass on, such as `TRACE`;
+- answers `431` to a request line and headers over 32 KiB together;
+- gives the visitor 60 seconds to send the request line and headers, and then 60
+  seconds more for the whole request to reach the app;
+- answers `413` to a request body over 100 MiB;
+- gives the app's answer 30 minutes to reach the visitor, counted from the end
+  of the request;
+- answers `502` in place of an app's answer whose body is over 1 GiB, or cuts it
+  off if it has started;
+- closes a kept-open connection after 120 seconds idle.
+
+`rproxy` does not limit the number of headers. `waf` limits the number of
+headers and cookies, and the length of the request line and of each header line.
+
+Together, `rproxy` and `waf` protect against:
 
 - Scrapers that fetch every page of a site, all day. Each client gets a limit on
   requests and on body bytes per minute, per hour and per day. The defaults
@@ -45,8 +76,6 @@ It protects against:
       limit, so that they are banned sooner;
     - refuse or limit clients on a blocklist, a DNS blocklist, or with a high
       AbuseIPDB score.
-- Slow and oversized requests. Every request and every answer has a time limit
-  and a size limit.
 
 For the operator, it:
 
@@ -58,8 +87,7 @@ For the operator, it:
 
 Not built, and not planned:
 
-- TLS and routing by host name. Both stay with the reverse proxy in front of
-  `rproxy`.
+- TLS and routing by host name. Both stay with the TLS-terminating proxy.
 - Browser challenges such as captchas.
 - A web console, or a configuration file.
 - Defence against floods large enough to fill the host's network link.
@@ -91,9 +119,9 @@ accepts connections, whether or not `waf` answers; in `waf`'s container, once
 The usual setup is three containers on one private network:
 
 - the app;
-- `rproxy`, in front of the app, which the reverse proxy that terminates TLS
-  forwards to: `SWW_RPROXY_WAF_BACKEND` names `waf` and
-  `SWW_RPROXY_UPSTREAM_URL` names the app;
+- `rproxy`, in front of the app, which the TLS-terminating proxy forwards to:
+  `SWW_RPROXY_WAF_BACKEND` names `waf` and `SWW_RPROXY_UPSTREAM_URL` names the
+  app;
 - `waf`, with `SWW_COMMAND=waf` and a volume at `/var/lib/sww` for its state
   files.
 
@@ -103,26 +131,39 @@ you trust. Each further app adds its own container and its own `rproxy`, whose
 `SWW_RPROXY_WAF_BACKEND` names the same `waf`. The "Smallest setup" example
 below shows this shape.
 
-### The reverse proxy in front
+### The TLS-terminating proxy
 
-`rproxy` serves plain HTTP. It runs behind any reverse proxy that terminates
-TLS, such as traefik, nginx or Caddy. That proxy must:
+`rproxy` serves plain HTTP. It runs behind any TLS-terminating proxy, such as
+traefik, nginx or Caddy. The TLS-terminating proxy must:
 
 - forward each request to port 8080 of `rproxy` over plain HTTP;
 - keep the visitor's `Host` header;
 - add the visitor's address to `X-Forwarded-For`;
 - set `X-Forwarded-Proto` to the scheme the visitor used;
+- close an unused connection to `rproxy` in under 120 seconds;
 - connect to `rproxy` from an address in `SWW_RPROXY_TRUSTED_PROXIES`, by
   default `10.0.0.0/8`, `172.16.0.0/12` or `192.168.0.0/16`.
 
 From any other address, `rproxy` ignores the forwarded headers and takes the
-proxy for the visitor. Every visitor then shares one address, and one ban.
+TLS-terminating proxy for the visitor. Every visitor then shares one address,
+and one ban.
 
 traefik and Caddy keep the `Host` header and set both forwarded headers by
 default. traefik's Docker label
-`traefik.http.services.<name>.loadbalancer.server.port=8080` names the port, and
-Caddy's `reverse_proxy rproxy:8080` needs nothing more. nginx sets none of the
-headers by default, so its site names them:
+`traefik.http.services.<name>.loadbalancer.server.port=8080` names the port.
+Caddy keeps an unused connection for 120 seconds by default, so its site
+shortens that to 90 seconds:
+
+```caddyfile
+reverse_proxy rproxy:8080 {
+    transport http {
+        keepalive 90s
+    }
+}
+```
+
+By default nginx sends the host in `proxy_pass` as `Host` and sets neither
+forwarded header, so its site sets all three:
 
 ```nginx
 location / {
@@ -183,8 +224,8 @@ entrypoint starts `rproxy` and the app side by side, each as its own user. Run
 the app's image with `SWW_RPROXY_WAF_BACKEND` set. `deploy/example-app` is such
 an app, and the "`rproxy` beside the app" example below runs one.
 
-The app sees the headers the reverse proxy in front sent, with that proxy's
-address added to `X-Forwarded-For`, from a TCP peer that is `rproxy`. So the app
+The app's TCP peer is `rproxy`. The app sees the headers the TLS-terminating
+proxy sent, with that proxy's address added to `X-Forwarded-For`. So the app
 must trust `rproxy`'s address for forwarded headers. In a container of its own,
 `rproxy` is on the private network, which the usual default of a trusted-proxy
 setting covers. Beside the app, its address is `127.0.0.1` or `::1`, which the
@@ -197,9 +238,9 @@ private ranges leave out, so the app's own setting must name them too, as
   `healthy` for each container of `smallwebwaf`.
 - A log line with `"msg":"starting"` gives the version, the address and every
   setting in effect, with secrets masked.
-- A request to the site through the reverse proxy in front gets the app's
-  answer. `https://<site>/_sww/healthz` answers `ok`. `waf`'s log lines about
-  the request have `"action":"forward"`.
+- A request to the site through the TLS-terminating proxy gets the app's answer.
+  `https://<site>/_sww/healthz` answers `ok`. `waf`'s log lines about the
+  request have `"action":"forward"`.
 - To see a refusal without banning yourself, run `waf` with
   `SWW_WAF_MODE=observe` and ask for `/.env`. The request reaches the app.
   `waf`'s log lines have `"would_action":"temporarily_banned"` and

SPEC.md

@@ -3,8 +3,7 @@
 `smallwebwaf` is a web application firewall for self-hosted apps. It is one
 binary, `sww`, and two of its commands do the work:
 
-- `sww rproxy` is a reverse proxy between one app and the reverse proxy that
-  terminates TLS.
+- `sww rproxy` is a reverse proxy between a TLS-terminating proxy and one app.
 - `sww waf` decides what happens to each request, for many sites.
 
 This document says what it must do and why, each requirement once. Everything in
@@ -46,8 +45,8 @@ never as a time.
 
 ## Non-goals
 
-- TLS, certificates and routing by host name. Those are the job of the reverse
-  proxy in front of `rproxy`, such as traefik, nginx or Caddy.
+- TLS, certificates and routing by host name. Those are the job of the
+  TLS-terminating proxy, such as traefik, nginx or Caddy.
 - More than one app behind one `rproxy`. Each app has its own.
 - Browser challenges such as captchas or proof of work. If wanted, chain Anubis
   between `rproxy` and the app.
@@ -1946,7 +1945,7 @@ leave out a cookie only when its name matches exactly, case included.
 
 `SWW_WAF_BAN_RESPONSE` is `403` by default, which makes a ban easy to recognise
 when debugging; `429` and `close` are the alternatives. `close` does not leave
-the client unanswered: the reverse proxy in front answers `502`, as it does
+the client unanswered: the TLS-terminating proxy answers `502`, as it does
 whenever its backend drops a connection. `SWW_WAF_BAN_SCOPE_V4_PREFIX` widens an
 IPv4 ban to the surrounding netblock. The four ban lengths are under "Bans".
 
@@ -2584,9 +2583,10 @@ request and ban notes name the site by its host.
 ## `rproxy`
 
 `sww rproxy` is the reverse proxy in front of one app. It asks `waf` about each
-request, and passes on what `waf` allows. It keeps nothing between requests and
-writes nothing to disk. When `waf` cannot be connected to, does not answer at
-all, or does not answer within `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`,
+request, and passes on what `waf` allows. It writes nothing to disk. The only
+thing it keeps between requests is its circuit breaker for asks to `waf`. When
+`waf` cannot be connected to, does not answer at all, or does not answer within
+`SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`,
 `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides. Its default, `allow`,
 keeps the site answering.
 
@@ -2680,14 +2680,15 @@ log line has status `0`.
 ### Without an answer from `waf`
 
 `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides what is done with the
-request only when `waf`:
+request when `waf`:
 
 - cannot be connected to;
 - does not answer at all;
 - does not answer within `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`, which covers
   connecting, sending the question and reading the whole answer.
 
-An answer whose body breaks off counts as no answer at all.
+An answer whose body breaks off counts as no answer at all. The setting also
+decides, without asking `waf`, while the circuit breaker is open.
 
 `allow`, the default, passes the request to the app. `deny` answers `503`.
 Either way `rproxy` writes a process warning, its log line has
@@ -2711,6 +2712,31 @@ A visitor that goes away while `waf` is being asked is no failure of `waf`.
 `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` does not apply. Its log line has
 status `0` and no `disposition`.
 
+### The circuit breaker
+
+`rproxy` stops asking `waf` for a while when `waf` keeps failing to answer. An
+ask fails when `waf` cannot be connected to, does not answer at all, or does not
+answer within `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`. Any answer in time succeeds,
+whatever it decides, and so does an answer `rproxy` cannot pass on. A visitor
+that goes away while `waf` is being asked counts as neither.
+
+The breaker works like this:
+
+- It opens when 5 asks fail within 5 seconds. Fewer failures never open it.
+- While it is open, a request gets
+  `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` at once, without asking `waf`.
+  It gets the same process warning and `waf_backend_no_answer` as a request
+  whose ask failed.
+- While it is open, one request a second still asks `waf`.
+- The first ask that succeeds closes it, and the failures before it no longer
+  count.
+
+A request that `waf` cannot decide within `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`
+counts as a failure too. Such a request is a bug in `waf`.
+
+The breaker lives in memory, and a restart of `rproxy` closes it. It has no
+settings.
+
 ### Passing a request to the app
 
 `rproxy` sends the app at `SWW_RPROXY_UPSTREAM_URL` the visitor's request: the
@@ -2773,10 +2799,9 @@ its whole body. The visitor gets that answer at once, and the connection closes
 after it.
 
 The largest request line and headers is 32 KiB. A kept-open connection is closed
-after 120 seconds idle. Neither has a setting. The reverse proxy in front should
+after 120 seconds idle. Neither has a setting. The TLS-terminating proxy should
 close an unused connection sooner, so that it never sends a request on a
 connection `rproxy` is closing. traefik closes one after 90 seconds by default.
-nginx, by default, opens a new connection for each request.
 
 What the visitor gets when a limit is passed:
 
@@ -2827,7 +2852,7 @@ chooses: `waf` runs `waf`, and with it unset the image runs `rproxy`.
 The usual setup is three containers on one private network:
 
 - the app;
-- `rproxy`, which the reverse proxy that terminates TLS forwards to, with
+- `rproxy`, which the TLS-terminating proxy forwards to, with
   `SWW_RPROXY_UPSTREAM_URL` naming the app and `SWW_RPROXY_WAF_BACKEND` naming
   `waf`;
 - `waf`, with `SWW_COMMAND=waf` and a volume for its state files.
@@ -2835,8 +2860,8 @@ The usual setup is three containers on one private network:
 Each further app adds its own container and its own `rproxy`, whose
 `SWW_RPROXY_WAF_BACKEND` names the same `waf` (see "Sites"). Anything on that
 network can reach an app around `rproxy`, and can ask `waf` questions or send it
-reports. So the network holds only what you trust. "The reverse proxy in front"
-in `README.md` lists what that proxy must do.
+reports. So the network holds only what you trust. `README.md` lists what the
+TLS-terminating proxy must do.
 
 ### `rproxy` in the app's container
 
@@ -2908,10 +2933,10 @@ process that stops at start is started again every second, not in a tight loop.
   container's output, which `docker logs` shows.
 - When a service exits, runit runs its `run` script again, and the container
   does not stop. Beside an app, the other process keeps running.
-- While `rproxy` is down, the reverse proxy in front answers `502`. While the
-  app is down, `rproxy` answers `502`, which is not a client offence. While
-  `waf` is down, `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides (see
-  "Without an answer from `waf`").
+- While `rproxy` is down, the TLS-terminating proxy answers `502`. While the app
+  is down, `rproxy` answers `502`, which is not a client offence. While `waf` is
+  down, `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides (see "Without an
+  answer from `waf`").
 - Only faults found at start stop `waf`:
     - invalid configuration;
     - a lookup database that is missing or unreadable;
@@ -2944,24 +2969,24 @@ checks:
 - With `SWW_COMMAND` unset, empty or `rproxy`, it passes while `rproxy` answers
   that request on `127.0.0.1`, at the port in `SWW_RPROXY_LISTEN_ADDR`, and the
   app accepts connections at `SWW_RPROXY_UPSTREAM_URL`. It does not ask `waf`,
-  so that the site stays in the routes of the reverse proxy in front while `waf`
-  is down.
+  so that the site stays in the TLS-terminating proxy's routes while `waf` is
+  down.
 - With any other value, it fails with a message naming `SWW_COMMAND` and its
   value.
 
-A reverse proxy that reads Docker's health status, as traefik does, sends a
-container no requests until it shows as healthy. So the check runs every second
-from the container's start until it first passes, for up to a minute, and every
-30 seconds after that. An app with a health check of its own can replace the
-image's `HEALTHCHECK` with one that checks both.
+A TLS-terminating proxy that reads Docker's health status, as traefik does,
+sends a container no requests until it shows as healthy. So the check runs every
+second from the container's start until it first passes, for up to a minute, and
+every 30 seconds after that. An app with a health check of its own can replace
+the image's `HEALTHCHECK` with one that checks both.
 
 ### Ports
 
 `rproxy` listens on no port but the one in `SWW_RPROXY_LISTEN_ADDR`, 8080 by
-default, which the reverse proxy in front forwards to. It passes requests to the
+default, which the TLS-terminating proxy forwards to. It passes requests to the
 app at `SWW_RPROXY_UPSTREAM_URL`, `http://127.0.0.1:8081` by default. Another
-port may be set: the health check follows the setting, and the reverse proxy in
-front must name it, as traefik's port label
+port may be set: the health check follows the setting, and the TLS-terminating
+proxy must name it, as traefik's port label
 (`traefik.http.services.<name>.loadbalancer.server.port`) does. An app beside
 `rproxy` must leave that port free.
 
@@ -2985,8 +3010,8 @@ host directory, keeps them across deploys. A host directory mounted there needs
 no change of owner, and files an earlier owner left in it can be read and
 replaced. The volume holds a few tens of MiB at most with the defaults, and
 needs no backup beyond the host's own. The image declares no volume, since every
-app image built on it would inherit it. `rproxy` keeps nothing, and needs no
-volume.
+app image built on it would inherit it. `rproxy` writes nothing to disk, and
+needs no volume.
 
 `waf` keeps its cache files in `SWW_WAF_CACHE_DIR`, `/var/cache/sww` by default,
 which the `run` script makes. The cache directory needs no volume and can be
@@ -3004,9 +3029,9 @@ in `docs/settings.md` shows the commands.
 ### Forwarded headers
 
 The app's TCP peer is `rproxy`, and the `X-Forwarded-For` the app receives ends
-with the address of the reverse proxy in front, which `rproxy` adds after the
+with the TLS-terminating proxy's address, which `rproxy` adds after the
 visitor's. So the app must trust `rproxy`'s address for forwarded headers,
-besides the private address ranges that proxy is on.
+besides the private address ranges the TLS-terminating proxy is on.
 
 - In a container of its own, `rproxy`'s address is on the private network. The
   usual default for a trusted-proxy setting, the private ranges, covers it.

docs/request-log.md

@@ -68,8 +68,8 @@ Every one of these lines has:
 ### Request detail
 
 - `request_id`: the id `rproxy` made for the request when it arrived.
-- `peer_ip`: the address of `rproxy`'s TCP peer, normally the reverse proxy in
-  front of it.
+- `peer_ip`: the address of `rproxy`'s TCP peer, normally the TLS-terminating
+  proxy.
 - `forwarded_for`: the `X-Forwarded-For` header the visitor's request came with.
 - `client_group`: the client as rate limiting counts it, an IPv4 address as a
   /32 or an IPv6 group.

docs/settings.md

@@ -454,9 +454,10 @@ start, and an invalid value stops the start. Any can be given as a file, as a
   never `off`.
 - `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` (default `allow`): what is done
   with a request when `waf` cannot be connected to, does not answer at all, or
-  does not answer within `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`. `allow` passes it
-  to the app, and `deny` answers `503`. It does not apply to an answer `waf`
-  gives, such as an error.
+  does not answer within `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS`, and while the
+  circuit breaker for asks to `waf` is open. `allow` passes it to the app, and
+  `deny` answers `503`. It does not apply to an answer `waf` gives, such as an
+  error.
 - `SWW_RPROXY_MAX_REQUEST_SIZE` (default `100M`): the largest request body. A
   size or `off`.
 - `SWW_RPROXY_MAX_RESPONSE_SIZE` (default `1G`): the largest response body. A
@@ -478,9 +479,9 @@ start, and an invalid value stops the start. Any can be given as a file, as a
   `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`): the netblocks whose
   `X-Forwarded-For` is believed. Set but empty, it trusts nothing. A client
   outside these netblocks cannot claim another address. Where other containers
-  reach `rproxy` directly, or visitors on a private network reach the reverse
-  proxy in front, they can name another address in the header. Narrowing the
-  setting to that proxy's own network closes that gap.
+  reach `rproxy` directly, or visitors on a private network reach the
+  TLS-terminating proxy, they can name another address in the header. Narrowing
+  the setting to the TLS-terminating proxy's own network closes that gap.
 
 ## The image's command
 

internal/rproxy/breaker.go

@@ -0,0 +1,83 @@
+package rproxy
+
+import (
+	"errors"
+	"sync"
+	"time"
+)
+
+// What opens the circuit breaker, and how often a request asks waf while it is
+// open.
+const (
+	breakerFailures    = 5
+	breakerWindow      = 5 * time.Second
+	breakerAskInterval = time.Second
+)
+
+// errBreakerOpen is why a request did not ask waf.
+var errBreakerOpen = errors.New(
+	"waf is not asked while the circuit breaker is open",
+)
+
+// breaker is the circuit breaker for asks to waf. It opens when
+// breakerFailures asks fail within breakerWindow. An ask fails when it gets no
+// answer in time. While it is open, at most one request each breakerAskInterval
+// asks waf. The first answer closes it, whatever it decides.
+type breaker struct {
+	mu sync.Mutex
+	// failures holds the times of the latest failed asks, oldest first, at most
+	// breakerFailures of them.
+	failures []time.Time
+	open     bool
+	// lastAsk is when a request last asked waf while the breaker was open.
+	lastAsk time.Time
+}
+
+// mayAsk reports whether a request may ask waf at now. While the breaker is
+// open, it says yes once each breakerAskInterval.
+func (b *breaker) mayAsk(now time.Time) bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if !b.open {
+		return true
+	}
+
+	if now.Sub(b.lastAsk) < breakerAskInterval {
+		return false
+	}
+
+	b.lastAsk = now
+
+	return true
+}
+
+// noteAnswer notes that an ask got an answer in time. It closes the breaker,
+// and forgets the failures before it.
+func (b *breaker) noteAnswer() {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if b.open {
+		b.open = false
+		b.failures = nil
+	}
+}
+
+// noteFailure notes that an ask that ended at now got no answer in time, and
+// opens the breaker if breakerFailures asks have failed within breakerWindow.
+func (b *breaker) noteFailure(now time.Time) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.failures = append(b.failures, now)
+	if len(b.failures) > breakerFailures {
+		b.failures = b.failures[1:]
+	}
+
+	if !b.open && len(b.failures) == breakerFailures &&
+		now.Sub(b.failures[0]) <= breakerWindow {
+		b.open = true
+		b.lastAsk = now
+	}
+}

internal/rproxy/breaker_test.go

@@ -0,0 +1,142 @@
+package rproxy_test
+
+import (
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/rproxy"
+)
+
+// The breaker tests give the breaker each time themselves, counted from
+// time.Now(), and never wait.
+
+// fail notes count failed asks on b, one each step from at.
+func fail(b *rproxy.Breaker, at time.Time, count int, step time.Duration) {
+	for i := range count {
+		b.NoteFailure(at.Add(time.Duration(i) * step))
+	}
+}
+
+// openBreaker returns a breaker opened at now by five failed asks, one a
+// second.
+func openBreaker(now time.Time) *rproxy.Breaker {
+	b := &rproxy.Breaker{}
+	fail(b, now.Add(-4*time.Second), 5, time.Second)
+
+	return b
+}
+
+func TestFourFailedAsksWithinFiveSecondsLeaveTheBreakerClosed(t *testing.T) {
+	t.Parallel()
+
+	now := time.Now()
+	b := &rproxy.Breaker{}
+	fail(b, now, 4, time.Second)
+
+	if !b.MayAsk(now.Add(3 * time.Second)) {
+		t.Error("a request may not ask, want it to")
+	}
+}
+
+func TestFiveFailedAsksWithinFiveSecondsOpenTheBreaker(t *testing.T) {
+	t.Parallel()
+
+	now := time.Now()
+	b := openBreaker(now)
+
+	if b.MayAsk(now) {
+		t.Error("a request may ask, want it not to")
+	}
+}
+
+func TestFiveFailedAsksOverMoreThanFiveSecondsLeaveTheBreakerClosed(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	now := time.Now()
+	b := &rproxy.Breaker{}
+	fail(b, now, 5, 1300*time.Millisecond)
+
+	if !b.MayAsk(now.Add(6 * time.Second)) {
+		t.Error("a request may not ask, want it to")
+	}
+}
+
+func TestAnAnswerBeforeTheBreakerOpensDoesNotForgetFailures(t *testing.T) {
+	t.Parallel()
+
+	now := time.Now()
+	b := &rproxy.Breaker{}
+	fail(b, now, 4, time.Millisecond)
+	b.NoteAnswer()
+	b.NoteFailure(now.Add(time.Second))
+
+	if b.MayAsk(now.Add(time.Second)) {
+		t.Error("a request may ask, want it not to")
+	}
+}
+
+func TestAnOpenBreakerLetsOneRequestAskEachSecond(t *testing.T) {
+	t.Parallel()
+
+	now := time.Now()
+	b := openBreaker(now)
+
+	for _, tc := range []struct {
+		after time.Duration
+		want  bool
+	}{
+		{999 * time.Millisecond, false},
+		{time.Second, true},
+		{time.Second, false},
+		{1500 * time.Millisecond, false},
+		{2 * time.Second, true},
+	} {
+		got := b.MayAsk(now.Add(tc.after))
+		if got != tc.want {
+			t.Errorf("may ask %v after it opened: %v, want %v",
+				tc.after, got, tc.want)
+		}
+	}
+}
+
+func TestAFailedAskKeepsTheBreakerOpen(t *testing.T) {
+	t.Parallel()
+
+	opened := time.Now()
+	b := openBreaker(opened)
+	now := opened.Add(time.Second)
+	b.MayAsk(now)
+	b.NoteFailure(now)
+
+	if b.MayAsk(now.Add(999 * time.Millisecond)) {
+		t.Error("a request may ask, want it not to")
+	}
+
+	if !b.MayAsk(now.Add(time.Second)) {
+		t.Error("a request may not ask a second later, want it to")
+	}
+}
+
+func TestOneAnswerClosesTheBreaker(t *testing.T) {
+	t.Parallel()
+
+	opened := time.Now()
+	b := openBreaker(opened)
+	now := opened.Add(time.Second)
+	b.MayAsk(now)
+	b.NoteAnswer()
+
+	if !b.MayAsk(now) {
+		t.Error("a request may not ask, want it to")
+	}
+
+	// The failures before the answer no longer count, so one more does not open
+	// the breaker again.
+	b.NoteFailure(now)
+
+	if !b.MayAsk(now) {
+		t.Error("a request may not ask after one failure, want it to")
+	}
+}

internal/rproxy/export_test.go

@@ -0,0 +1,23 @@
+package rproxy
+
+import "time"
+
+// Breaker is the circuit breaker, for tests that give it the time.
+type Breaker struct {
+	b breaker
+}
+
+// MayAsk reports whether a request may ask waf at now.
+func (b *Breaker) MayAsk(now time.Time) bool {
+	return b.b.mayAsk(now)
+}
+
+// NoteAnswer notes that an ask got an answer in time.
+func (b *Breaker) NoteAnswer() {
+	b.b.noteAnswer()
+}
+
+// NoteFailure notes that an ask that ended at now got no answer in time.
+func (b *Breaker) NoteFailure(now time.Time) {
+	b.b.noteFailure(now)
+}

internal/rproxy/rproxy.go

@@ -4,10 +4,11 @@
 // waf goes to the visitor as waf gave it.
 // SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION decides only when waf cannot
 // be connected to, does not answer at all, or does not answer within
-// SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS. rproxy itself refuses a request with a
-// method it does not pass on, or one it cannot put to waf as the visitor
-// sent it. It keeps nothing between requests and writes nothing to disk. "rproxy" in
-// SPEC.md says what it does.
+// SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS, or while the circuit breaker for asks to
+// waf is open. rproxy itself refuses a request with a method it does not pass
+// on, or one it cannot put to waf as the visitor sent it. It keeps nothing
+// between requests but the circuit breaker, and writes nothing to disk.
+// "rproxy" in SPEC.md says what it does.
 package rproxy
 
 import (
@@ -132,6 +133,8 @@ type handler struct {
 	wafTransport http.RoundTripper
 	// reportURL is where the reports go.
 	reportURL string
+	// breaker is the circuit breaker for asks to waf.
+	breaker breaker
 	// reports waits for the reports being sent. reportsMu guards starting one
 	// against reportsStopped, which is set once nothing is to wait for another.
 	reports        sync.WaitGroup
@@ -196,7 +199,7 @@ func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	answer, err := rq.ask(r.Context())
+	answer, err := rq.askUnlessBreakerOpen(r.Context())
 	if err != nil {
 		rq.handleNoUsableAnswer(r.Context(), err)
 

internal/rproxy/rproxy_test.go

@@ -15,6 +15,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -1395,6 +1396,62 @@ func TestSendsNoReportWithoutAnAnswer(t *testing.T) {
 	standIn.wantNoReport(t)
 }
 
+func TestFiveFailedAsksKeepTheNextRequestFromAskingWAF(t *testing.T) {
+	t.Parallel()
+
+	for name, failure := range map[string]http.HandlerFunc{
+		"no answer at all": func(http.ResponseWriter, *http.Request) {
+			panic(http.ErrAbortHandler)
+		},
+		"a slow answer": func(_ http.ResponseWriter, r *http.Request) {
+			<-r.Context().Done()
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var answering atomic.Bool
+
+			standIn := startWAF(
+				t,
+				func(w http.ResponseWriter, r *http.Request) {
+					if answering.Load() {
+						allow(w, r)
+
+						return
+					}
+
+					failure(w, r)
+				},
+			)
+			app := startApp(t, greet)
+			addr, out := startRProxy(
+				t,
+				standIn.URL,
+				app.URL,
+				map[string]string{
+					wafBackendTimeout: "200",
+				},
+			)
+
+			for range 5 {
+				wantGreeting(t, get(t, addr, "/"))
+				standIn.question(t)
+			}
+
+			answering.Store(true)
+			wantGreeting(t, get(t, addr, "/"))
+			out.waitFor(t, "the circuit breaker is open")
+
+			select {
+			case <-standIn.questions:
+				t.Error("waf was asked, want it not to be")
+			case <-time.After(10 * pollInterval):
+			}
+		})
+	}
+}
+
 func TestAPathUnderOwnPrefixNeverReachesTheApp(t *testing.T) {
 	t.Parallel()
 

internal/rproxy/waf.go

@@ -10,6 +10,7 @@ import (
 	"maps"
 	"net/http"
 	"strings"
+	"time"
 
 	"sneak.berlin/go/smallwebwaf/internal/waf"
 )
@@ -67,7 +68,8 @@ func (rq *request) handleNoUsableAnswer(ctx context.Context, err error) {
 		rq.answer(http.StatusBadGateway)
 	default:
 		// waf cannot be connected to, does not answer at all, or does not answer
-		// within SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS. A request that keeps waf
+		// within SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS; or the circuit breaker
+		// kept the request from asking. A request that keeps waf
 		// busy past SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS, like any request while
 		// waf is overloaded, gets SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION
 		// here. deny closes this, at the cost of answering 503 whenever waf is
@@ -86,6 +88,31 @@ func (rq *request) handleNoUsableAnswer(ctx context.Context, err error) {
 	}
 }
 
+// askUnlessBreakerOpen asks waf, unless the circuit breaker is open and it is
+// not yet time for a request to ask. It then tells the breaker whether waf
+// answered in time. An answer rproxy cannot pass on still came in time. A
+// visitor that goes away tells the breaker nothing. ctx is the request's own
+// context.
+func (rq *request) askUnlessBreakerOpen(
+	ctx context.Context,
+) (*wafAnswer, error) {
+	b := &rq.h.breaker
+	if !b.mayAsk(time.Now()) {
+		return nil, errBreakerOpen
+	}
+
+	answer, err := rq.ask(ctx)
+
+	switch {
+	case err == nil, errors.Is(err, errCannotPassOn):
+		b.noteAnswer()
+	case ctx.Err() == nil:
+		b.noteFailure(time.Now())
+	}
+
+	return answer, err
+}
+
 // ask sends waf the question, and returns its answer, which must have come
 // whole within SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS. It ends when ctx does, as
 // when the visitor goes away.

internal/sww/rproxy_test.go

@@ -260,7 +260,17 @@ func TestTheSiteAnswersWhileWAFIsStoppedAndStartedAgain(t *testing.T) {
 		stop()
 	}()
 
-	wantStatus(t, site+"/", placed, http.StatusForbidden)
+	// The visitor's asks have opened rproxy's circuit breaker, which lets one
+	// request a second ask until one is answered.
+	deadline := time.Now().Add(waitLimit)
+	for statusFrom(t, site+"/", placed) != http.StatusForbidden {
+		if time.Now().After(deadline) {
+			t.Fatalf("request from %s: never answered %d", placed,
+				http.StatusForbidden)
+		}
+
+		time.Sleep(pollInterval)
+	}
 
 	close(visitorStop)
 	<-visitorDone