Load every setting from one table in internal/config (closes #320)

Config.settings lists each setting once: its key, its environment
variable and the function that loads it. Most rows load through field,
whose arguments give the type, the default and the check. db_url and
cache_max_bytes keep their own load functions. Loading, the unknown-key
and unknown-variable checks and the names in error messages all read
the table. allowlist_hosts now loads through parseHostList.
isKnownConfigKey, envVarNames, strictLoader, validate,
validateAllowlistHostsValue and getStringSlice are gone, with the
getStringSlice tests. The key constants move to the tests, their only
users. README.md lists the settings one item each instead of in a
table. A new test checks that this list and configs/config.example.yml
name exactly the keys of the table.

Model: opus-5-5

README.md

@@ -133,7 +133,7 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for pixa needs:
       filesystem's free space and what the cache holds, and at least 500 MiB, so
       the cache can grow to three quarters or more of the space they all have
       left, and to all of it when that is 500 MiB or less.
-    - the rest are in the table under Configuration below
+    - the rest are in the list under Configuration below
 - **Memory:** pixa can use up to `max_concurrent_processing` times 4.2 GiB for
   the images it processes at once, plus `upstream_connections` times
   `upstream_max_response_size` for the source images it has fetched that wait
@@ -684,7 +684,7 @@ and the file's own key. A variable's value is parsed as the same text in the
 file would be. The three lists take comma-separated entries, with the spaces
 around each trimmed; an empty variable is an empty list. A value that does not
 parse or is invalid aborts startup, naming the variable. A variable whose name
-starts with `PIXA_` but is not in the table below, such as a misspelled one or
+starts with `PIXA_` but is not in the list below, such as a misspelled one or
 `PIXA_PORT`, aborts startup naming it, as an unknown config key does. The one
 other accepted name is `PIXA_CONFIG_PATH`, the config file's path (like
 `--config`). The variables set by the file's `env:` section are checked the same
@@ -701,31 +701,61 @@ pixa cannot read or parse aborts startup, naming the file. So does one in a
 directory pixa may not enter, whether or not it is there, since pixa cannot
 tell. With no file, pixa uses the environment and the defaults.
 
