Sets from Jarl: sets holding the addresses of names in Jarl

A set can take its addresses from Jarl: every A and AAAA record of its
names (NAME@VIEW), CNAMEs followed within Jarl's zones in the same view.
housecarld reads them every jarl.refresh and after each change, keeps
only the addresses within the zones and networks the set allows, and
keeps what it last read (saved in the database and the boot ruleset)
while Jarl can't be reached. A change of the addresses applies the
ruleset again without a history entry and is audited (set.jarl).

hc set add --jarl --within, hc set jarl; the kind "from Jarl" and
Addresses… on the Sets page; GET /sets/{name}/jarl and /jarl/refresh;
validation codes set_jarl_*, status warnings jarl_*; docs/jarl.md.
e2e phase with scripts/fakejarl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/api.md

@@ -129,6 +129,7 @@ The objects:
 ```json
 {"name": "lan", "interfaces": ["eth1", "eth1.*"], "external": false, "comment": ""}
 {"name": "trusted", "entries": ["192.168.1.0/24", "2001:db8:1::/64"], "dynamic": false, "timeout": 0, "comment": ""}
+{"name": "nas", "entries": [], "jarl": {"names": [{"name": "nas.example.com", "view": "internal"}], "within": ["lan", "10.9.0.0/16"]}, "comment": ""}
 {"name": "web", "entries": ["tcp/8080", "tcp/8443"], "comment": ""}
 {"chain": "input",
  "in_zones": ["wan"], "not_in": false, "out_zones": [], "not_out": false,
@@ -145,6 +146,12 @@ The objects:
  "comment": "", "disabled": false}
 ```
 
+A set with `jarl` takes its addresses from Jarl ([jarl.md](jarl.md#sets-from-jarl)):
+`names` are names in Jarl, each with a `view` (left out: the only view that
+has it); `within` are zones and addresses its addresses must lie in. It
+has no `entries` and isn't `dynamic`; `"jarl": null` makes it an ordinary
+set again.
+
 A source NAT rule is a match (as a rule's, without the rule's other
 fields) with `"to"` (empty: masquerade), a redirect a match with
 `"to_port"`. A ban list ([bans.md](bans.md)):
@@ -209,6 +216,35 @@ These need `sets:read` or `sets:write`, for that set
 ([permissions.md](permissions.md)); they aren't on probation or in the
 history, but are audited.
 
+### Sets from Jarl
+
+| | |
+|---|---|
+| `GET /sets/{name}/jarl` | what the set holds and why (below) |
+| `POST /sets/{name}/jarl/refresh` | reads Jarl now (for every set from Jarl), then answers as `GET` |
+
+They need `sets:read` for that set. 400 for a set that doesn't come from
+Jarl. The answer:
+
+```json
+{"set": "nas", "configured": true, "read": "2026-10-23T14:02:11Z", "error": "",
+ "entries": ["10.10.0.20", "10.10.0.21"], "within": ["lan"],
+ "names": [{"name": "files.example.com", "view": "", "found_view": "internal", "chain": ["nas.example.com"],
+            "addresses": [{"address": "10.10.0.20", "used": true},
+                          {"address": "2001:db8:10::20", "used": false, "why": "not within lan"}],
+            "problem": "", "checked": "2026-10-23T14:02:11Z", "error": ""}]}
+```
+
+* `configured`: `housecarl.yaml` names a Jarl server; `read`: when Jarl's
+  zones were last read; `error`: why the last read failed (the set keeps
+  its addresses).
+* `entries`: the addresses the set holds now.
+* For each name: `found_view` is the view it was read from, `chain` the
+  CNAMEs followed, `addresses` every address Jarl gives it with `used`
+  (or `why` not), `problem` why it gives none, `checked` when Jarl last
+  answered for it, and `error` why the last try failed (its addresses are
+  then those of `checked`).
+
 ### Bans
 
 | | |