SPEC: requirements and reasons only, reference material in docs/

docs/settings.md is now the one settings reference; the spec keeps the
conventions, the off list and each group's requirements and reasons, and
links to it for the per-setting entries. The endpoint list, the ban
notes, the state file contents, the rule file format and the alert
object likewise live in docs/ and are linked from the spec. The package
list from the README's Design section joins "Architecture". The nine
docs files are byte-identical to those on the README branch. Package
comments that named "Alert webhook schema", "Request log" and "Metrics
endpoint" for their field lists now name the docs files.

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
-// webhook schema" section of SPEC.md describes, to the Slack incoming
+// 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
@@ -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,
-// ASName and Country are, for a ban, the client's as the ban's notes give
-// them.
+// 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.
 //
-//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
-// SPEC.md describes. It refuses and bans nothing. At most 20,000 counters
+// 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

internal/metrics/metrics.go

@@ -1,6 +1,7 @@
-// Package metrics keeps smallwebwaf's Prometheus metrics, as the "Metrics
-// endpoint" section of SPEC.md lists them, and serves them in the
-// Prometheus text format. No metric carries a client's address.
+// 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 (

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/remotelog/remotelog.go

@@ -1,8 +1,9 @@
 // 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.
+// of SPEC.md requires and "Sending the log to a syslog server" in
+// docs/request-log.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 (

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
-// that may not apply to a request is left out of its line when it does
-// not.
+// their order, are those of docs/request-log.md. A field that may not
+// apply to a request is left out of its line when it does 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/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
-// SPEC.md describes them. It reads no response.
+// makes to it, as "Attack detection" under "Settings" in SPEC.md describes
+// 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
-# sample of gitea's ordinary use: signing in, pages of files and commits,
-# a diff, the API, a push, clone and fetch over HTTP, and two container
-# image pushes. Last, print each request smallwebwaf logged, with what it
-# did with it and the ids of the Core Rule Set's rules that matched it.
+# that reading gitea's source found the Core Rule Set refuses, which
+# docs/gitea.md records, and a short sample of gitea's ordinary use:
+# signing in, pages of files and commits, a diff, the API, a push, clone
+# and fetch over HTTP, and two container image pushes. Last, print each
+# 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,