SPEC: false statements fixed, repeats removed, dropped requirements restored

The bounds sentence, the blocklist URL sentence, the deny list sentence,
the limit action's scope and the observe mode sentence now say what the
code does. Each of the twenty-one requirements the fourth review found
twice is stated once, with a link from the other place. The request id
header, redirect_uri's case, change 4's reason and the live archive's
InRelease files are back. The biased thresholds are defined where they
are introduced. The docs files apply the fifth README review's findings
and stay identical to the README branch.

Model: fable-5-1

internal/alerts/alerts.go

@@ -1,8 +1,8 @@
 // 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 "Alert
+// SWWAF_ALERT_WEBHOOK_URL names, each as one JSON object, as "The JSON
-// webhook schema" section of SPEC.md describes, to the Slack incoming
+// 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
@@ -149,11 +149,10 @@ type Params struct {
 }
 
 // Alert is one alert, as the webhook is sent it and alerts.json holds it,
-// with the fields of the "Alert webhook schema" section of SPEC.md. ASN,
+// with the fields of "The JSON object" in docs/alerts.md. ASN, ASName and
-// ASName and Country are, for a ban, the client's as the ban's notes give
+// Country are, for a ban, the client's as the ban's notes give them.
-// them.
 //
-//nolint:tagliatelle // SPEC.md's alert webhook schema names its fields in snake_case
+//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"`

internal/anomaly/anomaly.go

@@ -1,8 +1,8 @@
 // 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 "Configuration surface" in
+// threshold, as "Anomaly thresholds" under "Settings" in SPEC.md
-// SPEC.md describes. It refuses and bans nothing. At most 20,000 counters
+// 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

internal/metrics/metrics.go

@@ -1,6 +1,7 @@
-// Package metrics keeps smallwebwaf's Prometheus metrics, as the "Metrics
+// Package metrics keeps smallwebwaf's Prometheus metrics, as
-// endpoint" section of SPEC.md lists them, and serves them in the
+// docs/metrics.md lists them, and serves them in the Prometheus text
-// Prometheus text format. No metric carries a client's address.
+// format, as the "Metrics endpoint" section of SPEC.md requires. No
+// metric carries a client's address.
 package metrics
 
 import (

internal/ratelimit/ratelimit.go

@@ -206,7 +206,7 @@ type Hit struct {
 // 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 // SPEC.md's request log names its fields in snake_case
+//nolint:tagliatelle // docs/request-log.md names the fields in snake_case
 type Counts struct {
 	Minute      float64 `json:"minute"`
 	Hour        float64 `json:"hour"`

internal/requestlog/requestlog.go

@@ -64,11 +64,10 @@ const LimitHitErrorBurst = "error_burst"
 const timeLayout = "2006-01-02T15:04:05.000Z07:00"
 
 // Line is one request's line in the request log. The field names, and
-// their order, are those of the "Request log" section of SPEC.md. A field
+// their order, are those of docs/request-log.md. A field that may not
-// that may not apply to a request is left out of its line when it does
+// apply to a request is left out of its line when it does not.
-// not.
 //
-//nolint:tagliatelle // SPEC.md's request log names its fields in snake_case
+//nolint:tagliatelle // docs/request-log.md names the fields in snake_case
 type Line struct {
 	Type string `json:"type"`
 

internal/state/state.go

@@ -1,5 +1,6 @@
 // Package state keeps smallwebwaf's state in JSON files in
-// SWWAF_STATE_DIR, as the "Persistent state" section of SPEC.md describes:
+// SWWAF_STATE_DIR, as the "Persistent state" section of SPEC.md requires
+// and docs/state-files.md lists them:
 // bans.json holds the bans, clients.json each client's counters and
 // history, lookups.json GeoJS's answers, reputation.json the last try and
 // last good copy of each list fetched from a URL, the DNSBL zones'

internal/state/state_test.go

@@ -1019,8 +1019,8 @@ func TestEditJustBeforeAScheduledWriteSurvivesIt(t *testing.T) {
 		edit(t, dir, bansJSON, permanentBansJSON)
 
 		// The write takes the edit in first, and writes it back. The second
-		// ban, made after the admin opened the file, is lost, as "Edits
+		// ban, made after the admin opened the file, is lost, as the
-		// while running" in SPEC.md says.
+		// "Persistent state" section of SPEC.md says.
 		time.Sleep(time.Nanosecond)
 		synctest.Wait()
 

internal/waf/waf.go

@@ -1,8 +1,8 @@
 // Package waf runs the OWASP Core Rule Set 4.25.0, through Coraza, on the
 // method, the URL with its query and the headers of a request, and on its
 // body while SWWAF_WAF_BODY_LIMIT is set, with the six changes smallwebwaf
-// makes to it, as "Attack detection" under "Configuration surface" in
+// makes to it, as "Attack detection" under "Settings" in SPEC.md describes
-// SPEC.md describes them. It reads no response.
+// them. It reads no response.
 //
 // smallwebwaf writes only to its state directory, so Coraza is built with
 // its no_fs_access tag, as the Dockerfile and script/build build it: of a

script/gitea-requests

@@ -2,11 +2,12 @@
 # script/gitea-requests: build the image and run gitea 1.27.3 behind it,
 # with every setting of smallwebwaf at its default but SWWAF_UPSTREAM_URL,
 # which names gitea's container. Then send through it the gitea requests
-# that reading gitea's source found the Core Rule Set refuses, and a short
+# that reading gitea's source found the Core Rule Set refuses, which
-# sample of gitea's ordinary use: signing in, pages of files and commits,
+# docs/gitea.md records, and a short sample of gitea's ordinary use:
-# a diff, the API, a push, clone and fetch over HTTP, and two container
+# signing in, pages of files and commits, a diff, the API, a push, clone
-# image pushes. Last, print each request smallwebwaf logged, with what it
+# and fetch over HTTP, and two container image pushes. Last, print each
-# did with it and the ids of the Core Rule Set's rules that matched it.
+# request smallwebwaf logged, with what it did with it and the ids of the
+# Core Rule Set's rules that matched it.
 # Every request comes from one client, docker's gateway, so more than
 # SWWAF_ERROR_BURST_THRESHOLD, 30, refusals in a minute would ban it, and
 # the requests after would show as banned. The containers, the network,