Re-vendor the canonical files from sneak/prompts at 0653579 (closes #221)

REPO_POLICIES.md, script/cibuild, script/docker, script/lint and
script/test are their copies at that commit. In every Dockerfile stage
the system package install and the Go module download now come before
ARG CACHEBUST, so check builds keep those layers until the base image,
the install line, go.mod or go.sum change. golangci-lint run also
mounts golangci-lint's cache. The test phase and the build stage
install their packages with apt-get and apk directly, as
REPO_POLICIES.md now has them do, instead of through
script/bootstrap --cgo. The test phase installs no recommended
packages and names libheif's AVIF encoder, libheif-plugin-aomenc,
which the tests use.

Model: opus-5-5

Dockerfile

@@ -34,11 +34,11 @@ RUN --mount=type=cache,target=/root/.cache/go-build \
 FROM golang@sha256:a02d35efc036053fdf0da8c15919276bf777a80cbfda6a35c5e9f087e652adfc AS test
 
 # govips compiles against the libvips and libheif headers, and the tests
-# need libvips' JPEG XL support and libheif's AVIF encoder. Debian's
-# libvips-dev brings all of them, the encoder as a recommended package,
-# so recommended packages are installed here.
+# need libvips' JPEG XL support; libvips-dev brings all three. The tests
+# also encode AVIF, which needs libheif's AVIF encoder,
+# libheif-plugin-aomenc: Debian only recommends it, so it is named here.
 RUN apt-get update \
-    && apt-get install -y libvips-dev \
+    && apt-get install -y --no-install-recommends libvips-dev libheif-plugin-aomenc \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /src

README.md

@@ -102,8 +102,8 @@ it uses libvips through CGO. pixad does not start unless libvips has its JPEG XL
 support, which on Alpine is the `vips-jxl` package and which the nix and brew
 packages of libvips include, as do the apt ones from Debian 12 and Ubuntu 24.04
 on. Building pixa also needs the development files of libvips and libheif,
-`pkg-config` and a C compiler. `script/bootstrap --cgo` installs all of these,
-as the `Dockerfile` does where it compiles pixa. Plain `script/bootstrap`, which
+`pkg-config` and a C compiler. `script/bootstrap --cgo` installs all of these;
+the `Dockerfile` installs its own packages. Plain `script/bootstrap`, which
 `script/setup` and `script/cibuild` run, installs git, make and Go, and Node,
 Yarn and the prettier pinned in `yarn.lock` for formatting the markdown, but
 none of the C libraries: the checks compile pixa in Docker. Docker itself must
@@ -199,7 +199,11 @@ into place, so a crash leaves no file under its own name with part of its data.
 When pixa starts, and every five minutes after, it removes each cached source or
 transformed image whose file is empty, or not the size the database records for
 it, with a warning naming the file; the next request for it fetches the source
-or converts the image again.
+or converts the image again. Looking for those files reads the database once for
+every cached file, so pixa skips each five-minute look that would start less
+than ten times as long after the last look ended as that look took. After a look
+that took one minute, the next one starts 10 to 15 minutes after that look
+ended.
 
 pixa's target is 1-5k r/s, which has not been measured at that rate (see Load
 Test). Toward it, pixa keeps in memory the content types of the 10,000
@@ -697,7 +701,9 @@ Key settings in more detail:
   benchmark, NAT64, and the like); an invalid CIDR aborts startup. An IPv6
   address in the IPv4-mapped form (`::ffff:a.b.c.d`) is matched only as the IPv4
   address it holds, so an IPv6 range such as `::/0` refuses neither it nor a
-  plain IPv4 address
+  plain IPv4 address. An entry written in that form is read as the IPv4 range it
+  covers, so `::ffff:10.0.0.0/104` refuses what `10.0.0.0/8` refuses; such an
+  entry shorter than `/96` covers more than IPv4 addresses and aborts startup
 - `trusted_proxies` — list of CIDR ranges of the reverse proxies in front of
   pixa. `X-Forwarded-For` is believed only when the direct peer falls inside one
   of these ranges; the logged and login-recorded client address is then the

TODO.md

@@ -34,6 +34,12 @@ P2: security: per-origin rate limiting
   each `Dockerfile` stage installs its system packages and downloads the Go
   modules above `ARG CACHEBUST`, so check builds keep them, and the lint step
   keeps golangci-lint's cache.
