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>

internal/model/changeset.go

@@ -0,0 +1,56 @@
+package model
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// Changeset statuses.
+const (
+	ChangesetOpen      = "open"
+	ChangesetApplied   = "applied"
+	ChangesetDiscarded = "discarded"
+)
+
+// Changeset is a list of changes, staged to be reviewed and applied
+// together (or discarded). Applied, it is one history entry.
+type Changeset struct {
+	ID          int64     `json:"id"`
+	UserID      int64     `json:"user_id,omitempty"`
+	Username    string    `json:"username"`
+	Via         string    `json:"via"`
+	Description string    `json:"description"`
+	Status      string    `json:"status"`
+	Ops         []Op      `json:"ops"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+	// HistoryID is the history entry an applied changeset became.
+	HistoryID int64 `json:"history_id,omitempty"`
+}
+
+// Operations.
+const (
+	OpCreate   = "create"
+	OpUpdate   = "update"
+	OpDelete   = "delete"
+	OpMove     = "move"
+	OpSettings = "settings"
+)
+
+// Op is one change, as the API received it, so it can be stored and
+// replayed on whatever the configuration is when it is applied.
+type Op struct {
+	Seq  int    `json:"seq"`
+	Op   string `json:"op"` // create, update, delete, move, settings
+	Kind string `json:"kind,omitempty"`
+	// Ref names the object (ID, or name) for update, delete and move.
+	Ref string `json:"ref,omitempty"`
+	// ID is the object a create makes, given when it is staged so later
+	// operations can name it.
+	ID int64 `json:"id,omitempty"`
+	// Data is the object (create), the fields to change (update,
+	// settings) or where to move it (move).
+	Data    json.RawMessage `json:"data,omitempty"`
+	Summary string          `json:"summary"`
+	AddedAt time.Time       `json:"added_at"`
+}

internal/model/objects.go

@@ -133,9 +133,17 @@ type Rule struct {
 	// LimitOver, beyond) a rate.
 	Limit *Limit `json:"limit,omitempty"`
 	// ConnLimit matches when a source already has more than this many
-	// connections (per source address).
-	ConnLimit int    `json:"conn_limit,omitempty"`
-	Action    string `json:"action"`
+	// connections (per source address, grouped as GroupV4/GroupV6 say).
+	ConnLimit int `json:"conn_limit,omitempty"`
+	// Quota, if set, is an allowance of bytes: the rule matches once it
+	// is used up (Over), or while it lasts.
+	Quota *Quota `json:"quota,omitempty"`
+	// GroupV4 and GroupV6 group addresses for the per-address limits,
+	// connection limit and quota: by prefix length (0: the default, each
+	// IPv4 address alone, IPv6 by /64, since one device has several).
+	GroupV4 int    `json:"group_v4,omitempty"`
+	GroupV6 int    `json:"group_v6,omitempty"`
+	Action  string `json:"action"`
 	// RejectWith: "" (ICMP port/admin unreachable as fits) or tcp-reset.
 	RejectWith string `json:"reject_with,omitempty"`
 	Log        bool   `json:"log,omitempty"`
@@ -155,18 +163,105 @@ func (r *Rule) Label() string {
 	return fmt.Sprintf("%s #%d", r.Chain, r.ID)
 }
 
-// Limit is a rate: Rate packets per Per (second, minute, hour, day), with
-// a burst.
+// Limit is a rate: Rate packets (or bytes, with Unit) per Per (second,
+// minute, hour, day), with a burst.
 type Limit struct {
-	Rate  int    `json:"rate"`
-	Per   string `json:"per"`
-	Burst int    `json:"burst,omitempty"`
+	Rate int    `json:"rate"`
+	Per  string `json:"per"`
+	// Burst is in the rate's unit.
+	Burst int `json:"burst,omitempty"`
+	// Unit: "" for packets, or bytes, kbytes or mbytes for a byte rate
+	// (bandwidth).
+	Unit string `json:"unit,omitempty"`
 	// Over matches packets beyond the rate instead of within it (to drop
 	// floods).
 	Over bool `json:"over,omitempty"`
 	// PerSource counts each source address on its own (a meter), instead
-	// of all traffic the rule sees together.
-	PerSource bool `json:"per_source,omitempty"`
+	// of all traffic the rule sees together; PerDestination each
+	// destination.
+	PerSource      bool `json:"per_source,omitempty"`
+	PerDestination bool `json:"per_destination,omitempty"`
+}
+
+// Byte units, as nftables writes them.
+var ByteUnits = map[string]int64{"bytes": 1, "kbytes": 1 << 10, "mbytes": 1 << 20, "gbytes": 1 << 30}
+
+// Quota is an allowance of bytes. nftables counts it; Housecarl keeps the
+// count across changes and restarts, and resets it each period.
+type Quota struct {
+	Bytes int64 `json:"bytes"`
+	// Over matches once the allowance is used up (to drop); otherwise the
+	// rule matches while it lasts (to accept).
+	Over bool `json:"over,omitempty"`
+	// PerSource gives each source address (grouped as the rule's
+	// GroupV4/GroupV6 say) its own allowance; PerDestination each
+	// destination.
+	PerSource      bool `json:"per_source,omitempty"`
+	PerDestination bool `json:"per_destination,omitempty"`
+	// Reset: "" (only by hand), daily, weekly (on Mondays) or monthly (on
+	// Day, 1-31: a short month's last day when it has no such day), at
+	// midnight.
+	Reset string `json:"reset,omitempty"`
+	Day   int    `json:"day,omitempty"`
+}
+
+// Quota resets.
+var QuotaResets = []string{"daily", "weekly", "monthly"}
+
+// PerAddress reports whether a quota (or limit) counts each address on its
+// own, and which: "saddr", "daddr" or "".
+func (q *Quota) PerAddress() string {
+	switch {
+	case q == nil:
+		return ""
+	case q.PerSource:
+		return "saddr"
+	case q.PerDestination:
+		return "daddr"
+	}
+	return ""
+}
+
+// PerAddress: as Quota's.
+func (l *Limit) PerAddress() string {
+	switch {
+	case l == nil:
+		return ""
+	case l.PerSource:
+		return "saddr"
+	case l.PerDestination:
+		return "daddr"
+	}
+	return ""
+}
+
+// CountsTraffic reports whether a rule measures traffic (a quota or a byte
+// rate): it must see every packet of a connection, so it is checked before
+// the built-in that accepts established connections.
+func (r *Rule) CountsTraffic() bool {
+	if r.Raw != "" {
+		return false
+	}
+	if r.Quota != nil {
+		return true
+	}
+	if r.Limit == nil {
+		return false
+	}
+	_, bytes := ByteUnits[r.Limit.Unit]
+	return bytes
+}
+
+// Groups returns a rule's address grouping, defaults applied.
+func (r *Rule) Groups() (v4, v6 int) {
+	v4, v6 = r.GroupV4, r.GroupV6
+	if v4 == 0 {
+		v4 = 32
+	}
+	if v6 == 0 {
+		v6 = 64
+	}
+	return v4, v6
 }
 
 // PortForward publishes a service on an inside host: incoming connections