feat: cache size management and LRU eviction (closes #51) (#55)

Implements #51 per the issue DoD and the owner direction comment (issuecomment-44068). ## Behavior **Config: `cache_max_bytes`** (integrates with the #52/#53 validation framework) - Strict int64 parsing via a new `getInt64`/`int64Val` getter in the existing strict-loader pattern; the key is registered in the known-keys list. A SET but invalid value — negative, float, null, non-numeric string, boolean, list — aborts startup with exit 1 naming the key and the offending value. - Explicit values are used exactly as given, any non-negative amount, no floor. `cache_max_bytes: 0` is a valid value that disables the disk cache entirely. - Omitted: after `state_dir` validation, the default resolves to `max(75% of free bytes on the filesystem containing <state_dir>/cache/, 500 MiB)`. The cache directory is created first and statfs runs on that actual path, so the measurement hits the right filesystem. The probe is injectable (`FreeSpaceProbeFunc`) so tests do not depend on the host disk. The effective limit (and disabled state) is logged at startup. **Size accounting** (no directory scans on the hot path) - Migration `002` adds a `variant_content` table — processed variants were previously untracked anywhere — and a `last_accessed_at` column on `source_content`, both indexed. Total usage is two SUM queries. - Stores record accounting rows; cache hits touch the LRU timestamps (same cost class as the existing per-request stats UPDATEs). The variant accounting insert is best-effort with a warning: the reconciliation pass (below) adopts any file that missed its row, and this keeps the pre-migration inline test schema working. **Eviction policy: global LRU across both content classes** - Candidates are the least-recently-used entries from `variant_content` and `source_content` (batched, 100 per class per pass, merged oldest-first by `COALESCE(last_accessed_at, fetched_at)`), evicted until usage is at or below the limit. - Why global LRU: recency of actual use is the best cheap predictor of future use for a CDN-style cache, and treating both classes in one ordering avoids pathologies of class-priority schemes (e.g. evicting every variant before any cold source blob, which would tank hit rate, or the reverse, which would hoard stale sources). Byte-for-byte, the coldest data goes first regardless of what kind it is. LFU-style schemes need more bookkeeping for marginal gain at this scale. - Reference safety (the multi-reference DoD case): evicting a source blob deletes ALL `source_metadata` rows referencing it plus its `source_content` row in a single transaction BEFORE the file is unlinked. A blob referenced by multiple source paths is only ever removed together with all of its references, and DB rows never point at deleted files (the crash window leaves at worst an orphaned file, which reconciliation sweeps). The JSON metadata sidecars for removed rows are deleted as well. **Triggers, off the request path** - A background goroutine (started in the handlers OnStart hook, stopped in OnStop) runs an eviction pass on a periodic ticker (5 min) and on write pressure: every store sends a non-blocking notification on a capacity-1 channel. Requests never wait on eviction. - On startup the goroutine first reconciles accounting with the disk (off the hot path): adopts untracked variant files (size/mtime from disk, content type from the `.meta` sidecar), drops accounting rows whose files are missing, removes source blob files the DB does not know (unreachable, since lookups go through `source_metadata`), removes rows whose files are gone, and sweeps `.tmp-*` files older than an hour. **`cache_max_bytes: 0` disables the disk cache** - No cache directories are created, lookups always miss, `StoreSource`/`StoreVariant` are no-ops, no evictor runs; every request fetches and processes uncached. Verified end-to-end (below). ## Notes for review - At the `imgcache.CacheConfig` layer, disabling is an explicit `DisableDiskCache` flag rather than `MaxBytes == 0`, because existing test fixtures construct `CacheConfig` without `MaxBytes` and rely on the legacy "no limit" behavior; per repo rules those tests were not touched. The config layer maps `cache_max_bytes: 0` to the flag in `handlers`. `MaxBytes == 0` at that layer means "no limit enforced" and is unreachable from production config (the computed default is always at least 500 MiB). - The negative cache stays active in disabled mode: it is DB-backed (TTL-expired rows in SQLite), not part of the disk cache this issue bounds, and it protects against hammering failing upstreams. Flagging explicitly since the direction said "no cache reads, no cache writes" — I read that as the disk cache; happy to disable it too if intended. - One deviation from pure red/green: after the red commit I extended the new-test fixture helper (`newEvictionTestCache`) to pass `DisableDiskCache: maxBytes == 0`, mirroring the production mapping, when the flag design emerged. Assertions were not touched; no pre-existing tests were modified. - Sidecar files (`.meta`, metadata JSON) are not counted in usage; they are bounded by entry counts and small (tens of bytes to ~1 KiB per entry) while content bytes dominate. Documented here for transparency. - Discovered while working: `Cache.Stats` reads the never-populated `output_content`/`request_cache` tables, so `TotalItems`/`TotalSizeBytes` are always 0. Out of scope here; filing as a separate issue. ## Verification - TDD: commit `3963ec3` adds the failing tests first (18 new tests covering strict parsing, default computation with injected probe including floor and 75% branches, explicit-no-floor, zero-disables, size accounting, dedup accounting, LRU order, multi-reference blob eviction with the no-dangling-references invariant, under-limit no-op, write-pressure trigger, periodic trigger, reconciliation); implementation follows in `8cb09b6`/`bdd86a4` until green. - `make check` green (all tests, lint 0 issues, fmt-check) at HEAD. - Pinned CI lint gate: `docker build --target lint .` green (golangci-lint v2.10.1). - End-to-end with the built binary: - omitted key: startup logs `computed default cache size limit from free space` and `effective cache size limit` (75% of the test host's free space); - `cache_max_bytes: banana`: exit 1 with `config key "cache_max_bytes": value "banana" is not an integer`; - `cache_max_bytes: 0`: `cache_disabled=true` logged, two identical requests both fetch upstream (2 upstream fetches logged), 200 `image/jpeg` responses, no `cache/` directory created, only `state.sqlite3` in the state dir; - enabled: second request served from cache (1 upstream fetch), `variant_content` and `source_content` rows match the on-disk file sizes. Co-authored-by: sneak <sneak@sneak.berlin> Reviewed-on: #55 Co-authored-by: clawbot <clawbot@noreply.example.org> Co-committed-by: clawbot <clawbot@noreply.example.org>
2026-08-09 13:22:51 +02:00
parent 61f42e6602
commit 63fbc98e63
15 changed files with 2597 additions and 41 deletions
--- a/internal/config/cache_max_bytes_test.go
+++ b/internal/config/cache_max_bytes_test.go
@@ -0,0 +1,271 @@
+package config
+
+import (
+	"errors"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// discardLogger returns a logger that swallows all output, for tests
+// that exercise code paths which log.
+func discardLogger() *slog.Logger {
+	return slog.New(slog.NewTextHandler(io.Discard, nil))
+}
+
+// TestCacheMaxBytesExplicitValueUsedWithoutFloor verifies that an
+// explicitly configured cache_max_bytes value is used exactly as
+// given: the 500 MiB floor applies only to the computed default, never
+// to explicit values.
+func TestCacheMaxBytesExplicitValueUsedWithoutFloor(t *testing.T) {
+	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 1024\n"
+
+	c, err := configFromYAML(t, yamlContent)
+	if err != nil {
+		t.Fatalf("explicit cache_max_bytes must be accepted, got error: %v", err)
+	}
+
+	if c.CacheMaxBytes != 1024 {
+		t.Errorf("CacheMaxBytes = %d, want 1024 (no floor for explicit values)",
+			c.CacheMaxBytes)
+	}
+}
+
+// TestCacheMaxBytesZeroIsValidAndDisablesCache verifies that an
+// explicit zero is a valid value (it disables the disk cache), not an
+// error.
+func TestCacheMaxBytesZeroIsValidAndDisablesCache(t *testing.T) {
+	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 0\n"
+
+	c, err := configFromYAML(t, yamlContent)
+	if err != nil {
+		t.Fatalf("cache_max_bytes: 0 must be accepted, got error: %v", err)
+	}
+
+	if c.CacheMaxBytes != 0 {
+		t.Errorf("CacheMaxBytes = %d, want 0", c.CacheMaxBytes)
+	}
+}
+
+// TestCacheMaxBytesLargeExplicitValueParses verifies that values above
+// 32-bit range parse correctly (the field is an int64 byte count).
+func TestCacheMaxBytesLargeExplicitValueParses(t *testing.T) {
+	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 10737418240\n"
+
+	c, err := configFromYAML(t, yamlContent)
+	if err != nil {
+		t.Fatalf("large cache_max_bytes must be accepted, got error: %v", err)
+	}
+
+	if c.CacheMaxBytes != 10737418240 {
+		t.Errorf("CacheMaxBytes = %d, want 10737418240", c.CacheMaxBytes)
+	}
+}
+
+// TestCacheMaxBytesInvalidValuesAbortStartup verifies that a SET but
+// invalid cache_max_bytes value aborts startup naming the key and the
+// offending value, per the no-silent-fallback rule: defaults apply
+// only to omitted keys.
+func TestCacheMaxBytesInvalidValuesAbortStartup(t *testing.T) {
+	signingKeyLine := "signing_key: " + validTestSigningKey + "\n"
+
+	cases := []struct {
+		name string
+		yaml string
+		// wantErrSubstrings must all appear in the error message.
+		wantErrSubstrings []string
+	}{
+		{
+			name:              "negative",
+			yaml:              signingKeyLine + "cache_max_bytes: -1024\n",
+			wantErrSubstrings: []string{"cache_max_bytes", "-1024"},
+		},
+		{
+			name:              "float",
+			yaml:              signingKeyLine + "cache_max_bytes: 3.5\n",
+			wantErrSubstrings: []string{"cache_max_bytes", "3.5"},
+		},
+		{
+			name:              "non-numeric string",
+			yaml:              signingKeyLine + "cache_max_bytes: banana\n",
+			wantErrSubstrings: []string{"cache_max_bytes", "banana"},
+		},
+		{
+			name:              "explicit null",
+			yaml:              signingKeyLine + "cache_max_bytes: null\n",
+			wantErrSubstrings: []string{"cache_max_bytes", "null"},
+		},
+		{
+			name:              "bare key no value",
+			yaml:              signingKeyLine + "cache_max_bytes:\n",
+			wantErrSubstrings: []string{"cache_max_bytes", "null"},
+		},
+		{
+			name:              "boolean",
+			yaml:              signingKeyLine + "cache_max_bytes: true\n",
+			wantErrSubstrings: []string{"cache_max_bytes", "true"},
+		},
+		{
+			name:              "list",
+			yaml:              signingKeyLine + "cache_max_bytes:\n  - 1\n",
+			wantErrSubstrings: []string{"cache_max_bytes"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c, err := configFromYAML(t, tc.yaml)
+			if err == nil {
+				t.Fatalf("config with %s cache_max_bytes must abort startup, got config: %+v",
+					tc.name, c)
+			}
+
+			t.Logf("got expected error: %v", err)
+
+			for _, want := range tc.wantErrSubstrings {
+				if !strings.Contains(err.Error(), want) {
+					t.Errorf("error %q does not mention %q", err.Error(), want)
+				}
+			}
+		})
+	}
+}
+
+// TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace verifies the
+// computed default is 75% of the probed free space when that exceeds
+// the floor.
+func TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace(t *testing.T) {
+	// 4 GiB free -> 3 GiB default.
+	probe := func(string) (uint64, error) { return 4294967296, nil }
+
+	got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
+	if err != nil {
+		t.Fatalf("ComputeDefaultCacheMaxBytes returned error: %v", err)
+	}
+
+	if got != 3221225472 {
+		t.Errorf("ComputeDefaultCacheMaxBytes = %d, want 3221225472 (75%% of 4 GiB)", got)
+	}
+}
+
+// TestComputeDefaultCacheMaxBytesAppliesFloorToComputedDefault
+// verifies that when 75% of free space is below 500 MiB, the computed
+// default is floored at DefaultCacheMaxBytesFloor.
+func TestComputeDefaultCacheMaxBytesAppliesFloorToComputedDefault(t *testing.T) {
+	cases := []struct {
+		name      string
+		freeBytes uint64
+	}{
+		{name: "100 MiB free", freeBytes: 104857600},
+		{name: "zero free", freeBytes: 0},
+		{name: "just below floor threshold", freeBytes: 699050665},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			probe := func(string) (uint64, error) { return tc.freeBytes, nil }
+
+			got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
+			if err != nil {
+				t.Fatalf("ComputeDefaultCacheMaxBytes returned error: %v", err)
+			}
+
+			if got != DefaultCacheMaxBytesFloor {
+				t.Errorf("ComputeDefaultCacheMaxBytes = %d, want floor %d",
+					got, DefaultCacheMaxBytesFloor)
+			}
+		})
+	}
+}
+
+// TestComputeDefaultCacheMaxBytesPropagatesProbeError verifies that a
+// failing free-space probe produces an error naming the config key,
+// instead of a silently wrong default.
+func TestComputeDefaultCacheMaxBytesPropagatesProbeError(t *testing.T) {
+	probe := func(string) (uint64, error) { return 0, errors.New("statfs failed") }
+
+	_, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
+	if err == nil {
+		t.Fatal("probe failure must produce an error, got nil")
+	}
+
+	t.Logf("got expected error: %v", err)
+
+	if !strings.Contains(err.Error(), "cache_max_bytes") {
+		t.Errorf("error %q does not name the config key cache_max_bytes", err.Error())
+	}
+}
+
+// TestResolveCacheMaxBytesComputesDefaultWhenOmitted verifies that an
+// omitted cache_max_bytes key resolves to the computed default, that
+// the probe is pointed at <state_dir>/cache/ (which must be created
+// first so statfs measures the right filesystem), and that the result
+// lands on the Config.
+func TestResolveCacheMaxBytesComputesDefaultWhenOmitted(t *testing.T) {
+	c, err := configFromYAML(t, "signing_key: "+validTestSigningKey+"\n")
+	if err != nil {
+		t.Fatalf("minimal config should be valid, got error: %v", err)
+	}
+
+	c.StateDir = t.TempDir()
+	wantCacheDir := filepath.Join(c.StateDir, "cache")
+
+	var probedPath string
+
+	// 4 GiB free -> 3 GiB default.
+	probe := func(path string) (uint64, error) {
+		probedPath = path
+
+		return 4294967296, nil
+	}
+
+	if err := c.resolveCacheMaxBytes(discardLogger(), probe); err != nil {
+		t.Fatalf("resolveCacheMaxBytes returned error: %v", err)
+	}
+
+	if c.CacheMaxBytes != 3221225472 {
+		t.Errorf("CacheMaxBytes = %d, want computed default 3221225472", c.CacheMaxBytes)
+	}
+
+	if probedPath != wantCacheDir {
+		t.Errorf("free space probed at %q, want cache directory %q", probedPath, wantCacheDir)
+	}
+
+	info, err := os.Stat(wantCacheDir)
+	if err != nil || !info.IsDir() {
+		t.Errorf("cache directory %q was not created before probing: info=%v err=%v",
+			wantCacheDir, info, err)
+	}
+}
+
+// TestResolveCacheMaxBytesDoesNotOverrideExplicitValue verifies that
+// an explicitly configured value survives resolution untouched and
+// that the free-space probe is never consulted for it.
+func TestResolveCacheMaxBytesDoesNotOverrideExplicitValue(t *testing.T) {
+	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 1024\n"
+
+	c, err := configFromYAML(t, yamlContent)
+	if err != nil {
+		t.Fatalf("explicit cache_max_bytes must be accepted, got error: %v", err)
+	}
+
+	c.StateDir = t.TempDir()
+
+	probe := func(string) (uint64, error) {
+		t.Error("free-space probe must not be consulted for explicit values")
+
+		return 0, errors.New("probe must not be called")
+	}
+
+	if err := c.resolveCacheMaxBytes(discardLogger(), probe); err != nil {
+		t.Fatalf("resolveCacheMaxBytes returned error: %v", err)
+	}
+
+	if c.CacheMaxBytes != 1024 {
+		t.Errorf("CacheMaxBytes = %d, want explicit 1024 (no floor, no recompute)",
+			c.CacheMaxBytes)
+	}
+}
--- a/internal/config/cachesize.go
+++ b/internal/config/cachesize.go
@@ -0,0 +1,110 @@
+package config
+
+import (
+	"fmt"
+	"log/slog"
+	"math"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+// DefaultCacheMaxBytesFloor is the minimum computed default for the
+// cache_max_bytes setting: 500 MiB. The floor applies only to the
+// computed default (when the key is omitted from the configuration),
+// never to explicitly configured values.
+const DefaultCacheMaxBytesFloor int64 = 524288000
+
+// cacheDirPerms is the permission mode for the cache directory created
+// before probing free space, matching the state directory permissions.
+const cacheDirPerms = 0o750
+
+// freeSpaceFractionNumerator and freeSpaceFractionDenominator express
+// the 75% share of free space used for the computed default limit as
+// integer arithmetic (dividing before multiplying avoids overflow).
+const (
+	freeSpaceFractionNumerator   uint64 = 3
+	freeSpaceFractionDenominator uint64 = 4
+)
+
+// FreeSpaceProbeFunc reports the number of free bytes available on the
+// filesystem containing path. It is a function type so tests can
+// inject a fake probe instead of depending on the host disk.
+type FreeSpaceProbeFunc func(path string) (uint64, error)
+
+// defaultFreeSpaceProbe reports free filesystem bytes via statfs on
+// the given path, as available to unprivileged processes.
+func defaultFreeSpaceProbe(path string) (uint64, error) {
+	var stat syscall.Statfs_t
+	if err := syscall.Statfs(path, &stat); err != nil {
+		return 0, err
+	}
+
+	if stat.Bsize < 0 {
+		return 0, fmt.Errorf("statfs reported negative block size %d for %q", stat.Bsize, path)
+	}
+
+	blockSize := uint64(stat.Bsize) //nolint:gosec // G115: negative Bsize rejected above
+
+	return stat.Bavail * blockSize, nil
+}
+
+// ComputeDefaultCacheMaxBytes returns the default cache size limit for
+// the filesystem containing cacheDir: 75% of the free bytes reported
+// by probe, with a floor of DefaultCacheMaxBytesFloor.
+func ComputeDefaultCacheMaxBytes(cacheDir string, probe FreeSpaceProbeFunc) (int64, error) {
+	freeBytes, err := probe(cacheDir)
+	if err != nil {
+		return 0, fmt.Errorf("config key %q: cannot determine free space for %q: %w",
+			"cache_max_bytes", cacheDir, err)
+	}
+
+	computed := freeBytes / freeSpaceFractionDenominator * freeSpaceFractionNumerator
+	if computed > math.MaxInt64 {
+		computed = math.MaxInt64
+	}
+
+	limit := int64(computed) //nolint:gosec // G115: clamped to MaxInt64 above
+
+	if limit < DefaultCacheMaxBytesFloor {
+		limit = DefaultCacheMaxBytesFloor
+	}
+
+	return limit, nil
+}
+
+// resolveCacheMaxBytes finalizes CacheMaxBytes after state_dir
+// validation: an explicitly configured value is kept as-is (no floor
+// applies), while an omitted key receives the computed default based
+// on free space in <state_dir>/cache/. The cache directory is created
+// first so statfs measures the filesystem that will actually hold the
+// cache. The effective limit is logged either way.
+func (c *Config) resolveCacheMaxBytes(log *slog.Logger, probe FreeSpaceProbeFunc) error {
+	if !c.cacheMaxBytesExplicit {
+		cacheDir := filepath.Join(c.StateDir, "cache")
+
+		if err := os.MkdirAll(cacheDir, cacheDirPerms); err != nil {
+			return fmt.Errorf("config key %q: cannot create cache directory %q: %w",
+				"cache_max_bytes", cacheDir, err)
+		}
+
+		limit, err := ComputeDefaultCacheMaxBytes(cacheDir, probe)
+		if err != nil {
+			return err
+		}
+
+		c.CacheMaxBytes = limit
+
+		log.Info("computed default cache size limit from free space",
+			"cache_max_bytes", limit,
+			"cache_dir", cacheDir,
+		)
+	}
+
+	log.Info("effective cache size limit",
+		"cache_max_bytes", c.CacheMaxBytes,
+		"cache_disabled", c.CacheMaxBytes == 0,
+	)
+
+	return nil
+}
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -48,6 +48,19 @@ type Config struct {
 	AllowlistHosts             []string // Hosts that don't require signatures
 	AllowHTTP                  bool     // Allow non-TLS upstream (testing only)
 	UpstreamConnectionsPerHost int      // Max concurrent connections per upstream host
+
+	// CacheMaxBytes is the disk cache size limit in bytes. Zero
+	// disables the disk cache entirely. When cache_max_bytes is
+	// omitted from the configuration, this holds the computed default
+	// (75% of free space on the filesystem containing
+	// <state_dir>/cache/, floored at DefaultCacheMaxBytesFloor).
+	CacheMaxBytes int64
+
+	// cacheMaxBytesExplicit records whether cache_max_bytes was
+	// explicitly set in the configuration file. Explicit values are
+	// used exactly as given; only an omitted key gets the computed
+	// default (and its floor) in resolveCacheMaxBytes.
+	cacheMaxBytesExplicit bool
 }

 // New creates a new Config instance by loading configuration from file.
@@ -73,6 +86,10 @@ func New(_ fx.Lifecycle, params Params) (*Config, error) {
 		return nil, err
 	}

+	if err := c.resolveCacheMaxBytes(log, defaultFreeSpaceProbe); err != nil {
+		return nil, err
+	}
+
 	if c.Debug {
 		params.Logger.EnableDebugLogging()
 	}
@@ -111,6 +128,16 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 		AllowHTTP:       loader.boolVal("allow_http", false),
 		UpstreamConnectionsPerHost: loader.intVal(
 			"upstream_connections_per_host", DefaultUpstreamConnectionsPerHost),
+		CacheMaxBytes: loader.int64Val("cache_max_bytes", 0),
+	}
+
+	// The computed default for cache_max_bytes needs a validated
+	// state_dir, so it is resolved later (resolveCacheMaxBytes); here
+	// we only record whether the operator set the key explicitly.
+	if sc != nil {
+		if _, present := sc.Get("cache_max_bytes"); present {
+			c.cacheMaxBytesExplicit = true
+		}
 	}

 	// Build DBURL from StateDir if not explicitly set. The derived URL