+- 2026-10-18 the next reconciliation pass waits at least ten times as long as
+  the last one took, so passes on a large cache no longer run back to back
+  (closes #250).
+- 2026-10-18 a `blocked_networks` entry in the IPv4-mapped form refused nothing;
+  `::ffff:10.0.0.0/104` is now read as `10.0.0.0/8`, and such an entry shorter
+  than `/96` aborts startup (closes #301).
 - 2026-10-16 P1 security bug: the check that keeps pixa from fetching internal
   addresses refuses the local-use NAT64 range (`64:ff9b:1::/48`, RFC 8215) as it
   refuses `64:ff9b::/96`, and refuses an IPv6 address in the IPv4-compatible

internal/config/blocked_networks_internal_test.go

@@ -88,3 +88,56 @@ func TestBlockedNetworksInvalidAbortsStartup(t *testing.T) {
 		},
 	})
 }
+
+// TestBlockedNetworksMappedEntryIsIPv4Range checks that an entry written in
+// the IPv4-mapped form (::ffff:a.b.c.d) is kept as the IPv4 range it covers,
+// since the fetcher matches an IPv4-mapped address as the IPv4 address it
+// holds. /96, the shortest such entry, covers every IPv4 address.
+func TestBlockedNetworksMappedEntryIsIPv4Range(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := signingKeyLine + `blocked_networks:
+  - "::ffff:10.0.0.0/104"
+  - "::ffff:0:0/96"
+`
+
+	c, err := configFromYAML(t, yamlContent)
+	if err != nil {
+		t.Fatalf("IPv4-mapped blocked_networks entries should load, got error: %v", err)
+	}
+
+	want := []string{"10.0.0.0/8", "0.0.0.0/0"}
+	if len(c.BlockedNetworks) != len(want) {
+		t.Fatalf("BlockedNetworks = %v, want %d entries", c.BlockedNetworks, len(want))
+	}
+
+	for i, w := range want {
+		if got := c.BlockedNetworks[i].String(); got != w {
+			t.Errorf("BlockedNetworks[%d] = %q, want %q", i, got, w)
+		}
+	}
+}
+
+// TestBlockedNetworksMappedEntryShorterThan96AbortsStartup checks that an
+// entry in the IPv4-mapped form shorter than /96, which covers more than the
+// IPv4 addresses, aborts startup with an error naming the key and the value.
+func TestBlockedNetworksMappedEntryShorterThan96AbortsStartup(t *testing.T) {
+	t.Parallel()
+
+	runAbortCases(t, []abortCase{
+		{
+			name: "mapped-shorter-than-96",
+			yaml: signingKeyLine + `blocked_networks:
+  - "::ffff:0.0.0.0/80"
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks, "::ffff:0.0.0.0/80"},
+		},
+		{
+			name: "mapped-95",
+			yaml: signingKeyLine + `blocked_networks:
+  - "::ffff:0:0/95"
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks},
+		},
+	})
+}

internal/config/config.go

@@ -91,6 +91,7 @@ var (
 	errNotABoolean       = errors.New("not a boolean")
 	errNotAStringList    = errors.New("not a list of strings")
 	errNotAValidCIDR     = errors.New("not a valid CIDR network")
+	errMappedTooShort    = errors.New("in the IPv4-mapped form but shorter than /96")
 	errNotAMetricsMap    = errors.New("not a map of metrics settings")
 	errEmptyListEntry    = errors.New("list contains an empty entry")
 	errEmptyEntry        = errors.New("contains an empty entry")
@@ -271,7 +272,7 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 		return nil, err
 	}
 
-	blockedNetworks, err := parseCIDRList(sc, keyBlockedNetworks)
+	blockedNetworks, err := parseBlockedNetworks(sc)
 	if err != nil {
 		return nil, err
 	}
@@ -1278,6 +1279,39 @@ func parseCIDRList(sc *smartconfig.Config, key string) ([]netip.Prefix, error) {
 	return prefixes, nil
 }
 
+// parseBlockedNetworks parses blocked_networks with parseCIDRList, and keeps
+// an entry written in the IPv4-mapped form (::ffff:a.b.c.d) as the IPv4
+// range it covers: ::ffff:10.0.0.0/104 is kept as 10.0.0.0/8. The fetcher
+// matches an IPv4-mapped address as the IPv4 address it holds, so the entry
+// as written would match nothing. Such an entry shorter than /96 covers more
+// than the IPv4 addresses and aborts startup.
+func parseBlockedNetworks(sc *smartconfig.Config) ([]netip.Prefix, error) {
+	prefixes, err := parseCIDRList(sc, keyBlockedNetworks)
+	if err != nil {
+		return nil, err
+	}
+
+	// An IPv4-mapped address is the 96 bits of ::ffff:0:0/96 followed by
+	// the 32 bits of the IPv4 address it holds.
+	const mappedPrefixBits = 96
+
+	for i, prefix := range prefixes {
+		if !prefix.Addr().Is4In6() {
+			continue
+		}
+
+		if prefix.Bits() < mappedPrefixBits {
+			return nil, fmt.Errorf("%s: value %q is %w",
+				settingName(keyBlockedNetworks), prefix, errMappedTooShort)
+		}
+
+		prefixes[i] = netip.PrefixFrom(prefix.Addr().Unmap(),
+			prefix.Bits()-mappedPrefixBits)
+	}
+
+	return prefixes, nil
+}
+
 // parseHostList parses the value of the named config key into host patterns,
 // or returns nil if the key is omitted. It accepts a YAML list of strings or a
 // comma-separated string. An explicitly null value, a wrong type, an empty

