Log the rest of the request log's fields (closes #79)

Each request log line now has the fields "Request log" in SPEC.md lists
whose features are built: instance (SWWAF_INSTANCE_NAME), scheme,
request_id (a trusted proxy's X-Request-ID or a new one, sent on to the
app), forwarded_for, client_group, content_type, content_length, the
headers SWWAF_LOG_REQUEST_HEADERS names, has_authorization, has_cookie,
websocket, response_content_type, cache_control, location, counts and
the timings. Authorization, Cookie and Set-Cookie values are never
logged. An entry of SWWAF_LOG_REQUEST_HEADERS that is not a header name
stops the start.

Deviation: counts has request totals only.
Deviation: SWWAF_INSTANCE_NAME is on request lines only.

Model: opus-5-5

README.md

@@ -13,23 +13,24 @@ JSON log line for every request.
 
 Status: the first two milestones are built
 (https://git.eeqj.de/sneak/smallwebwaf/issues/13 and
-https://git.eeqj.de/sneak/smallwebwaf/issues/14), and so are six parts of
+https://git.eeqj.de/sneak/smallwebwaf/issues/14), and so are seven parts of
 milestone 3: the static lists, the bans that broken rate limits lead to and the
 JSON state files with your edits taken in while it runs, which come next in the
-build order, `observe` mode, which comes a little later, and the metrics
-endpoint and the header size and the idle time as settings, which come last in
-it. `smallwebwaf` passes each request to the app and the app's answer back,
-unchanged, within its timeouts and size limits, works out each client's address,
-bans a client that sends too many requests, refuses a client that comes from a
-country you refuse or from a network you refuse, lets the networks you choose
-through, keeps its bans, each client's counters and history, and GeoJS's answers
-in JSON files across restarts, takes in your edits of those files while it runs,
-writes a JSON log line for every request, serves Prometheus metrics to a scraper
-that holds the metrics token, and in `observe` mode passes on the requests it
-would refuse, logging what it would have done with them. It comes as the image
-the app's own image is built on. The rest of the design comes after that, in the
-order of the build order in [`SPEC.md`](SPEC.md). The survey of existing tools
-that led to the design is in [`EVALUATION.md`](EVALUATION.md).
+build order, `observe` mode and the rest of the request log's fields, which come
+a little later, and the metrics endpoint and the header size and the idle time
+as settings, which come last in it. `smallwebwaf` passes each request to the app
+and the app's answer back, unchanged, within its timeouts and size limits, works
+out each client's address, bans a client that sends too many requests, refuses a
+client that comes from a country you refuse or from a network you refuse, lets
+the networks you choose through, keeps its bans, each client's counters and
+history, and GeoJS's answers in JSON files across restarts, takes in your edits
+of those files while it runs, writes a JSON log line for every request, serves
+Prometheus metrics to a scraper that holds the metrics token, and in `observe`
+mode passes on the requests it would refuse, logging what it would have done
+with them. It comes as the image the app's own image is built on. The rest of
+the design comes after that, in the order of the build order in
+[`SPEC.md`](SPEC.md). The survey of existing tools that led to the design is in
+[`EVALUATION.md`](EVALUATION.md).
 
 ## Getting started
 
@@ -66,7 +67,9 @@ in `bin/state` unless `SWWAF_STATE_DIR` is set.
   address outside `SWWAF_TRUSTED_PROXIES` is the client; if every address in it
   is inside, the leftmost is, and with no header the peer is. The app sees what
   it would see from traefik directly: the same `Host`, the same
-  `X-Forwarded-Proto`, and `X-Forwarded-For` with the peer added at the end.
+  `X-Forwarded-Proto`, and `X-Forwarded-For` with the peer added at the end. It
+  also gets the request's id in `X-Request-ID`, the same id as in the request's
+  log line (see `request_id` in "Request log" below).
 - Enforces the timeouts and the size limits below. A limit passed before the
   response has started gets `smallwebwaf`'s own answer: `408` for a client too
   slow to send its request, `413` for a request body that is too large, `504`
@@ -154,6 +157,11 @@ it, and the effective settings are logged at start.
 - `SWWAF_LISTEN_ADDR` (default `:8080`): where `smallwebwaf` listens.
 - `SWWAF_UPSTREAM_URL` (default `http://127.0.0.1:8081`): the app, as `http` or
   `https`, a host and an optional port, and nothing more.
+- `SWWAF_INSTANCE_NAME` (default: the host's name, which docker sets to the
+  first 12 characters of the container's id unless the deployment names one):
+  the name each request log line gives as `instance`. Set it, for example to
+  `fsn1app1/gitea`, for a name that stays the same when a deploy replaces the
+  container, and that tells instances apart when several log to one place.
 - `SWWAF_MODE` (default `enforce`): `enforce`, or `observe` to pass on the
   requests `smallwebwaf` would refuse and log what it would have done (see "What
   it does so far" above).
@@ -221,6 +229,11 @@ it, and the effective settings are logged at start.
   `bans.json` is written, with every ban made in between.
 - `SWWAF_STATE_COUNTER_INTERVAL` (default `15m`): how often every state file is
   written.
+- `SWWAF_LOG_REQUEST_HEADERS` (default
+  `accept,accept-language,accept-encoding,content-type,origin,range`): the
+  request headers whose values the request log gives, in either case.
+  `Authorization`, `Cookie` and `Set-Cookie` are never logged, even when listed
+  (see "Request log" below).
 - `SWWAF_METRICS_TOKEN` (default unset): the token a scraper sends for the
   metrics, a long random value. While it is unset the metrics are off; one
   shorter than 32 characters stops the start. The settings logged at start show
@@ -250,18 +263,42 @@ GeoJS are kept, for 7 days each.
 refused ones included:
 
 ```
-{"type":"request","time":"2026-10-03T12:00:00.123Z","client_ip":"203.0.113.9","peer_ip":"172.18.0.2","country":"DE","method":"GET","host":"app.example","path":"/","query":"","protocol":"HTTP/1.1","status":200,"upstream_status":200,"request_bytes":0,"response_bytes":5120,"referer":"","user_agent":"curl/8.9.1","action":"forward","duration_total":3.217,"duration_upstream_total":3.104}
+{"type":"request","time":"2026-10-03T12:00:00.123Z","instance":"fsn1app1/gitea","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","country":"DE","request_headers":{"accept":"*/*"},"response_content_type":"text/html; charset=utf-8","upstream_status":200,"action":"forward","counts":{"minute":1,"hour":12,"day":40},"duration_total":3.217,"duration_checks":0.041,"duration_upstream_connect":0.052,"duration_upstream_first_byte":2.874,"duration_upstream_total":3.104}
 ```
 
-- `time` is when the request arrived, in UTC. `peer_ip` is the TCP peer,
-  normally traefik. `path` and `query` are as the client sent them.
+A field that does not apply to a request is left out of its line, apart from
+`type`, the fields from `time` to `user_agent`, `request_id`, `peer_ip`,
+`client_group`, `country`, `action` and `duration_total`, which every line has.
+
+- `time` is when the request arrived, in UTC. `instance` is
+  `SWWAF_INSTANCE_NAME`. `scheme` is the `X-Forwarded-Proto` a trusted proxy
+  sent, and otherwise `http`. `path` and `query` are as the client sent them.
+- `request_id` is the `X-Request-ID` a trusted proxy sent, or a new random one
+  of 26 letters and digits when it sent none, or when the peer is not a trusted
+  proxy. A request passed to the app takes it there in `X-Request-ID`.
+- `peer_ip` is the TCP peer, normally traefik. `forwarded_for` is the
+  `X-Forwarded-For` header as received, several lines of it joined with `, `.
+  `client_group` is the client as the rate limits count it: its IPv4 address as
+  a /32, or the /64 of its IPv6 address.
 - `country` is the client's country as GeoJS places it. It is empty with neither
   country list set, for a client in `SWWAF_ALLOW_NETS` or `SWWAF_DENY_NETS`, for
   a client on a private, loopback or link-local address, when GeoJS cannot place
   the client or has not answered in time, and for a request whose client a ban
   covers, even when the client's country is known.
+- `content_type` is the request's `Content-Type`, and `content_length` the
+  length the request announced for its body, which is left out for none or zero.
+- `request_headers` are the request's headers that `SWWAF_LOG_REQUEST_HEADERS`
+  names, by name in lower case, several lines of one joined with `, `.
+  `Authorization`, `Cookie` and `Set-Cookie` are never among them, whatever the
+  setting says: `has_authorization` and `has_cookie` are there instead, and
+  true, when the request has an `Authorization` or a `Cookie` header.
+- `websocket` is there, and true, when the app switched the connection to
+  another protocol, as it does for a WebSocket.
 - `status` is what the client was sent, `0` if nothing was; `upstream_status` is
   what the app answered, and is left out when the app did not answer.
+- `response_content_type`, `cache_control` and `location` are the
+  `Content-Type`, `Cache-Control` and `Location` headers of the answer: the
+  app's, as passed on, or those of `smallwebwaf`'s own answer.
 - `request_bytes` and `response_bytes` count body bytes.
 - `action` is `forward` for a request passed to the app, `denied` for one
   refused because its client is in `SWWAF_DENY_NETS`, `banned` for one refused
@@ -277,6 +314,15 @@ refused ones included:
   `banned`, `country_denied` or `rate_limited`. `action` then names what was
   done: `forward` for a request passed to the app, and another action, such as
   `too_large`, for one a size or time limit refused.
+- `counts` gives the client's requests in the minute, the hour and the day as
+  the rate limits count them, this request included: in each window, those in
+  the bucket under way and a share of those in the bucket before, so a count can
+  have a fraction. For a request that broke a limit, they are the counts that
+  broke it. It is left out for a request the rate limits do not count: the
+  health check, one from a client in `SWWAF_ALLOW_NETS` or
+  `SWWAF_RATE_LIMIT_EXEMPT_NETS`, and one that `SWWAF_DENY_NETS`, a ban or the
+  country lists refuse, or would refuse in `observe` mode. The byte totals come
+  with the byte limits.
 - `limit_hit` is there for a request that broke a rate limit, and names the
   window whose limit it went over: `minute`, `hour` or `day`, the shortest if it
   went over several. `offence` is then `limit`.
@@ -284,10 +330,19 @@ refused ones included:
   or in `observe` mode would have been refused under one, and gives when the ban
   ends, in the same form as `time`, or `permanent`.
 - `aborted` is there, and true, when the client went away early.
-- `duration_total` and `duration_upstream_total` are in milliseconds.
+- The timings are in milliseconds, to the microsecond. `duration_total` runs
+  from when the request's headers had been read to when its line is written, and
+  `duration_checks` over the same start to when the checks were done; the health
+  check runs none, and its line has no `duration_checks`.
+  `duration_upstream_connect`, `duration_upstream_first_byte` and
+  `duration_upstream_total` are there for a request passed to the app, and run
+  from when it was handed to the app: until there was a connection to it, new or
+  kept open from an earlier request, until the first byte of its answer arrived,
+  and until the end. The first two are left out when that never happened, as for
+  an app that cannot be reached.
 
-No body and no other header is logged. `smallwebwaf`'s own messages (start, the
-settings, stop, errors) share the stream as JSON lines marked
+No body is logged, and no header but those above. `smallwebwaf`'s own messages
+(start, the settings, stop, errors) share the stream as JSON lines marked
 `"type":"process"`.
 
 Go's HTTP server, on which `smallwebwaf` is built, reads a request's line and
@@ -773,9 +828,8 @@ so that they run in minimal containers.
 
 ## TODO
 
-- The rest of milestone 3: exemptions and the rest of the request log's fields;
-  then the rest of the design, in the order of the build order in
-  [`SPEC.md`](SPEC.md).
+- The rest of milestone 3: exemptions; then the rest of the design, in the order
+  of the build order in [`SPEC.md`](SPEC.md).
 
 ## Documents