@@ -219,7 +246,7 @@ func isKnownConfigKey(key string) bool {
 	switch key {
 	case "debug", "maintenance_mode", "port", "state_dir", "sentry_dsn",
 		"db_url", "metrics", "signing_key", "allowlist_hosts", "allow_http",
-		"upstream_connections_per_host", "env":
+		"upstream_connections_per_host", "cache_max_bytes", "env":
 		return true
 	}

@@ -289,6 +316,13 @@ func (c *Config) validate() error {
 		return fmt.Errorf("config key %q: value must not be empty", "state_dir")
 	}

+	// Zero is valid (it disables the disk cache); only negative
+	// values are rejected. No floor applies to explicit values.
+	if c.CacheMaxBytes < 0 {
+		return fmt.Errorf("config key %q: value %d must not be negative",
+			"cache_max_bytes", c.CacheMaxBytes)
+	}
+
 	for _, host := range c.AllowlistHosts {
 		if err := validateAllowlistHost(host); err != nil {
 			return err
@@ -412,6 +446,19 @@ func (l *strictLoader) intVal(key string, defaultVal int) int {
 	return val
 }

+func (l *strictLoader) int64Val(key string, defaultVal int64) int64 {
+	if l.err != nil {
+		return 0
+	}
+
+	val, err := getInt64(l.sc, key, defaultVal)
+	if err != nil {
+		l.err = err
+	}
+
+	return val
+}
+
 func (l *strictLoader) boolVal(key string, defaultVal bool) bool {
 	if l.err != nil {
 		return false
@@ -492,6 +539,55 @@ func getInt(sc *smartconfig.Config, key string, defaultVal int) (int, error) {
 	}
 }

+// getInt64 returns the 64-bit integer value for key, or defaultVal if
+// the key is omitted. A present value that is not a whole number, or
+// is explicitly null, is an error; fractional values are never
+// truncated and out-of-range values are never clamped.
+func getInt64(sc *smartconfig.Config, key string, defaultVal int64) (int64, error) {
+	if sc == nil {
+		return defaultVal, nil
+	}
+
+	raw, ok := sc.Get(key)
+	if !ok {
+		return defaultVal, nil
+	}
+
+	if raw == nil {
+		return 0, errNullConfigValue(key)
+	}
+
+	switch val := raw.(type) {
+	case int:
+		return int64(val), nil
+	case int64:
+		return val, nil
+	case uint64:
+		if val > math.MaxInt64 {
+			return 0, fmt.Errorf("config key %q: value %d overflows a 64-bit integer",
+				key, val)
+		}
+
+		return int64(val), nil //nolint:gosec // G115: bounds checked above
+	case float64:
+		if val != math.Trunc(val) {
+			return 0, fmt.Errorf("config key %q: value %v is not an integer", key, val)
+		}
+
+		return int64(val), nil
+	case string:
+		parsed, err := strconv.ParseInt(strings.TrimSpace(val), 10, 64)
+		if err != nil {
+			return 0, fmt.Errorf("config key %q: value %q is not an integer", key, val)
+		}
+
+		return parsed, nil
+	default:
+		return 0, fmt.Errorf("config key %q: value %v (%T) is not an integer",
+			key, raw, raw)
+	}
+}
+
 // getBool returns the boolean value for key, or defaultVal if the key
 // is omitted. A present value that is not a boolean (or a ParseBool-able
 // string), or is explicitly null, is an error; numbers are not accepted