internal/imgcache/eviction.go

@@ -18,6 +18,14 @@ import (
 // write-pressure wakeups triggered by stores.
 const DefaultEvictionInterval = 5 * time.Minute
 
+// reconciliationWaitFactor is how many times as long as a
+// reconciliation pass took the eviction loop waits at least, after that
+// pass ends, before it starts the next one. A pass reads a row and stats a
+// file for every cached file, so its time grows with the cache; waiting
+// ten times as long keeps reconciliation to at most a tenth of the time,
+// however large the cache is.
+const reconciliationWaitFactor = 10
+
 // evictionBatchSize is how many LRU candidates of each class (variants
 // and source blobs) one eviction pass fetches from the database.
 const evictionBatchSize = 100
@@ -438,10 +446,12 @@ func (c *Cache) notifyWritePressure() {
 }
 
 // StartEviction launches the background eviction goroutine, which
-// reconciles the database accounting with the cache directories and
 // removes the expired negative cache rows at startup and again on every
-// periodic tick thereafter, and evicts to the configured limit on the
-// given periodic interval and on write-pressure notifications. On a
+// periodic tick thereafter, reconciles the database accounting with the
+// cache directories at startup and again on the first periodic tick
+// that comes at least ten times as long after a reconciliation pass
+// ended as that pass took, and evicts to the configured limit on the given
+// periodic interval and on write-pressure notifications. On a
 // disabled cache it only removes the expired negative cache rows, as
 // the negative cache is used either way. It is a no-op when already
 // started. The goroutine outlives the caller, so it runs with its own
@@ -482,7 +492,7 @@ func (c *Cache) StopEviction(ctx context.Context) error {
 func (c *Cache) evictionLoop(ctx context.Context, interval time.Duration) {
 	defer close(c.evictionDone)
 
-	c.runReconciliationPass(ctx)
+	nextReconciliation := c.runReconciliationPass(ctx)
 	c.runCleanExpired(ctx)
 	c.runEvictionPass(ctx)
 
@@ -494,16 +504,20 @@ func (c *Cache) evictionLoop(ctx context.Context, interval time.Duration) {
 		case <-ctx.Done():
 			return
 		case <-ticker.C:
-			// Reconciliation walks the cache directories, so it only
-			// runs on the periodic ticker rather than on every
-			// write-pressure wakeup, keeping it off the per-store hot
-			// path. Reusing the eviction interval itself (rather than a
-			// separate, longer one) is a deliberate choice: it is the
-			// simplest option that still bounds how long a store's
-			// best-effort accounting insert can stay silently
-			// unaccounted for to one interval, on a process that is
-			// already running this loop regardless.
-			c.runReconciliationPass(ctx)
+			// Reconciliation walks the cache directories and reads a
+			// row for every file, so it runs only on the periodic
+			// ticker rather than on every write-pressure wakeup, and
+			// only on the first tick at or after nextReconciliation,
+			// which is ten times as long after the last pass ended as
+			// that pass took. Passes then never run back to back,
+			// however long one takes. A file whose best-effort
+			// accounting insert failed in a store stays unaccounted for
+			// until the next pass, up to about one eviction interval
+			// plus ten times the last pass's time.
+			if !time.Now().Before(nextReconciliation) {
+				nextReconciliation = c.runReconciliationPass(ctx)
+			}
+
 			c.runCleanExpired(ctx)
 		case <-c.evictionPressure:
 		}
@@ -527,17 +541,25 @@ func (c *Cache) runEvictionPass(ctx context.Context) {
 }
 
 // runReconciliationPass runs one reconciliation pass, logging failures
-// instead of propagating them (the loop must keep running). It does
-// nothing once ctx is cancelled.
-func (c *Cache) runReconciliationPass(ctx context.Context) {
+// instead of propagating them (the loop must keep running), and returns
+// the earliest time the next pass may start: reconciliationWaitFactor
+// times as long after this pass ended as it took. It does nothing once
+// ctx is cancelled.
+func (c *Cache) runReconciliationPass(ctx context.Context) time.Time {
 	if ctx.Err() != nil {
-		return
+		return time.Now()
 	}
 
+	started := time.Now()
+
 	err := c.reconcileAccounting(ctx)
 	if err != nil {
 		c.log.Warn("cache accounting reconciliation failed", "error", err)
 	}
+
+	ended := time.Now()
+
+	return ended.Add(reconciliationWaitFactor * ended.Sub(started))
 }
 
 // runCleanExpired runs CleanExpired, logging a failure instead of
@@ -556,7 +578,8 @@ func (c *Cache) runCleanExpired(ctx context.Context) {
 
 // reconcileAccounting synchronizes the database size accounting with
 // the actual contents of the cache directories. It runs at startup and
-// again on every periodic eviction tick thereafter, off the request
+// then on the first periodic eviction tick that comes at least ten times
+// as long after the last pass ended as that pass took, off the request
 // hot path: it adopts variant files that predate the accounting table
 // (or whose accounting insert failed, e.g. StoreVariant's best-effort
 // insert under transient DB contention), drops accounting rows whose
@@ -566,9 +589,10 @@ func (c *Cache) runCleanExpired(ctx context.Context) {
 // files left behind by crashed writes, and last checks the total cache
 // usage against the tables. It reads the tables a page at a time.
 // Running it periodically, not just once, bounds how long such drift can
-// accumulate unaccounted for on a long-running process to one eviction
-// interval. Once ctx is cancelled, it stops at the next file or row and
-// returns ctx's error.
+// accumulate unaccounted for on a long-running process to about one
+// eviction interval plus ten times the last pass's time.
+// Once ctx is cancelled, it stops at the next file or row and returns
+// ctx's error.
 func (c *Cache) reconcileAccounting(ctx context.Context) error {
 	if c.disabled {
 		return nil

internal/imgcache/eviction_internal_test.go

@@ -918,6 +918,89 @@ func TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup(t *testing.T) {
 	}
 }
 
+// TestReconciliationPassesAreSpacedByTenTimesTheirTime makes the hook
+// called after every read of the reconciliation pass sleep 10 ms, runs
+// the eviction loop on a 10 ms interval, and records when each of those
+// calls starts and ends. A pass starts before its first call and ends
+// after its last, so the time from the first call's start to the last
+// call's end is at most the pass's time. The next pass's first call must
+// start at least ten times that long after the last call ended.
+func TestReconciliationPassesAreSpacedByTenTimesTheirTime(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	// A pass made here, before the loop starts, counts the reads one
+	// pass makes on this empty cache, so the reads recorded below can be
+	// split into passes.
+	readsPerPass := 0
+	cache.reconciliationReadTestHook = func(int) { readsPerPass++ }
+
+	err := cache.reconcileAccounting(t.Context())
+	if err != nil {
+		t.Fatalf("reconcileAccounting failed: %v", err)
+	}
+
+	t.Logf("one reconciliation pass makes %d reads", readsPerPass)
+
+	if readsPerPass == 0 {
+		t.Fatal("a reconciliation pass made no read")
+	}
+
+	// The pass at startup and two after it.
+	const passes = 3
+
+	type read struct{ start, end time.Time }
+
+	// The channel holds every read the test looks at, so none of those
+	// is dropped; reads after them are, and never block the loop.
+	reads := make(chan read, passes*readsPerPass)
+
+	cache.reconciliationReadTestHook = func(int) {
+		start := time.Now()
+
+		time.Sleep(10 * time.Millisecond)
+
+		select {
+		case reads <- read{start: start, end: time.Now()}:
+		default:
+		}
+	}
+
+	cache.StartEviction(10 * time.Millisecond)
+	defer func() { _ = cache.StopEviction(t.Context()) }()
+
+	recorded := make([]read, 0, passes*readsPerPass)
+	timeout := time.After(15 * time.Second)
+
+	for len(recorded) < passes*readsPerPass {
+		select {
+		case r := <-reads:
+			recorded = append(recorded, r)
+		case <-timeout:
+			t.Fatalf("saw %d reconciliation reads in 15 s, want %d (%d passes)",
+				len(recorded), passes*readsPerPass, passes)
+		}
+	}
+
+	for pass := range passes - 1 {
+		first := recorded[pass*readsPerPass]
+		last := recorded[(pass+1)*readsPerPass-1]
+		next := recorded[(pass+1)*readsPerPass]
+
+		passTime := last.end.Sub(first.start)
+		wait := next.start.Sub(last.end)
+
+		t.Logf("pass %d took at least %v, and the next pass started %v after it",
+			pass+1, passTime, wait)
+
+		if wait < 10*passTime {
+			t.Errorf("pass %d took at least %v, and the next pass started %v "+
+				"after it, want at least %v", pass+1, passTime, wait, 10*passTime)
+		}
+	}
+}
+
 // TestStopEvictionInterruptsPassInProgress holds the test database's
 // only connection, so the startup reconciliation pass waits for it, and
 // checks that StopEviction stops that pass instead of waiting for the