Quotas: reset one address, or give some back

POST /rules/{ref}/reset-quota takes an optional address (one entry of a
per-address quota starts again) and give (bytes taken off what was used,
one address's or everyone's, until the next reset). The firewall keeps
the adjustment for its next apply, which writes the new usage into the
ruleset; housecarld applies at once and saves the usage. hc rule
reset-quota --address/--give; Reset and Give back in the web UI, per
address in the usage dialog.

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

internal/api/types.go

@@ -326,6 +326,16 @@ type CertificateResponse struct {
 	Status *CertStatus `json:"status,omitempty"`
 }
 
+// QuotaReset is POST /rules/{ref}/reset-quota's optional body. Without
+// one the whole quota starts again. Address starts one address of a
+// per-address quota again (any address in its group: 10.0.10.23, or an
+// IPv6 address for its /64); Give takes that many bytes off what was used
+// instead (the address's, or every address's), until the next reset.
+type QuotaReset struct {
+	Address string `json:"address,omitempty"`
+	Give    int64  `json:"give,omitempty"`
+}
+
 // QuotaInfo is a rule's quota and what it used.
 type QuotaInfo struct {
 	RuleID int64       `json:"rule_id"`

internal/nft/nft.go

@@ -422,6 +422,8 @@ type Firewall struct {
 	// restore is the quota usage saved before housecarld (or the machine)
 	// stopped, put back by the next apply.
 	restore *QuotaUsage
+	// adjust are quota changes the next apply makes (AdjustQuota).
+	adjust []QuotaAdjust
 	// flowDevs are the flowtable's devices in the ruleset in force, by
 	// name, with their interface index then (0: left out, missing).
 	flowDevs map[string]int
@@ -462,6 +464,52 @@ func (f *Firewall) RestoreQuotas(u *QuotaUsage) {
 	f.restore = u
 }
 
+// QuotaAdjust takes Give bytes off what a quota used (never below zero):
+// the named quota Name, or the entries of the per-address sets Name_v4
+// and Name_v6, Addr's alone if given (the set's key, as listed).
+type QuotaAdjust struct {
+	Name string
+	Addr string
+	Give int64
+}
+
+// AdjustQuota has the next apply change what a quota used.
+func (f *Firewall) AdjustQuota(a QuotaAdjust) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.adjust = append(f.adjust, a)
+}
+
+// apply takes what a's say off u. An entry with nothing left used is
+// dropped, so its quota starts again with its next packet.
+func (u *QuotaUsage) apply(adj []QuotaAdjust) {
+	less := func(used, give int64) int64 {
+		if give >= used {
+			return 0
+		}
+		return used - give
+	}
+	for _, a := range adj {
+		if used, ok := u.Quotas[a.Name]; ok {
+			u.Quotas[a.Name] = less(used, a.Give)
+		}
+		for _, set := range []string{a.Name + "_v4", a.Name + "_v6"} {
+			var kept []render.Element
+			for _, e := range u.QuotaSets[set] {
+				if a.Addr == "" || e.Addr == a.Addr {
+					e.Used = less(e.Used, a.Give)
+				}
+				if e.Used > 0 {
+					kept = append(kept, e)
+				}
+			}
+			if _, ok := u.QuotaSets[set]; ok {
+				u.QuotaSets[set] = kept
+			}
+		}
+	}
+}
+
 // ResetQuota starts a rule's quota again: the named quota, or the
 // per-address quota sets (both families).
 func (f *Firewall) ResetQuota(ctx context.Context, ruleID int64, perAddress bool) error {
@@ -531,6 +579,8 @@ func (f *Firewall) Apply(ctx context.Context, st *model.State) error {
 		usage = old.QuotaUsage
 	}
 	usage.merge(f.restore)
+	usage.apply(f.adjust)
+	f.adjust = nil
 	opt.Quotas, opt.QuotaSets = usage.Quotas, usage.QuotaSets
 	if old != nil {
 		opt.DeviceSets = old.DeviceSets

internal/nft/nft_test.go

@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"reflect"
 	"sort"
 	"strings"
 	"testing"
@@ -186,6 +187,16 @@ func TestQuotasInContainer(t *testing.T) {
 	if t2, d2 := used(); t2 < total || d2 < dev {
 		t.Errorf("after a reload: total %d (was %d), per destination %d (was %d)", t2, total, d2, dev)
 	}
+	// Some given back, and one address started again, by the next apply.
+	total, dev = used()
+	fw.AdjustQuota(QuotaAdjust{Name: "quota_r1", Give: 1000})
+	fw.AdjustQuota(QuotaAdjust{Name: "quota_r2", Addr: "127.0.0.3", Give: 1 << 62})
+	if err := fw.Apply(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	if t2, d2 := used(); t2 > total-1000 || t2 < total-2000 || d2 != 0 {
+		t.Errorf("after giving back: total %d (was %d, gave 1000), per destination %d (was %d, reset)", t2, total, d2, dev)
+	}
 	// Reset by hand.
 	if err := fw.ResetQuota(ctx, 1, false); err != nil {
 		t.Fatal(err)
@@ -212,6 +223,23 @@ func TestQuotasInContainer(t *testing.T) {
 	}
 }
 
+// TestQuotaAdjust: giving back takes off what was used, never below
+// zero; an entry with nothing left goes.
+func TestQuotaAdjust(t *testing.T) {
+	u := QuotaUsage{Quotas: map[string]int64{"quota_r1": 5000, "quota_r9": 10},
+		QuotaSets: map[string][]render.Element{"quota_r2_v4": {{Addr: "10.0.0.1", Used: 3000}, {Addr: "10.0.0.2", Used: 4000}},
+			"quota_r2_v6": {{Addr: "2001:db8::", Used: 100}}}}
+	u.apply([]QuotaAdjust{{Name: "quota_r1", Give: 2000}, {Name: "quota_r9", Give: 2000}, {Name: "quota_r2", Addr: "10.0.0.2", Give: 1500},
+		{Name: "quota_r2", Give: 100}})
+	if u.Quotas["quota_r1"] != 3000 || u.Quotas["quota_r9"] != 0 {
+		t.Errorf("named: %v", u.Quotas)
+	}
+	want := map[string][]render.Element{"quota_r2_v4": {{Addr: "10.0.0.1", Used: 2900}, {Addr: "10.0.0.2", Used: 2400}}, "quota_r2_v6": nil}
+	if !reflect.DeepEqual(u.QuotaSets, want) {
+		t.Errorf("sets: %+v", u.QuotaSets)
+	}
+}
+
 // TestDeviceCountsInContainer: the per-device counters are read back and
 // survive a reload.
 func TestDeviceCountsInContainer(t *testing.T) {

internal/server/quota.go

@@ -4,8 +4,11 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"math"
 	"net/http"
+	"net/netip"
 	"sort"
+	"strings"
 	"time"
 
 	"housecarl/internal/api"
@@ -237,7 +240,8 @@ func (s *Server) listQuotas(w http.ResponseWriter, r *http.Request, p *auth.Prin
 	return nil
 }
 
-// resetQuota starts a rule's quota again now.
+// resetQuota starts a rule's quota again now: all of it, or one
+// address's; or gives some of what it used back, until its next reset.
 func (s *Server) resetQuota(w http.ResponseWriter, r *http.Request, p *auth.Principal) error {
 	if err := require(p, auth.ResConfig, true); err != nil {
 		return err
@@ -250,14 +254,103 @@ func (s *Server) resetQuota(w http.ResponseWriter, r *http.Request, p *auth.Prin
 	if rule.Quota == nil {
 		return badRequest("%s has no quota", rule.Label())
 	}
-	if err := s.fw.ResetQuota(r.Context(), rule.ID, rule.Quota.PerAddress() != ""); err != nil {
+	var in api.QuotaReset
+	if err := decodeOptional(r, &in); err != nil {
 		return err
 	}
-	resets := s.quotaResets(r.Context())
-	resets[fmt.Sprintf("r%d", rule.ID)] = s.nowFn()
-	s.saveQuotaResets(r.Context(), resets)
-	s.forgetQuotaUsage(r.Context(), rule.ID)
-	s.eng.Audit(r.Context(), p, "quota.reset", rule.Label(), "success", "")
-	writeJSON(w, http.StatusOK, map[string]any{"reset": rule.Label()})
+	if in.Give < 0 {
+		return badRequest("give a number of bytes to give back, 1 or more")
+	}
+	if in.Address == "" && in.Give == 0 {
+		if err := s.fw.ResetQuota(r.Context(), rule.ID, rule.Quota.PerAddress() != ""); err != nil {
+			return err
+		}
+		resets := s.quotaResets(r.Context())
+		resets[fmt.Sprintf("r%d", rule.ID)] = s.nowFn()
+		s.saveQuotaResets(r.Context(), resets)
+		s.forgetQuotaUsage(r.Context(), rule.ID)
+		s.eng.Audit(r.Context(), p, "quota.reset", rule.Label(), "success", "")
+		writeJSON(w, http.StatusOK, map[string]any{"reset": rule.Label()})
+		return nil
+	}
+	name := render.QuotaName(rule.ID)
+	adj := nft.QuotaAdjust{Name: name, Give: in.Give}
+	if in.Address != "" {
+		if rule.Quota.PerAddress() == "" {
+			return badRequest("%s has one quota for everything it matches, not one per address: leave out the address", rule.Label())
+		}
+		key, err := quotaKey(rule, in.Address)
+		if err != nil {
+			return err
+		}
+		if !s.quotaHas(r.Context(), name, key) {
+			return notFound("%s hasn't used the quota of %s since its last reset", in.Address, rule.Label())
+		}
+		adj.Addr = key
+	}
+	if adj.Give == 0 {
+		adj.Give = math.MaxInt64 // all of it: the address starts again
+	}
+	// The next apply writes the quota's new usage into the ruleset.
+	s.fw.AdjustQuota(adj)
+	if err := s.eng.ApplyCurrent(r.Context()); err != nil {
+		return fmt.Errorf("putting the ruleset in force with the quota's new usage: %w", err)
+	}
+	s.SaveQuotaUsage(r.Context())
+	detail, out := "", map[string]any{}
+	if in.Give > 0 {
+		detail = fmt.Sprintf("gave back %d bytes", in.Give)
+		out["given"] = in.Give
+	}
+	if in.Address != "" {
+		detail = strings.TrimSpace(detail + " " + in.Address)
+		out["address"] = in.Address
+	}
+	action := "quota.reset"
+	if in.Give > 0 {
+		action = "quota.give"
+	}
+	s.eng.Audit(r.Context(), p, action, rule.Label(), "success", detail)
+	out["reset"] = rule.Label()
+	writeJSON(w, http.StatusOK, out)
 	return nil
 }
+
+// quotaKey is the entry of a per-address quota an address counts under:
+// the address, or its group's first address (10.0.10.0 for a /24; an
+// IPv6 address's /64).
+func quotaKey(rule *model.Rule, s string) (string, error) {
+	var a netip.Addr
+	if p, err := netip.ParsePrefix(s); err == nil {
+		a = p.Addr()
+	} else if a, err = netip.ParseAddr(s); err != nil {
+		return "", badRequest("%q isn't an address", s)
+	}
+	a = a.Unmap()
+	v4, v6 := rule.Groups()
+	bits := v4
+	if a.Is6() {
+		bits = v6
+	}
+	p, err := a.Prefix(bits)
+	if err != nil {
+		return "", badRequest("%q: %v", s, err)
+	}
+	return p.Addr().String(), nil
+}
+
+// quotaHas reports whether a per-address quota has an entry for key.
+func (s *Server) quotaHas(ctx context.Context, name, key string) bool {
+	t, err := s.fw.Table(ctx)
+	if err != nil {
+		return false
+	}
+	for _, set := range []string{name + "_v4", name + "_v6"} {
+		for _, e := range t.QuotaSets[set] {
+			if e.Addr == key {
+				return true
+			}
+		}
+	}
+	return false
+}

internal/server/server.go

@@ -79,6 +79,8 @@ type Firewall interface {
 	SaveBoot(st *model.State) error
 	// ResetQuota starts a rule's quota again (perAddress: its sets).
 	ResetQuota(ctx context.Context, ruleID int64, perAddress bool) error
+	// AdjustQuota has the next apply change what a quota used.
+	AdjustQuota(a nft.QuotaAdjust)
 	// Trace follows packets (internal/trace) until ctx ends.
 	Trace(ctx context.Context, script string, line func(string)) error
 }

internal/server/server_test.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"math"
 	"net/http"
 	"net/http/cookiejar"
 	"net/http/httptest"
@@ -45,6 +46,8 @@ type fakeFW struct {
 	fallback   bool // the boot fallback is in force
 	shadow     bool
 	ruleset    string // nft -j list ruleset ("": a default)
+	quotas     nft.QuotaUsage
+	adjusted   []nft.QuotaAdjust
 }
 
 func (f *fakeFW) Check(_ context.Context, st *model.State) error { return nil }
@@ -74,7 +77,12 @@ func (f *fakeFW) Table(context.Context) (*nft.Table, error) {
 	if len(f.applied) == 0 {
 		return nil, errors.New("No such file or directory: list table inet housecarl")
 	}
-	return &nft.Table{Counters: map[string]nft.Counter{"r1": {Packets: 3, Bytes: 180}}, Elements: f.elements, Fallback: f.fallback}, nil
+	return &nft.Table{Counters: map[string]nft.Counter{"r1": {Packets: 3, Bytes: 180}}, Elements: f.elements, Fallback: f.fallback, QuotaUsage: f.quotas}, nil
+}
+func (f *fakeFW) AdjustQuota(a nft.QuotaAdjust) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.adjusted = append(f.adjusted, a)
 }
 func (f *fakeFW) AddElement(_ context.Context, set, addr string, timeout int) error {
 	f.mu.Lock()
@@ -750,9 +758,38 @@ func TestQuotaResets(t *testing.T) {
 	if len(qs) != 1 || qs[0].NextReset == nil || qs[0].NextReset.Day() != 21 {
 		t.Errorf("quotas %+v", qs)
 	}
-	if code := e.call(e.token, "POST", "/rules/"+itoa(created.ID)+"/reset-quota", nil, nil); code != 200 || len(e.fw.resets) != 2 {
+	reset := "/rules/" + itoa(created.ID) + "/reset-quota"
+	if code := e.call(e.token, "POST", reset, nil, nil); code != 200 || len(e.fw.resets) != 2 {
 		t.Errorf("reset by hand: %d %v", code, e.fw.resets)
 	}
+
+	// One address started again, or some given back: the next apply
+	// (made at once) writes the new usage.
+	name := render.QuotaName(created.ID)
+	e.fw.quotas = nft.QuotaUsage{QuotaSets: map[string][]render.Element{name + "_v4": {{Addr: "10.0.10.23", Used: 6 << 30}},
+		name + "_v6": {{Addr: "2001:db8:1:2::", Used: 1 << 30}}}}
+	applies := len(e.fw.applied)
+	if code := e.call(e.token, "POST", reset, api.QuotaReset{Address: "10.0.10.23"}, nil); code != 200 {
+		t.Errorf("reset one address: %d", code)
+	}
+	if code := e.call(e.token, "POST", reset, api.QuotaReset{Address: "2001:db8:1:2:aaaa::7", Give: 2 << 30}, nil); code != 200 {
+		t.Errorf("give back to an IPv6 address (its /64): %d", code)
+	}
+	if code := e.call(e.token, "POST", reset, api.QuotaReset{Give: 1 << 30}, nil); code != 200 {
+		t.Errorf("give back to everyone: %d", code)
+	}
+	want3 := []nft.QuotaAdjust{{Name: name, Addr: "10.0.10.23", Give: math.MaxInt64}, {Name: name, Addr: "2001:db8:1:2::", Give: 2 << 30}, {Name: name, Give: 1 << 30}}
+	if !reflect.DeepEqual(e.fw.adjusted, want3) || len(e.fw.applied) != applies+3 || len(e.fw.resets) != 2 {
+		t.Errorf("adjusted %+v, applied %d more, resets %v", e.fw.adjusted, len(e.fw.applied)-applies, e.fw.resets)
+	}
+	for _, c := range []struct {
+		in   api.QuotaReset
+		code int
+	}{{api.QuotaReset{Address: "10.0.10.99"}, 404}, {api.QuotaReset{Address: "nonsense"}, 400}, {api.QuotaReset{Give: -5}, 400}} {
+		if code := e.call(e.token, "POST", reset, c.in, nil); code != c.code {
+			t.Errorf("%+v: %d, want %d", c.in, code, c.code)
+		}
+	}
 }
 
 // TestAutoConfirm: the client that made a change confirms it by itself:

internal/web/static/assets/pages/rules.js

@@ -175,24 +175,57 @@ function quotaLine(r, q) {
   return h("div", { class: "muted small" }, (qt.over ? "quota over " : "quota ") + fmtBytes(qt.bytes) + each + ", resets " + resets,
     used ? [" · ", used] : null,
     q && q.next_reset ? " · next reset " + new Date(q.next_reset).toLocaleString() : null,
-    can("config", true) && q && r.pending !== "new" ? [" ", h("button", { class: "small", onclick: () => resetQuota(r) }, "Reset")] : null);
+    can("config", true) && q && r.pending !== "new" ? [" ", h("button", { class: "small", onclick: () => resetQuota(r) }, "Reset"),
+      " ", h("button", { class: "small", onclick: () => giveBack(r) }, "Give back…")] : null);
 }
 
 async function usageDialog(r, q) {
   const names = await lookupNames(q.addresses.map((a) => a.address));
+  // A row's action closes this dialog first: it opens one of its own.
+  const then = (f) => (e) => { e.target.closest(".modal").querySelector(".buttons button").click(); f(); };
+  const write = can("config", true);
   await modal("Quota usage of " + (r.comment || "rule #" + r.id), h("div", null,
     h("p", { class: "muted" }, "Each " + (r.quota.per_source ? "source" : "destination") + " has " + fmtBytes(r.quota.bytes) + "."),
     table([
       { label: "Address", render: (a) => h("span", { class: "mono" }, named(names, a.address)) },
       { label: "Used", render: (a) => fmtBytes(a.used) },
       { label: "", render: (a) => usageBar(a.used, r.quota.bytes) },
-    ], q.addresses)), [{ label: "Close", value: null }], { wide: true });
+      write ? { label: "", render: (a) => h("span", { class: "nowrap" },
+        h("button", { class: "small", onclick: then(() => resetQuota(r, a.address)) }, "Reset"), " ",
+        h("button", { class: "small", onclick: then(() => giveBack(r, a.address)) }, "Give back…")) } : null,
+    ].filter(Boolean), q.addresses)), [{ label: "Close", value: null }], { wide: true });
 }
 
-async function resetQuota(r) {
+// giveBack takes an amount off what a quota used (one address's, or
+// everyone's): extra allowance until its next reset.
+async function giveBack(r, address) {
+  const amount = input({ type: "number", min: 1, value: "1", class: "short" });
+  const unit = select([["mb", "MB"], ["gb", "GB"]], "gb", { class: "inline" });
+  const perAddress = r.quota.per_source || r.quota.per_destination;
+  const who = address ? " for " + address : perAddress ? " for every address" : "";
+  await modal("Give back quota", h("div", null,
+    h("p", null, "Take this much off what " + (r.comment || "rule #" + r.id) + "'s quota used" + who + ": extra allowance until its next reset, without changing the rule. This is done at once, not staged."),
+    field("Amount", h("div", null, amount, " ", unit))), [
+    { label: "Cancel", value: null },
+    { label: "Give back", kind: "primary", onclick: async () => {
+      const n = parseInt(amount.value, 10);
+      if (!(n > 0)) { toast("Give an amount of 1 or more", "err"); return false; }
+      const give = n * (unit.value === "gb" ? 1 << 30 : 1 << 20);
+      try {
+        await api("POST", "/rules/" + r.id + "/reset-quota", { body: address ? { give, address } : { give } });
+        toast("Gave back " + fmtBytes(give)); rerender();
+      } catch (e) { modal("Not given back", errorBox(e)); return false; }
+    } },
+  ]);
+}
+
+async function resetQuota(r, address) {
   if (!await confirmDialog("Reset the quota", "Start the quota of " + (r.comment || "rule #" + r.id) + " again now" +
-    (r.quota.per_source || r.quota.per_destination ? ", for every address" : "") + "? This is done at once, not staged.", "Reset")) return;
-  try { await api("POST", "/rules/" + r.id + "/reset-quota"); toast("Quota reset"); rerender(); } catch (e) { modal("Not reset", errorBox(e)); }
+    (address ? " for " + address : r.quota.per_source || r.quota.per_destination ? ", for every address" : "") + "? This is done at once, not staged.", "Reset")) return;
+  try {
+    await api("POST", "/rules/" + r.id + "/reset-quota", address ? { body: { address } } : {});
+    toast("Quota reset"); rerender();
+  } catch (e) { modal("Not reset", errorBox(e)); }
 }
 
 async function move(r, where) {