-| Variable                             | Config key                      | Meaning                                                                      |
-| ------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------- |
-| `PIXA_SIGNING_KEY`                   | `signing_key`                   | Required: secret for signed and encrypted URLs and login, 32+ characters     |
-| `PORT`                               | `port`                          | Port to listen on; default `8080`                                            |
-| `PIXA_STATE_DIR`                     | `state_dir`                     | Directory for the database and the disk cache; default `/var/lib/pixa`       |
-| `PIXA_DB_URL`                        | `db_url`                        | SQLite database URL; default `state.sqlite3` in the state directory          |
-| `PIXA_CACHE_MAX_BYTES`               | `cache_max_bytes`               | Disk cache limit in bytes; `0` disables it; default 75% of (free + cached)   |
-| `PIXA_ALLOWLIST_HOSTS`               | `allowlist_hosts`               | Upstream hosts served without a signature                                    |
-| `PIXA_REFERER_BLOCKLIST`             | `referer_blocklist`             | Hosts whose pages the image routes refuse with 403, by `Referer`             |
-| `PIXA_BLOCKED_NETWORKS`              | `blocked_networks`              | CIDR ranges never fetched from, on top of the built-in ones                  |
-| `PIXA_TRUSTED_PROXIES`               | `trusted_proxies`               | CIDR ranges of proxies whose `X-Forwarded-For` is believed; default RFC 1918 |
-| `PIXA_ALLOW_HTTP`                    | `allow_http`                    | Allow plain-HTTP upstreams, for testing only; default `false`                |
-| `PIXA_UPSTREAM_CONNECTIONS_PER_HOST` | `upstream_connections_per_host` | Concurrent connections per upstream host; default `20`                       |
-| `PIXA_UPSTREAM_CONNECTIONS`          | `upstream_connections`          | Concurrent connections to all upstream hosts together; default `64`          |
-| `PIXA_MAX_CONCURRENT_PROCESSING`     | `max_concurrent_processing`     | Images processed at once; default half the CPUs, at least 1                  |
-| `PIXA_IMAGE_REQUESTS_PER_MINUTE`     | `image_requests_per_minute`     | Image requests per client per minute; `0` turns it off; default `600`        |
-| `PIXA_UPSTREAM_FETCH_TIMEOUT`        | `upstream_fetch_timeout`        | Time allowed for one fetch from an upstream host; default `30s`              |
-| `PIXA_UPSTREAM_MAX_RESPONSE_SIZE`    | `upstream_max_response_size`    | Largest upstream response accepted, in bytes; default 50 MiB                 |
-| `PIXA_DOWNSTREAM_TIMEOUT`            | `downstream_timeout`            | Time allowed for answering one client request; default `60s`                 |
-| `PIXA_ACCESS_CONTROL_ALLOW_ORIGIN`   | `access_control_allow_origin`   | CORS origin allowed to read image responses: `*` or one origin; default `*`  |
-| `PIXA_METRICS_USERNAME`              | `metrics.username`              | Username for `/metrics`, which is served only when both are set              |
-| `PIXA_METRICS_PASSWORD`              | `metrics.password`              | Password for `/metrics`; set together with the username                      |
-| `PIXA_SENTRY_DSN`                    | `sentry_dsn`                    | Sentry DSN for error reporting; empty disables it                            |
-| `PIXA_DEBUG`                         | `debug`                         | Debug logging and plain-HTTP local development; default `false`              |
-| `PIXA_MAINTENANCE_MODE`              | `maintenance_mode`              | Answer image requests with 503; the health check stays 200; default `false`  |
+Each item below is one setting, named by its config key:
+
+- `signing_key`: variable `PIXA_SIGNING_KEY`, required. The secret for signed
+  URLs, encrypted URLs and login. It must be 32 characters or longer.
+- `port`: variable `PORT`, default `8080`. The port to listen on.
+- `state_dir`: variable `PIXA_STATE_DIR`, default `/var/lib/pixa`. The directory
+  for the database and the disk cache.
+- `db_url`: variable `PIXA_DB_URL`, default `state.sqlite3` in the state
+  directory. The URL of the SQLite database.
+- `cache_max_bytes`: variable `PIXA_CACHE_MAX_BYTES`, default 75% of the free
+  space plus what the cache holds. The disk cache limit in bytes. `0` turns the
+  disk cache off.
+- `allowlist_hosts`: variable `PIXA_ALLOWLIST_HOSTS`, default none. The upstream
+  hosts whose images pixa serves without a signature.
+- `referer_blocklist`: variable `PIXA_REFERER_BLOCKLIST`, default none. The
+  image routes refuse a request with 403 when its `Referer` header names one of
+  these hosts.
+- `blocked_networks`: variable `PIXA_BLOCKED_NETWORKS`, default none. The CIDR
+  ranges pixa never fetches from, on top of the built-in ones.
+- `trusted_proxies`: variable `PIXA_TRUSTED_PROXIES`, default the RFC 1918
+  ranges. The CIDR ranges of the proxies whose `X-Forwarded-For` header pixa
+  believes.
+- `allow_http`: variable `PIXA_ALLOW_HTTP`, default `false`. Allows plain-HTTP
+  upstream hosts. It is for testing only.
+- `upstream_connections_per_host`: variable
+  `PIXA_UPSTREAM_CONNECTIONS_PER_HOST`, default `20`. The most connections to
+  one upstream host at once.
+- `upstream_connections`: variable `PIXA_UPSTREAM_CONNECTIONS`, default `64`.
+  The most connections to all upstream hosts together at once.
+- `max_concurrent_processing`: variable `PIXA_MAX_CONCURRENT_PROCESSING`,
+  default half the CPUs, at least 1. The most images processed at once.
+- `image_requests_per_minute`: variable `PIXA_IMAGE_REQUESTS_PER_MINUTE`,
+  default `600`. How many image requests one client may send per minute. `0`
+  turns the limit off.
+- `upstream_fetch_timeout`: variable `PIXA_UPSTREAM_FETCH_TIMEOUT`, default
+  `30s`. The time allowed for one fetch from an upstream host.
+- `upstream_max_response_size`: variable `PIXA_UPSTREAM_MAX_RESPONSE_SIZE`,
+  default 50 MiB. The largest upstream response accepted, in bytes.
+- `downstream_timeout`: variable `PIXA_DOWNSTREAM_TIMEOUT`, default `60s`. The
+  time allowed for answering one client request.
+- `access_control_allow_origin`: variable `PIXA_ACCESS_CONTROL_ALLOW_ORIGIN`,
+  default `*`. The CORS origin allowed to read image responses. It is `*` or one
+  origin.
+- `metrics.username`: variable `PIXA_METRICS_USERNAME`, default empty. The
+  username for `/metrics`. pixa serves `/metrics` only when the username and the
+  password are both set.
+- `metrics.password`: variable `PIXA_METRICS_PASSWORD`, default empty. The
+  password for `/metrics`. Set it together with the username.
+- `sentry_dsn`: variable `PIXA_SENTRY_DSN`, default empty. The Sentry DSN for
+  error reporting. An empty DSN turns error reporting off.
+- `debug`: variable `PIXA_DEBUG`, default `false`. Turns on debug logging and
+  plain-HTTP local development.
+- `maintenance_mode`: variable `PIXA_MAINTENANCE_MODE`, default `false`. While
+  `true`, pixa answers image requests with 503. The health check still
+  answers 200.
 
 Key settings in more detail:
 

