Add metadata TTL and stale-while-revalidate support

Cached metadata is now served directly within a configurable TTL window
(default 5m) without contacting upstream, reducing latency and upstream
load. When upstream is unreachable and the cache is past its TTL, stale
content is served with a Warning: 110 header per RFC 7234.

New config: `metadata_ttl` (YAML) / `PROXY_METADATA_TTL` (env).
Set to "0" to always revalidate with upstream.

Author: andrew

cmd/proxy/main.go

@@ -453,6 +453,7 @@ func runMirror() {
 	resolver := fetch.NewResolver()
 	proxy := handler.NewProxy(db, store, fetcher, resolver, logger)
 	proxy.CacheMetadata = true // mirror always caches metadata
+	proxy.MetadataTTL = cfg.ParseMetadataTTL()
 
 	m := mirror.New(proxy, db, store, logger, *concurrency)
 

docs/configuration.md

@@ -225,6 +225,20 @@ Or via environment variable: `PROXY_CACHE_METADATA=true`.
 
 The `proxy mirror` command always enables metadata caching regardless of this setting.
 
+### Metadata TTL
+
+When metadata caching is enabled, `metadata_ttl` controls how long a cached response is considered fresh before revalidating with upstream. During the TTL window, cached metadata is served directly without contacting upstream, reducing latency and upstream load.
+
+```yaml
+metadata_ttl: "5m"   # default
+```
+
+Or via environment variable: `PROXY_METADATA_TTL=10m`.
+
+Set to `"0"` to always revalidate with upstream (ETag-based conditional requests still avoid re-downloading unchanged content).
+
+When upstream is unreachable and the cached entry is past its TTL, the proxy serves the stale cached copy with a `Warning: 110 - "Response is Stale"` header so clients can tell the data may be outdated.
+
 ## Mirror API
 
 The `/api/mirror` endpoints are disabled by default. Enable them to allow starting mirror jobs via HTTP:

internal/config/config.go

@@ -55,6 +55,7 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"time"
 
 	"gopkg.in/yaml.v3"
 )
@@ -89,6 +90,11 @@ type Config struct {
 	// The mirror command always enables this regardless of this setting.
 	CacheMetadata bool `json:"cache_metadata" yaml:"cache_metadata"`
 
+	// MetadataTTL is how long cached metadata is considered fresh before
+	// revalidating with upstream. Uses Go duration syntax (e.g. "5m", "1h").
+	// Default: "5m". Set to "0" to always revalidate.
+	MetadataTTL string `json:"metadata_ttl" yaml:"metadata_ttl"`
+
 	// MirrorAPI enables the /api/mirror endpoints for starting mirror jobs via HTTP.
 	// Disabled by default to prevent unauthenticated users from triggering downloads.
 	MirrorAPI bool `json:"mirror_api" yaml:"mirror_api"`
@@ -321,6 +327,9 @@ func (c *Config) LoadFromEnv() {
 	if v := os.Getenv("PROXY_MIRROR_API"); v != "" {
 		c.MirrorAPI = v == "true" || v == "1"
 	}
+	if v := os.Getenv("PROXY_METADATA_TTL"); v != "" {
+		c.MetadataTTL = v
+	}
 }
 
 // Validate checks the configuration for errors.
@@ -370,9 +379,34 @@ func (c *Config) Validate() error {
 		}
 	}
 
+	// Validate metadata TTL if specified
+	if c.MetadataTTL != "" && c.MetadataTTL != "0" {
+		if _, err := time.ParseDuration(c.MetadataTTL); err != nil {
+			return fmt.Errorf("invalid metadata_ttl %q: %w", c.MetadataTTL, err)
+		}
+	}
+
 	return nil
 }
 
