Merge branch 'main' into golangci-v2.12.2

Absorbs the cache size management and LRU eviction work (#55). All four
textual conflicts resolved in favor of main's implementation, with this
branch's mechanical lint conformance re-applied on top:

- internal/config/config.go: took main's cache_max_bytes wiring
  (CacheMaxBytes, cacheMaxBytesExplicit) verbatim and expressed the key
  through this branch's constant convention as keyCacheMaxBytes.
- internal/imgcache/cache.go: took main's disabled-cache guards, LRU
  touch on lookup, and variant_content size accounting verbatim;
  re-applied this branch's signature wrapping for lll.
- internal/imgcache/storage.go: took main's new writeIfAbsent helper and
  its temp-file cleanup defer verbatim. The auto-merge had silently
  dropped that defer in favor of this branch's inline cleanup form;
  restored so the cleanup semantics that arrived from main are intact.
- TODO.md: kept both sides' Completed Steps entries.

.golangci.yml resolves to this branch's canonical version
(sha256 021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb).

make build and make test are green; #55's code is not yet conformant
with the canonical lint config, which the following commits address.

internal/config/config.go

@@ -41,6 +41,7 @@ const (
 	keyAllowlistHosts             = "allowlist_hosts"
 	keyAllowHTTP                  = "allow_http"
 	keyUpstreamConnectionsPerHost = "upstream_connections_per_host"
+	keyCacheMaxBytes              = "cache_max_bytes"
 )
 
 // Static validation errors. Each use site attaches the offending key
@@ -94,6 +95,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.
@@ -120,6 +134,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()
 	}
@@ -160,6 +178,16 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 		AllowHTTP:       loader.boolVal(keyAllowHTTP, false),
 		UpstreamConnectionsPerHost: loader.intVal(
 			keyUpstreamConnectionsPerHost, DefaultUpstreamConnectionsPerHost),
+		CacheMaxBytes: loader.int64Val(keyCacheMaxBytes, 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(keyCacheMaxBytes); present {
+			c.cacheMaxBytesExplicit = true
+		}
 	}
 
 	// Build DBURL from StateDir if not explicitly set. The derived URL
@@ -266,7 +294,7 @@ func isKnownConfigKey(key string) bool {
 	switch key {
 	case keyDebug, keyMaintenanceMode, keyPort, keyStateDir, keySentryDSN,
 		keyDBURL, keyMetrics, keySigningKey, keyAllowlistHosts, keyAllowHTTP,
-		keyUpstreamConnectionsPerHost, "env":
+		keyUpstreamConnectionsPerHost, keyCacheMaxBytes, "env":
 		return true
 	}
 
@@ -339,6 +367,13 @@ func (c *Config) validate() error {
 		return fmt.Errorf("config key %q: %w", keyStateDir, errValueEmpty)
 	}
 
+	// 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 {
 		err := validateAllowlistHost(host)
 		if err != nil {
@@ -463,6 +498,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
@@ -545,6 +593,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