Caches of outside APIs live in /var/cache/sww (closes #314)

Every cache of answers from an outside service has its own file in `SWW_CACHE_DIR` (default `/var/cache/sww`): `lookups.json` (GeoJS), `lists.json` (lists fetched by URL, CrowdSec's decisions included), `dnsbl.json`, `abuseipdb-scores.json` and `routewatch.json` (at most 100,000 answers, each kept an hour). `reputation.json` is gone; the AbuseIPDB checks spent today stay in `SWW_STATE_DIR` as `abuseipdb-checks-spent.json`, since losing them would spend the daily budget twice.

A cache file never stops the start: one that does not parse is set aside as `<name>.bad` with a `file_error` alert. An unwritable `SWW_CACHE_DIR` stops the start. The `run` script creates the cache directory and gives it to `sww`. The cache directory needs no volume and can be left out of backups.

Model: opus-5-5

docs/state-files.md

@@ -1,8 +1,23 @@
-# State files
+# State and cache files
 
-The five JSON files in `SWW_STATE_DIR`, and what each holds. "Persistent state"
-in [`SPEC.md`](../SPEC.md) says how they are written, read and edited. Each has
-a top-level `version` of 1.
+The JSON files `waf` keeps, and what each holds. "Persistent state" in
+[`SPEC.md`](../SPEC.md) says how they are written, read and edited. Each has a
+top-level `version` of 1.
+
+- The state files are in `SWW_STATE_DIR`, `/var/lib/sww` by default. They hold
+  what cannot be fetched again, so back them up:
+    - `bans.json`;
+    - `clients.json`;
+    - `abuseipdb-checks-spent.json`;
+    - `alerts.json`.
+- The cache files are in `SWW_CACHE_DIR`, `/var/cache/sww` by default. They hold
+  answers from outside services, which are asked again when a file is lost, so
+  the directory can be left out of backups:
+    - `lookups.json`;
+    - `lists.json`;
+    - `dnsbl.json`;
+    - `abuseipdb-scores.json`;
+    - `routewatch.json`.
 
 ## `bans.json`
 
@@ -67,21 +82,13 @@ since it was first seen:
   `blocked_by_core_rule_set`. A file may also hold `token_refused`, which is
   kept, and which nothing adds to.
 
-## `lookups.json`
+## `abuseipdb-checks-spent.json`
 
-GeoJS answers, one per line:
+The AbuseIPDB checks spent today, so that a restart does not spend the daily
+budget again:
 
-- `client`;
-- `asn`, `as_name` and `country`;
-- `answered`: when GeoJS answered;
-- `used`: when the answer was last used.
-
-## `reputation.json`
-
-- the last good copy of each list fetched from a URL, with when it was last
-  tried;
-- each DNS blocklist verdict still in use;
-- AbuseIPDB's scores, and the checks spent today.
+- `day`: the day, in UTC;
+- `spent`: the checks spent on it.
 
 ## `alerts.json`
 
@@ -91,6 +98,51 @@ GeoJS answers, one per line:
 - the alerts sent and held back in the current hour;
 - the alerts waiting for each destination.
 
+## `lookups.json`
+
+A cache file. GeoJS answers, one per line:
+
+- `client`;
+- `asn`, `as_name` and `country`;
+- `answered`: when GeoJS answered;
+- `used`: when the answer was last used.
+
+## `lists.json`
+
+A cache file. The last good copy of each list fetched from a URL, with when it
+was last tried:
+
+- `url`;
+- `tried`: when it was last fetched or tried;
+- `fetched` and `lines`: when the last good copy was fetched, and its lines,
+  comment lines included.
+
+## `dnsbl.json`
+
+A cache file. Each DNS blocklist verdict still in use, one per line:
+
+- `zone` and `client`;
+- `listed`: whether the zone lists the client;
+- `fetched`: when the zone answered.
+
+## `abuseipdb-scores.json`
+
+A cache file. AbuseIPDB's scores still in use, one per line:
+
+- `client`;
+- `score`: from 0 to 100;
+- `fetched`: when AbuseIPDB answered.
+
+## `routewatch.json`
+
+A cache file. routewatch's answers from the last hour, one per line:
+
+- `client`;
+- `netblock`: the netblock the client's address is announced in, empty for an
+  address without a live route;
+- `asn`: the number of the AS that originates the netblock, 0 for none;
+- `answered`: when routewatch answered.
+
 ## Sizes
 
 - `clients.json`: about 1 KiB per client, about 20 MiB at the default
@@ -102,4 +154,7 @@ GeoJS answers, one per line:
   more.
 - `lookups.json`: about 150 bytes per answer, under 1.5 GiB of writes a day when
   full.
-- `reputation.json` and `alerts.json`: usually a few MiB or less.
+- `routewatch.json`: about 120 bytes per answer, at most about 12 MiB.
+- `abuseipdb-checks-spent.json`: a few bytes.
+- `lists.json`, `dnsbl.json`, `abuseipdb-scores.json` and `alerts.json`: usually
+  a few MiB or less.