TODO.md

@@ -46,10 +46,11 @@ P2: security: per-origin rate limiting
       loaded.
     - When a config holds more than one invalid value, the error names the one
       that comes first in the table.
-    - A test checks that `README.md` and `configs/config.example.yml` name the
+    - `README.md` lists the settings one item each, where it had a table. A test
+      checks that this list and `configs/config.example.yml` name exactly the
       keys of the table.
+    - The key constants moved to the tests, their only users.
     - Removed:
-        - the key constants
         - `isKnownConfigKey`, `envVarNames`, `strictLoader` and `validate`
         - `validateAllowlistHostsValue` and `getStringSlice`, with the three
           tests of `getStringSlice`

internal/config/documented_settings_internal_test.go

@@ -8,11 +8,10 @@ import (
 	"testing"
 )
 
-// TestReadmeNamesEverySetting checks that the Configuration section of
-// README.md names every key of the settings table in backticks. It also
-// checks that every name in backticks there written like a key with an
-// underscore, such as state_dir, is a key of the table. The other keys,
-// such as port and metrics.username, are checked only the first way.
+// TestReadmeNamesEverySetting checks that the list of settings in
+// README.md names exactly the keys of the settings table, one item each.
+// The list is the first one in the Configuration section, and it ends at
+// the first blank line. Each item starts with its key in backticks.
 func TestReadmeNamesEverySetting(t *testing.T) {
 	t.Parallel()
 
@@ -30,28 +29,48 @@ func TestReadmeNamesEverySetting(t *testing.T) {
 	section, _, _ = strings.Cut(section, "\n## ")
 	section, _, _ = strings.Cut(section, "\n### ")
 
+	_, list, found := strings.Cut(section, "\n- ")
+	if !found {
+		t.Fatal("README.md's Configuration section has no list")
+	}
+
+	list, _, _ = strings.Cut("- "+list, "\n\n")
+
+	itemKey := regexp.MustCompile("^- `([^`]+)`")
 	named := map[string]bool{}
 
-	for _, match := range regexp.MustCompile("`([^`]+)`").
-		FindAllStringSubmatch(section, -1) {
+	for line := range strings.SplitSeq(list, "\n") {
+		// A line that does not start with "- " goes on with the item above.
+		if !strings.HasPrefix(line, "- ") {
+			continue
+		}
+
+		match := itemKey.FindStringSubmatch(line)
+		if match == nil {
+			t.Errorf("README.md's list of settings has an item "+
+				"that does not start with a key in backticks: %s", line)
+
+			continue
+		}
+
+		if named[match[1]] {
+			t.Errorf("README.md's list of settings names %s twice", match[1])
+		}
+
 		named[match[1]] = true
 	}
 
 	for _, s := range new(Config).settings() {
 		if !named[s.key] {
-			t.Errorf("README.md's Configuration section does not name %s", s.key)
+			t.Errorf("README.md's list of settings does not name %s", s.key)
 		}
 
 		delete(named, s.key)
 	}
 
-	keyWithUnderscore := regexp.MustCompile(`^[a-z]+(_[a-z]+)+$`)
-
-	for name := range named {
-		if keyWithUnderscore.MatchString(name) {
-			t.Errorf("README.md's Configuration section names %s, "+
-				"which is not a setting", name)
-		}
+	for key := range named {
+		t.Errorf("README.md's list of settings names %s, "+
+			"which is not a setting", key)
 	}
 }