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

Documents only. The byte limits and byte anomaly thresholds count body
bytes, as SWW_BYTES_COUNT chooses them, with WebSocket traffic each way,
once a response has ended; the request that passes a limit is not cut
off and the client is banned. README.md, SPEC.md and docs/ now say so,
and no longer call a response's bytes the request's. Also made plain:
rate limits and their exemptions, the refusal threshold,
SWRP_MAX_REQUEST_TIME_MS, SWRP_MAX_RESPONSE_SIZE, SWW_LOOKUP_SOURCE,
SWW_LIMIT_BAN_REPEAT_WINDOW, the metrics' byte series, and the SPEC.md
claim about answering within SWRP_TIMEOUT_MS. EVALUATION.md is audited
too; its survey facts and date are unchanged.

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.