Say which bytes the byte limits count, and what passing one does (closes #203)

sneak asked for every document to be audited for sentences that do not say what they mean. The byte limits now say which bytes count (response bodies, request bodies or both, as `SWW_BYTES_COUNT` says, WebSocket traffic included) and what passing one does. Other unclear or false sentences in `README.md`, `SPEC.md`, `EVALUATION.md` and `docs/` are rewritten.

Documents only. `REPO_POLICIES.md` is shared policy text and stayed out.

Model: fable-5-1 (first audit); opus-5-5 (rework)

docs/metrics.md

@@ -5,6 +5,9 @@ What `GET /_sww/metrics` answers with, at `discriminator`'s own address.
 keeps the `instance` label as `exported_instance` unless the scrape sets
 `honor_labels: true`. `rproxy` has no metrics.
 
+Every `sww_*request_bytes_total` and `sww_*response_bytes_total` series counts
+body bytes, never headers, whatever `SWW_BYTES_COUNT` says.
+
 ## Traffic
 
 - `sww_requests_total`, `sww_request_bytes_total` and

docs/request-log.md

@@ -145,20 +145,22 @@ Every one of these lines has:
   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.
+    - `minute_bytes`, `hour_bytes` and `day_bytes`: the body bytes
+      `SWW_BYTES_COUNT` names, in that window.
 
     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.
+    [`SPEC.md`](../SPEC.md)). The bytes counted for an allowed request and its
+    response are added when its report comes. So on the `decision` line, the
+    three byte totals leave them out.
 
 - `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.
+    When the bytes counted for a request and its response break a limit, the
+    request has been 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.

docs/settings.md

@@ -98,6 +98,8 @@ between the two (see "The image's command" below).
 
 ## Request rate limits, per client
 
+The request past one of these limits is refused, and the client is banned.
+
 - `SWW_RATE_LIMIT_PER_MINUTE` (default `120`, 2 a second): the most requests a
   client may make in a minute. A count or `off`. The default leaves room for a
   person opening two pages at once with an empty cache, up to 60 files each.
@@ -120,11 +122,22 @@ between the two (see "The image's command" below).
 
 ## Byte limits, per client
 
+These count body bytes, never headers. What the visitor sent over a WebSocket
+counts as request bytes, and what the app sent as response bytes. The bytes
+counted for a request and its response are added to the client's total once the
+response has ended. The request that takes a client's total past a limit is not
+cut off; the client is banned.
+
 - `SWW_BYTES_LIMIT_PER_MINUTE` (default `off`), `SWW_BYTES_LIMIT_PER_HOUR`
   (default `50G`) and `SWW_BYTES_LIMIT_PER_DAY` (default `100G`): the most bytes
-  counted for a client in each window. A size or `off`.
-- `SWW_BYTES_COUNT` (default `both`): which body bytes the byte limits count:
-  `response`, `request` or `both`.
+  counted for a client in each window, a size or `off`. `SWW_BYTES_COUNT` says
+  which bytes count: response bodies, request bodies or both. The request that
+  passes the limit is not cut off, and the client is banned when its response
+  ends.
+- `SWW_BYTES_COUNT` (default `both`): what the byte limits and the byte anomaly
+  thresholds count: `response`, the app's response bodies; `request`, the
+  visitors' request bodies; or `both`. What the visitor sent over a WebSocket
+  counts as request bytes, and what the app sent as response bytes.
 
 ## Lookup of AS number and country
 
@@ -233,8 +246,9 @@ the request first.
   a range. So does a directive that removes or changes rules as the file loads,
   such as `SecRuleRemoveById`, since none of the Core Rule Set's rules is loaded
   yet. It has no `_FILE` form.
-- `SWW_ERROR_BURST_THRESHOLD` (default `30`): the most refusals of one client in
-  a minute (see "Attack detection" in `SPEC.md`). A count or `off`.
+- `SWW_ERROR_BURST_THRESHOLD` (default `30`): the most refusals a client may get
+  in a minute from a rule file, a trap path or the Core Rule Set, a count or
+  `off`. The next one bans the client (see "Attack detection" in `SPEC.md`).
 
 ## Ban lengths, response and scope
 
@@ -311,9 +325,10 @@ the request first.
 
 ## 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:
+Each scope has four thresholds: the most requests and the most body bytes
+counted in a minute and in an hour. The bytes are those `SWW_BYTES_COUNT` names.
+Requests are counts, bytes are sizes. Each is `off` by default. The four
+thresholds per client are:
 
 - `SWW_ANOMALY_CLIENT_REQUESTS_PER_MINUTE`;
 - `SWW_ANOMALY_CLIENT_REQUESTS_PER_HOUR`;

docs/state-files.md

@@ -61,7 +61,7 @@ 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;
+- body bytes of its requests, and of the responses it was sent;
 - 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.