Add changesets, bandwidth limits and quotas; generic examples

Changesets, as in Jarl: configuration changes are operations that can be
staged in a changeset, checked as they are added (validation and nft -c),
reviewed with the diff of the ruleset, and applied together as one
history entry, then on probation like any change made over the network.
The web UI collects edits for review by default (pending rows, a bar with
Review and Apply now, a Changes page, a switch for live edits); hc stages
with -C ID or HOUSECARL_CHANGESET (checked like JARL_CHANGESET) and has
hc changeset create/list/show/diff/apply/discard/remove. Undo, import and
takeover refuse a changeset. --dry-run shows the ruleset's diff.

Bandwidth and quotas: rate limits in bytes, per source or destination;
quotas per rule or per address that reset daily, weekly, monthly on a
day, or by hand, with their usage carried across reloads, saved for
reboots, shown by hc quotas and on the rules page, and reset with hc rule
reset-quota. Rules that count traffic are checked before established
connections are accepted (so they see every packet) and can't accept.
Per-address limits group IPv6 by /64 by default (--group-v4/-v6).
Per-source rate meters use update. The importer turns meters, byte rates
and quotas into these fields.

The examples in the web UI, hc's help and the docs use documentation
addresses and generic names instead of the maintainer's network.

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

docs/cli.md

@@ -27,7 +27,8 @@ command and its flags.
 | `--config FILE` | `HOUSECARL_CLI_CONFIG` | the CLI's configuration file |
 | | `HOUSECARL_SOCKET` | the local socket's path |
 | `--insecure`, `--ca-cert FILE` | | TLS: skip the check, or trust another CA |
-| `-n, --dry-run` | | check and show a change without making it |
+| `-n, --dry-run` | | check and show a change without making it, with the ruleset's diff |
+| `-C, --changeset ID` | `HOUSECARL_CHANGESET` (checked, see [Changesets](#changesets)) | stage configuration changes in this changeset instead of making them |
 | `-o, --output FORMAT` | | `table` (default), `json`, `yaml` or `id` |
 | `-q, --quiet` | | print only errors (and the IDs of new objects) |
 
@@ -56,8 +57,69 @@ Through the socket the change is kept at once:
 applied and saved (history 12; undo with 'hc history undo 12')
 ```
 
-`-n` shows what would change without changing it; nftables checks it
-too.
+`-n` shows what would change without changing it, with the diff of the
+ruleset; nftables checks it too.
+
+## Changesets
+
+To review several changes and apply them together, as one entry in the
+history, stage them in a changeset:
+
+```sh
+export HOUSECARL_CHANGESET=$(hc changeset create "guest network" -q)
+hc zone add guest -i eth1.30
+hc rule add forward --in guest --out wan
+hc changeset diff                 # the operations, problems, nftables' check, the ruleset's diff
+hc changeset remove 2             # take operation 2 out
+hc changeset apply                # one change; over the network on probation
+unset HOUSECARL_CHANGESET
+```
+
+```
+$ hc rule add forward --in guest --out wan
+changeset 7 (guest network, 1 operation) from HOUSECARL_CHANGESET
+staged: create rule forward #52
+staged in changeset 7 as operation 2 (2 operations now); review with 'hc changeset diff 7', apply with 'hc changeset apply 7'
+```
+
+Each change is checked as it is staged: the changeset with it must stay
+valid, and nftables must accept the ruleset, so make a set before the
+rule that names it. Applying checks the whole changeset again, on the
+configuration as it is then; an operation whose object changed since is
+named (`operation 3 (update rule input #12) can't be applied: …`), and
+`hc changeset remove` takes it out.
+
+| Command | |
+|---|---|
+| `changeset create [DESCRIPTION]` | start one; `-q` prints only its ID |
+| `changeset list [--status open\|applied\|discarded\|""] [--mine]` | open ones by default |
+| `changeset show [ID]` | its operations |
+| `changeset diff [ID]` | what applying it would do |
+| `changeset apply [ID] [--description D]` | apply it |
+| `changeset discard [ID]` | throw it away |
+| `changeset remove [ID] OP` | take one operation out |
+
+`show`, `diff`, `apply`, `discard` and `remove` work on the changeset you
+name, else the one in `-C`, else the one in `HOUSECARL_CHANGESET`.
+
+A changeset from `HOUSECARL_CHANGESET` is checked before anything uses
+it, because an exported ID easily outlives its changeset:
+
+- Staging into it, and `apply`, `discard` and `remove` on it, need it to
+  be open and yours. Otherwise the command stops and says why (`there is
+  no changeset 99`, `changeset 42 is applied`, `changeset 57 is sam's`).
+  Commands that only read, and `hc changeset create`, don't care.
+- Each command says on stderr which changeset it uses: `changeset 42
+  (guest network, 2 operations) from HOUSECARL_CHANGESET` (not with `-q`).
+- After `apply` or `discard`, a reminder to `unset HOUSECARL_CHANGESET`.
+
+`-C ID` and an ID argument are used as given (housecarld still refuses a
+changeset that isn't open, or another user's unless you are an
+administrator). Only configuration changes are staged: dynamic set
+entries, `confirm` and `rollback` are made at once, and `history undo`,
+`import` and `takeover` can't be staged, so they are refused while a
+changeset is named. Changesets staged in the web UI show up here too,
+and the other way round.
 
 ## Commands
 
@@ -72,6 +134,7 @@ by name.
 | `interfaces` | the machine's interfaces, their addresses and zones |
 | `ruleset` | the nftables ruleset Housecarl builds |
 | `counters` | the hits of every rule, NAT rule, built-in and policy, by mark (`r12`, `f3`, `b-established`, `p-input`) |
+| `quotas` | what each rule's quota used (each address's, for per-address quotas), and when it resets |
 | `log [-f] [--search TEXT] [--limit N]` | the packets logged by rules and policies ([operations.md](operations.md#the-log)) |
 
 ### zone, set, service
@@ -103,6 +166,7 @@ See [rules.md](rules.md).
 | `rule update ID [flags]` | only the flags given |
 | `rule move ID --before ID\|--after ID\|--first\|--last\|--chain CHAIN` | |
 | `rule enable\|disable ID` | |
+| `rule reset-quota ID` | start a rule's quota again now |
 | `rule delete ID` | |
 
 The match flags (`rule add`, `snat add`, `redirect add`):
@@ -115,7 +179,9 @@ The match flags (`rule add`, `snat add`, `redirect add`):
 | `--family ipv4\|ipv6` | |
 
 And for rules: `--state`, `--status`, `--days`, `--hours`, `--limit
-10/minute[,burst=N][,over][,per-source]`, `--conn-limit N`, `-a
+10/minute|1mbytes/second[,burst=N][,over][,per-source|,per-destination]`,
+`--quota 50gbytes[,over][,per-source|,per-destination][,daily|,weekly|,monthly=DAY]`,
+`--group-v4 N`, `--group-v6 N`, `--conn-limit N`, `-a
 accept|drop|reject|log`, `--reject-with tcp-reset`, `--log`,
 `--log-prefix`, `--raw RULE`, `--comment`, `--disabled`
 ([rules.md](rules.md#rules)).