+const defaultMetadataTTL = 5 * time.Minute //nolint:mnd // sensible default
+
+// ParseMetadataTTL returns the metadata TTL duration.
+// Returns 5 minutes if unset, 0 if explicitly disabled.
+func (c *Config) ParseMetadataTTL() time.Duration {
+	if c.MetadataTTL == "" {
+		return defaultMetadataTTL
+	}
+	if c.MetadataTTL == "0" {
+		return 0
+	}
+	d, err := time.ParseDuration(c.MetadataTTL)
+	if err != nil {
+		return defaultMetadataTTL
+	}
+	return d
+}
+
 // ParseSize parses a human-readable size string (e.g., "10GB", "500MB").
 // Returns the size in bytes.
 func ParseSize(s string) (int64, error) {

internal/config/config_test.go

@@ -4,6 +4,7 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+	"time"
 )
 
 const (
@@ -301,3 +302,56 @@ func TestLoadFileNotFound(t *testing.T) {
 		t.Error("expected error for nonexistent file")
 	}
 }
+
+func TestParseMetadataTTL(t *testing.T) {
+	tests := []struct {
+		name string
+		ttl  string
+		want time.Duration
+	}{
+		{"empty defaults to 5m", "", 5 * time.Minute},
+		{"explicit zero", "0", 0},
+		{"10 minutes", "10m", 10 * time.Minute},
+		{"1 hour", "1h", 1 * time.Hour},
+		{"invalid defaults to 5m", "not-a-duration", 5 * time.Minute},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Default()
+			cfg.MetadataTTL = tt.ttl
+			got := cfg.ParseMetadataTTL()
+			if got != tt.want {
+				t.Errorf("ParseMetadataTTL() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestValidateMetadataTTL(t *testing.T) {
+	cfg := Default()
+	cfg.MetadataTTL = "invalid"
+	if err := cfg.Validate(); err == nil {
+		t.Error("expected validation error for invalid metadata_ttl")
+	}
+
+	cfg.MetadataTTL = "5m"
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("unexpected error for valid metadata_ttl: %v", err)
+	}
+
+	cfg.MetadataTTL = "0"
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("unexpected error for zero metadata_ttl: %v", err)
+	}
+}
+
+func TestLoadMetadataTTLFromEnv(t *testing.T) {
+	cfg := Default()
+	t.Setenv("PROXY_METADATA_TTL", "10m")
+	cfg.LoadFromEnv()
+
+	if cfg.MetadataTTL != "10m" {
+		t.Errorf("MetadataTTL = %q, want %q", cfg.MetadataTTL, "10m")
+	}
+}

internal/handler/handler.go

@@ -68,6 +68,7 @@ type Proxy struct {
 	Logger        *slog.Logger
 	Cooldown      *cooldown.Config
 	CacheMetadata bool
+	MetadataTTL   time.Duration
 	HTTPClient    *http.Client
 }
 
@@ -383,12 +384,31 @@ func (p *Proxy) FetchOrCacheMetadata(ctx context.Context, ecosystem, cacheKey, u
 
 	storagePath := metadataStoragePath(ecosystem, cacheKey)
 
-	// Check for existing cache entry (for ETag revalidation)
+	// Check for existing cache entry (for ETag revalidation and TTL)
 	var entry *database.MetadataCacheEntry
 	if p.CacheMetadata && p.DB != nil {
 		entry, _ = p.DB.GetMetadataCache(ecosystem, cacheKey)
 	}
 
+	// Serve from cache if within TTL (skip upstream entirely)
+	if entry != nil && p.MetadataTTL > 0 && entry.FetchedAt.Valid {
+		if time.Since(entry.FetchedAt.Time) < p.MetadataTTL {
+			cached, readErr := p.Storage.Open(ctx, entry.StoragePath)
+			if readErr == nil {
+				defer func() { _ = cached.Close() }()
+				data, readErr := ReadMetadata(cached)
+				if readErr == nil {
+					ct := contentTypeJSON
+					if entry.ContentType.Valid {
+						ct = entry.ContentType.String
+					}
+					return data, ct, nil
+				}
+			}
+			// Cache file missing/unreadable, fall through to upstream
+		}
+	}
+
 	accept := contentTypeJSON
 	if len(acceptHeaders) > 0 && acceptHeaders[0] != "" {
 		accept = acceptHeaders[0]
@@ -529,6 +549,37 @@ func (p *Proxy) cacheMetadataBlob(ctx context.Context, ecosystem, cacheKey, stor
 	})
 }
 
+// cachedMeta holds cache validators and freshness state from a metadata cache entry.
+type cachedMeta struct {
+	etag         string
+	lastModified time.Time
+	stale        bool
+}
+
+// lookupCachedMeta retrieves cache validators for a metadata entry.
+func (p *Proxy) lookupCachedMeta(ecosystem, cacheKey string) cachedMeta {
+	if p.DB == nil {
+		return cachedMeta{}
+	}
+	entry, err := p.DB.GetMetadataCache(ecosystem, cacheKey)
+	if err != nil || entry == nil {
+		return cachedMeta{}
+	}
+	var cm cachedMeta
+	if entry.ETag.Valid {
+		cm.etag = entry.ETag.String
+	}
+	if entry.LastModified.Valid {
+		cm.lastModified = entry.LastModified.Time
+	}
+	// If FetchedAt is older than TTL, upstream must have failed and
+	// we served from stale cache (successful fetches update FetchedAt).
+	if p.MetadataTTL > 0 && entry.FetchedAt.Valid && time.Since(entry.FetchedAt.Time) > p.MetadataTTL {
+		cm.stale = true
+	}
+	return cm
+}
+
 // ProxyCached fetches metadata from upstream (with optional caching for offline fallback)
 // and writes it to the response. Optional acceptHeaders specify the Accept header to send.
 // When metadata caching is disabled, the response is streamed directly to avoid buffering
@@ -551,30 +602,18 @@ func (p *Proxy) ProxyCached(w http.ResponseWriter, r *http.Request, upstreamURL,
 		return
 	}
 
-	// Look up cache entry to get ETag and upstream Last-Modified for conditional response headers
-	var etag string
-	var lastModified time.Time
-	if p.DB != nil {
-		if entry, err := p.DB.GetMetadataCache(ecosystem, cacheKey); err == nil && entry != nil {
-			if entry.ETag.Valid {
-				etag = entry.ETag.String
-			}
-			if entry.LastModified.Valid {
-				lastModified = entry.LastModified.Time
-			}
-		}
-	}
+	cm := p.lookupCachedMeta(ecosystem, cacheKey)
 
 	// Honor client conditional request headers
-	if etag != "" {
-		if match := r.Header.Get("If-None-Match"); match != "" && match == etag {
+	if cm.etag != "" {
+		if match := r.Header.Get("If-None-Match"); match != "" && match == cm.etag {
 			w.WriteHeader(http.StatusNotModified)
 			return
 		}
 	}
-	if !lastModified.IsZero() {
+	if !cm.lastModified.IsZero() {
 		if ims := r.Header.Get("If-Modified-Since"); ims != "" {
-			if t, err := http.ParseTime(ims); err == nil && !lastModified.After(t) {
+			if t, err := http.ParseTime(ims); err == nil && !cm.lastModified.After(t) {
 				w.WriteHeader(http.StatusNotModified)
 				return
 			}
@@ -583,11 +622,14 @@ func (p *Proxy) ProxyCached(w http.ResponseWriter, r *http.Request, upstreamURL,
 
 	w.Header().Set("Content-Type", contentType)
 	w.Header().Set("Content-Length", strconv.Itoa(len(body)))
-	if etag != "" {
-		w.Header().Set("ETag", etag)
+	if cm.etag != "" {
+		w.Header().Set("ETag", cm.etag)
+	}
+	if !cm.lastModified.IsZero() {
+		w.Header().Set("Last-Modified", cm.lastModified.UTC().Format(http.TimeFormat))
 	}
-	if !lastModified.IsZero() {
-		w.Header().Set("Last-Modified", lastModified.UTC().Format(http.TimeFormat))
+	if cm.stale {
+		w.Header().Set("Warning", `110 - "Response is Stale"`)
 	}
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(body)